From a1324a7eb3822aae7799a6c110169cdd88243ab2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Barnab=C3=A1s=20Gell=C3=A9r?= Date: Thu, 27 Aug 2026 19:27:46 +0200 Subject: [PATCH] feat: introduce host integration lookup to ensure agentic discovery --- .github/workflows/ci.yml | 11 +++- CHANGELOG.md | 20 +++++++ MANIFEST.txt | 39 +++++++------ README.md | 16 ++++- docs/AGENTIC_WORKFLOW_SANITY.md | 24 ++++++++ docs/DESIGN_NOTES.md | 37 ++++++++++++ docs/README.md | 1 + .../.agents/skills/agentic-workflow/SKILL.md | 7 ++- .../.agents/skills/learning-closure/SKILL.md | 6 ++ .../skills/repository-learning/SKILL.md | 18 ++++-- sample/common/agentic-flow/.managed-files | 1 + sample/common/agentic-flow/AGENTS.md | 15 +++++ .../common/agentic-flow/HOST_INTEGRATION.md | 58 +++++++++++++++++++ sample/common/agentic-flow/LEARN.md | 3 + sample/common/agentic-flow/LOCAL.md | 14 +++++ sample/common/agentic-flow/README.md | 1 + .../common/agentic-flow/ROOT_INTEGRATION.md | 4 ++ .../skills/learning-bootstrap/SKILL.md | 21 ++++--- scripts/README.md | 5 ++ scripts/ci-install-test.sh | 14 ++++- scripts/ci-release-test.sh | 2 + scripts/install.ps1 | 3 +- scripts/install.sh | 3 +- skill-evals/agentic-cases.yaml | 16 +++++ 24 files changed, 297 insertions(+), 42 deletions(-) create mode 100644 sample/common/agentic-flow/HOST_INTEGRATION.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3f42f03..2bcdcc5 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -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." } diff --git a/CHANGELOG.md b/CHANGELOG.md index 33f38a7..50fcb6a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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`. diff --git a/MANIFEST.txt b/MANIFEST.txt index 1f91638..d51d40a 100644 --- a/MANIFEST.txt +++ b/MANIFEST.txt @@ -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 diff --git a/README.md b/README.md index b128989..2c1ae6a 100644 --- a/README.md +++ b/README.md @@ -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: diff --git a/docs/AGENTIC_WORKFLOW_SANITY.md b/docs/AGENTIC_WORKFLOW_SANITY.md index 9b7f12e..fbdfd89 100644 --- a/docs/AGENTIC_WORKFLOW_SANITY.md +++ b/docs/AGENTIC_WORKFLOW_SANITY.md @@ -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. + diff --git a/docs/DESIGN_NOTES.md b/docs/DESIGN_NOTES.md index 212fc28..2ba4993 100644 --- a/docs/DESIGN_NOTES.md +++ b/docs/DESIGN_NOTES.md @@ -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 diff --git a/docs/README.md b/docs/README.md index c99a356..60f2cce 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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) | diff --git a/sample/common/.agents/skills/agentic-workflow/SKILL.md b/sample/common/.agents/skills/agentic-workflow/SKILL.md index 79e0a0a..12d83ed 100644 --- a/sample/common/.agents/skills/agentic-workflow/SKILL.md +++ b/sample/common/.agents/skills/agentic-workflow/SKILL.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 diff --git a/sample/common/.agents/skills/learning-closure/SKILL.md b/sample/common/.agents/skills/learning-closure/SKILL.md index de71251..6bf3562 100644 --- a/sample/common/.agents/skills/learning-closure/SKILL.md +++ b/sample/common/.agents/skills/learning-closure/SKILL.md @@ -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: diff --git a/sample/common/.agents/skills/repository-learning/SKILL.md b/sample/common/.agents/skills/repository-learning/SKILL.md index e53aaa6..d286552 100644 --- a/sample/common/.agents/skills/repository-learning/SKILL.md +++ b/sample/common/.agents/skills/repository-learning/SKILL.md @@ -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. diff --git a/sample/common/agentic-flow/.managed-files b/sample/common/agentic-flow/.managed-files index e5f0fe3..62dcf78 100644 --- a/sample/common/agentic-flow/.managed-files +++ b/sample/common/agentic-flow/.managed-files @@ -8,5 +8,6 @@ CONFIGURE.md EDUCATION.md LEARN.md LOCAL.md +HOST_INTEGRATION.md ROOT_INTEGRATION.md REFERENCE_INTEGRATION.md diff --git a/sample/common/agentic-flow/AGENTS.md b/sample/common/agentic-flow/AGENTS.md index e38a78d..0adaf25 100644 --- a/sample/common/agentic-flow/AGENTS.md +++ b/sample/common/agentic-flow/AGENTS.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. diff --git a/sample/common/agentic-flow/HOST_INTEGRATION.md b/sample/common/agentic-flow/HOST_INTEGRATION.md new file mode 100644 index 0000000..5477a51 --- /dev/null +++ b/sample/common/agentic-flow/HOST_INTEGRATION.md @@ -0,0 +1,58 @@ +# Host discovery integration + +Framework storage and host discovery are separate contracts. Installing files +under `~/.agents/` does not prove that an agent host will automatically read +them. + +```mermaid +flowchart LR + H[Host discovery adapter] --> R[Repository instructions] + R --> F[Framework root resolution] + F --> S[Repository-local state probe] +``` + +## Contract + +1. Use the host's documented project instruction source when the repository + carries root instructions. +2. For a global installation, configure one short account- or user-level + adapter that points to the framework root. Do not copy framework policy into + every repository. +3. Keep repository precedence unchanged: repository `agentic-flow/` and + `learning-flow/` win; otherwise use `~/.agents/`. +4. Repository state remains in the repository. Before repository learning, + continuation, or persistence, directly inspect `.local/`, `learning-flow/`, + and `agentic-flow/`; search results alone cannot establish absence. +5. Verify the adapter in a fresh session. The host should identify the resolved + framework root and existing repository state without creating replacement + records. + +## Cursor + +Cursor documents project-tree `AGENTS.md` and User Rules as instruction +sources. A global Codebase Learning Flow installation therefore needs a Cursor +User Rule (or an equivalent supported account-level rule). Use this compact +adapter and let the referenced files own the detailed policy: + +```text +Read root and nested repository instructions first. Resolve agentic-flow/ and +learning-flow/ from the repository root when present, otherwise from +~/.agents/ (%USERPROFILE%\.agents\ on Windows). + +For repository learning, onboarding, or continuation, directly inspect the +repository-root .local/, learning-flow/, and agentic-flow/ paths before relying +on glob or indexed-search results. Read .local/learning-history.md first when +present, then only relevant maps and recent session state. Before creating or +replacing a learning record, read the exact destination and preserve its +documented owner. +``` + +Review the rule before saving it. The installer deliberately does not edit +Cursor account settings. + +## Other hosts + +Use the host's documented global or user instruction mechanism to provide the +same bridge. If the host has no such mechanism, use repository root +instructions or invoke the framework explicitly; do not claim that global +storage is self-discovering. diff --git a/sample/common/agentic-flow/LEARN.md b/sample/common/agentic-flow/LEARN.md index c706032..74ab8d7 100644 --- a/sample/common/agentic-flow/LEARN.md +++ b/sample/common/agentic-flow/LEARN.md @@ -3,6 +3,8 @@ The repository's agent-facing setup is part of the system collaborators need to understand. Explain it at a high level first, then reveal detail on demand. ```text +Host discovery adapter + ↓ Repository instructions ↓ Agentic collaboration workflow @@ -18,6 +20,7 @@ Private learning and temporary state in .local/ Show: +- which documented host surface discovers repository or global instructions; - which files provide stable rules, and whether they resolve from this repository or a global installation at `~/.agents/`; - which workflow governs planning, autonomy, validation, and handoff; - which skills load only for particular tasks; diff --git a/sample/common/agentic-flow/LOCAL.md b/sample/common/agentic-flow/LOCAL.md index a658687..c3171eb 100644 --- a/sample/common/agentic-flow/LOCAL.md +++ b/sample/common/agentic-flow/LOCAL.md @@ -15,6 +15,20 @@ This framework's own source checkout follows the same model lazily: when `.local └── follow-ups/ ``` +## Discover before reading or writing + +At the start of repository learning, onboarding, or continuation, probe the +exact repository-root `.local/`, `learning-flow/`, and `agentic-flow/` paths. +Use a direct path read or directory listing before concluding that a path is +absent: indexed search, globs, ignore rules, dot-directory handling, junctions, +and symbolic links can omit state that still exists. + +When present, read `.local/learning-history.md` first, then only relevant maps, +custom baseline or entry-point documents, and recent session state. Before +creating or replacing any history, session, map, takeaway, baseline, or other +learning record, read the exact destination and confirm its documented owner. +Do not recreate a record merely because search did not reveal it. + - `learning-history.md` is compact cross-session memory: current goals, system models, revised assumptions, demonstrated understanding, fragile areas, and useful next directions. - `sessions/` holds complete state for meaningful learning sessions, including the goal, attempts, observations, model revisions, questions, checks, summary, and next step. - `follow-ups/` holds generated revision material, practice, or quizzes intended for later use. diff --git a/sample/common/agentic-flow/README.md b/sample/common/agentic-flow/README.md index 0d34ad2..72cdbf7 100644 --- a/sample/common/agentic-flow/README.md +++ b/sample/common/agentic-flow/README.md @@ -59,6 +59,7 @@ New evidence can change the route mid-task. This is a set of behavioral rules, n | `EDUCATION.md` | durable ownership, AI leverage, resilience, and teaching judgment | | `LEARN.md` | understanding the effective repository harness | | `LOCAL.md` | private learning continuity and deliberate promotion | +| `HOST_INTEGRATION.md` | making global instructions discoverable to each host | | `ROOT_INTEGRATION.md` | connecting existing or missing root instructions | | `REFERENCE_INTEGRATION.md` | extracting value from another source | | `learn-anything` | general-topic learning without repository inspection | diff --git a/sample/common/agentic-flow/ROOT_INTEGRATION.md b/sample/common/agentic-flow/ROOT_INTEGRATION.md index b6c90be..49badbf 100644 --- a/sample/common/agentic-flow/ROOT_INTEGRATION.md +++ b/sample/common/agentic-flow/ROOT_INTEGRATION.md @@ -2,6 +2,10 @@ The installed workflow must coexist with the repository's actual agent-facing setup. Never assume this template is the only source of instructions. +This guide begins after the agent host has found the framework. For a global +installation, configure that discovery bridge through `HOST_INTEGRATION.md`; +root integration cannot substitute for an undiscovered global rule. + ## First inspect Before creating or editing a root `AGENTS.md`, look for: diff --git a/sample/profiles/full/.agents/skills/learning-bootstrap/SKILL.md b/sample/profiles/full/.agents/skills/learning-bootstrap/SKILL.md index 7667766..ae922d0 100644 --- a/sample/profiles/full/.agents/skills/learning-bootstrap/SKILL.md +++ b/sample/profiles/full/.agents/skills/learning-bootstrap/SKILL.md @@ -7,15 +7,18 @@ description: Create or refresh a compact repository baseline covering the real s Follow `agentic-flow/AGENTS.md` (repository root, else `~/.agents/`) and `agentic-flow/SETTINGS.md` for collaboration behavior. Read `agentic-flow/EDUCATION.md` and `learning-flow/AGENTS.md`. -1. Inspect repository instructions, shape, entry points, build and proof commands, and relevant configuration. -2. Recognize managed template markers quietly. -3. Map custom instruction exceptions only when they affect work and will be useful again. -4. Identify the real business, scientific, human, or physical system when evidence supports it. -5. Update `REPOSITORIES.md` only for repositories actually needed. -6. Create a compact `MAP.md` with major boundaries, one domain slice, one representative path, and proof entry points. -7. Include failure, access, deployment, legacy, validation, or fallback boundaries only when relevant. -8. Add only already-qualified durable lessons to `TAKEAWAYS.md`. -9. Stop with reviewable changes. +1. Directly inspect repository-root `.local/`, `learning-flow/`, and + `agentic-flow/`. Read existing history, maps, baselines, and entry-point + documents before deciding what is missing. +2. Inspect repository instructions, shape, entry points, build and proof commands, and relevant configuration. +3. Recognize managed template markers quietly. +4. Map custom instruction exceptions only when they affect work and will be useful again. +5. Identify the real business, scientific, human, or physical system when evidence supports it. +6. Update `REPOSITORIES.md` only for repositories actually needed. +7. Create or refresh a compact `MAP.md` with major boundaries, one domain slice, one representative path, and proof entry points; read the exact destination before writing. +8. Include failure, access, deployment, legacy, validation, or fallback boundaries only when relevant. +9. Add only already-qualified durable lessons to an existing `TAKEAWAYS.md`. +10. Stop with reviewable changes. Do not screen fixed themes or modify application code unless explicitly requested. diff --git a/scripts/README.md b/scripts/README.md index 8a0d902..636dafd 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -108,6 +108,11 @@ Which files belong to which scope is declared, not inferred: `.managed-files` an Under `global`, managed skills install to `/skills/` rather than `/.agents/skills/`, because the global root is itself the `.agents` directory a host agent scans. Skills the framework does not manage are never touched. +Global storage does not by itself prove that a host reads global instructions. +Configure the host discovery bridge documented in +`agentic-flow/HOST_INTEGRATION.md`; the installer reports this required next +step but does not edit host account settings. + `--target`/`-TargetPath` overrides the global root when given. `CODEBASE_LEARNING_FLOW_HOME` overrides the default location for every scope's global lookup.
diff --git a/scripts/ci-install-test.sh b/scripts/ci-install-test.sh index 9a23971..ce9d68a 100755 --- a/scripts/ci-install-test.sh +++ b/scripts/ci-install-test.sh @@ -7,10 +7,20 @@ repository="${GITHUB_REPOSITORY:-legrab/codebase-learning-flow}" ref="${GITHUB_SHA:-main}" bash "$repo_root/scripts/install.sh" --target "$target" --repository "$repository" --ref "$ref" --profile minimal --mode fail --skip-root-agents test -d "$target/learning-flow" +git -C "$target" init -q +printf '%s\n' "/.local/" "/learning-flow/" "/agentic-flow/" > "$target/.git/info/exclude" mkdir -p "$target/.local" printf '%s\n' "CI sentinel" > "$target/.local/ci-sentinel" +printf '%s\n' "Existing baseline" > "$target/.local/repository-baseline.md" +printf '%s\n' "Existing entry points" > "$target/.local/maintenance-entry-points.md" +printf '%s\n' "Existing map" > "$target/learning-flow/MAP.md" +printf '%s\n' "Existing takeaways" > "$target/learning-flow/TAKEAWAYS.md" bash "$repo_root/scripts/install.sh" --target "$target" --repository "$repository" --ref "$ref" --profile minimal --mode update --skip-root-agents grep -Fxq "CI sentinel" "$target/.local/ci-sentinel" +grep -Fxq "Existing baseline" "$target/.local/repository-baseline.md" +grep -Fxq "Existing entry points" "$target/.local/maintenance-entry-points.md" +grep -Fxq "Existing map" "$target/learning-flow/MAP.md" +grep -Fxq "Existing takeaways" "$target/learning-flow/TAKEAWAYS.md" full_target="$(mktemp -d)" global_root="$(mktemp -d)" @@ -24,13 +34,15 @@ test -f "$full_target/.agents/skills/repository-learning/SKILL.md" # A global installation owns framework files only; a linked repository owns # only what it authors. The two must never hold the other's content. export CODEBASE_LEARNING_FLOW_HOME="$global_root" -bash "$repo_root/scripts/install.sh" --scope global --repository "$repository" --ref "$ref" --profile full --mode fail +global_output="$(bash "$repo_root/scripts/install.sh" --scope global --repository "$repository" --ref "$ref" --profile full --mode fail)" test -f "$global_root/agentic-flow/AGENTS.md" +test -f "$global_root/agentic-flow/HOST_INTEGRATION.md" test -f "$global_root/skills/repository-learning/SKILL.md" test ! -e "$global_root/agentic-flow/SETTINGS.md" test ! -e "$global_root/learning-flow/MAP.md" test ! -e "$global_root/.local" test ! -e "$global_root/AGENTS.md" +printf '%s\n' "$global_output" | grep -Fq "Configure your agent host to discover this global installation" bash "$repo_root/scripts/install.sh" --target "$linked_target" --scope linked --repository "$repository" --ref "$ref" --mode fail --skip-root-agents test -f "$linked_target/learning-flow/MAP.md" diff --git a/scripts/ci-release-test.sh b/scripts/ci-release-test.sh index 3136743..d6a7f9b 100755 --- a/scripts/ci-release-test.sh +++ b/scripts/ci-release-test.sh @@ -31,6 +31,7 @@ PACKAGE_ROOT="$(find "$INSPECT_DIR" -mindepth 1 -maxdepth 1 -type d | head -n 1) [ -f "$PACKAGE_ROOT/adoption/ADOPT.md" ] || fail "Package is missing adoption/ADOPT.md" [ -f "$PACKAGE_ROOT/adoption/README.md" ] || fail "Package is missing adoption/README.md" [ -f "$PACKAGE_ROOT/VERSION" ] || fail "Package is missing a VERSION file" +[ -f "$PACKAGE_ROOT/sample/common/agentic-flow/HOST_INTEGRATION.md" ] || fail "Package is missing host discovery guidance" [ -f "$PACKAGE_ROOT/sample/vault/AGENTS.md" ] || fail "Package is missing the LearningVault AGENTS.md" [ -f "$PACKAGE_ROOT/scripts/register-vault.sh" ] || fail "Package is missing register-vault.sh" [ -f "$PACKAGE_ROOT/scripts/register-vault.ps1" ] || fail "Package is missing register-vault.ps1" @@ -91,6 +92,7 @@ run_install "global" "$WORK_ROOT/global" \ --vault-init \ --vault-path "$WORK_ROOT/LearningVault" [ -f "$WORK_ROOT/global/agentic-flow/AGENTS.md" ] || fail "global install has no agentic-flow/AGENTS.md" +[ -f "$WORK_ROOT/global/agentic-flow/HOST_INTEGRATION.md" ] || fail "global install has no host discovery guidance" [ -f "$WORK_ROOT/global/skills/repository-learning/SKILL.md" ] || fail "global install has no managed skills" [ -f "$WORK_ROOT/global/skills/regulatory-knowledge/SKILL.md" ] || fail "global install has no extension skill" [ ! -e "$WORK_ROOT/global/agentic-flow/SETTINGS.md" ] || fail "repository-authored SETTINGS.md reached the global root" diff --git a/scripts/install.ps1 b/scripts/install.ps1 index 8242c44..938977a 100644 --- a/scripts/install.ps1 +++ b/scripts/install.ps1 @@ -1240,7 +1240,8 @@ try { Write-Host "" if ($scopeName -eq "global") { Write-Host "Next step:" - Write-Host "Run the installer with -Scope Linked inside a repository to give it its own learning state, or start working: the managed skills in $targetSkills already apply everywhere." + Write-Host "Configure your agent host to discover this global installation; see $(Join-Path $targetAgentic 'HOST_INTEGRATION.md')." + Write-Host "Then run the installer with -Scope Linked inside a repository when it should have its own learning state." } else { Write-Host "Suggested first instruction:" diff --git a/scripts/install.sh b/scripts/install.sh index 6033909..84d7f53 100644 --- a/scripts/install.sh +++ b/scripts/install.sh @@ -1313,7 +1313,8 @@ printf 'Scope: %s (%s)\n' "$SCOPE" "$TARGET_PATH" log "Installation complete: scope=$SCOPE profile=$SELECTED_PROFILE extension=$SELECTED_EXTENSION mode=$MODE root-agents=$RESOLVED_ROOT_AGENTS_MODE" if [ "$SCOPE" = "global" ]; then printf '\n%s\n' "Next step:" - printf '%s\n' "Run the installer with --scope linked inside a repository to give it its own learning state, or start working: the managed skills in $TARGET_SKILLS already apply everywhere." + printf '%s\n' "Configure your agent host to discover this global installation; see $TARGET_AGENTIC/HOST_INTEGRATION.md." + printf '%s\n' "Then run the installer with --scope linked inside a repository when it should have its own learning state." exit 0 fi printf '\n%s\n' "Suggested first instruction:" diff --git a/skill-evals/agentic-cases.yaml b/skill-evals/agentic-cases.yaml index 8a29eb2..337e192 100644 --- a/skill-evals/agentic-cases.yaml +++ b/skill-evals/agentic-cases.yaml @@ -125,6 +125,22 @@ cases: must_include: [preserve existing local files, ensure root .gitignore excludes .local, create only missing structure] must_not: [overwrite learning history, delete follow-ups, commit local state] + - prompt: > + Continue repository learning. Ordinary search shows no learning files, but + this repository excludes .local/, learning-flow/, and agentic-flow/ and + may expose them through directory links. + expected_behavior: explicit_repository_state_discovery + must_include: + - directly inspect exact repository-root .local learning-flow and agentic-flow paths + - read learning-history first when present + - reuse relevant existing maps baselines entry points and recent session state + - read the exact destination before writing + - preserve existing record ownership + must_not: + - treat empty search results as proof of absence + - bootstrap replacement learning records + - overwrite MAP or TAKEAWAYS with session detail + - prompt: "Update an existing minimal installation that has custom MAP.md and TAKEAWAYS.md to this revision." expected_behavior: safe_framework_update must_include: [add managed EDUCATION.md, refresh managed instructions and skills, preserve MAP.md TAKEAWAYS.md SETTINGS.md .local and unrelated skills]