legrab · legrab · Aug 25, 2026 · Aug 25, 2026
@@ -54,3 +54,37 @@ jobs:
  if (-not (Test-Path "$root/learning-flow")) {
  throw "Installer did not create the learning-flow component."
  }
+ - name: Run global and linked scope smoke test
+ shell: pwsh
+ run: |
+ $globalRoot = Join-Path $env:RUNNER_TEMP "learning-flow-global"
+ $linked = Join-Path $env:RUNNER_TEMP "learning-flow-linked"
+ New-Item -ItemType Directory -Force -Path $globalRoot, $linked | Out-Null
+ $env:CODEBASE_LEARNING_FLOW_HOME = $globalRoot
+ & "$PWD/scripts/install.ps1" `
+ -Scope Global `
+ -Repository $env:GITHUB_REPOSITORY `
+ -Ref $env:GITHUB_SHA `
+ -Profile full `
+ -Mode fail
+ if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+ & "$PWD/scripts/install.ps1" `
+ -Target $linked `
+ -Scope Linked `
+ -Repository $env:GITHUB_REPOSITORY `
+ -Ref $env:GITHUB_SHA `
+ -Mode fail `
+ -SkipRootAgents
+ if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+ if (-not (Test-Path "$globalRoot/skills/repository-learning/SKILL.md")) {
+ throw "Global scope did not install managed skills."
+ }
+ if (Test-Path "$globalRoot/learning-flow/MAP.md") {
+ throw "Repository-authored MAP.md reached the global root."
+ }
+ if (-not (Test-Path "$linked/learning-flow/MAP.md")) {
+ throw "Linked scope did not install repository learning state."
+ }
+ if (Test-Path "$linked/agentic-flow/AGENTS.md") {
+ throw "Framework instructions were duplicated into the linked repository."
+ }
@@ -1,5 +1,36 @@
 # Changelog
 
+## 1.4.0
+
+Install scopes: the framework can now be installed once into `%USERPROFILE%\.agents\` (`~/.agents/`) and shared by every repository, while each repository keeps its own learning state locally. Repository-scoped installation is unchanged and remains the default.
+
+### Added
+
+- `--scope repository|global|linked` / `-Scope Repository|Global|Linked` on both installers. `global` installs framework-owned instructions and managed skills into `$HOME/.agents` (skills at `<root>/skills/`, where host agents already look) and writes no repository state — no `.local/`, no `.gitignore` entry, no home-directory `AGENTS.md`. `linked` installs only a repository's own learning state and reads everything else from the global installation.
+- `.repository-files` manifests in `sample/common/agentic-flow/` and both profiles' `learning-flow/`, naming the repository-authored seeds (`SETTINGS.md`, `DECISIONS.md`, `MAP.md`, `TAKEAWAYS.md`, and `REPOSITORIES.md` in the full profile). The framework-owned half was already declared in `.managed-files`; this makes the other half explicit instead of implicit in what `update` happens not to overwrite.
+- "Framework root" section in `agentic-flow/AGENTS.md`: the single canonical rule that `agentic-flow/` and `learning-flow/` resolve at the repository root first and at `~/.agents/` second, that a repository copy always wins, that the two roots are never merged, and that repository state is never read from the global root.
+- `learning-flow/.install-scope` marker recording the scope and framework version of each installation, plus the global version a linked repository was linked against. The installer compares them and warns on drift. This reintroduces a version marker under the three conditions `docs/DESIGN_NOTES.md` set in 1.3 when it removed `.template-version`: a documented reader, a stated compatibility rule, and a CI check.
+- Install-scope classification check in `scripts/ci-validate.py`: every packaged file in a component must appear in exactly one of its managed/repository manifests, so a new file cannot ship without a declared install scope.
+- Global and linked scenarios in `scripts/ci-install-test.sh`, `scripts/ci-release-test.sh`, and the PowerShell CI job, including assertions that neither root holds the other's content and that the two scope markers agree on the version.
+- `CODEBASE_LEARNING_FLOW_HOME` environment override for the global root.
+- Two routing cases in `skill-evals/agentic-cases.yaml` covering framework-root resolution and the rule that repository knowledge is never written to the global root.
+
+### Changed
+
+- Scope conversion is supported in both directions. `--scope linked --mode update` removes a repository's framework copies through their own manifests and leaves authored state in place; `--scope repository --mode update` restores them at the profile and extension the global installation was providing.
+- The root pointer block and lean root template now state the framework-root resolution rule, so one pointer stays correct whether the framework files are local, global, or later moved between the two.
+- `scripts/ci-validate.py` now validates `.extension-managed-files` and `.extension-managed-skills` the same way it already validated their non-extension counterparts.
+- Both installers report the resolved scope and root in their closing summary, and warn when a repository-scoped install would make the host agent discover every managed skill twice.
+- `agentic-workflow`'s discovery step now detects `learning-flow/.install-scope` and reports which root the framework files resolve from; `agentic-flow/LEARN.md`'s setup explanation names that root too, so "explain my agentic setup" stays accurate in a linked repository.
+- `learning-closure` states that every destination it recommends belongs to the repository being worked on, closing the one place a skill could write repository knowledge to a global root.
+- The regulatory extension is now detected by skill name rather than by the literal path `.agents/skills/regulatory-knowledge/`, which resolves differently under a global installation and would have made the extension look absent in a linked repository.
+
+### Fixed
+
+- `agentic-flow/ROOT_INTEGRATION.md`'s documented pointer-block example, which had again fallen behind `sample/root/AGENTS.pointer.md`.
+- `docs/EXAMPLE_WALKTHROUGH.md` was missing from `MANIFEST.txt`, so released packages shipped a `docs/README.md` whose link to it was broken.
+
+
 ## 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).

@@ -1,32 +1,33 @@
 .gitattributes	40
 .gitignore	324
 AGENTS.md	2995
-CHANGELOG.md	26666
+CHANGELOG.md	31134
 LICENSE	2213
-README.md	9023
+README.md	12031
 adoption/ADOPT.md	4177
 adoption/README.md	2445
-docs/AGENTIC_WORKFLOW_SANITY.md	9802
-docs/ARCHITECTURE.md	7131
-docs/DESIGN_NOTES.md	37828
+docs/AGENTIC_WORKFLOW_SANITY.md	10021
+docs/ARCHITECTURE.md	8577
+docs/DESIGN_NOTES.md	45480
+docs/EXAMPLE_WALKTHROUGH.md	3614
 docs/EDUCATION_MODEL.md	5452
-docs/INITIALIZE_LEARNING_FLOW.md	10880
-docs/README.md	4016
+docs/INITIALIZE_LEARNING_FLOW.md	12199
+docs/README.md	4257
 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
 docs/references/REFERENCE_REVIEW_GOOSE.md	2486
 docs/references/REFERENCE_REVIEW_LEARNING_FLOW_ADJUSTMENT.md	9505
 docs/references/REFERENCE_REVIEW_LITT.md	2069
 docs/references/REFERENCE_REVIEW_POCOK.md	2155
-sample/README.md	3065
-sample/common/.agents/skills/agentic-workflow/SKILL.md	2686
-sample/common/.agents/skills/learn-anything/SKILL.md	1756
+sample/README.md	3382
+sample/common/.agents/skills/agentic-workflow/SKILL.md	2828
+sample/common/.agents/skills/learn-anything/SKILL.md	1793
 sample/common/.agents/skills/learn-anything/agents/openai.yaml	246
-sample/common/.agents/skills/learning-closure/SKILL.md	3605
+sample/common/.agents/skills/learning-closure/SKILL.md	3709
 sample/common/.agents/skills/learning-freshness/SKILL.md	1908
-sample/common/.agents/skills/repository-learning/SKILL.md	4904
-sample/common/.agents/skills/structured-change/SKILL.md	3059
+sample/common/.agents/skills/repository-learning/SKILL.md	4941
+sample/common/.agents/skills/structured-change/SKILL.md	3096
 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
@@ -37,19 +38,20 @@ 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	152
+sample/common/agentic-flow/.managed-files	170
 sample/common/agentic-flow/.managed-skills	106
-sample/common/agentic-flow/AGENTS.md	5995
-sample/common/agentic-flow/CONFIGURE.md	4475
+sample/common/agentic-flow/.repository-files	25
+sample/common/agentic-flow/AGENTS.md	6825
+sample/common/agentic-flow/CONFIGURE.md	4469
 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	4179
+sample/common/agentic-flow/LEARN.md	1910
+sample/common/agentic-flow/LOCAL.md	4366
 sample/common/agentic-flow/README.md	2897
 sample/common/agentic-flow/REFERENCE_INTEGRATION.md	2183
-sample/common/agentic-flow/ROOT_INTEGRATION.md	3392
+sample/common/agentic-flow/ROOT_INTEGRATION.md	3803
 sample/common/agentic-flow/SETTINGS.md	544
-sample/common/agentic-flow/WORKFLOW.md	6086
+sample/common/agentic-flow/WORKFLOW.md	6080
 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
@@ -67,36 +69,38 @@ sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regul
 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	1882
-sample/profiles/full/.agents/skills/change-explainer/SKILL.md	1308
+sample/extensions/regulatory/learning-flow/REGULATORY.md	1827
+sample/profiles/full/.agents/skills/change-explainer/SKILL.md	1345
 sample/profiles/full/.agents/skills/change-explainer/templates/change-explainer.md	353
-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/learning-bootstrap/SKILL.md	1528
+sample/profiles/full/.agents/skills/ticket-learning-path/SKILL.md	1550
 sample/profiles/full/.agents/skills/ticket-learning-path/templates/ticket-learning-path.md	405
-sample/profiles/full/learning-flow/.managed-files	69
+sample/profiles/full/learning-flow/.managed-files	87
 sample/profiles/full/learning-flow/.managed-skills	57
+sample/profiles/full/learning-flow/.repository-files	36
 sample/profiles/full/learning-flow/.template-profile	5
-sample/profiles/full/learning-flow/AGENTS.md	3198
+sample/profiles/full/learning-flow/AGENTS.md	3360
 sample/profiles/full/learning-flow/MAP.md	1464
 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	69
+sample/profiles/minimal/learning-flow/.managed-files	87
 sample/profiles/minimal/learning-flow/.managed-skills	0
+sample/profiles/minimal/learning-flow/.repository-files	20
 sample/profiles/minimal/learning-flow/.template-profile	8
-sample/profiles/minimal/learning-flow/AGENTS.md	1362
+sample/profiles/minimal/learning-flow/AGENTS.md	1525
 sample/profiles/minimal/learning-flow/MAP.md	1229
 sample/profiles/minimal/learning-flow/README.md	1974
 sample/profiles/minimal/learning-flow/TAKEAWAYS.md	973
-sample/root/AGENTS.md	2102
-sample/root/AGENTS.pointer.md	551
-scripts/README.md	6771
+sample/root/AGENTS.md	2263
+sample/root/AGENTS.pointer.md	712
+scripts/README.md	10227
 scripts/install.bat	1477
-scripts/install.ps1	40477
-scripts/install.sh	34980
+scripts/install.ps1	55583
+scripts/install.sh	47145
 skill-evals/README.md	1689
 skill-evals/adoption-cases.yaml	1337
-skill-evals/agentic-cases.yaml	8895
+skill-evals/agentic-cases.yaml	9830
 skill-evals/conversation-cases.yaml	3653
 skill-evals/full-cases.yaml	5001
 skill-evals/minimal-cases.yaml	3913

@@ -86,6 +86,39 @@ curl -fsSL https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/
 
 *Contributing to the framework itself? Run `scripts/install.sh` from your local checkout instead of curling the remote copy above.*
 
+### One installation for every repository
+
+By default the framework installs into a single repository. `--scope global` instead installs the framework-owned instructions and skills once, into `%USERPROFILE%\.agents\` (`~/.agents/` elsewhere), where every repository picks them up:
+
+```powershell
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/scripts/install.ps1))) -Scope Global -Profile Full
+```
+
+```sh
+sh install.sh --scope global --profile full
+```
+
+That alone is enough to work in any repository. What it deliberately does not do is create repository state: a global installation writes no `.local/`, no `.gitignore` entry, and no `AGENTS.md` in your home directory.
+
+When a repository should keep its own durable learning — a map of the system, verified takeaways, its own collaboration settings and decision record — run `--scope linked` inside it:
+
+```sh
+sh install.sh --scope linked
+```
+
+The repository then holds only what it authors; the instructions and skills stay global and shared.
+
+| Scope | Root | Holds |
+|---|---|---|
+| `repository` (default) | the repository | everything, self-contained |
+| `global` | `~/.agents/` | instructions and skills, shared by every repository |
+| `linked` | the repository | that repository's own learning state only |
+
+> [!NOTE]
+> Instructions resolve at the repository root first and fall back to `~/.agents/`, so a repository with its own copy always wins. Repository state — `.local/`, `MAP.md`, `TAKEAWAYS.md`, `SETTINGS.md`, `DECISIONS.md` — is never read from the global root.
+
+An existing installation can move between scopes: `--scope linked --mode update` strips the framework copies out of a repository and leaves its authored state behind, and `--scope repository --mode update` puts them back.
+
 <details>
 <summary>Profiles, extensions, and update modes</summary>
 
@@ -197,6 +230,28 @@ learning-flow/
 
 Task-specific templates live inside their owning skills and are materialized only when justified.
 
+<details>
+<summary>Where each file lands under a global installation</summary>
+
+The split follows the manifests the installer already used to decide what `update` may overwrite: `.managed-files` and `.managed-skills` name framework-owned content, `.repository-files` names the repository-authored seeds.
+
+```text
+~/.agents/ <repository>/
+├── agentic-flow/ ├── agentic-flow/
+│ ├── AGENTS.md │ ├── SETTINGS.md
+│ ├── WORKFLOW.md │ └── DECISIONS.md
+│ ├── EDUCATION.md ├── learning-flow/
+│ └── ... │ ├── MAP.md
+├── learning-flow/ │ ├── TAKEAWAYS.md
+│ ├── AGENTS.md │ └── REPOSITORIES.md
+│ └── README.md ├── .local/
+└── skills/ └── AGENTS.md
+```
+
+`learning-flow/.install-scope` in each root records the scope and the framework version it was installed at. A linked repository also records the version of the global installation it was linked against, and the installer warns when the two drift apart.
+
+</details>
+
 ## Documentation
 
 - [`docs/EDUCATION_MODEL.md`](docs/EDUCATION_MODEL.md) · learning and ownership model

@@ -39,6 +39,8 @@ one narrowly relevant knowledge/reference file, if needed
 
 Learning and regulatory material are conditional branches, not part of the universal baseline.
 
+Resolving the framework root — repository first, then `~/.agents/` — happens once, when the first framework file is opened. It is not a step, does not add a read, and must not turn into an inventory of both roots.
+
 ## Sanity scenarios
 
 ### 1. Typo-only change

@@ -116,6 +116,30 @@ This separation is a trust and context boundary as well as an installation bound
 
 </details>
 
+## Install roots
+
+The three layers are content boundaries. Cutting across them is a second, independent boundary: whether a given file describes *the framework* or *one repository*.
+
+| Kind | Example | Root |
+|---|---|---|
+| Framework-owned | `agentic-flow/AGENTS.md`, `learning-flow/AGENTS.md`, every managed skill | repository or `~/.agents/` |
+| Repository-authored | `MAP.md`, `TAKEAWAYS.md`, `REPOSITORIES.md`, `SETTINGS.md`, `DECISIONS.md`, `.local/` | always the repository |
+
+Framework-owned content is identical in every repository, so it can be installed once globally and shared. Repository-authored content describes one system and cannot be. This is the same line the installer's `.managed-files` manifests already drew to decide what `update` may overwrite; `.repository-files` names the other side of it explicitly so both can be installed independently.
+
+Instructions resolve at the repository root first and fall back to the global root, so a self-contained repository never consults the global installation. There is no merging between roots: whichever answers first is the one that applies.
+
+```mermaid
+flowchart LR
+ T[Task in a repository] --> R{Repository has agentic-flow/?}
+ R -->|yes| L[Read repository copy]
+ R -->|no| G[Read ~/.agents copy]
+ L --> S[Repository state: MAP, TAKEAWAYS, SETTINGS, .local]
+ G --> S
+```
+
+Repository state sits below the fork because it is read from the repository either way.
+
 ## Runtime instruction flow
 
 The path an agent actually walks for one task, independent of profile: