Problem
The protocol's only navigation artifact today is the folder map in PROJECT_RULES.md §J6 (topic → folder/file). In practice this is not enough: agents in fresh sessions repeatedly fail to realize that information already exists in the repository, because:
- §J6 maps folders, not questions. Knowing which file answers which question (and which section) still depends on the maintainer's mental map.
- The append-only logs are invisible by topic.
JOURNAL.md, LESSONS.md, and decisions.jsonl hold decisions and history that no context file summarizes, but nothing in the baseline tells an agent to grep them before concluding "this was never discussed".
- Per-folder indexes are unspecified. Projects grow ad-hoc
INDEX.md/README.md files with no governance, so coverage is inconsistent and they silently drift from disk state.
Observed in a real consumer project (cloud-sync substrate, document repository, no code): a full audit found the folder map stale (ghost entries, missing folders), index coverage inconsistent across folders, and no topic-level entry point at all — the direct cause of the "agent doesn't know the info exists" failure mode.
Proposal
Make a knowledge map a first-class protocol artifact:
INDEX.md at repo root (project layer) — a question-oriented topic map: question → file → section, plus grep recipes for JOURNAL.md, LESSONS.md (tags), and decisions.jsonl. Pointer-only by rule: it never duplicates data, only locates it.- Boot integration in the framework templates — the shipped
CLAUDE.md / AGENTS.md pointer templates should instruct: "Before answering any project question, consult the root INDEX.md. Never conclude that information does not exist without checking it first." (Today a consumer project cannot add this itself without violating the maintainer-managed status of the pointers — it can only reference INDEX.md from §J6, which is the workaround currently in use.)
- Same-session maintenance contract — extend the
§J5-style quality checklist: any session that creates/renames/removes folders, reference files, or indexes must update root INDEX.md (and the affected per-folder index) in the same session, never deferred.
- Per-folder index convention — optional
INDEX.md/README.md per high-volume folder, registered in the root knowledge map, with the same pointer-only discipline.
Why protocol-level and not per-project
Items 2 (pointer templates) and 3–4 (checklist contract) are framework-layer changes — consumer projects cannot ship them themselves under the current governance (pointers and framework files are maintainer-managed). The failure mode is generic to any multi-session / multi-agent repository, not specific to one project.
Prior art in the protocol
§J6 already establishes the folder map; this proposal adds the complementary topic map and wires it into the baseline load.LESSONS.md inline tags already enable grep-by-topic; the knowledge map makes that mechanism discoverable to agents that don't know it exists.
Problem
The protocol's only navigation artifact today is the folder map in
PROJECT_RULES.md §J6(topic → folder/file). In practice this is not enough: agents in fresh sessions repeatedly fail to realize that information already exists in the repository, because:JOURNAL.md,LESSONS.md, anddecisions.jsonlhold decisions and history that no context file summarizes, but nothing in the baseline tells an agent to grep them before concluding "this was never discussed".INDEX.md/README.mdfiles with no governance, so coverage is inconsistent and they silently drift from disk state.Observed in a real consumer project (cloud-sync substrate, document repository, no code): a full audit found the folder map stale (ghost entries, missing folders), index coverage inconsistent across folders, and no topic-level entry point at all — the direct cause of the "agent doesn't know the info exists" failure mode.
Proposal
Make a knowledge map a first-class protocol artifact:
INDEX.mdat repo root (project layer) — a question-oriented topic map: question → file → section, plus grep recipes forJOURNAL.md,LESSONS.md(tags), anddecisions.jsonl. Pointer-only by rule: it never duplicates data, only locates it.CLAUDE.md/AGENTS.mdpointer templates should instruct: "Before answering any project question, consult the rootINDEX.md. Never conclude that information does not exist without checking it first." (Today a consumer project cannot add this itself without violating the maintainer-managed status of the pointers — it can only referenceINDEX.mdfrom§J6, which is the workaround currently in use.)§J5-style quality checklist: any session that creates/renames/removes folders, reference files, or indexes must update rootINDEX.md(and the affected per-folder index) in the same session, never deferred.INDEX.md/README.mdper high-volume folder, registered in the root knowledge map, with the same pointer-only discipline.Why protocol-level and not per-project
Items 2 (pointer templates) and 3–4 (checklist contract) are framework-layer changes — consumer projects cannot ship them themselves under the current governance (pointers and framework files are maintainer-managed). The failure mode is generic to any multi-session / multi-agent repository, not specific to one project.
Prior art in the protocol
§J6already establishes the folder map; this proposal adds the complementary topic map and wires it into the baseline load.LESSONS.mdinline tags already enable grep-by-topic; the knowledge map makes that mechanism discoverable to agents that don't know it exists.