legrab · legrab · Aug 26, 2026 · Aug 26, 2026 · Aug 26, 2026 · Aug 26, 2026
@@ -22,7 +22,7 @@ jobs:
  - name: Validate repository structure
  run: python scripts/ci-validate.py
  - name: Validate POSIX installer syntax
- run: sh -n scripts/install.sh
+ run: sh -n scripts/install.sh scripts/register-vault.sh
  - name: Run installer smoke test
  run: bash scripts/ci-install-test.sh
 
@@ -34,9 +34,17 @@ jobs:
  - name: Validate PowerShell syntax
  shell: pwsh
  run: |
- $errors = $null
- [void][System.Management.Automation.Language.Parser]::ParseFile(
- (Resolve-Path "scripts/install.ps1"), [ref]$null, [ref]$errors)
+ $errors = @()
+ foreach ($path in @(
+ "scripts/install.ps1",
+ "scripts/register-vault.ps1",
+ "scripts/ci-vault-test.ps1"
+ )) {
+ $fileErrors = $null
+ [void][System.Management.Automation.Language.Parser]::ParseFile(
+ (Resolve-Path $path), [ref]$null, [ref]$fileErrors)
+ $errors += $fileErrors
+ }
  if ($errors.Count -gt 0) { $errors | Format-List; exit 1 }
  - name: Run installer smoke test
  shell: pwsh
@@ -88,3 +96,6 @@ jobs:
  if (Test-Path "$linked/agentic-flow/AGENTS.md") {
  throw "Framework instructions were duplicated into the linked repository."
  }
+ - name: Run LearningVault lifecycle test
+ shell: pwsh
+ run: ./scripts/ci-vault-test.ps1
@@ -1,5 +1,34 @@
 # Changelog
 
+## 1.5.0
+
+Optional LearningVault storage for linked installations: repository-authored state can live in one local vault while framework files stay in `~/.agents`. Combined linked and vault installs write private harness exclusions to `.git/info/exclude` instead of shared `.gitignore`.
+
+### Added
+
+- Optional LearningVault initialization through `--vault-init` /
+ `-VaultInit`, with configurable `--vault-path` / `-VaultPath` and
+ `CODEBASE_LEARNING_VAULT`.
+- Opt-in linked-repository registration through `--vault-register` /
+ `-VaultRegister`. Repository state is moved under
+ `LearningVault/repositories/<repository-id>/` and exposed at its original
+ paths by POSIX symbolic links or Windows directory junctions.
+- Cross-platform `register-vault` commands for idempotent registration,
+ status, relocation/relinking, and explicit restoration.
+- A compact vault root `AGENTS.md`, README, and `.gitignore` for safe
+ cross-repository use without crawling every registered repository.
+- Linux and Windows lifecycle coverage for packaged seeding, local Git
+ excludes, relocation, update, restore, tracked-path refusal, and the
+ no-remote boundary.
+
+### Changed
+
+- Combined linked installation and vault registration writes private harness
+ exclusions to `.git/info/exclude` instead of changing shared `.gitignore`.
+- Conversion from a vault-linked installation to repository scope now requires
+ `unregister --restore` first, preventing installer replacement logic from
+ operating on a link node.
+
 ## 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.

@@ -1,14 +1,14 @@
 .gitattributes	40
 .gitignore	324
 AGENTS.md	2995
-CHANGELOG.md	31134
+CHANGELOG.md	32641
 LICENSE	2213
-README.md	12031
+README.md	13579
 adoption/ADOPT.md	4177
 adoption/README.md	2445
 docs/AGENTIC_WORKFLOW_SANITY.md	10021
-docs/ARCHITECTURE.md	8577
-docs/DESIGN_NOTES.md	45480
+docs/ARCHITECTURE.md	9277
+docs/DESIGN_NOTES.md	48397
 docs/EXAMPLE_WALKTHROUGH.md	3614
 docs/EDUCATION_MODEL.md	5452
 docs/INITIALIZE_LEARNING_FLOW.md	12199
@@ -21,7 +21,7 @@ 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	3382
-sample/common/.agents/skills/agentic-workflow/SKILL.md	2828
+sample/common/.agents/skills/agentic-workflow/SKILL.md	2986
 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	3709
@@ -46,7 +46,7 @@ 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	1910
-sample/common/agentic-flow/LOCAL.md	4366
+sample/common/agentic-flow/LOCAL.md	4564
 sample/common/agentic-flow/README.md	2897
 sample/common/agentic-flow/REFERENCE_INTEGRATION.md	2183
 sample/common/agentic-flow/ROOT_INTEGRATION.md	3803
@@ -94,10 +94,15 @@ sample/profiles/minimal/learning-flow/README.md	1974
 sample/profiles/minimal/learning-flow/TAKEAWAYS.md	973
 sample/root/AGENTS.md	2263
 sample/root/AGENTS.pointer.md	712
-scripts/README.md	10227
+sample/vault/.gitignore	32
+sample/vault/AGENTS.md	1580
+sample/vault/README.md	1369
+scripts/README.md	13020
 scripts/install.bat	1477
-scripts/install.ps1	55583
-scripts/install.sh	47145
+scripts/install.ps1	61308
+scripts/install.sh	51826
+scripts/register-vault.ps1	21228
+scripts/register-vault.sh	16299
 skill-evals/README.md	1689
 skill-evals/adoption-cases.yaml	1337
 skill-evals/agentic-cases.yaml	9830

@@ -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.3.0 --profile minimal
+sh install.sh --release v1.5.0 --profile minimal
 ```
 
 ```powershell
-& ([scriptblock]::Create((irm https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/scripts/install.ps1))) -Release v1.3.0 -Profile Minimal
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/scripts/install.ps1))) -Release v1.5.0 -Profile Minimal
 ```
 
 The installer verifies the release checksum before extraction and reports the resolved `Version:` and `Source:`.
@@ -119,6 +119,42 @@ The repository then holds only what it authors; the instructions and skills stay
 
 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.
 
+### Optional LearningVault
+
+Linked repositories normally keep their authored state in place. LearningVault
+is an opt-in storage adapter that instead collects that state in one local-only
+Git repository while preserving the source paths through Windows directory
+junctions or POSIX symbolic links.
+
+```powershell
+# Seed the vault while installing the global framework.
+.\scripts\install.ps1 -Scope Global -Profile Full -VaultInit
+
+# In a source Git repository, install linked state and register it.
+.\scripts\install.ps1 -Scope Linked -VaultRegister
+```
+
+```sh
+sh scripts/install.sh --scope global --profile full --vault-init
+sh scripts/install.sh --scope linked --vault-register
+```
+
+The default vault is `%USERPROFILE%\LearningVault` on Windows and
+`$HOME/LearningVault` elsewhere. Override it with `-VaultPath` /
+`--vault-path` or `CODEBASE_LEARNING_VAULT`.
+
+The vault stores each repository under `repositories/<repository-id>/` and
+ships its own compact `AGENTS.md`, README, registration scripts, and
+`.gitignore`. The source repository keeps its physical root `AGENTS.md`;
+`.local/`, `learning-flow/`, and `agentic-flow/` become links. Their exclusions
+are written to `.git/info/exclude`, not shared `.gitignore`.
+
+Registration never creates a remote, stages files, or commits. Use
+`register-vault status`, `relink`, and `unregister --restore` (PowerShell:
+`-Restore`) for the rest of the lifecycle. A vault can contain private
+continuity and Git history retains deleted content, so review it before
+committing or adding any remote manually.
+
 <details>
 <summary>Profiles, extensions, and update modes</summary>
 

@@ -123,22 +123,34 @@ The three layers are content boundaries. Cutting across them is a second, indepe
 | 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 |
+| Repository-authored | `MAP.md`, `TAKEAWAYS.md`, `REPOSITORIES.md`, `SETTINGS.md`, `DECISIONS.md`, `.local/` | logically the repository; physically in place by default or under optional LearningVault |
 
 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.
 
+LearningVault is an optional physical-storage adapter for the repository side
+of this boundary. It is not another framework root or install scope. A linked
+repository may expose `.local/`, `learning-flow/`, and `agentic-flow/` through
+directory links into `~/LearningVault/repositories/<repository-id>/`. Root
+`AGENTS.md` remains a real source-repository file, and managed instructions and
+skills remain under `~/.agents`.
+
 ```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]
+ L --> S[Repository paths: MAP, TAKEAWAYS, SETTINGS, .local]
  G --> S
+ S --> P{Vault registered?}
+ P -->|no| D[Physical state in source repository]
+ P -->|yes| V[Physical state in LearningVault]
 ```
 
-Repository state sits below the fork because it is read from the repository either way.
+Repository state sits below the fork because it is read through repository
+paths either way. Vault storage does not transfer ownership to a global
+knowledge base.
 
 ## Runtime instruction flow
 

@@ -4,6 +4,59 @@
 
 The harness should keep a developer able to reason about a repository while collaborating with an agent, and let any learner use the same lightweight methods for a general subject. It should improve delivery, code and architecture understanding, domain reasoning, debugging, ownership growth, and conversational learning without making workflow administration or learning administration the primary activity.
 
+## v1.5: optional LearningVault storage
+
+The global install introduced in 1.4 deliberately left repository state in
+each repository. That remains the default and the ownership model. The missing
+use case was physical aggregation: one developer may want maps, takeaways,
+settings, and private continuity from several dependent repositories visible
+in one local Git client without moving reusable framework files out of
+`~/.agents`.
+
+LearningVault addresses only that storage concern. It is not a fourth install
+scope. A vault registration requires `linked` scope, moves `.local/`,
+`learning-flow/`, and `agentic-flow/` under
+`~/LearningVault/repositories/<repository-id>/`, and preserves their source
+paths through Windows directory junctions or POSIX symbolic links. Root
+`AGENTS.md` remains a physical source-repository file because Git operations
+can replace tracked files and silently sever hard links.
+
+This is intentionally narrower than the symlink design rejected in 1.4. That
+decision concerned shared framework files and ambiguous `update` ownership.
+LearningVault links only repository-authored state after the framework/state
+boundary has already been established by `linked` scope. Managed framework
+updates continue under `~/.agents`; repository seeds remain copy-if-missing
+through their source paths.
+
+### Alternatives rejected
+
+- Copy/synchronization would create two writable copies and require a new
+ conflict protocol.
+- A `vault` install scope would mix framework placement with repository-state
+ storage and duplicate the existing linked workflow.
+- Vaulting only `.local/` would not provide the cross-repository map and
+ settings workflow that motivated the feature.
+- Automatically untracking repository files would turn a local storage choice
+ into an unreviewed team-visible migration.
+
+### Lifecycle and safety boundaries
+
+- The installer seeds the vault and may invoke registration, while standalone
+ registration scripts own register, status, relink, and restore. This keeps
+ filesystem migration out of ordinary install/update paths.
+- Link support is probed before migration. Source/vault conflicts and tracked
+ state are refused. Moved directories are rolled back when linking fails.
+- Registration owns one marked `.git/info/exclude` block and never rewrites
+ unrelated entries or excludes root `AGENTS.md`.
+- Repository IDs use repository name plus a hash of origin URL (when
+ available) and absolute worktree path. This prevents clones or worktrees of
+ one remote from sharing state; an explicit recorded ID repairs relocations.
+- The vault initializes a local Git repository but never creates a remote,
+ stages files, or commits. Users must treat its history as private because
+ deleted sensitive material remains in prior commits.
+- Empty registrations remain visible through `VAULT.md`; this also records the
+ source path, origin, and link kind needed for recovery.
+
 ## v1.4 install scopes: one framework, many repositories
 
 Until 1.4 the framework had exactly one install root. A developer who wanted this behavior in fifteen repositories installed and updated fifteen byte-identical copies of `agentic-flow/`, `learning-flow/`, and every managed skill, and had no way at all to get the behavior in a repository they could not or should not modify. The layer architecture was already right; the *deployment* model assumed the repository was the only place content could live.

@@ -11,7 +11,7 @@ Read `agentic-flow/README.md` and `AGENTS.md` (repository root, else `~/.agents/
 
 1. Inspect root and nested instructions plus tool-specific files.
 2. Find skills, prompts, plans, sessions, records, and refresh rules.
-3. Detect managed template markers, including `learning-flow/.install-scope`, and note which root the framework files actually resolve from.
+3. Detect managed template markers, including `learning-flow/.install-scope`, and note which root the framework files actually resolve from. When repository state is linked into LearningVault, use that repository's `VAULT.md` as the storage index without treating the vault as the repository owner.
 4. Inspect custom additions, overrides, conflicts, and precedence.
 5. Keep stable policy, task procedures, shared learning, and private `.local/` state distinct.
 6. Keep context narrow.

@@ -4,7 +4,7 @@ Use one rule:
 
 > Learn locally first. Promote only reusable knowledge deliberately.
 
-The repository-root `.local/` directory owns private learning continuity. The installer creates it, adds `/.local/` to the root `.gitignore`, and never overwrites existing local files. This stays true for a global installation: instructions and skills may live in `~/.agents/`, but `.local/` always belongs to the repository being worked on. There is no global `.local/`.
+The repository-root `.local/` directory owns private learning continuity. The installer creates it, adds `/.local/` to the root `.gitignore`, and never overwrites existing local files. In optional LearningVault mode, the path is instead a junction or symbolic link to that repository's vault directory and is hidden through local `.git/info/exclude`; logical ownership is unchanged. This stays true for a global installation: instructions and skills may live in `~/.agents/`, but `.local/` always belongs to the repository being worked on. There is no global `.local/`.
 
 This framework's own source checkout follows the same model lazily: when `.local/` is missing, create the two directories below and copy `sample/common/local/learning-history.md` only if the local history file does not exist.
 

@@ -0,0 +1,4 @@
+.DS_Store
+Thumbs.db
+*.tmp
+*.bak
@@ -0,0 +1,34 @@
+# LearningVault agent instructions
+
+This repository is a local index of learning state for other source
+repositories. It is not an application codebase and does not own their
+implementation.
+
+## Boundaries
+
+- Reusable framework instructions and skills live under `~/.agents`
+ (`%USERPROFILE%\.agents` on Windows), not here.
+- Each `repositories/<repository-id>/` directory belongs logically to one
+ source repository. Start with its `VAULT.md`.
+- `learning-flow/`, `agentic-flow/`, and `.local/` are exposed in the source
+ repository through directory links. Changes on either side affect the same
+ files.
+- Root `AGENTS.md` remains physically in each source repository.
+- Do not infer that every registered repository is relevant. For
+ cross-repository work, identify the involved repository IDs first and read
+ only their maps, settings, and relevant continuity.
+
+## Safety
+
+- Never create or configure a remote, commit, push, publish, or rewrite
+ history without explicit permission.
+- Treat `.local/` as private. Do not copy secrets, customer data, raw
+ operational evidence, identity information, or sensitive personal state
+ into shared maps or takeaways.
+- Git history can retain deleted content. Removing a sensitive file from the
+ working tree does not erase it from existing commits.
+- Do not crawl every repository or load every session merely to understand
+ this vault. Use `repositories/*/VAULT.md` as the index.
+
+Use the normal Codebase Learning Flow routing from the global harness. This
+file adds only the storage and cross-repository boundaries above.
@@ -0,0 +1,43 @@
+# LearningVault
+
+LearningVault is an optional, local-only Git repository that collects learning
+state from multiple source repositories without changing the paths expected by
+Codebase Learning Flow.
+
+Each registered repository keeps a physical root `AGENTS.md`. Its `.local/`,
+`learning-flow/`, and `agentic-flow/` directories are stored here and exposed
+at their original paths through a directory junction on Windows or a symbolic
+link on POSIX systems.
+
+```text
+repositories/
+ <repository-id>/
+ VAULT.md
+ .local/
+ learning-flow/
+ agentic-flow/
+```
+
+The reusable framework remains under `~/.agents` (`%USERPROFILE%\.agents` on
+Windows). Content under `repositories/` remains logically owned by its source
+repository.
+
+## Register a repository
+
+First install the global harness and create a linked repository installation.
+Then run the matching script from the source repository:
+
+```powershell
+& "$HOME\LearningVault\scripts\register-vault.ps1" register
+```
+
+```sh
+"$HOME/LearningVault/scripts/register-vault.sh" register
+```
+
+Use `status` to inspect a registration, `relink` after moving the vault, and
+`unregister --restore` to move the state back into the source repository.
+
+The scripts never add a remote, stage files, or create commits. Review the
+vault before committing because its local Git history can retain deleted
+private or sensitive data.