legrab · legrab · Aug 27, 2026 · Aug 27, 2026
@@ -69,13 +69,17 @@ jobs:
  $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" `
+$globalOutput = & "$PWD/scripts/install.ps1" `
  -Scope Global `
  -Repository $env:GITHUB_REPOSITORY `
  -Ref $env:GITHUB_SHA `
  -Profile full `
- -Mode fail
+ -Mode fail 6>&1
  if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+ Write-Host ($globalOutput -join [Environment]::NewLine)
+ if (($globalOutput -join "`n") -notmatch "Configure your agent host to discover this global installation") {
+ throw "Global install did not report the host discovery requirement."
+ }
  & "$PWD/scripts/install.ps1" `
  -Target $linked `
  -Scope Linked `
@@ -87,6 +91,9 @@ jobs:
  if (-not (Test-Path "$globalRoot/skills/repository-learning/SKILL.md")) {
  throw "Global scope did not install managed skills."
  }
+ if (-not (Test-Path "$globalRoot/agentic-flow/HOST_INTEGRATION.md")) {
+ throw "Global scope did not install host discovery guidance."
+ }
  if (Test-Path "$globalRoot/learning-flow/MAP.md") {
  throw "Repository-authored MAP.md reached the global root."
  }

@@ -1,5 +1,25 @@
 # Changelog
 
+## Unreleased
+
+### Added
+
+- A managed host-discovery contract with a reviewed Cursor User Rule for global
+ installations, plus installer guidance that makes the required host bridge
+ explicit without mutating account settings.
+- A behavioral conformance fixture for ignored, dot-directory, and
+ junction/symlink-backed repository learning state.
+
+### Changed
+
+- Repository learning, bootstrap, workflow discovery, local continuity, and
+ promotion now directly probe repository-root state and read exact
+ destinations before writing, preventing missed records from being recreated
+ or assigned the wrong owner.
+- Installer smoke coverage now preserves existing custom baselines, entry
+ points, MAP, and TAKEAWAYS behind local Git excludes and verifies that host
+ discovery guidance reaches global and packaged installations.
+
 ## 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`.

@@ -1,18 +1,18 @@
 .gitattributes	40
 .gitignore	324
 AGENTS.md	2995
-CHANGELOG.md	32641
+CHANGELOG.md	33474
 LICENSE	2213
-README.md	13579
+README.md	13905
 adoption/ADOPT.md	4177
 adoption/README.md	2445
-docs/AGENTIC_WORKFLOW_SANITY.md	10021
+docs/AGENTIC_WORKFLOW_SANITY.md	11071
 docs/ARCHITECTURE.md	9277
-docs/DESIGN_NOTES.md	48397
+docs/DESIGN_NOTES.md	50471
 docs/EXAMPLE_WALKTHROUGH.md	3614
 docs/EDUCATION_MODEL.md	5452
 docs/INITIALIZE_LEARNING_FLOW.md	12199
-docs/README.md	4257
+docs/README.md	4419
 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
@@ -21,12 +21,12 @@ 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	2986
+sample/common/.agents/skills/agentic-workflow/SKILL.md	3268
 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
+sample/common/.agents/skills/learning-closure/SKILL.md	4074
 sample/common/.agents/skills/learning-freshness/SKILL.md	1908
-sample/common/.agents/skills/repository-learning/SKILL.md	4941
+sample/common/.agents/skills/repository-learning/SKILL.md	5323
 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
@@ -38,18 +38,19 @@ 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	190
 sample/common/agentic-flow/.managed-skills	106
 sample/common/agentic-flow/.repository-files	25
-sample/common/agentic-flow/AGENTS.md	6825
+sample/common/agentic-flow/AGENTS.md	7624
 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	4564
-sample/common/agentic-flow/README.md	2897
+sample/common/agentic-flow/HOST_INTEGRATION.md	2454
+sample/common/agentic-flow/LEARN.md	2016
+sample/common/agentic-flow/LOCAL.md	5346
+sample/common/agentic-flow/README.md	2978
 sample/common/agentic-flow/REFERENCE_INTEGRATION.md	2183
-sample/common/agentic-flow/ROOT_INTEGRATION.md	3803
+sample/common/agentic-flow/ROOT_INTEGRATION.md	4026
 sample/common/agentic-flow/SETTINGS.md	544
 sample/common/agentic-flow/WORKFLOW.md	6080
 sample/common/local/learning-history.md	1528
@@ -72,7 +73,7 @@ sample/extensions/regulatory/learning-flow/.extension-name	11
 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	1528
+sample/profiles/full/.agents/skills/learning-bootstrap/SKILL.md	1786
 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	87
@@ -97,15 +98,15 @@ sample/root/AGENTS.pointer.md	712
 sample/vault/.gitignore	32
 sample/vault/AGENTS.md	1580
 sample/vault/README.md	1369
-scripts/README.md	13020
+scripts/README.md	13273
 scripts/install.bat	1477
-scripts/install.ps1	61308
-scripts/install.sh	51826
+scripts/install.ps1	61382
+scripts/install.sh	51884
 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
+skill-evals/agentic-cases.yaml	10617
 skill-evals/conversation-cases.yaml	3653
 skill-evals/full-cases.yaml	5001
 skill-evals/minimal-cases.yaml	3913

@@ -88,7 +88,10 @@ curl -fsSL https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/
 
 ### 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:
+By default the framework installs into a single repository. `--scope global`
+instead stores the framework-owned instructions and skills once, in
+`%USERPROFILE%\.agents\` (`~/.agents/` elsewhere), for a configured host adapter
+to use from every repository:
 
 ```powershell
 & ([scriptblock]::Create((irm https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/scripts/install.ps1))) -Scope Global -Profile Full
@@ -98,7 +101,16 @@ By default the framework installs into a single repository. `--scope global` ins
 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.
+Global storage is not automatically discoverable by every agent host. Configure
+the host's documented user/global instruction mechanism once; for Cursor, use
+the reviewed User Rule in
+[`agentic-flow/HOST_INTEGRATION.md`](sample/common/agentic-flow/HOST_INTEGRATION.md).
+The installer prints this requirement but deliberately does not edit account
+settings.
+
+What global installation deliberately does not do is create repository state:
+it 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:
 

@@ -229,3 +229,27 @@ Expected behavior:
 
 Failure signal: a profile declares a skill whose implementation is only discoverable by following another profile, or two profile copies can drift independently.
 
+### 13. Hidden or linked repository learning state
+
+**Fixture:** A repository excludes `.local/`, `learning-flow/`, and
+`agentic-flow/` from ordinary search. Existing state includes learning history,
+a custom baseline, maintenance entry points, MAP, TAKEAWAYS, and a recent
+session; one or more directories may be a junction or symbolic link.
+
+**Prompt:** Continue repository learning and retain the reusable result.
+
+Expected behavior:
+
+- directly inspect the three exact repository-root paths before using search as
+ evidence of absence;
+- read learning history first, then only relevant maps, custom entry points,
+ and recent session state;
+- preserve each existing record's ownership;
+- read the exact destination before writing;
+- keep complete investigation detail in one private session and promote only a
+ concise qualified conclusion.
+
+Failure signal: treating an empty search result as absence, bootstrapping
+replacement records, turning MAP or TAKEAWAYS into session dumps, or writing
+repository state under the global framework root.
+
@@ -4,6 +4,43 @@
 
 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.
 
+## Post-v1.5: host discovery and repository-state conformance
+
+The global-install design correctly separated framework-owned files from
+repository-owned state, but it treated storage under `~/.agents/` as if every
+host would discover and load it. A live Cursor session disproved that
+assumption: project `AGENTS.md` and User Rules were documented discovery
+surfaces, while `%USERPROFILE%\.agents\AGENTS.md` was not an automatic Cursor
+instruction source. Once the bridge failed, ignored and junction-backed local
+state was missed and later writes followed the wrong ownership model.
+
+> **Design takeaway:** Correct storage and ownership are insufficient without a
+> small, verifiable host discovery bridge and an explicit repository-state
+> probe before learning records are created or replaced.
+
+The change keeps those concerns separate:
+
+- `HOST_INTEGRATION.md` is the single managed contract for host adapters. It
+ documents a compact Cursor User Rule but the installer does not mutate
+ account settings.
+- `agentic-flow/AGENTS.md` owns the always-loaded direct-path and pre-write
+ invariants. `LOCAL.md` owns the detailed probe order, while repository
+ learning, bootstrap, workflow, and closure skills apply it at their write
+ boundaries.
+- Global installer summaries now state that host discovery must be configured;
+ they no longer claim globally stored skills already apply everywhere.
+- Behavioral fixtures cover ignored or linked state, and installer smoke tests
+ preserve existing history, custom entry points, MAP, and TAKEAWAYS while
+ proving the host guide ships to global installations.
+
+A repository-state manifest was not added. Optional custom records such as
+`repository-baseline.md` and `maintenance-entry-points.md` are not universal
+framework surfaces; direct inspection plus repository-native ownership
+instructions finds them without creating another source of truth. Static CI
+also does not claim to prove model compliance: it verifies packaging and
+preservation, while the behavioral scenario defines the fresh-session
+conformance review.
+
 ## v1.5: optional LearningVault storage
 
 The global install introduced in 1.4 deliberately left repository state in

@@ -40,6 +40,7 @@ be adopted into an existing agentic workflow without replacing that workflow.
 | understand the educational direction | [`EDUCATION_MODEL.md`](EDUCATION_MODEL.md) |
 | understand ownership and historical architecture decisions | [`DESIGN_NOTES.md`](DESIGN_NOTES.md) |
 | reconstruct or adapt the framework | [`INITIALIZE_LEARNING_FLOW.md`](INITIALIZE_LEARNING_FLOW.md) |
+| configure host discovery for a global installation | [`../sample/common/agentic-flow/HOST_INTEGRATION.md`](../sample/common/agentic-flow/HOST_INTEGRATION.md) |
 | see the proposal-challenge and ambiguity routing behavior in a worked example | [`EXAMPLE_WALKTHROUGH.md`](EXAMPLE_WALKTHROUGH.md) |
 | integrate an external source | [`references/REFERENCE_INTEGRATION.md`](references/REFERENCE_INTEGRATION.md) |
 | inspect installer behavior | [`../scripts/README.md`](../scripts/README.md) |

@@ -10,7 +10,10 @@ Read `agentic-flow/README.md` and `AGENTS.md` (repository root, else `~/.agents/
 ## Discover
 
 1. Inspect root and nested instructions plus tool-specific files.
-2. Find skills, prompts, plans, sessions, records, and refresh rules.
+2. Directly inspect repository-root `.local/`, `learning-flow/`, and
+ `agentic-flow/` before searching for skills, prompts, plans, sessions,
+ records, and refresh rules. Hidden, ignored, or linked state may be absent
+ from search results.
 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.
@@ -25,6 +28,8 @@ Read `agentic-flow/README.md` and `AGENTS.md` (repository root, else `~/.agents/
 5. Ask for configuration only during requested or guided setup.
 6. Update `SETTINGS.md` without rewriting unrelated instructions.
 7. Update learning maps only for durable custom exceptions or conflicts.
+8. Before creating or replacing a record, read the exact destination and
+ preserve its documented owner.
 
 ## Explain
 

@@ -40,6 +40,12 @@ If this session corrected an existing `learning-flow/MAP.md` or `TAKEAWAYS.md` e
 
 Prefer the module's own documentation when it is necessary to use or extend that module correctly. Prefer learning-flow surfaces for cross-cutting repository understanding. Every destination above belongs to the repository being worked on, never to a global installation root.
 
+Before recommending or writing a destination, inspect its exact
+repository-root path directly. Do not treat an empty glob or indexed-search
+result as proof that ignored, dot-directory, junction-backed, or symlinked
+state is absent. Read an existing destination before editing it so promotion
+cannot replace its established ownership or duplicate a focused record.
+
 ## Ask at meaningful closure
 
 At pull-request or substantial change completion, if a useful candidate exists, present a compact recommendation:

@@ -9,12 +9,16 @@ Follow `agentic-flow/AGENTS.md` (repository root, else `~/.agents/`) and `agenti
 
 ## Shared route
 
-1. Identify the real outcome, system boundary, governing rule or invariant, representative path, and proof surface.
-2. Work from decisive repository evidence before committing to a model or proposed design.
-3. Use the smallest responsible investigation, attempt, or change.
-4. Verify against decisive evidence and relevant failure modes.
-5. Use at most one consequential understanding check when a mistaken model would affect later reasoning.
-6. Transfer only verified, reusable learning into the normal handoff or a qualified shared record.
+1. Directly inspect repository-root `.local/`, `learning-flow/`, and
+ `agentic-flow/`. Read `.local/learning-history.md` first when present, then
+ only relevant maps and recent session state; do not infer absence from
+ search results.
+2. Identify the real outcome, system boundary, governing rule or invariant, representative path, and proof surface.
+3. Work from decisive repository evidence before committing to a model or proposed design.
+4. Use the smallest responsible investigation, attempt, or change.
+5. Verify against decisive evidence and relevant failure modes.
+6. Use at most one consequential understanding check when a mistaken model would affect later reasoning.
+7. Transfer only verified, reusable learning into the normal handoff or a qualified shared record.
 
 Select exactly one branch below. Do not load or execute the other branches.
 
@@ -77,3 +81,5 @@ Ask at most one check about the preserved contract, failure boundary, or new res
 Use `MAP.md`, `TAKEAWAYS.md`, and, in the full profile, `REPOSITORIES.md` as the single owners for durable shared knowledge. Keep private attempts, personal state, uncertainty, secrets, and sensitive operational evidence under `.local/`.
 
 Promote only verified, repository-specific, reusable, non-sensitive findings that are costly enough to rediscover.
+Before creating or replacing any learning record, read its exact path and
+confirm that the content matches that record's existing ownership.
@@ -8,5 +8,6 @@ CONFIGURE.md
 EDUCATION.md
 LEARN.md
 LOCAL.md
+HOST_INTEGRATION.md
 ROOT_INTEGRATION.md
 REFERENCE_INTEGRATION.md
@@ -17,6 +17,21 @@ Repository state is never read from the global root. `.local/`, `learning-flow/M
 
 When neither root has a file this layer names, the guidance simply does not apply. Do not create it to satisfy a reference.
 
+## Repository-state discovery
+
+For repository learning, onboarding, continuation, or persistence, inspect the
+repository-root `.local/`, `learning-flow/`, and `agentic-flow/` paths directly
+before relying on glob or indexed-search results. Ignore rules, dot-directory
+handling, junctions, and symbolic links can hide existing state; an empty
+search result is not evidence that these paths are absent.
+
+Read `.local/learning-history.md` first when present, then only the relevant
+map, baseline or entry-point document, and recent session state. Before
+creating, replacing, or promoting into a learning record, resolve its owner and
+read the exact destination. Preserve existing records and do not bootstrap
+missing state unless the user requests it or the active repository instructions
+require it.
+
 ## Route
 
 1. Follow root, nested, and tool-specific repository instructions first.