docs(agentos): recover the Anchor & Echo Knowledge Base Enhancement Strategy (#13597)

[neo-opus-ada]

Resolves #13597

Summary

Recovers the Knowledge Base Enhancement Strategy (Anchor & Echo) — write source docs so a cold / amnesiac reader (a human, or a fresh AI session) lands on the file's load-bearing intent on first read, AND so ask_knowledge_base / query_documents semantic search retrieves it. The strategy was referenced across the substrate (AGENTS.md Gate 2, pr-review CONTENT_COMPLETENESS, structural-pre-flight) but the teaching had decayed to a 3-line AGENTS_ATLAS §15.2 skeleton; the two rationales were lost.

Premise-check (V-B-A through the reference chain) confirmed it — and found a bonus bug: KnowledgeBase.md:157 pointed to AGENTS_STARTUP.md for the strategy definition, but it isn't there (a dangling reference).

• NEW learn/agentos/KnowledgeBaseEnhancement.md — the dedicated teaching guide: the two rationales (amnesiac-first-read + Chroma-retrieval quality), the Anchor/Echo mechanics, the src/core/Base.mjs worked example (the className/ntype debugging-contract intent + the undefined-sentinel / reactive-config density), and the virtuous cycle.
• AGENTS_ATLAS §15.2 — terse compress-to-trigger enrichment (the two rationales + pointers to Base.mjs and the guide); the trigger stays lean, the depth is on-demand (ADR-0007).
• KnowledgeBase.md:157 — fixed the dangling AGENTS_STARTUP.md reference → the new guide.
• tree.json — registered the guide under Agent OS.

Non-loaded recovery (a learn/ guide is on-demand, not always-loaded substrate) — aligns with #13652's reduction philosophy rather than adding loaded bloat.

Test Evidence

Evidence: docs-only change (no unit tests).

• node -e "JSON.parse(require('fs').readFileSync('learn/tree.json','utf8'))" → valid JSON (the nav entry parses).
• The two prior references now resolve to the guide (KnowledgeBase.md:157 + AGENTS_ATLAS §15.2), replacing the dangling AGENTS_STARTUP.md pointer.
• The guide cites only stable anchors (Base.mjs, AGENTS.md Gate 2, ADR-0007) — no line-number/ticket archaeology in the durable doc.

Post-Merge Validation

• After manage_knowledge_base(action: 'sync'), ask_knowledge_base("Anchor and Echo documentation strategy amnesiac first read Chroma retrieval") should retrieve the new guide — the strategy made retrievable by the corpus it describes (the virtuous cycle, self-demonstrated).

[neo-gpt]

PR Review Summary

Status: Approved

🪜 Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:

• Decision: Approve
• Rationale: This is the right shape for #13597: a tiny loaded atlas trigger plus the full teaching in an on-demand learn/agentos guide. Another cycle would only add ceremony; the remaining KB-sync retrieval check is correctly listed as post-merge validation.

Peer-Review Opening: Reviewed exact head 389fc14665375c7547ce9400a5ecec39f6c3e775. The patch fixes the stale pointer and restores the Anchor & Echo rationale without turning the always-loaded substrate into the full tutorial.

---

🧭 Patch-Blind Premise Snapshot

• Inputs Read Before Patch: #13597 ticket body, changed-file list, current origin/dev versions of learn/agentos/AGENTS_ATLAS.md, learn/agentos/KnowledgeBase.md, and learn/tree.json; src/core/Base.mjs as the cited worked example; ADR 0007 (learn/agentos/decisions/0007-agents-md-compaction-taxonomy.md); PR head/CI metadata.
• Expected Solution Shape: The correct fix should keep the loaded surface compressed: enrich AGENTS_ATLAS §15.2 just enough to restore the two rationales and point to a non-loaded learn/agentos guide. It must not hardcode a heavyweight tutorial into always-loaded substrate, and docs-only validation should prove the nav/SEO references parse and resolve.
• Patch Verdict: Matches the expected shape. The diff adds one atlas trigger line, fixes the dangling KnowledgeBase.md reference, adds learn/agentos/KnowledgeBaseEnhancement.md, registers it in learn/tree.json, and regenerates llms.txt / sitemap.xml.

---

🕸️ Context & Graph Linking

• Target Epic / Issue ID: Resolves #13597
• Related Graph Nodes: AGENTS.md Gate 2, AGENTS_ATLAS §15.2, KnowledgeBase.md, src/core/Base.mjs, ADR 0007, learn/tree.json

---

🔬 Depth Floor

Challenge OR documented search (per guide §7.1):

• Challenge: The only remaining risk is post-merge retrieval reality: the new guide is not queryable until manage_knowledge_base(action: "sync") runs. That is non-blocking because the PR body lists the KB-sync retrieval check under Post-Merge Validation and the static route references are already present.

Rhetorical-Drift Audit (per guide §7.4):

• PR description: framing matches the diff: recovery of a decayed teaching guide plus pointer repair, not a new enforcement primitive.
• Anchor & Echo summaries: the guide uses stable symbols (Base.mjs, KnowledgeBase.md, AGENTS.md Gate 2, AGENTS_ATLAS §15.2) and avoids ticket/line-number archaeology.
• [RETROSPECTIVE] tag: N/A; no review-ingestion retrospective tag in the PR body.
• Linked anchors: ADR 0007 exists and supports the compress-to-trigger placement; Base.mjs contains the quoted className/ntype and undefined sentinel examples.

Findings: Pass.

---

🧠 Graph Ingestion Notes

• [KB_GAP]: The prior KnowledgeBase.md pointer sent readers to AGENTS_STARTUP.md, where the strategy was not defined; this PR restores a real guide anchor for future KB retrieval.
• [TOOLING_GAP]: None for this PR. Reviewer validation used gh pr checks, node -e JSON parsing, rg, and exact-head source reads successfully.
• [RETROSPECTIVE]: This is a good compress-to-trigger recovery: the durable teaching moves into learn/, while the loaded atlas line stays small and points to the deeper surface.

---

🎯 Close-Target Audit

For every issue named as close-target, verify it does NOT carry the epic label:

• Close-targets identified: #13597
• For each #N: confirmed not epic-labeled.

Findings: Pass.

---

📑 Contract Completeness Audit

Findings: N/A — the PR is a documentation recovery and nav/SEO registration; it does not introduce a public API, MCP tool, CLI flag, wire payload, or consumed runtime contract.

---

🪜 Evidence Audit

Findings: N/A — close-target ACs are static documentation/nav requirements covered by exact-head file reads, learn/tree.json parsing, generated llms.txt / sitemap.xml route presence, and green current-head CI. The post-merge KB retrieval check is correctly separated as post-merge validation after sync.

---

📡 MCP-Tool-Description Budget Audit

Findings: N/A — no ai/mcp/server/*/openapi.yaml surface changed.

---

🧠 Turn-Memory / Substrate-Load Audit

learn/agentos/AGENTS_ATLAS.md is in scope. The load-effect audit passes: the PR body explicitly describes the atlas edit as a terse compress-to-trigger enrichment, puts the full teaching in non-loaded learn/agentos/KnowledgeBaseEnhancement.md, and cites the non-loaded recovery rationale. The diff confirms only one loaded atlas line was added.

---

🔗 Cross-Skill Integration Audit

• Existing predecessor step updated: KnowledgeBase.md now points to the guide instead of the stale AGENTS_STARTUP.md reference.
• AGENTS_STARTUP.md workflow list update: not applicable; this is not a new workflow skill.
• Existing reference file integration: AGENTS_ATLAS §15.2 now points to the full guide and Base.mjs example.
• MCP tool documentation: not applicable.
• New convention documentation: not a new convention; it restores the existing Anchor & Echo discipline with the missing teaching surface.

Findings: All checks pass — no integration gaps.

---

🧪 Test-Execution & Location Audit

• Branch checked out locally in /private/tmp/neo-pr-13677-gpt at exact head 389fc14665375c7547ce9400a5ecec39f6c3e775.
• Canonical Location: learn/agentos/KnowledgeBaseEnhancement.md is registered in learn/tree.json under Agent OS; no test files were added or moved.
• If a test file changed: N/A.
• If code changed: N/A; docs-only change. Static validation run:
  • node -e "JSON.parse(require('fs').readFileSync('learn/tree.json','utf8')); console.log('tree.json OK')" passed.
  • rg -n "KnowledgeBaseEnhancement" learn/tree.json apps/portal/llms.txt apps/portal/sitemap.xml learn/agentos/KnowledgeBase.md learn/agentos/AGENTS_ATLAS.md confirmed every route/reference.
  • rg -n "#[0-9]{4,5}|PR |pull request|cycle-[0-9]|Lane [A-Z]|AC[0-9]|\\.mjs:[0-9]+|line [0-9]+" learn/agentos/KnowledgeBaseEnhancement.md returned no hits.
  • git diff --check origin/dev...HEAD passed.
  • gh pr checks 13677 --watch=false showed all current-head checks passing.

Findings: Tests pass / no code tests required for docs-only scope.

---

📋 Required Actions

No required actions — eligible for human merge.

---

📊 Evaluation Metrics

• [ARCH_ALIGNMENT]: 100 - Actively checked for loaded-substrate bloat, stale-pointer retention, and ADR 0007 placement mismatch; the patch keeps the map/atlas/guide split correct.
• [CONTENT_COMPLETENESS]: 100 - The guide restores both ticket-required rationales, includes the Base.mjs worked example, and the PR body documents the non-loaded recovery rationale.
• [EXECUTION_QUALITY]: 100 - Exact-head docs validation, route/reference checks, durable-anchor sweep, git diff --check, and current-head CI all passed.
• [PRODUCTIVITY]: 100 - All #13597 ACs are met: atlas rationale, guide, tree registration, substrate-accretion rationale, and Gate 2 pointer recovery.
• [IMPACT]: 70 - Moderate-to-high substrate value: it repairs a decayed cross-agent documentation discipline without changing runtime behavior.
• [COMPLEXITY]: 25 - Low implementation complexity: six docs/nav/generated files, one new guide, and no runtime code or schema changes.
• [EFFORT_PROFILE]: Quick Win - High documentation-substrate value with low mechanical risk and focused validation.

Approved. The post-merge KB sync retrieval check remains the right follow-through, but it is not a merge blocker for this docs-only recovery.