Repository navigation
feat(docs): code→doc reverse index — every edit names the docs that claim to describe it (Event 173) - #157
Merged
Conversation
…laim to describe it (Event 173) Invert the drift linter's existing citation edges into a code→doc map with zero hand-maintained state: build_reverse_index / edges_for_path / docs_for_path / annotate_docs / cached_reverse_index in doc_references.py (one notion of 'what a doc cites'; dangling citations excluded; archive/ and fixture trees obligation-exempt; mtime-digest cache at .episteme/cache/doc_map.json, written only where .episteme/ exists). workflow_guard.py: the path-blind static advisory is REPLACED by a targeted DOC ADVISORY naming the citing docs with lifecycle labels ([via dir/] for directory edges, overflow counted never silent), falling back to the generic string when the package is unimportable, the project has no git, or no doc cites the path (positive system: no citation, no obligation). Also repairs a latent bug the new advisory exposed: doc-path suppression never matched the absolute file paths harness payloads carry (lstrip strips a char set, not a prefix) — targets now normalize to project-relative before the policy test. New query surface: episteme docs map [path ...] (same ordering and labels as the hook; full target ← docs dump with no args). COMMANDS.md names its source of truth so cli.py edits surface it; AGENTS.md carries the workflow pointer; SPEC_DOC_MAP.md records the ratified design (docs at ceiling 32/32). Anti-accretion: counters late-discovered doc-code drift (the E172 sweep class); replaces workflow_guard's static advisory. Suite 1787+91.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
…project The E173 absolute-path normalization used resolve(), which follows symlinks — and this repo's authoritative docs (docs/NEXT_STEPS.md, docs/EVENTS.md) are symlinks into a private tree outside the checkout, so a repo-path edit of exactly the files the suppression exists for would resolve out of cwd and nag again. Textual prefix-strip first; resolve() only as fallback for spelling mismatches (/tmp vs /private/tmp). Covered by a symlinked-doc hook test.
…not go blind to pre-documented files Adversarial review confirmed the hole by disconfirmation: the digest hashes only the markdown corpus, so a doc citing a not-yet-existing file produced no edge at build time and creating the file later never moved the digest — the cached index served a stale empty answer for exactly the pre-documented-file case. Root cause: dropping dangling citations made the index depend on target existence, which a markdown-only digest cannot observe. Fix: a citation is a CLAIM — unresolved citations keep their root-relative spelling as edges, so the index is a pure function of the markdown corpus and the digest is honest by construction. Dangling claims remain find_drift's findings; the mechanisms stay separate. Also: pid-suffixed cache tmp file (concurrent hook processes), spec updated to tell the truth, reviewer's disconfirmation scenario added as a regression test. Suite 1789+91.
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Operator-ratified design C: the drift linter's existing doc→code citation edges, inverted, become an agent-navigable code→doc map with zero hand-maintained state — the map cannot rot by construction.
doc_references.py:build_reverse_index/edges_for_path/docs_for_path/annotate_docs/cached_reverse_index(mtime-digest cache,.episteme/cache/doc_map.json, written only where.episteme/already exists; 196ms cold → 6–11ms steady-state, measured)workflow_guard.py: path-blind static advisory replaced by a targetedDOC ADVISORYnaming the citing docs with lifecycle labels; graceful fallback ladder (no package / no git / no citations → the old generic string). Repairs a latent bug the new advisory exposed: doc-path suppression never matched absolute harness paths (lstrip("./")strips a char set, not a prefix).episteme docs map [path ...]query surface + COMMANDS.md row; AGENTS.md workflow pointer;docs/SPEC_DOC_MAP.mdspec.Governance
workflow_guard's static advisory. No new queue (K6) — the write path is the drain ("repair in the same change or record why not").Verification
Suite 1787 passed + 91 subtests (baseline 1766+91; +21 new tests: inversion semantics, cache contract, real-corpus edges, hook fallback ladder end-to-end).
docs lint/docs index --check/kernel verifyclean. Live-verified: the targeted advisory fired on this event's own edits mid-implementation.