Dev/bg/3 layer

MANIFEST.txt

@@ -2,10 +2,10 @@
 .gitignore	317
 AGENTS.md	3172
 CHANGELOG.md	13500
-docs/DESIGN_NOTES.md	22495
+docs/DESIGN_NOTES.md	23730
 docs/EDUCATION_MODEL.md	5452
 docs/INITIALIZE_LEARNING_FLOW.md	10880
-docs/README.md	2428
+docs/README.md	4185
 docs/references/REFERENCE_INTEGRATION.md	4551
 docs/references/REFERENCE_REVIEW_AWESOME_AGENT_SKILLS.md	2317
 docs/references/REFERENCE_REVIEW_BEST_OF_AGENT_HARNESSES.md	2540
@@ -14,35 +14,35 @@ docs/references/REFERENCE_REVIEW_LEARNING_FLOW_ADJUSTMENT.md	9505
 docs/references/REFERENCE_REVIEW_LITT.md	2069
 docs/references/REFERENCE_REVIEW_POCOK.md	2155
 LICENSE	2213
-README.md	10942
-sample/common/.agents/skills/agentic-workflow/SKILL.md	3653
+README.md	16282
+sample/common/.agents/skills/agentic-workflow/SKILL.md	4185
 sample/common/.agents/skills/learn-anything/agents/openai.yaml	246
-sample/common/.agents/skills/learn-anything/SKILL.md	3225
+sample/common/.agents/skills/learn-anything/SKILL.md	3362
 sample/common/.agents/skills/structured-change/knowledge/engineering/ai-collaboration.md	2533
 sample/common/.agents/skills/structured-change/knowledge/engineering/architecture.md	1386
 sample/common/.agents/skills/structured-change/knowledge/engineering/dependency-management.md	1300
 sample/common/.agents/skills/structured-change/knowledge/engineering/documentation.md	1334
 sample/common/.agents/skills/structured-change/knowledge/engineering/maintainability.md	1319
 sample/common/.agents/skills/structured-change/knowledge/engineering/modernization.md	1254
 sample/common/.agents/skills/structured-change/knowledge/engineering/testing.md	1287
-sample/common/.agents/skills/structured-change/SKILL.md	4136
+sample/common/.agents/skills/structured-change/SKILL.md	4283
 sample/common/.agents/skills/structured-change/templates/design.md	649
 sample/common/.agents/skills/structured-change/templates/exploration.md	368
 sample/common/agentic-flow/.managed-files	170
-sample/common/agentic-flow/.managed-skills	50
+sample/common/agentic-flow/.managed-skills	86
 sample/common/agentic-flow/.template-version	6
-sample/common/agentic-flow/AGENTS.md	5788
+sample/common/agentic-flow/AGENTS.md	8182
 sample/common/agentic-flow/CONFIGURE.md	4475
 sample/common/agentic-flow/DECISIONS.md	963
 sample/common/agentic-flow/EDUCATION.md	5232
 sample/common/agentic-flow/LEARN.md	1822
 sample/common/agentic-flow/LOCAL.md	3513
-sample/common/agentic-flow/README.md	1624
+sample/common/agentic-flow/README.md	2039
 sample/common/agentic-flow/REFERENCE_INTEGRATION.md	2183
 sample/common/agentic-flow/ROOT_INTEGRATION.md	3086
 sample/common/agentic-flow/SETTINGS.md	544
-sample/common/agentic-flow/WORKFLOW.md	4674
-sample/common/local/learning-history.md	986
+sample/common/agentic-flow/WORKFLOW.md	5020
+sample/common/local/learning-history.md	1528
 sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/audit-trails.md	1444
 sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/cfr-part-11-overview.md	2336
 sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/change-control.md	1447
@@ -59,7 +59,7 @@ sample/extensions/regulatory/.agents/skills/regulatory-knowledge/SKILL.md	3530
 sample/extensions/regulatory/learning-flow/.extension-managed-files	81
 sample/extensions/regulatory/learning-flow/.extension-managed-skills	21
 sample/extensions/regulatory/learning-flow/.extension-name	11
-sample/extensions/regulatory/learning-flow/REGULATORY.md	1719
+sample/extensions/regulatory/learning-flow/REGULATORY.md	1882
 sample/profiles/full/.agents/skills/analogous-feature/SKILL.md	1408
 sample/profiles/full/.agents/skills/challenge-debugging/SKILL.md	1426
 sample/profiles/full/.agents/skills/challenge-debugging/templates/challenge.md	428
@@ -87,7 +87,7 @@ sample/profiles/minimal/learning-flow/.managed-files	87
 sample/profiles/minimal/learning-flow/.managed-skills	20
 sample/profiles/minimal/learning-flow/.template-profile	8
 sample/profiles/minimal/learning-flow/.template-version	6
-sample/profiles/minimal/learning-flow/AGENTS.md	3064
+sample/profiles/minimal/learning-flow/AGENTS.md	3459
 sample/profiles/minimal/learning-flow/MAP.md	1229
 sample/profiles/minimal/learning-flow/README.md	1974
 sample/profiles/minimal/learning-flow/TAKEAWAYS.md	973
@@ -97,10 +97,16 @@ sample/root/AGENTS.pointer.md	296
 scripts/install.bat	1477
 scripts/install.ps1	35102
 scripts/install.sh	29472
-scripts/README.md	4502
+scripts/README.md	4900
 skill-evals/agentic-cases.yaml	7109
 skill-evals/conversation-cases.yaml	3653
 skill-evals/full-cases.yaml	4248
 skill-evals/minimal-cases.yaml	3208
-skill-evals/README.md	1352
+skill-evals/README.md	1667
 skill-evals/structured-change-cases.yaml	3735
+adoption/ADOPT.md	3941
+adoption/README.md	2057
+sample/common/.agents/skills/learning-closure/SKILL.md	3263
+sample/common/.agents/skills/learning-freshness/SKILL.md	1866
+skill-evals/learning-lifecycle-cases.yaml	1220
+skill-evals/adoption-cases.yaml	1337

README.md

@@ -19,10 +19,63 @@ flowchart LR
     K --> L
 ```
 
-## Start in two minutes
+> [!WARNING]
+> The regulatory extension is a reasoning and workflow aid, not a compliance determination or substitute for qualified regulatory/quality expertise.
+
+## What this repository is
+
+Codebase Learning Flow is both a working, literate example of repository-native agentic engineering and a reusable framework that can be installed into another repository.
+
+The repository is intentionally literate: its documentation, workflow instructions, skills, examples, and validation describe how the system is supposed to work while also serving as the system being developed. The installable part packages the reusable behavior so another repository can adopt the useful pieces without having to adopt this repository's complete workflow.
+
+The framework does not provide an agent runtime, sandbox, retry engine, or background worker. It configures a host coding agent through repository-local instructions, skills, learning surfaces, and optional risk lenses.
+
+## Three layers
+
+The framework has three explicit layers with different ownership and adoption boundaries:
+
+| Layer | Purpose | Adoption boundary |
+|---|---|---|
+| **Agentic Delivery** | Common collaboration policy, task routing, verification, and handoff | Most invasive. A repository may use it as the common agentic baseline. |
+| **Learning & Ownership** | Repository learning, general learning, private continuity, and durable knowledge | Independently adoptable into an existing agentic workflow. |
+| **Optional Risk Lenses** | Regulatory, safety, security, or other domain-specific reasoning | Selective and additive. Never a replacement for the active workflow. |
+
+The normal complete installation composes these layers, but they are not inseparable. In particular, a repository with an existing agentic workflow can adopt the learning or risk layers without replacing its own delivery model.
+
+```text
+Agentic Delivery
+      │
+      ├── may use ──► Learning & Ownership
+      │
+      └── may use ──► Optional Risk Lenses
+                         │
+                         └── elaborates the active workflow when relevant
+```
+
+This separation is deliberate. Adding a new learning or risk concern should not automatically create another global workflow layer or increase the amount of instruction every task must load.
+
+## Instruction budget and workflow sanity
+
+The framework treats agent context as a limited engineering resource. The common delivery layer is the baseline; learning and risk material are conditional branches. Ordinary work should select one primary task route, load only the narrow evidence it needs, reuse current findings, and stop when the evidence threshold is met. A skill must not become a second workflow merely because it is related to the task.
+
+The framework is intentionally tested against representative low-risk, learning, consequential, and regulated scenarios to guard against the main failure mode: **making a competent developer perform framework rituals instead of making them faster and more aware**. See [`docs/AGENTIC_WORKFLOW_SANITY.md`](docs/AGENTIC_WORKFLOW_SANITY.md) for the context-budget rules and sanity scenarios.
+
+## Installation
+
+### Preferred: packaged release
+
+For team and enterprise use, install a reviewed, versioned release rather than
+executing a mutable checkout from `main`. Release installation will be the
+preferred distribution path once packaged releases are published.
+
+Pin the exact release version used by the team and retain the version in the
+installation record.
+
+### Development checkout
 
 Run one installer from the repository that should receive the framework:
 
+
 ```powershell
 & ([scriptblock]::Create((irm https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/scripts/install.ps1)))
 ```
@@ -63,6 +116,33 @@ Remote piping executes the referenced revision. Pin a release tag or commit for
 
 </details>
 
+## Adoption situations
+
+| Situation | Recommended approach | Installation / adoption procedure |
+|---|---|---|
+| **A. No agentic flow** | Complete installation with `minimal` by default; add `full` or `regulatory` deliberately. | Prefer a pinned packaged release. Use checkout installers for development or experimentation. |
+| **B. Custom agentic flow per developer** | Preserve the existing delivery layer and selectively adopt learning/risk capabilities. | Check out this repository and run the guided adoption prompt from [`adoption/ADOPT.md`](adoption/ADOPT.md). |
+| **C. Lightweight agentic flow, no learning/regulatory concepts** | Keep the existing delivery workflow and add the Learning & Ownership layer plus relevant risk lenses. | Prefer guided adoption; use complete installation only when the repository explicitly wants to standardize its delivery layer. |
+
+Complete installation and guided adoption are intentionally different operations.
+Complete installation consumes the framework payload under `sample/`; guided
+adoption consumes the instructions under `adoption/` and integrates only the
+selected concepts into an existing setup.
+
+## Guided adoption for existing agentic setups
+
+Check out this repository and ask the host coding agent to read
+[`adoption/ADOPT.md`](adoption/ADOPT.md). The agent should inspect the existing
+repository workflow, ask about profile and extension choices, propose a
+minimal compatible integration, and wait for approval before consequential
+changes.
+
+The guided process considers `structured-change`, `learn-anything`,
+`learning-closure`, `learning-freshness`, the Learning & Ownership model,
+private `.local/` continuity, and relevant risk extensions. It does **not**
+automatically install the common `agentic-flow` or rewrite the root
+`AGENTS.md`.
+
 ## Choose the route
 
 | You want to... | Route | What stays primary |

adoption/ADOPT.md

@@ -0,0 +1,129 @@
+# Guided adoption protocol
+
+Use this document only for **guided adoption into an existing custom agentic
+setup**. It is deliberately separate from the complete installation payload.
+
+## 1. Inspect before proposing
+
+Inspect only enough of the target repository to understand:
+
+- root and nested agent instructions;
+- existing skills and task routing;
+- existing learning or knowledge surfaces;
+- local/session continuity;
+- current validation and handoff behavior;
+- repository-specific ownership boundaries.
+
+Do not load the entire Codebase Learning Flow repository into active context.
+
+Summarize the existing setup before proposing changes.
+
+## 2. Explain the three layers
+
+Use these adoption boundaries:
+
+| Layer | Meaning | Default adoption behavior |
+|---|---|---|
+| Agentic Delivery | existing task execution, collaboration, verification, and handoff | Preserve the host repository's existing layer unless the user explicitly wants to replace or augment it |
+| Learning & Ownership | learning routes, private continuity, durable knowledge, learning closure, freshness checks | Candidate for independent adoption |
+| Optional Risk Lenses | regulatory or other selective risk reasoning | Candidate only when relevant |
+
+The purpose is to add capabilities without accidentally creating a second global
+workflow.
+
+## 3. Ask the user about concrete choices
+
+Ask only questions whose answers affect the proposed changes.
+
+At minimum consider:
+
+1. Which profile or learning depth is wanted: `minimal`, `full`, or a custom subset?
+2. Should `structured-change` be adopted?
+3. Should `learn-anything` be adopted?
+4. Should learning closure be part of substantial/PR handoff?
+5. Should learning freshness checks be available?
+6. Should private `.local/` continuity be adopted?
+7. Is a risk extension such as `regulatory` relevant?
+
+Do not ask all questions mechanically if repository evidence already answers one.
+
+The user may choose a custom subset.
+
+## 4. Build an adoption plan
+
+For every selected component, identify:
+
+- existing instruction or skill it complements;
+- potential conflict;
+- target location;
+- whether the change is additive, replacement, or adaptation;
+- what will remain untouched.
+
+Prefer adapting the concept to the repository's existing vocabulary over
+copying files wholesale.
+
+## 5. Approval boundary
+
+Before modifying consequential repository instructions, present a compact plan:
+
+```text
+Adopting:
+- <component> → <target>
+
+Preserving:
+- <existing workflow/instruction>
+
+Conflict:
+- <conflict or none>
+
+Not adopting:
+- <component> → <reason>
+
+Root AGENTS.md:
+- unchanged / specific approved edit
+
+Proceed?
+```
+
+An explicit user instruction already resolving the choice counts as approval.
+
+## 6. Integrate selectively
+
+When implementing:
+
+- preserve existing repository-authored content;
+- add only selected capabilities;
+- adapt references to the host repository;
+- keep one primary task procedure;
+- avoid creating a second competing workflow;
+- do not install the complete `agentic-flow` unless the user explicitly changes
+  the adoption request into a complete installation.
+
+If the repository already has a root `AGENTS.md`, do not rewrite it automatically.
+If a pointer or reference would improve discoverability, propose the smallest
+change and obtain approval.
+
+## 7. Verify the resulting workflow
+
+After integration, test at least:
+
+- one trivial task;
+- one normal engineering task;
+- one meaningful learning task;
+- one consequential change if `structured-change` was adopted.
+
+Check that the selected additions activate only when relevant and do not turn
+ordinary work into framework ceremony.
+
+## 8. Finish with an adoption summary
+
+Report:
+
+- selected components;
+- files/instructions changed;
+- preserved existing behavior;
+- conflicts resolved;
+- verification performed;
+- anything intentionally left for later.
+
+The result is a host-specific adaptation, not a disguised complete installation.

adoption/README.md

@@ -0,0 +1,57 @@
+# Guided adoption
+
+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:
+
+- `sample/` contains the framework payload used by complete installation.
+- `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
+
+Give the repository-aware coding agent this instruction:
+
+> Read `adoption/ADOPT.md` in the Codebase Learning Flow repository. Inspect my
+> existing repository-native agentic setup before changing anything. Treat this
+> as guided adoption, not complete installation. Ask me about the meaningful
+> choices, recommend compatible components, and integrate only what I approve.
+> Preserve existing instructions and workflows unless I explicitly approve a
+> change.
+
+The agent should then follow `ADOPT.md`.
+
+## What adoption can add
+
+The primary candidates are:
+
+- `structured-change`;
+- `learn-anything`;
+- `learning-closure`;
+- `learning-freshness`;
+- the Learning & Ownership model;
+- private `.local/` continuity;
+- `regulatory-knowledge` where relevant.
+
+The common Agentic Delivery layer is intentionally not a default adoption target.
+An existing repository may already have a better delivery workflow for its users.
+
+## What adoption must preserve
+
+Adoption must not:
+
+- replace the existing agent runtime;
+- silently replace the existing agentic workflow;
+- automatically install `agentic-flow`;
+- automatically rewrite the root `AGENTS.md`;
+- overwrite repository-authored skills or documentation;
+- create unnecessary framework ceremony.
+
+If a proposed integration conflicts with an existing instruction, surface the
+conflict and ask the user to choose rather than resolving it by silently giving
+one instruction higher priority.