diff --git a/CHANGELOG.md b/CHANGELOG.md index 6b6e7c1..7985087 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/MANIFEST.txt b/MANIFEST.txt index a04f396..7c5e000 100644 --- a/MANIFEST.txt +++ b/MANIFEST.txt @@ -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 diff --git a/README.md b/README.md index b168af9..13d92f0 100644 --- a/README.md +++ b/README.md @@ -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.*
Profiles, extensions, and update modes diff --git a/adoption/README.md b/adoption/README.md index 298ea21..e343536 100644 --- a/adoption/README.md +++ b/adoption/README.md @@ -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
its own agentic workflow?} + Q -->|Yes| A[Guided adoption
adoption/ADOPT.md] + Q -->|No| I[Complete installation
scripts/install.sh · install.ps1] + A --> S1[Integrate only the
layers you approve] + I --> S2[Install every
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. + +
+Directory boundaries - `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. + +
## Start adoption diff --git a/docs/DESIGN_NOTES.md b/docs/DESIGN_NOTES.md index ca4f838..5099ec9 100644 --- a/docs/DESIGN_NOTES.md +++ b/docs/DESIGN_NOTES.md @@ -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: diff --git a/sample/common/agentic-flow/.managed-files b/sample/common/agentic-flow/.managed-files index 161d0fe..e74f70c 100644 --- a/sample/common/agentic-flow/.managed-files +++ b/sample/common/agentic-flow/.managed-files @@ -1,6 +1,5 @@ .managed-files .managed-skills -.template-version README.md AGENTS.md WORKFLOW.md diff --git a/sample/common/agentic-flow/.template-version b/sample/common/agentic-flow/.template-version deleted file mode 100644 index 26aaba0..0000000 --- a/sample/common/agentic-flow/.template-version +++ /dev/null @@ -1 +0,0 @@ -1.2.0 diff --git a/sample/common/agentic-flow/ROOT_INTEGRATION.md b/sample/common/agentic-flow/ROOT_INTEGRATION.md index 100c486..3ef80bb 100644 --- a/sample/common/agentic-flow/ROOT_INTEGRATION.md +++ b/sample/common/agentic-flow/ROOT_INTEGRATION.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 -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. ``` diff --git a/sample/common/agentic-flow/WORKFLOW.md b/sample/common/agentic-flow/WORKFLOW.md index 65cab66..81e4043 100644 --- a/sample/common/agentic-flow/WORKFLOW.md +++ b/sample/common/agentic-flow/WORKFLOW.md @@ -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: diff --git a/sample/profiles/full/learning-flow/.managed-files b/sample/profiles/full/learning-flow/.managed-files index 8329141..2767dfc 100644 --- a/sample/profiles/full/learning-flow/.managed-files +++ b/sample/profiles/full/learning-flow/.managed-files @@ -1,6 +1,5 @@ .managed-files .managed-skills .template-profile -.template-version README.md AGENTS.md diff --git a/sample/profiles/full/learning-flow/.template-version b/sample/profiles/full/learning-flow/.template-version deleted file mode 100644 index 9084fa2..0000000 --- a/sample/profiles/full/learning-flow/.template-version +++ /dev/null @@ -1 +0,0 @@ -1.1.0 diff --git a/sample/profiles/full/learning-flow/AGENTS.md b/sample/profiles/full/learning-flow/AGENTS.md index 99d6dbe..46d9e23 100644 --- a/sample/profiles/full/learning-flow/AGENTS.md +++ b/sample/profiles/full/learning-flow/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. + +
+Check techniques and handling + +- 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. + +
## Persistent surfaces diff --git a/sample/profiles/full/learning-flow/README.md b/sample/profiles/full/learning-flow/README.md index 86e9eb1..b7fd2dc 100644 --- a/sample/profiles/full/learning-flow/README.md +++ b/sample/profiles/full/learning-flow/README.md @@ -8,6 +8,7 @@ flowchart TB T --> L["repository-learning
(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 ``` diff --git a/sample/profiles/minimal/learning-flow/.managed-files b/sample/profiles/minimal/learning-flow/.managed-files index 8329141..2767dfc 100644 --- a/sample/profiles/minimal/learning-flow/.managed-files +++ b/sample/profiles/minimal/learning-flow/.managed-files @@ -1,6 +1,5 @@ .managed-files .managed-skills .template-profile -.template-version README.md AGENTS.md diff --git a/sample/profiles/minimal/learning-flow/.template-version b/sample/profiles/minimal/learning-flow/.template-version deleted file mode 100644 index 3eefcb9..0000000 --- a/sample/profiles/minimal/learning-flow/.template-version +++ /dev/null @@ -1 +0,0 @@ -1.0.0 diff --git a/scripts/README.md b/scripts/README.md index b19fa65..ceab37c 100644 --- a/scripts/README.md +++ b/scripts/README.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) ``` diff --git a/skill-evals/README.md b/skill-evals/README.md index ae93bdc..0480e46 100644 --- a/skill-evals/README.md +++ b/skill-evals/README.md @@ -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.