chore(repository): revise and adjust content based on Litt and Pocok …

.gitignore

@@ -18,4 +18,5 @@ Desktop.ini
 *.log
 
 # Locally generated distribution archives
-/codebase-learning-flow.zip
+/INITIALIZE_LEARNING_FLOW_*.zip
+/codebase-learning-flow*.zip

AGENTS.md

@@ -0,0 +1,29 @@
+# Codebase Learning Flow maintenance instructions
+
+## Purpose
+
+Maintain a small repository-native harness for safe agentic collaboration and deliberate codebase learning. Preserve the separation between:
+
+- repository-specific engineering rules;
+- general collaboration behavior in `agentic-flow/`;
+- optional learning behavior in `learning-flow/`;
+- temporary task state.
+
+## Working rules
+
+- Read `README.md`, `docs/DESIGN_NOTES.md`, and `CHANGELOG.md` before structural changes.
+- Keep minimal and full profiles behaviorally compatible where they share concepts.
+- Prefer a small common rule over duplicated profile-specific prose.
+- Do not add workflow ceremony without a demonstrated problem.
+- Treat installer update and preservation behavior as part of the public contract.
+- Update manifests, version markers, examples, and regression fixtures with framework changes.
+
+## External reference integration
+
+When asked to incorporate value from another repository, article source, or ZIP, follow `docs/references/REFERENCE_INTEGRATION.md`.
+
+The expected outcome is not a copy of the source harness. Extract the smallest generally useful patterns, preserve source-specific rules only in the reference review, and add `docs/references/REFERENCE_REVIEW_<SOURCE>.md` for provenance and historical context.
+
+## Communication
+
+Use friendly, direct, summary-first language. Say concretely what changed and why it matters, grouping substantial updates into a few descriptive bullets rather than a tool log or file inventory. Put secondary rationale, long examples, command matrices, and historical notes in `<details>` blocks when the Markdown renderer supports them. Never hide required warnings, decisions, or next actions inside a collapsed section.

CHANGELOG.md

@@ -0,0 +1,89 @@
+# Changelog
+
+## 0.5.3
+
+### Added
+
+- Descriptive handoff and commit-message shapes that connect each change to its reason or effect without forcing empty sections.
+- Dual licensing: MIT for software and CC BY 4.0 for original documentation, workflow text, templates, and evaluation content.
+
+### Changed
+
+- Substantial agent updates now favor a plain-language result and a few outcome-grouped bullets over dry labels, tool chronology, or file inventories.
+- Maintenance and reconstruction notes moved under `docs/`; reference integration guidance and provenance reviews moved under `docs/references/`.
+
+## 0.5.2
+
+### Added
+
+- Root maintenance instructions and `docs/references/REFERENCE_INTEGRATION.md` for reproducible value extraction from a GitHub repository, article source, or ZIP.
+- Installed `agentic-flow/REFERENCE_INTEGRATION.md` and external-reference handling in the `agentic-workflow` skill.
+- `docs/references/REFERENCE_REVIEW_LITT.md`, designating the exact `geoffreylitt/homepage` revision and source paths behind “Understanding is the new bottleneck.”
+- Optional full-profile A/B/C/D learner-context tailoring when experience materially changes useful scaffolding.
+
+### Changed
+
+- Communication defaults are friendlier, shorter, summary-first, and concept-first.
+- Human-facing Markdown now prefers collapsible sections for optional detail, evidence inventories, examples, and long command output.
+- Essential warnings, decisions, failures, and required actions must remain visible.
+- Pocok reference review was shortened and aligned with the repeatable reference-review format.
+- Root README and common agentic documentation were condensed.
+
+## 0.5.1
+
+### Added
+
+- Initial learning baseline coverage for the repository's actual agentic setup, including root and nested instructions, tool-specific files, custom skills, prompts, plans, sessions, status artifacts, and evidence ledgers.
+- A compact `Agentic collaboration setup` section in both profile map templates.
+- `agentic-flow/ROOT_INTEGRATION.md` with separate A/B/C/D choices for repositories with and without a root `AGENTS.md`.
+- A lean Pocok-informed root template containing reusable evidence and validation discipline without Pocok-specific package, commit, or release rules.
+- Idempotent managed pointer block for connecting existing root instructions to `agentic-flow/` and `learning-flow/`.
+- Installer root modes: `auto`, `integrate`, `initialize`, `preserve`, and `skip`.
+
+### Changed
+
+- `learning-bootstrap` now maps effective agentic instruction order before code and domain orientation.
+- Minimal orientation also maps agentic setup when the baseline has not yet been populated.
+- Managed template markers are treated as known evidence so agents research custom additions and integration rather than rereading the framework exhaustively.
+- `agentic-workflow` now handles later root integration, custom-harness mapping, conflict review, and learning-map updates.
+- The learning module explains the repository's effective setup, not merely the template's intended layer model.
+- Interactive installers ask how to handle existing or missing root instructions. Safe non-interactive defaults remain available.
+
+### Preserved
+
+- Existing root `AGENTS.md` content is never replaced wholesale.
+- `update` does not overwrite repository-authored maps, takeaways, settings, research, or custom skills.
+- Root integration and collaboration settings can be completed or revised later through the `agentic-workflow` skill.
+
+## 0.5.0
+
+### Added
+
+- Common `agentic-flow/` layer for collaboration behavior, separate from `learning-flow/`.
+- Minimal workflow: `Frame → Inspect → Decide → Act → Verify → Handoff`.
+- `agentic-workflow` skill for setup, configuration, explanation, and review of repository agentic content.
+- Four compact A/B/C/D configuration choices for autonomy, planning, validation, and learning or records.
+- Balanced defaults that allow routine work before configuration.
+- `LEARN.md` module explaining repository-native instructions, workflow settings, skills, learning support, and temporary task state.
+- Agentic routing and behavior regression fixtures.
+- Exact integration guidance for repositories that already have a root `AGENTS.md`.
+
+### Changed
+
+- Root pointer now loads `agentic-flow/` generally and `learning-flow/` only for learning-oriented support.
+- Minimal and full learning instructions defer planning, approval, validation depth, records, and handoff to the agentic layer.
+- Full-profile skills explicitly avoid competing with `agentic-workflow` as a second task procedure.
+- Installer manages common agentic files and skills independently from the selected learning profile.
+- `update` installs the new common layer into v0.4 repositories while preserving settings and repository-authored knowledge.
+- `replace` replaces both framework directories and their managed skills.
+
+### Simplified
+
+- No mandatory plan file, session record, one-step approval loop, one commit per step, or phase gate.
+- No configuration questionnaire for trivial work.
+- Temporary handoff is excluded from stable instruction files.
+- Source changes applied and executable verification completed are reported as separate facts.
+
+### Reference review
+
+The revision was informed by the current `legrab/pocok` agentic documentation on `main` at review commit `cdfb8bfaec5dcc74c62e5f6d5d401222c82dc45a`. It preserves Pocok's evidence discipline, current-truth rule, explicit boundaries, and handoff value while removing repository-specific and overly restrictive defaults.