legrab · legrab · Aug 11, 2026 · Aug 11, 2026 · Aug 11, 2026 · Aug 11, 2026
@@ -1,6 +1,6 @@
 # Changelog
 
-## Unreleased
+## 1.3.0
 
 Architectural simplification of the `full` profile: reduced meta-ceremony while preserving every behavior the framework depends on (repository authority, selective learning, hypothesis-first proposals, consequential-change reasoning, private continuity, optional regulatory guidance).
 
@@ -31,6 +31,26 @@ Architectural simplification of the `full` profile: reduced meta-ceremony while
 - Removed redundant full-profile bootstrap, playbook, and understanding-check documents whose rules are now owned by the common workflow or selected skill.
 - Added regression coverage for shared skill ownership and profile routing.
 
+### Fixed
+
+- `full/learning-flow/AGENTS.md`'s "Understanding checks" heading and check-techniques collapsible, referenced by `full/learning-flow/README.md` but missing after the profile rewrite.
+- `full/learning-flow/AGENTS.md`'s fallback-routing table, which named `change-explainer` and `ticket-learning-path` as `repository-learning` branches; they aren't — the table now says so.
+- `agentic-flow/WORKFLOW.md`'s reference to "the commit shape in `AGENTS.md`", which pointed at a section that doesn't exist anywhere in the framework; commit format is repository-native, not framework-defined.
+- Packaged-release install examples in `README.md` and `scripts/README.md`, still pinned to the `v1.1.0` tag.
+- `agentic-flow/ROOT_INTEGRATION.md`'s documented "Managed pointer block" example, which no longer matched the actual `sample/root/AGENTS.pointer.md` content it was describing.
+- `docs/DESIGN_NOTES.md`'s "v1.3 consolidation" entry claimed three maintenance boundaries but listed two; added the missing third (the understanding-check rule's single canonical location).
+
+### Removed
+
+- `.template-version` marker files from `agentic-flow/`, `full/learning-flow/`, and `minimal/learning-flow/`. Nothing read them and their values had drifted with no defined meaning. See `docs/DESIGN_NOTES.md` for the plausible future use and what would need to exist before reintroducing it.
+
+### Polish
+
+- Added a decision flowchart to `adoption/README.md` for guided adoption vs. complete installation, and moved directory-boundary detail into a collapsible section.
+- Added the missing ticket-learning-path to repository-learning handoff edge in `full/learning-flow/README.md`'s routing diagram.
+- Folded `skill-evals/README.md`'s bolted-on "Additional lifecycle and adoption cases" section into the main fixture list.
+- Minor wording tightening in `README.md`'s development-checkout note.
+
 
 ## 1.1.0
 

@@ -1,14 +1,14 @@
 .gitattributes	40
 .gitignore	324
 AGENTS.md	2995
-CHANGELOG.md	24788
+CHANGELOG.md	26666
 LICENSE	2213
-README.md	8952
+README.md	9023
 adoption/ADOPT.md	4177
-adoption/README.md	2057
+adoption/README.md	2445
 docs/AGENTIC_WORKFLOW_SANITY.md	9802
 docs/ARCHITECTURE.md	7131
-docs/DESIGN_NOTES.md	36475
+docs/DESIGN_NOTES.md	37828
 docs/EDUCATION_MODEL.md	5452
 docs/INITIALIZE_LEARNING_FLOW.md	10880
 docs/README.md	4016
@@ -37,9 +37,8 @@ sample/common/.agents/skills/structured-change/knowledge/engineering/testing.md
 sample/common/.agents/skills/structured-change/templates/design.md	649
 sample/common/.agents/skills/structured-change/templates/exploration.md	368
 sample/common/.agents/skills/structured-change/templates/structure.md	243
-sample/common/agentic-flow/.managed-files	170
+sample/common/agentic-flow/.managed-files	152
 sample/common/agentic-flow/.managed-skills	106
-sample/common/agentic-flow/.template-version	6
 sample/common/agentic-flow/AGENTS.md	5995
 sample/common/agentic-flow/CONFIGURE.md	4475
 sample/common/agentic-flow/DECISIONS.md	963
@@ -48,9 +47,9 @@ sample/common/agentic-flow/LEARN.md	1822
 sample/common/agentic-flow/LOCAL.md	4179
 sample/common/agentic-flow/README.md	2897
 sample/common/agentic-flow/REFERENCE_INTEGRATION.md	2183
-sample/common/agentic-flow/ROOT_INTEGRATION.md	3086
+sample/common/agentic-flow/ROOT_INTEGRATION.md	3392
 sample/common/agentic-flow/SETTINGS.md	544
-sample/common/agentic-flow/WORKFLOW.md	6059
+sample/common/agentic-flow/WORKFLOW.md	6086
 sample/common/local/learning-history.md	1528
 sample/extensions/regulatory/.agents/skills/regulatory-knowledge/SKILL.md	3530
 sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/audit-trails.md	1444
@@ -74,19 +73,17 @@ sample/profiles/full/.agents/skills/change-explainer/templates/change-explainer.
 sample/profiles/full/.agents/skills/learning-bootstrap/SKILL.md	1491
 sample/profiles/full/.agents/skills/ticket-learning-path/SKILL.md	1513
 sample/profiles/full/.agents/skills/ticket-learning-path/templates/ticket-learning-path.md	405
-sample/profiles/full/learning-flow/.managed-files	87
+sample/profiles/full/learning-flow/.managed-files	69
 sample/profiles/full/learning-flow/.managed-skills	57
 sample/profiles/full/learning-flow/.template-profile	5
-sample/profiles/full/learning-flow/.template-version	6
-sample/profiles/full/learning-flow/AGENTS.md	2580
+sample/profiles/full/learning-flow/AGENTS.md	3198
 sample/profiles/full/learning-flow/MAP.md	1464
-sample/profiles/full/learning-flow/README.md	2345
+sample/profiles/full/learning-flow/README.md	2383
 sample/profiles/full/learning-flow/REPOSITORIES.md	439
 sample/profiles/full/learning-flow/TAKEAWAYS.md	970
-sample/profiles/minimal/learning-flow/.managed-files	87
+sample/profiles/minimal/learning-flow/.managed-files	69
 sample/profiles/minimal/learning-flow/.managed-skills	0
 sample/profiles/minimal/learning-flow/.template-profile	8
-sample/profiles/minimal/learning-flow/.template-version	6
 sample/profiles/minimal/learning-flow/AGENTS.md	1362
 sample/profiles/minimal/learning-flow/MAP.md	1229
 sample/profiles/minimal/learning-flow/README.md	1974
@@ -97,7 +94,7 @@ scripts/README.md	6771
 scripts/install.bat	1477
 scripts/install.ps1	40477
 scripts/install.sh	34980
-skill-evals/README.md	1667
+skill-evals/README.md	1689
 skill-evals/adoption-cases.yaml	1337
 skill-evals/agentic-cases.yaml	8895
 skill-evals/conversation-cases.yaml	3653

@@ -65,11 +65,11 @@ For team or enterprise use, install a reviewed, versioned release. Substitute th
 
 ```sh
 curl -fsSL https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/scripts/install.sh -o install.sh
-sh install.sh --release v1.1.0 --profile minimal
+sh install.sh --release v1.3.0 --profile minimal
 ```
 
 ```powershell
-& ([scriptblock]::Create((irm https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/scripts/install.ps1))) -Release v1.1.0 -Profile Minimal
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/scripts/install.ps1))) -Release v1.3.0 -Profile Minimal
 ```
 
 The installer verifies the release checksum before extraction and reports the resolved `Version:` and `Source:`.
@@ -84,7 +84,7 @@ curl -fsSL https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/
 & ([scriptblock]::Create((irm https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/scripts/install.ps1)))
 ```
 
-*For local development, use the installer scripts directly.*
+*Contributing to the framework itself? Run `scripts/install.sh` from your local checkout instead of curling the remote copy above.*
 
 <details>
 <summary>Profiles, extensions, and update modes</summary>

@@ -4,14 +4,26 @@ This directory is **not part of complete installation**. It is the repository's
 guided adoption surface for repositories that already have their own agentic
 workflow.
 
-The distinction is structural:
+```mermaid
+flowchart LR
+    Q{Repository already has<br/>its own agentic workflow?}
+    Q -->|Yes| A[Guided adoption<br/>adoption/ADOPT.md]
+    Q -->|No| I[Complete installation<br/>scripts/install.sh · install.ps1]
+    A --> S1[Integrate only the<br/>layers you approve]
+    I --> S2[Install every<br/>selected layer]
+```
+
+> [!IMPORTANT]
+> `adoption/` must never cause the common `agentic-flow` to be installed automatically, or the target repository's root `AGENTS.md` to be rewritten without approval.
+
+<details>
+<summary>Directory boundaries</summary>
 
 - `sample/` contains the framework payload used by complete installation.
-- `adoption/` contains guidance for adapting selected framework concepts into
-  an existing setup.
+- `adoption/` contains guidance for adapting selected framework concepts into an existing setup.
 - `scripts/` contains installers for complete installation.
-- `adoption/` must not cause the common `agentic-flow` to be installed or the
-  target repository's root `AGENTS.md` to be rewritten automatically.
+
+</details>
 
 ## Start adoption
 

@@ -10,9 +10,16 @@ The 1.3 cleanup makes three small maintenance boundaries explicit:
 
 1. `repository-learning` has one common skill owner. Minimal and full profiles differ in routing and persistence surfaces, not by carrying duplicate implementations.
 2. Profile `learning-flow/AGENTS.md` files are routing contracts. Common collaboration, context economy, evidence, understanding-check, and handoff policy remains owned by the common agentic/education layer.
+3. The understanding-check rule and its elaboration have one canonical location, the "Understanding checks" heading in `full/learning-flow/AGENTS.md`. `full/learning-flow/README.md` points there instead of restating it.
 
 The goal is lower effective context, less opportunity for agentic drift, and faster human navigation without introducing another framework layer.
 
+### Removed: `.template-version` marker files
+
+`agentic-flow/.template-version`, `full/learning-flow/.template-version`, and `minimal/learning-flow/.template-version` were removed. Nothing read them: no installer, no CI check, no documentation. Their per-component values (1.0.0/1.1.0/1.2.0) had drifted from each other and from the package's own release tag with no defined meaning to drift from. An unread, undocumented file that looks like it should mean something is worse than no file.
+
+The plausible future use is a per-component compatibility matrix for `update` mode, so the installer could warn before merging a template that changed shape incompatibly with what a target repository has customized, rather than relying on `merge`/`fail` conflict detection alone. That is a real gap only once template files diverge enough for a naive merge to be actively wrong, which has not happened yet. If it becomes real, it should be reintroduced with the reader documented (`install.sh`/`install.ps1`), the compatibility rule stated here, and a CI check that fails when the value goes stale, not shipped ahead of any of those three.
+
 ## Current three-layer architecture
 
 The current architecture consolidates the earlier ownership distinctions into three user-facing framework layers:

@@ -1,6 +1,5 @@
 .managed-files
 .managed-skills
-.template-version
 README.md
 AGENTS.md
 WORKFLOW.md

@@ -45,15 +45,18 @@ It does not copy Pocok-specific package, .NET, commit, session, or release polic
 
 ## Managed pointer block
 
-The installer and the `agentic-workflow` skill may add this idempotent block:
+The installer and the `agentic-workflow` skill may add this idempotent block (verbatim source: `sample/root/AGENTS.pointer.md`):
 
 ```md
 <!-- codebase-learning-flow:start -->
-For collaboration behavior, planning, validation, and handoff, follow
-`agentic-flow/AGENTS.md`.
+For collaboration behavior, planning, validation, and handoff, follow `agentic-flow/AGENTS.md`.
 
-For repository learning, onboarding, explanation, and durable understanding,
-follow `learning-flow/AGENTS.md` when relevant.
+**Learning is automatic:** `help me understand`, `explain`, `teach me`, and similar general
+questions use `learn-anything`; questions about the current repository use repository
+learning. Build a compact model, use a useful example when helpful, and check back for
+understanding when it adds value.
+
+Do not turn mechanical work into a lesson. Keep the user's actual task primary.
 <!-- codebase-learning-flow:end -->
 ```
 

@@ -90,7 +90,7 @@ For pull-request or substantial change completion, learning closure is a normal
 
 ## Traceability
 
-For most work, the commit shape in `AGENTS.md` is enough. For a consequential or regulated change, and only then, add a `Traceability` section to the commit body:
+For most work, follow the repository's own commit conventions and add nothing extra. For a consequential or regulated change, and only then, add a `Traceability` section to the commit body:
 
 ```text
 Traceability:

@@ -1,6 +1,5 @@
 .managed-files
 .managed-skills
 .template-profile
-.template-version
 README.md
 AGENTS.md
@@ -17,7 +17,7 @@ Do not load all skills. Do not use `agentic-workflow` as a second engineering pr
 
 ## Fallback routing
 
-For an agent without task-skill support, use the matching branch in `repository-learning`:
+For an agent without task-skill support, use the matching flow below inline. The first four rows are `repository-learning`'s own branches; the last two are compact fallbacks for `change-explainer` and `ticket-learning-path`.
 
 | Task | Learning route |
 |---|---|
@@ -28,7 +28,20 @@ For an agent without task-skill support, use the matching branch in `repository-
 | Change explanation | intended outcome → governing rules → generated/human decisions → conceptual walkthrough → risks and proof |
 | Ticket path | actor/outcome → ownership → build judgment → missing context → shortest route → handoff or stop |
 
-The common Agentic Delivery and Education instructions own the learning loop, context economy, ownership lenses, understanding checks, evidence language, and completion behavior. Do not duplicate those rules here.
+The common Agentic Delivery and Education instructions own the learning loop, context economy, ownership lenses, evidence language, and completion behavior. Do not duplicate those rules here.
+
+## Understanding checks
+
+Use at most one consequential understanding check per task. A declined check never blocks engineering.
+
+<details>
+<summary>Check techniques and handling</summary>
+
+- Prefer a prediction, trace, or explain-back over a recall question.
+- Skip the check entirely when the task is short, mechanical, or evidence already demonstrates understanding.
+- If the answer is wrong or shaky, correct the model directly and continue. Do not repeat the check or turn it into a quiz.
+
+</details>
 
 ## Persistent surfaces
 

@@ -8,6 +8,7 @@ flowchart TB
     T --> L["repository-learning<br/>(orientation, bug, feature, or refactor)"]
     T --> X[Change explanation]
     T --> P[Ticket learning path]
+    P -. implementation handoff .-> L
     L --> K[Durable map or takeaway only when justified]
     X --> K
 ```

@@ -1,6 +1,5 @@
 .managed-files
 .managed-skills
 .template-profile
-.template-version
 README.md
 AGENTS.md
@@ -32,11 +32,11 @@ flowchart LR
 ```
 
 ```text
-sh install.sh --release v1.1.0 --profile minimal
+sh install.sh --release v1.3.0 --profile minimal
 ```
 
 ```powershell
-.\install.ps1 -Release v1.1.0 -Profile Minimal
+.\install.ps1 -Release v1.3.0 -Profile Minimal
 ```
 
 `--release`/`-Release` downloads the packaged artifact and `checksums.txt`
@@ -54,7 +54,7 @@ Every install prints which trust boundary it used:
 
 ```text
 Codebase Learning Flow
-Version: v1.1.0
+Version: v1.3.0
 Source: packaged release (checksum verified)
 ```
 

@@ -14,16 +14,12 @@ flowchart LR
 - `minimal-cases.yaml` checks the compact repository skill, resilience and ownership lenses, and persistence restraint.
 - `full-cases.yaml` checks focused skill routing, responsible machine-generated work review, domain depth, and anti-ceremony behavior.
 - `structured-change-cases.yaml` checks when Explore/Design/Approve is (and is not) warranted, decision-record promotion discipline, traceability proportionality, and the regulatory extension's additive, non-reproducing behavior.
+- `learning-lifecycle-cases.yaml` checks learning placement and periodic freshness review.
+- `adoption-cases.yaml` checks guided integration into a repository with an existing agentic setup.
+
+Lifecycle and adoption cases guard the same thing as the rest of the suite: no unnecessary context expansion, no unnecessary framework ceremony.
 
 Review these fixtures when changing skill descriptions, routing, profiles, extensions, educational principles, baseline research, local continuity, understanding checks, or persistence rules.
 
 > [!NOTE]
 > Expected phrases describe behavioral evidence, not exact generated wording.
-
-
-## Additional lifecycle and adoption cases
-
-`learning-lifecycle-cases.yaml` covers learning placement and freshness checks.
-`adoption-cases.yaml` covers guided integration into repositories with an
-existing agentic setup. Both are intended to protect against unnecessary
-context expansion and framework ceremony.