From 242c555f931459d55e7915c289720c92619f414e Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 23 Sep 2026 19:05:16 +0000 Subject: [PATCH] context-forge: content-anchor code citations (CF-N13) for large multi-tenant repos MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Raw `path:line` citations were the identity of every citation the toolkit emits (constitution rules, both findings logs) and the key both staleness engines checked (refresh re-check, scrubber's "stale citation" category). In large, churning, multi-tenant repos this backfired: any edit above a cited line drifted the number, so citations went "stale" without the referenced knowledge changing, and the same relative path shape recurring under many tenants made a bare path+line ambiguous. The result was constant re-flagging and rework — the exact churn the plugin exists to prevent. Re-key every emitted citation on a stable content anchor: - New governing norm CF-N13 (shared principles.md, both copies): citations are `path#anchor` — a grep-resolvable symbol/heading (or short unique snippet), repo-root-relative and module-qualified so tenants aren't ambiguous — with a line number only ever an optional, approximate `(~Lnn)` hint, never the identity. Amends CF-N1 and CF-N9 to reference it. - Staleness redefined across both engines: a citation is stale only when its anchor no longer resolves; a merely drifted `~L` hint is current and is re-stamped in place as metadata, never flagged (refresh-protocol, audit-protocol, both SKILLs, both agents). - Multi-site ambiguity is disambiguated by module-qualified path or deduped up the tree (CF-N3), never guessed. - Legacy `path:line` citations stay valid input and are re-grounded to `path#anchor` the next time refresh/re-audit touches the row — backward compatible. - Threaded the `path#anchor (~Lnn)` form through every placeholder and example in the agents, protocols, and all three templates; README gains a "Content-anchored citations" design note. - Version 0.8.0 -> 0.9.0 across all three tool manifests. Validators (plugin + marketplace, self-tests and live) pass. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01VzYYP7rcbdLLLKapxfvfvR --- .../context-forge/.claude-plugin/plugin.json | 2 +- .../context-forge/.codex-plugin/plugin.json | 2 +- .../context-forge/.cursor-plugin/plugin.json | 2 +- plugins/context-forge/README.md | 21 +++++++-- .../context-forge/agents/context-auditor.md | 45 ++++++++++++------- .../context-forge/agents/convention-scout.md | 29 +++++++++--- .../skills/context-constitution/SKILL.md | 10 +++-- .../reference/principles.md | 33 +++++++++++--- .../reference/refresh-protocol.md | 20 ++++++--- .../reference/scan-protocol.md | 3 ++ .../reference/synthesis-protocol.md | 12 ++--- .../templates/context-constitution.md | 18 +++++--- .../templates/findings.md | 12 ++--- .../skills/context-scrubber/SKILL.md | 22 +++++---- .../reference/apply-protocol.md | 3 +- .../reference/audit-protocol.md | 23 +++++----- .../context-scrubber/reference/principles.md | 33 +++++++++++--- .../templates/scrubber-findings.md | 39 ++++++++-------- 18 files changed, 223 insertions(+), 106 deletions(-) diff --git a/plugins/context-forge/.claude-plugin/plugin.json b/plugins/context-forge/.claude-plugin/plugin.json index 7e08834..f47a492 100644 --- a/plugins/context-forge/.claude-plugin/plugin.json +++ b/plugins/context-forge/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "context-forge", "displayName": "Context Forge", - "version": "0.8.0", + "version": "0.9.0", "description": "A context-engineering toolkit for AI coding agents. context-constitution reverse-engineers a repo's non-obvious tribal knowledge into an evidence-cited context-constitution.md plus a behavioral contract in CLAUDE.md; context-scrubber audits the repo's context files and reports every line that fails the litmus test — stale citations, restated facts, cross-file duplication, contradicted-by-code, should-be-just-in-time, brittle/over-specified, bloat — plus two file-level advisories, a context-budget rot check and a silent-skill (weak trigger surface) audit, with an optional gated trim. Adds the high-signal context, removes the low-signal; invents nothing, every rule and verdict is grounded.", "author": { "name": "David Castillo", diff --git a/plugins/context-forge/.codex-plugin/plugin.json b/plugins/context-forge/.codex-plugin/plugin.json index b34b19a..c350075 100644 --- a/plugins/context-forge/.codex-plugin/plugin.json +++ b/plugins/context-forge/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "context-forge", - "version": "0.8.0", + "version": "0.9.0", "description": "A context-engineering toolkit for AI coding agents. context-constitution reverse-engineers a repo's non-obvious tribal knowledge into an evidence-cited context-constitution.md plus a behavioral contract in CLAUDE.md; context-scrubber audits the repo's context files and reports every line that fails the litmus test — stale citations, restated facts, cross-file duplication, contradicted-by-code, should-be-just-in-time, brittle/over-specified, bloat — plus two file-level advisories, a context-budget rot check and a silent-skill (weak trigger surface) audit, with an optional gated trim. Adds the high-signal context, removes the low-signal; invents nothing, every rule and verdict is grounded.", "author": { "name": "David Castillo", diff --git a/plugins/context-forge/.cursor-plugin/plugin.json b/plugins/context-forge/.cursor-plugin/plugin.json index 7e08834..f47a492 100644 --- a/plugins/context-forge/.cursor-plugin/plugin.json +++ b/plugins/context-forge/.cursor-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "context-forge", "displayName": "Context Forge", - "version": "0.8.0", + "version": "0.9.0", "description": "A context-engineering toolkit for AI coding agents. context-constitution reverse-engineers a repo's non-obvious tribal knowledge into an evidence-cited context-constitution.md plus a behavioral contract in CLAUDE.md; context-scrubber audits the repo's context files and reports every line that fails the litmus test — stale citations, restated facts, cross-file duplication, contradicted-by-code, should-be-just-in-time, brittle/over-specified, bloat — plus two file-level advisories, a context-budget rot check and a silent-skill (weak trigger surface) audit, with an optional gated trim. Adds the high-signal context, removes the low-signal; invents nothing, every rule and verdict is grounded.", "author": { "name": "David Castillo", diff --git a/plugins/context-forge/README.md b/plugins/context-forge/README.md index bc07814..b2b58c6 100644 --- a/plugins/context-forge/README.md +++ b/plugins/context-forge/README.md @@ -16,7 +16,7 @@ Both run on the same premise and the same litmus test: *the value of a context l proportional to how easily an agent would find it alone.* `context-constitution` keeps only what an agent would **miss**; `context-scrubber` flags what an agent would **find for free**. Both are single orchestrators that own every write and every gate, spawn only read-only advisory subagents, and never -invent — every rule and every verdict is grounded in `path:line` evidence. They share one config file +invent — every rule and every verdict is grounded in content-anchored `path#anchor` evidence. They share one config file (`.agents/context-forge.json`) and one governance set (`CF-*` Floor rules, `CF-N*` Norms). ## `/context-constitution` — forge the high-signal context @@ -35,7 +35,7 @@ Turns a repo's non-obvious knowledge into two durable artifacts: - **Scans** the repo with a read-only subagent (`convention-scout`) that hunts the non-obvious: emergent multi-site patterns (each with the *wrong default* it prevents), asymmetries, implicit cross-module contracts, and "looks-wrong-but-intentional" flags — every finding grounded in - `path:line` evidence. + content-anchored `path#anchor` evidence. - **Mines git history** for scars — reverts, hotfixes, "fix: … because …" — to recover the *why* the code alone can't show, cited to commits/PRs. - **Asks you** about anything that looks wrong but appears intentional, and records your answer as @@ -89,7 +89,7 @@ what an agent would find for free and is therefore dead weight in an auto-loaded - **Audits** the repo's auto-loaded instruction files — root + nested `CLAUDE.md`, `AGENTS.md`, the generated `context-constitution.md` / findings, `.cursor/rules/*` — with a read-only subagent (`context-auditor`), classifying each line against the actual repo. -- **Seven failure categories**, every verdict cited: **stale citations** (a `path:line` that no longer +- **Seven failure categories**, every verdict cited: **stale citations** (a citation whose content anchor no longer resolves), **restated facts** (a line an agent reads for free), **cross-file duplication** (the same rule in two context files), **contradicted by code** (a claim the code disproves), **should be just-in-time** (accurate but pre-loaded content that belongs behind a pointer), **brittle / @@ -140,6 +140,21 @@ Each skill is a single orchestrator that owns every write and every gate; its su protocol detail loads only when its phase runs. The two skills' shared `principles.md` and `config-protocol.md` are byte-identical copies. +### Content-anchored citations (`CF-N13`) + +Every code citation an artifact emits is keyed on a **stable content anchor**, not a line number: +`path#anchor` — where `anchor` is a grep-resolvable symbol, migration id, or doc heading (or a short +unique quoted snippet when no symbol fits), and the path is repo-root-relative and module-qualified. A +line number is only ever an approximate, regenerable hint appended as `(~Lnn)`, never the citation's +identity. This is what keeps the toolkit sound in **large, multi-tenant repos**: raw `path:line` +citations rot the instant any edit lands above them, and the same relative path shape recurs under many +tenants/modules, so line-keyed citations both churn constantly and read ambiguously. With anchors, a +citation is **stale only when its anchor no longer resolves** (a renamed or deleted symbol) — a merely +drifted line never triggers a false "stale" flag on `refresh` or in a scrub, and an anchor that resolves +under more than one tenant is disambiguated by its module-qualified path or deduped up the tree +(`CF-N3`). Legacy `path:line` citations remain valid input and are re-grounded to `path#anchor` the next +time a `refresh` or re-audit touches the row. + ## Compatibility Ships one shared `skills/` + `agents/` tree with a manifest for each tool, so it runs on **Claude Code**, diff --git a/plugins/context-forge/agents/context-auditor.md b/plugins/context-forge/agents/context-auditor.md index c2bbb5b..042234c 100644 --- a/plugins/context-forge/agents/context-auditor.md +++ b/plugins/context-forge/agents/context-auditor.md @@ -1,6 +1,6 @@ --- name: context-auditor -description: Read-only auditor for the context-scrubber skill. Given a list of a repo's auto-loaded context/instruction files (root + nested CLAUDE.md, AGENTS.md, the generated context-constitution.md, .cursor/rules/*) and the repo root, it classifies each substantive line AGAINST the actual repo — stale citation, restated-free fact, cross-file duplication, contradicted-by-code, should-be-just-in-time, brittle/over-specified (anti-altitude), or bloat — grounding every "fails" verdict in path:line evidence (the free-to-read source, the contradicting site, a duplicate location, or a citation that no longer resolves), and measuring each file's size for the file-level budget signal. It audits only the named context files, never source code as context, and skips anything inside a context-forge:* / constitution-forge:* sentinel block. Never writes; never asserts a verdict it cannot ground. +description: Read-only auditor for the context-scrubber skill. Given a list of a repo's auto-loaded context/instruction files (root + nested CLAUDE.md, AGENTS.md, the generated context-constitution.md, .cursor/rules/*) and the repo root, it classifies each substantive line AGAINST the actual repo — stale citation, restated-free fact, cross-file duplication, contradicted-by-code, should-be-just-in-time, brittle/over-specified (anti-altitude), or bloat — grounding every "fails" verdict in content-anchored evidence (path#anchor — the free-to-read source, the contradicting site, a duplicate location, or a citation whose anchor no longer resolves; a merely drifted line hint is not stale), and measuring each file's size for the file-level budget signal. It audits only the named context files, never source code as context, and skips anything inside a context-forge:* / constitution-forge:* sentinel block. Never writes; never asserts a verdict it cannot ground. tools: Glob, Grep, Read model: inherit readonly: true @@ -40,12 +40,14 @@ Run the inclusion test (**CF-N4**) in reverse: A `fails` verdict is grounded only when it rests on something you actually checked: -- **Stale citation** — the `path:line` the context line cites does not resolve (you Read/Grep'd and the file/line - is gone, or the symbol moved). Cite what you found (or "grep: zero hits"). -- **Restated (fails CF-N4)** — a specific free-to-read `path:line` (the single file an agent would edit, a +- **Stale citation** — the citation's **content anchor** does not resolve (you grepped the symbol/heading or + quoted snippet and it is gone, renamed, or the file moved). Cite what you found (or "grep: zero hits"). A + citation whose anchor still resolves but whose `~L` line hint merely drifted is **not** stale — say nothing + (**CF-N13**); a bare line-number mismatch is never a verdict. +- **Restated (fails CF-N4)** — a specific free-to-read `path#anchor` (the single file an agent would edit, a manifest/dependency list, a doc/CI file it already loads) that makes the context line redundant. - **Cross-file duplication** — one or more **other** context files stating the same thing; cite every location. -- **Contradicted by code** — the `path:line` where the code does the opposite of what the context line claims. +- **Contradicted by code** — the `path#anchor` where the code does the opposite of what the context line claims. This is a **defect** (**CF-N9**): report it, but flag that the orchestrator routes it to `/context-constitution`'s findings log for triage — it is never a `remove`/`apply` target (deciding *implement vs. remove the doc* is a human call). Note whether the code merely *lacks* the behavior (doc-lie) or *does something different* (drift). @@ -67,8 +69,12 @@ what would confirm it. 1. **Read each context file** and segment it into substantive claims. Skip blank lines, pure headings, and — every time — anything inside a `context-forge:*` / `constitution-forge:*` sentinel span (flag the block, never audit inside it). -2. **Stale citations.** For every `path:line` or symbol a context line cites, resolve it against the tree. Doesn't - resolve → stale (note whether the code looks *moved*, so the orchestrator can suggest re-ground vs. remove). +2. **Stale citations.** For every citation a context line makes, resolve its **anchor** by grepping the + symbol/heading (or quoted snippet) across the tree — never by checking the `~L` line hint (**CF-N13**). Anchor + resolves nowhere → stale (note whether the code looks *moved*, so the orchestrator can suggest re-ground vs. + remove). Anchor still resolves but the line hint drifted → **not** stale; do not report it. A legacy + `path:line` with no anchor: resolve by the symbol on/near that line, and if it still exists, treat it as + current (re-anchor, don't flag). 3. **Restated-free.** For a line stating a fact, ask whether an agent working the relevant file already sees it — in that file, a manifest, or a doc/CI file it loads. If yes, cite that source; the line is redundant. 4. **Cross-file duplication.** Index claims across **all** the files you were given. The same rule in ≥2 files → @@ -84,47 +90,52 @@ what would confirm it. 9. **Measure each file.** Record every audited file's total lines and characters (you hold its bytes) so the orchestrator can build the file-level budget signal. This is measurement, not a verdict — report the numbers, don't judge. -10. **Distill.** Each finding is one line: the context `file:line`, a one-line reason, and the evidence citation. +10. **Distill.** Each finding is one line: the context `file#anchor`, a one-line reason, and the evidence citation. Prefer 12 sharp findings over 40 shallow ones. Never paste file bodies. ## Output format (always) +Cite content-anchored, per **CF-N13**. The **context-side** handle is the file's nearest heading plus the quoted +line — `path/CLAUDE.md#
` — since the quoted content is itself the anchor (a `~L` hint is optional and +approximate). The **evidence-side** handle is `path#anchor` (a grep-resolvable symbol/heading), module-qualified +from the repo root, with an optional `(~Lnn)` hint. Never key a citation on a bare line number. + ``` ## Context files audited (with measured size) - `` — — lines, chars ## Stale citations -- `path/CLAUDE.md:NN` — cites `src/foo.go:120` → does not resolve (grep: zero hits) — [moved? to `src/bar.go:88` | gone] +- `path/CLAUDE.md#
` — "" cites `src/foo.go#fooHandler` → anchor does not resolve (grep: zero hits) — [moved? to `src/bar.go#fooHandler` | gone] - (or "none") ## Restated (fails CF-N4) -- `CLAUDE.md:NN` — "" — free to read at `package.json:12` — action: remove +- `CLAUDE.md#
` — "" — free to read at `package.json#dependencies` — action: remove - (or "none") ## Cross-file duplication (CF-N3) -- `apps/web/CLAUDE.md:NN` — same rule as `CLAUDE.md:MM` (root) — keep: root +- `apps/web/CLAUDE.md#
` — same rule as `CLAUDE.md#
` (root) — keep: root - (or "none") ## Contradicted by code -- [⚠ security] `CLAUDE.md:NN` — claims "" — code does "" at `src/auth.go:40` +- [⚠ security] `CLAUDE.md#
` — claims "" — code does "" at `src/auth.go#authMiddleware` - (or "none") ## Should be just-in-time -- `CLAUDE.md:NN–MM` — narrow: only relevant to `payments/`; auto-loaded everywhere — home: `payments/README.md` +- `CLAUDE.md#
` — "" — narrow: only relevant to `payments/`; auto-loaded everywhere — home: `payments/README.md` - (or "none") ## Brittle / over-specified (anti-altitude) -- `CLAUDE.md:NN–MM` — "" — heuristic: "" +- `CLAUDE.md#
` — "" — heuristic: "" - (or "none") ## Bloat / low-value prose -- `CLAUDE.md:NN–MM` — narrative with no directive an agent acts on +- `CLAUDE.md#
` — "" — narrative with no directive an agent acts on - (or "none") ## Protected blocks (found; NOT audited) -- behavioral contract — `CLAUDE.md:NN–MM` — marker `context-forge:behavioral-contract` +- behavioral contract — `CLAUDE.md#
` — marker `context-forge:behavioral-contract` - (or "none") ## Keep-but-verify (CF-1) -- `path/CLAUDE.md:NN` — "" — suspected ; would confirm: | "none" +- `path/CLAUDE.md#
` — "" — suspected ; would confirm: | "none" ``` diff --git a/plugins/context-forge/agents/convention-scout.md b/plugins/context-forge/agents/convention-scout.md index 01768ae..d78716f 100644 --- a/plugins/context-forge/agents/convention-scout.md +++ b/plugins/context-forge/agents/convention-scout.md @@ -1,6 +1,6 @@ --- name: convention-scout -description: Read-only scout for the context-forge skill. Given an analysis root (a repo or one module of a monorepo), it hunts the NON-OBVIOUS — emergent patterns followed across many files with no doc stating them, asymmetries (the one place that deviates), implicit cross-module contracts, and code that looks wrong but is load-bearing — each grounded in multi-site path:line evidence. It deliberately does NOT re-list rules already stated in docs or enforced by CI (those become one-line pointers). Never writes; never asserts a pattern it cannot ground in real code sites. +description: Read-only scout for the context-forge skill. Given an analysis root (a repo or one module of a monorepo), it hunts the NON-OBVIOUS — emergent patterns followed across many files with no doc stating them, asymmetries (the one place that deviates), implicit cross-module contracts, and code that looks wrong but is load-bearing — each grounded in multi-site, content-anchored evidence (path#anchor — a grep-resolvable symbol/heading, module-qualified from the repo root, line only an optional hint). It deliberately does NOT re-list rules already stated in docs or enforced by CI (those become one-line pointers). Never writes; never asserts a pattern it cannot ground in real code sites. tools: Glob, Grep, Read model: inherit readonly: true @@ -34,6 +34,21 @@ A finding is grounded when it rests on **real code sites you read**, in one of t Anything you suspect but cannot ground this way is a **question or candidate**, never a finding. Report it under `## Ask the human` or `## Candidates`, phrased as a question. +## How to cite (content-anchored — CF-N13) + +Cite every site as **`path#anchor`**, never a bare `path:line`: + +- `path` is **repo-root-relative** and, in a monorepo, **module-qualified** — so the same relative shape + under different tenants/modules is never ambiguous (`services/billing/pool.go`, not `pool.go`). +- `anchor` is a **stable, grep-resolvable** handle: a symbol (function/type/const/method), a migration id, + or a doc heading — or, only when no symbol fits, a **short unique quoted snippet**. +- A line number is optional and **approximate**: append it as `(~L)`, never as the citation's identity. +- If your anchor resolves at **more than one** site, qualify the path further until it's unique, or say so + (`ambiguous across N tenants`) — an unqualified multi-site anchor is not valid grounding. + +This keeps a citation valid as the code churns: it stays resolvable when edits shift line numbers, and only +breaks when the symbol itself is renamed or removed — which is exactly when the orchestrator *should* re-check. + ## Method 1. **Map languages & modules.** Glob package manifests at root and 1–2 levels down (`go.mod`/ @@ -80,7 +95,7 @@ Report it under `## Ask the human` or `## Candidates`, phrased as a question. read by no code, a CLAUDE.md-promised behavior (a retry loop, a limit, a guard, a dependency call) with no implementation, an orphaned module nothing imports, a write-dead column. These are the findings an agent trusting the docs gets *wrong*. Report each with the doc claim, the code reality, - and a `path:line` (or "grep found zero call sites"). Do **not** phrase them as rules — they are + and a `path#anchor` (or "grep found zero call sites"). Do **not** phrase them as rules — they are defects for the orchestrator's findings log (CF-N9), not governance. 7. **Pointers, not restatements.** For rules the repo already states (docs) or enforces (CI/lint), @@ -109,16 +124,16 @@ its citations. Prefer 12 sharp findings over 40 shallow ones. - `` — — (or "single module: ") ## Emergent patterns (undocumented, multi-site) -- — sites: `path:line`, `path:line`, … (N=) [inherited? y/n] +- — sites: `path#anchor (~Lnn)`, `path#anchor`, … (N=) [inherited? y/n] Wrong default an agent would pick: - (or "none grounded") ## Asymmetries (the exception to a pattern) -- Norm: (`path:line`×N). Deviant: `path:line` — looks : +- Norm: (`path#anchor`×N). Deviant: `path#anchor` — looks : - (or "none found") ## Cross-module contracts -- — producer `path:line` → consumer `path:line`; breaks if +- — producer `path#anchor` → consumer `path#anchor`; breaks if - (or "none found") ## Ask the human (looks-wrong-but-intentional / unresolved why) @@ -126,11 +141,11 @@ its citations. Prefer 12 sharp findings over 40 shallow ones. - (or "none") ## Documentation drift & dead code (defects — NOT rules) -- — but code: — `path:line` (or "zero call sites") [kind: doc-lie | dead-config | dead-code | write-dead | latent-bug] +- — but code: — `path#anchor` (or "zero call sites") [kind: doc-lie | dead-config | dead-code | write-dead | latent-bug] - (or "none") ## Pointers (already stated/enforced — do NOT restate as rules) -- — `path:line` +- — `path#anchor` - (or "none") ## Existing governance diff --git a/plugins/context-forge/skills/context-constitution/SKILL.md b/plugins/context-forge/skills/context-constitution/SKILL.md index ba50cae..c43fcfb 100644 --- a/plugins/context-forge/skills/context-constitution/SKILL.md +++ b/plugins/context-forge/skills/context-constitution/SKILL.md @@ -1,6 +1,6 @@ --- name: context-constitution -description: "Capture the undocumented rules of a codebase — conventions nobody wrote down, the one file that breaks the pattern, and the scars behind them — into an evidence-cited context-constitution.md, plus a behavioral contract prepended to CLAUDE.md. Use when the user wants to write, generate, bootstrap, or improve a CLAUDE.md / AGENTS.md / agent instructions file; document a repo's conventions, house style, or tribal knowledge; onboard an agent to an unfamiliar or inherited codebase; or fix an agent that 'keeps making the same mistake', 'doesn't know how we do things here', or 'has to be told the same thing every session'. Also for 'our CLAUDE.md is out of date / has drifted' — that's `refresh`. Usage: `context-constitution [scan|write|refresh] [path]`; `scan` writes nothing. Every rule cites path:line; nothing is invented." +description: "Capture the undocumented rules of a codebase — conventions nobody wrote down, the one file that breaks the pattern, and the scars behind them — into an evidence-cited context-constitution.md, plus a behavioral contract prepended to CLAUDE.md. Use when the user wants to write, generate, bootstrap, or improve a CLAUDE.md / AGENTS.md / agent instructions file; document a repo's conventions, house style, or tribal knowledge; onboard an agent to an unfamiliar or inherited codebase; or fix an agent that 'keeps making the same mistake', 'doesn't know how we do things here', or 'has to be told the same thing every session'. Also for 'our CLAUDE.md is out of date / has drifted' — that's `refresh`. Usage: `context-constitution [scan|write|refresh] [path]`; `scan` writes nothing. Every rule cites a stable content anchor (path#anchor, line an optional hint); nothing is invented." argument-hint: "[scan|write] [path]" allowed-tools: Read Write Edit AskUserQuestion Task Bash(ls *) Bash(find *) Bash(grep *) Bash(cat *) Bash(git log *) Bash(git show *) Bash(git rev-parse *) Bash(git merge-base *) mcp__Context7__resolve-library-id mcp__Context7__query-docs disable-model-invocation: true @@ -143,8 +143,9 @@ Read **`reference/synthesis-protocol.md`** and follow it. Per target (each modul 3. **Dedup up the tree (CF-N3).** A rule that holds repo-wide belongs in the **root** constitution; a module constitution states only what is specific to that module and *points to* the root for inherited rules — never restates them. Cross-module contracts and repo-wide defects live at the root. -4. **Evidence or candidate (CF-1).** Every emitted rule cites `path:line` (or a commit). Anything - plausible but unverified goes under `## Candidate rules (unverified)`, never asserted. +4. **Evidence or candidate (CF-1).** Every emitted rule cites a **content anchor** — `path#anchor`, a + stable symbol/heading grep resolves, with the line only an optional `(~Lnn)` hint (**CF-N13**) — or a + commit. Anything plausible but unverified goes under `## Candidate rules (unverified)`, never asserted. 5. **Build the behavioral contract** from `templates/behavioral-contract.md` (the canonical block — single source); `reference/synthesis-protocol.md` Step 6 covers the `citeIds` variant. If `citeIds` is on and this target produced a constitution, each behavior cites the IDs that enforce it; @@ -184,7 +185,8 @@ Only after Approve, and never in `scan` mode. Per target: date + branch + commit provenance ref as the constitution. Skip the file only when the target has zero defects — never manufacture an empty one. If a findings log already exists for this target, first run the staleness re-check on its open rows (same method as `refresh-protocol.md` - Phase 0′ step 3: re-resolve each cited `path:line`/doc claim against current code) and move any that + Phase 0′ step 3: re-resolve each cited **anchor**/doc claim against current code — the anchor, not a + line number (**CF-N13**)) and move any that no longer reproduce to `## Resolved`, dated, with how it was confirmed — don't just append on top of stale rows. 5. **Findings triage gate (CF-N12).** If this run added any *new* findings-log rows, run one triage diff --git a/plugins/context-forge/skills/context-constitution/reference/principles.md b/plugins/context-forge/skills/context-constitution/reference/principles.md index c84fd41..0081035 100644 --- a/plugins/context-forge/skills/context-constitution/reference/principles.md +++ b/plugins/context-forge/skills/context-constitution/reference/principles.md @@ -40,9 +40,10 @@ skill to *resolve* it, or stop. A departure from a Norm must be answered (a fix, or a recorded, user-waived trade-off). -- **CF-N1 — Evidence-cited rules.** Every binding rule cites the `path:line` where the repo already - states or enforces it (a doc line, a CI step, a lint config, a branch/migration convention). A - rule with no home in the repo is a candidate, not a rule (see **CF-1**). +- **CF-N1 — Evidence-cited rules.** Every binding rule cites the **content anchor** (see **CF-N13**) + where the repo already states or enforces it (a doc line, a CI step, a lint config, a + branch/migration convention). A rule with no home in the repo is a candidate, not a rule + (see **CF-1**). - **CF-N2 — Behavior vs. fact separation.** The behavioral contract holds only the four repo-agnostic *behaviors* — how the agent should act. Repo-specific *facts* (build commands, ports, naming schemes, hard rules) stay in the constitution and the body of `CLAUDE.md`. Never fatten the @@ -88,8 +89,8 @@ A departure from a Norm must be answered (a fix, or a recorded, user-waived trad alignment contract) is a constitution rule or gotcha. A **defect** — a latent bug, dead/orphaned code, an unused config key, or **documentation that describes behavior the code does not have** — is NOT a rule (you don't govern "the audit route has an auth gap"); it goes to the **findings log** - (`context-constitution-findings.md`, sibling to the constitution) with its `path:line`/commit citation and a - suggested action, so it is actioned rather than frozen into governance. Both are durable outputs; + (`context-constitution-findings.md`, sibling to the constitution) with its **content-anchored** citation + (**CF-N13**) or commit and a suggested action, so it is actioned rather than frozen into governance. Both are durable outputs; neither is dropped. **The scrubber honors this in reverse:** a *contradicted-by-code* line that is such a defect (documented behavior the code lacks — a dead config key, a fictional dependency, an unimplemented event, a promised safety/risk control) is **routed** to the findings log and deferred to @@ -125,3 +126,25 @@ A departure from a Norm must be answered (a fix, or a recorded, user-waived trad and dismissed rows stay in the file, dated and reasoned; they just leave the *open* sections a human is meant to action. A resolved/dismissed disposition requires an actual re-check or an actual human answer, never a guess (**CF-1**). +- **CF-N13 — Citations are content-anchored, not line-keyed.** A raw `path:line` rots the instant any + edit lands above it, and in a large multi-tenant repo the *same* relative path shape recurs under many + tenants/modules, so a bare path + line is both fragile and ambiguous — the churn (and false-positive + "stale" flags) this toolkit exists to prevent. So every code citation an artifact emits names a **stable + content anchor**: a symbol grep can resolve (a function, type, const, migration id) or a doc heading, or + — only when no symbol fits — a **short unique quoted snippet**. Write it `path#anchor`, with `path` + **repo-root-relative and module-qualified** (never a tenant-ambiguous relative shape). A line number is + only ever an **approximate, regenerable hint**, appended as `(~L)` — never the citation's identity. + Consequences that bind both skills: + - **Staleness is anchor-resolution, not line-match.** A citation is **stale only when its anchor no + longer resolves** (renamed/deleted symbol, grep zero hits), never when the `~L` hint merely drifted. + A drifted hint is re-stamped in place as metadata (like the header provenance line) — not a rule + change (**CF-4**) and not a scrubber finding. This is the single change that stops constant re-flagging + in a churning repo. + - **Ambiguity is disambiguated or deduped, never guessed.** When an anchor resolves at **multiple** + sites, the citation carries the module-qualified path that singles one out (or the rule is deduped up + the tree, **CF-N3**). An unqualified anchor that resolves in more than one tenant is itself a citation + defect to fix, not valid grounding (**CF-1**). + - **Legacy citations stay valid input.** A pre-existing `path:line` is read as before; a `refresh` / + re-audit **re-grounds** it to `path#anchor` when it next touches that row, and treats a legacy + line-only citation whose file still exists but whose line drifted as **re-ground the anchor**, never + **retire**. Multi-site (`×N`) evidence anchors each of the N sites the same way. diff --git a/plugins/context-forge/skills/context-constitution/reference/refresh-protocol.md b/plugins/context-forge/skills/context-constitution/reference/refresh-protocol.md index e2f48a0..106e96e 100644 --- a/plugins/context-forge/skills/context-constitution/reference/refresh-protocol.md +++ b/plugins/context-forge/skills/context-constitution/reference/refresh-protocol.md @@ -68,12 +68,17 @@ For each in-scope target `T`, resolve `R` from git as above, then: touching the changed files. It may still report a pattern spanning changed + unchanged sites — changes often *reveal* an existing invariant. 3. **Staleness check (always — this is the correctness net).** For every rule already in `T`'s - `context-constitution.md`, verify each cited `path:line` still resolves to the referenced code (Read/Grep). - A citation that no longer resolves flags the rule **stale**. A rule whose sites still resolve but + `context-constitution.md`, verify each cited **anchor still resolves** by grepping the symbol/heading + (or quoted snippet) — **CF-N13**, never by checking the `~L` line hint. A citation whose anchor no + longer resolves (renamed/deleted, grep zero hits) flags the rule **stale**; a citation whose anchor + still resolves but whose `~L` hint drifted is **current** — silently re-stamp the hint in place + (metadata, not a CF-4 rule change) and do **not** flag it. A legacy line-only `path:line` (forged + before this contract) whose file still exists but whose line drifted is **re-grounded to `path#anchor`** + from the code it still describes, never retired. A rule whose sites still resolve but whose count dropped below the induction bar (e.g. a 9/9 pattern is now 3/9) flags **weakening**. This runs even when the change set is empty, so drift is caught no matter where R landed. **Same check extends to `context-constitution-findings.md`, if `T` has one (CF-N12):** for every open - row under Documentation-that-lies / Latent bugs / Dead-or-orphaned-code, re-resolve its citation and + row under Documentation-that-lies / Latent bugs / Dead-or-orphaned-code, re-resolve its **anchor** and re-check its claim against current code — a doc-lie row where the code now implements the promised behavior (or the false doc line is gone), a latent bug whose site no longer reproduces it, or dead code that's since been wired up all flag **findings-resolved**. A row stays open unless its citation @@ -90,8 +95,9 @@ Per changed target, produce a **delta report** rather than a whole new file: - **Added** — new grounded rules from changed/emergent patterns (assign the *next* free IDs in the target's existing scheme; never renumber existing rules — **CF-4, CF-N5**). -- **Stale** — existing rules whose citations no longer resolve. Proposed action: retire, or re-ground - to the moved code if the scout found it. +- **Stale** — existing rules whose **anchor** no longer resolves (**CF-N13**; a drifted `~L` hint is not + stale — it is re-stamped, not reported). Proposed action: retire, or re-ground the anchor to the moved + code if the scout found it. - **Weakening** — rules whose evidence thinned; proposed action: demote a tier, or keep with a note. - **Resolved candidates** — prior `## Candidate rules (unverified)` entries the new evidence now grounds (promote) or refutes (drop). @@ -161,8 +167,8 @@ modify the repo — and since it needs no stored state, it works on any checkout interchangeable and never trusts a ref git can't confirm. - **Staleness is the correctness net, the diff is the optimization.** Always run the staleness check, even when the change set is empty. -- **Never invent (CF-1).** A "stale" flag requires a citation that actually failed to resolve, not a - guess; a scar in the window cites its commit. Same for a **findings-resolved** flag (**CF-N12**) — it +- **Never invent (CF-1).** A "stale" flag requires an **anchor** that actually failed to resolve + (**CF-N13**), not a guess and not a merely drifted `~L` hint; a scar in the window cites its commit. Same for a **findings-resolved** flag (**CF-N12**) — it requires the citation to have actually been re-checked against current code, never assumed from an empty diff. - **`check` writes nothing, ever.** diff --git a/plugins/context-forge/skills/context-constitution/reference/scan-protocol.md b/plugins/context-forge/skills/context-constitution/reference/scan-protocol.md index 6b30446..fe3fc13 100644 --- a/plugins/context-forge/skills/context-constitution/reference/scan-protocol.md +++ b/plugins/context-forge/skills/context-constitution/reference/scan-protocol.md @@ -72,6 +72,9 @@ finding earns a durable home. - **Read-only.** The scout has Glob/Grep/Read only. You run only read/inspect git and shell. Nothing in Phase 0 changes the repo. - **Distill, don't dump.** Digests are findings + citations, never file bodies. +- **Citations are content-anchored (CF-N13).** The scout returns `path#anchor` (a grep-resolvable + symbol/heading), module-qualified from the repo root, with the line only an optional `(~Lnn)` hint — + carry those anchors through synthesis unchanged; never re-key a citation on a bare line number. - **Grounded beats plausible.** A pattern "every repo has" that this one doesn't actually follow is a candidate at most. A rationale you didn't read in a commit or hear from the human is a *question*, not a rule. diff --git a/plugins/context-forge/skills/context-constitution/reference/synthesis-protocol.md b/plugins/context-forge/skills/context-constitution/reference/synthesis-protocol.md index d43a602..a0e7ed4 100644 --- a/plugins/context-forge/skills/context-constitution/reference/synthesis-protocol.md +++ b/plugins/context-forge/skills/context-constitution/reference/synthesis-protocol.md @@ -9,7 +9,7 @@ is where judgment lives. You (the orchestrator) do all of it; no subagent writes Before writing anything, clear the scout's `## Ask the human` list — this is where Tier-3 tribal knowledge actually enters the file. For each flagged observation, ask the user (one `AskUserQuestion` batching related items; plain chat under Cursor): "*Found `` at -`` — it looks like `` but appears intentional (``). Is it, and +`` — it looks like `` but appears intentional (``). Is it, and why?*" Record the answer as the rule's **rationale**. If the user doesn't know or says "it's a bug," it becomes a candidate or a noted cleanup — never a rule dressed up as intentional (**CF-1, CF-2**). @@ -72,16 +72,18 @@ the repo's own framing if it has one (**CF-N5**): a scar proves: "never edit an applied migration — PR #412 outage"). - **Rules** — binding patterns an agent must follow to fit in (the undocumented conventions, cross-module contracts). -- **Norms** — defaults/preferences and asymmetry guidance ("follow the `path:line` shape, not the - `path:line` outlier"). +- **Norms** — defaults/preferences and asymmetry guidance ("follow the `path#anchor` shape, not the + `path#anchor` outlier"). Every rule carries: the intent, its **evidence** (multi-site citations, an authoritative site, or a -commit/PR for a scar), and — when known — a one-line **why**. The *why* is what makes it stick; +commit/PR for a scar), and — when known — a one-line **why**. Every code citation is **content-anchored** +per **CF-N13**: `path#anchor` (a symbol/heading grep resolves), module-qualified from the repo root, with +the line only an optional `(~Lnn)` hint — carry the anchors the scout returned, never a bare line number. The *why* is what makes it stick; include it whenever git or the human supplied it. **Designate a canonical example where one exists (few-shot by pointer).** For a Rule or Norm with one site that best demonstrates the pattern — the cleanest "copy this" instance — record it as the rule's -**Example**: a `path:line` **pointer**, not inlined code (a pointer stays cheap and just-in-time — the +**Example**: a `path#anchor` **pointer**, not inlined code (a pointer stays cheap and just-in-time — the agent opens it only when following the rule). Optional per rule: fill it only when a single site clearly shows the shape, and never fabricate one (**CF-1**). Floor rules are prohibitions ("never do X"), so an example is usually pointless — skip it there. The Example is a *pointer among* the evidence, not extra diff --git a/plugins/context-forge/skills/context-constitution/templates/context-constitution.md b/plugins/context-forge/skills/context-constitution/templates/context-constitution.md index 295f718..cb436da 100644 --- a/plugins/context-forge/skills/context-constitution/templates/context-constitution.md +++ b/plugins/context-forge/skills/context-constitution/templates/context-constitution.md @@ -3,6 +3,10 @@ empty section. Keep it dense. Every rule is grounded (multi-site citations, one authoritative site, or a commit/PR) and — where known — carries a one-line *why*. Do NOT restate rules the repo already documents or CI enforces; those are pointers at most. Do not copy this comment into output. + Every code citation is content-anchored — `path#anchor` (a grep-resolvable symbol/heading, + module-qualified from the repo root), with the line only an optional `(~Lnn)` hint, never the + identity (CF-N13). A citation stays valid as lines drift; it goes stale only when its anchor is + renamed or removed. --> # — Constitution @@ -22,7 +26,7 @@ enforces (see `## Pointers`). Refresh by re-running `/context-constitution`. | ID | Rule | Why | Evidence | |---|---|---|---| -| **-01** | | | `path:line`×N / commit / PR | +| **-01** | | | `path#anchor`×N / commit / PR | ## Rules (`-*`) — binding, easy-to-miss conventions @@ -30,15 +34,15 @@ The **Example** column is a *pointer* to the one site that best demonstrates the copy when following it (few-shot by reference, not inlined code). Fill it only when a single site clearly shows the shape; leave it `—` otherwise. Never invent one (**CF-1**). -| ID | Rule | Why | Evidence | Example (canonical `path:line`) | +| ID | Rule | Why | Evidence | Example (canonical `path#anchor`) | |---|---|---|---|---| -| **-NN** | | | `path:line`, `path:line`, … | `path:line` (copy this) / — | +| **-NN** | | | `path#anchor`, `path#anchor`, … | `path#anchor` (copy this) / — | ## Norms (`-*`) — defaults & asymmetry guidance -| ID | Norm | Why | Evidence | Example (canonical `path:line`) | +| ID | Norm | Why | Evidence | Example (canonical `path#anchor`) | |---|---|---|---|---| -| **-NN** | | | `path:line` (norm) vs `path:line` (outlier) | `path:line` (the shape to follow) / — | +| **-NN** | | | `path#anchor` (norm) vs `path#anchor` (outlier) | `path#anchor` (the shape to follow) / — | ## Gotchas & scars @@ -46,7 +50,7 @@ Tier-3 knowledge that isn't a rule so much as a landmine map — *why* a thing t intentional, and what broke when someone "fixed" it. Each cites the code and the commit/PR/human answer it came from. -- **** — . Evidence: `path:line` + . +- **** — . Evidence: `path#anchor` + . - (or "_None recovered._") ## Candidate rules (unverified) @@ -61,7 +65,7 @@ Plausible but not yet grounded — confirm or drop before treating as binding. | What | Where | |---|---| -| | `path:line` | +| | `path#anchor` | diff --git a/plugins/context-forge/skills/context-constitution/templates/findings.md b/plugins/context-forge/skills/context-constitution/templates/findings.md index 278df71..6a8a574 100644 --- a/plugins/context-forge/skills/context-constitution/templates/findings.md +++ b/plugins/context-forge/skills/context-constitution/templates/findings.md @@ -3,6 +3,8 @@ fix, not an invariant to respect (CF-N9). Written as /context-constitution-findings.md, sibling to the constitution, per target (root + each module). Nothing the scout grounded is dropped (CF-N8): if it isn't a rule/pointer/gotcha/candidate, it lands here. Scratch mode emits it inline. + Every citation is content-anchored — `path#anchor` (a grep-resolvable symbol/heading, module-qualified + from the repo root), the line only an optional `(~Lnn)` hint, never the identity (CF-N13). Do not copy this comment into the output. --> # — Constitution Findings @@ -24,19 +26,19 @@ open, or dismiss with a recorded reason to `## Dismissed (won't fix)`) instead o | What the docs say | What the code does | Evidence | Suggested action | |---|---|---|---| -| | | `path:line` or "zero call sites" | fix the code, or correct the doc | +| | | `path#anchor` or "zero call sites" | fix the code, or correct the doc | ## Latent bugs (looks broken, not merely non-obvious) | Issue | Impact | Evidence | |---|---|---| -| | | `path:line` (+ commit if a regression) | +| | | `path#anchor` (+ commit if a regression) | ## Dead / orphaned code | What | Why it looks dead | Evidence | |---|---|---| -| | | `path:line` (+ "grep: zero call sites") | +| | | `path#anchor` (+ "grep: zero call sites") | ## Open questions (unresolved *why* — needs a maintainer) @@ -54,7 +56,7 @@ from scratch, it is reported again rather than assumed still-dismissed. | What the docs say / issue | Evidence | Dismissed | Reason | |---|---|---|---| -| | `path:line` | | | +| | `path#anchor` | | | ## Resolved @@ -63,7 +65,7 @@ never assumed from an empty diff or a stale citation going unresolved. | What the docs say / issue | Evidence (was) | Resolved | How confirmed | |---|---|---|---| -| | `path:line` | | | +| | `path#anchor` | | | diff --git a/plugins/context-forge/skills/context-scrubber/SKILL.md b/plugins/context-forge/skills/context-scrubber/SKILL.md index 03bb5e4..5b06166 100644 --- a/plugins/context-forge/skills/context-scrubber/SKILL.md +++ b/plugins/context-forge/skills/context-scrubber/SKILL.md @@ -10,8 +10,11 @@ miss on a normal read; you *find and report* the low-signal content already sitt the lines that **fail the litmus test** (**CF-N4**) and cost tokens on every load without changing how the agent works. You audit seven kinds of failing content: -- **Stale citations** — a `path:line` the context file cites that no longer resolves (file moved/deleted, or the - line drifted off the cited code). +- **Stale citations** — a citation whose **content anchor** no longer resolves (the symbol/heading was renamed or + deleted, or the file moved/is gone — grep finds nothing). A citation whose anchor still resolves but whose + `~L` line hint merely drifted is **not** stale (**CF-N13**): the hint is regenerable metadata, so a bare + line-number drift is never a finding — that is the false-positive this toolkit must not manufacture in a + churning multi-tenant repo. - **Restated facts an agent reads for free** — a line that just repeats what's plain in the single file an agent would edit, a manifest/dependency list, or a doc/CI file it already loads. - **Cross-file duplication** — the same rule/fact stated in more than one context file (violates dedup-up-the-tree, @@ -39,9 +42,9 @@ first, and any in-place trim happens only behind an explicit gate. confirm its verdicts yourself and produce the findings file. **Never invent (CF-1).** Every "fails the litmus test" verdict cites the evidence that makes it fail — the -free-to-read `path:line`, the contradicting site, a duplicate location, or a citation that provably no longer -resolves. A line you merely *suspect* is low-value, with no such basis, is `keep-but-verify` — never asserted as -removable. +free-to-read `path#anchor`, the contradicting site, a duplicate location, or a citation whose **anchor** provably +no longer resolves (not a merely drifted `~L` hint — **CF-N13**). A line you merely *suspect* is low-value, with +no such basis, is `keep-but-verify` — never asserted as removable. **Interactive gates.** Every gate uses one structured multiple-choice prompt — the `AskUserQuestion` tool in Claude Code. Where that tool isn't available (e.g. under Cursor), ask the same question, with the same options, in @@ -133,11 +136,12 @@ the repo (symlinked to a shared/global library) are excluded — not the repo's Read **`reference/audit-protocol.md`** and follow it. In short: hand the discovered target list to a `context-auditor` subagent (Agent tool). For a large repo or a monorepo with many context files, spawn one auditor **per file cluster in parallel** (one message, multiple Task calls), each returning a scoped digest. Each -verdict ties a context line (`file:line`) to exactly one of the five categories, plus the **evidence it fails** +verdict ties a context line (`file#anchor`) to exactly one of the five categories, plus the **evidence it fails** and a suggested action. Then **you confirm every verdict yourself** before it can enter the findings file (**CF-1, CF-3**): resolve a -claimed-stale `path:line` against the tree, open the contradicting site, confirm a duplicate actually matches — +claimed-stale citation by grepping its **anchor** across the tree (never by checking a line number — **CF-N13**), +open the contradicting site, confirm a duplicate actually matches — no verdict is auditor's-word-only. The auditor is read-only and never writes; you are the only writer. Present a 4–8 line summary: files audited, count of failing lines by category, and the `keep-but-verify` count. @@ -152,8 +156,8 @@ in scratch mode). Its header records the audit date plus the branch + commit thi 1. **No silent drops (CF-N8).** Every confirmed verdict lands under its category section; confidence ranks a finding *within* the report (higher-token / higher-certainty first), it never deletes one. An ungrounded suspicion lands under `## Keep-but-verify`, phrased as a question — never asserted as removable (**CF-1**). -2. **One row per failing context line**, cited on both sides: the context `file:line`, the evidence it fails - (the free-to-read `path:line`, the contradicting site, the duplicate location, or — for *just-in-time* and +2. **One row per failing context line**, cited on both sides: the context `file#anchor`, the evidence it fails + (the free-to-read `path#anchor`, the contradicting site, the duplicate location, or — for *just-in-time* and *brittle* — the reason it's mis-placed or over-specified), the category, why it fails, and a suggested action — `remove` / `trim` / `move-to-` (just-in-time) / `trim to a heuristic` (brittle) / `keep-but-verify`. A *just-in-time* row's action leaves a pointer behind (it relocates, it doesn't delete); a *brittle* row keeps diff --git a/plugins/context-forge/skills/context-scrubber/reference/apply-protocol.md b/plugins/context-forge/skills/context-scrubber/reference/apply-protocol.md index 5956477..f84a298 100644 --- a/plugins/context-forge/skills/context-scrubber/reference/apply-protocol.md +++ b/plugins/context-forge/skills/context-scrubber/reference/apply-protocol.md @@ -17,7 +17,8 @@ triage (**CF-N9**), not lines this skill deletes. From the approved rows, assemble a per-file edit set: for each target file, the exact lines to remove or shorten, located by **content** (quote the current line), not by a bare line number — line numbers drift as edits land, and -content-anchored edits stay correct. Group by file so each file is opened once. Exclude, up front: +content-anchored edits stay correct (the same **CF-N13** principle the citations follow). Group by file so each +file is opened once. Exclude, up front: - any line inside a `context-forge:*` / `constitution-forge:*` sentinel span (**CF-N11** — off-limits); - **every contradicted-by-code row** (a defect deferred to `/context-constitution`'s findings log, **CF-N9** — diff --git a/plugins/context-forge/skills/context-scrubber/reference/audit-protocol.md b/plugins/context-forge/skills/context-scrubber/reference/audit-protocol.md index be65f94..ff85dea 100644 --- a/plugins/context-forge/skills/context-scrubber/reference/audit-protocol.md +++ b/plugins/context-forge/skills/context-scrubber/reference/audit-protocol.md @@ -13,10 +13,10 @@ grounded in real evidence (**CF-1**): | Category | What it is | Grounded by | |---|---|---| -| **Stale citation** | a `path:line` the context file cites that no longer resolves | the citation fails to resolve (Read/Grep/ls found nothing there) | -| **Restated (fails CF-N4)** | a fact plain in the one file an agent would edit, a manifest, or a doc/CI file it already loads | the free-to-read `path:line` that makes it redundant | +| **Stale citation** | a citation whose **content anchor** no longer resolves (**CF-N13**) — symbol/heading renamed or deleted, file moved/gone. A merely drifted `~L` line hint is **not** stale | grepping the anchor finds nothing (Read/Grep/ls) — never a line-number mismatch | +| **Restated (fails CF-N4)** | a fact plain in the one file an agent would edit, a manifest, or a doc/CI file it already loads | the free-to-read `path#anchor` that makes it redundant | | **Cross-file duplication (CF-N3)** | the same rule/fact in ≥2 context files | every duplicate location + which copy is highest in the tree | -| **Contradicted by code** | a context claim the code now disproves | the contradicting `path:line` | +| **Contradicted by code** | a context claim the code now disproves | the contradicting `path#anchor` | | **Should be just-in-time** | accurate but *pre-loaded* content that belongs behind a pointer to an on-demand doc — task-specific/rarely-needed detail that costs tokens on every load | the content is narrow/rarely-needed and an on-demand home exists or should; **not** a duplicate (that's cross-file) — it's *misplaced*, not redundant | | **Brittle / over-specified (anti-altitude)** | a long if-else / step-by-step instruction block that should be a heuristic — it shapes behavior but too rigidly, and rots as the code moves | the block enumerates cases/steps a strong one-line heuristic would cover; **not** filler (that's bloat) — it *does* steer the agent, just brittly | | **Bloat / low-value prose** | verbose filler that shapes no agent action | — (judgment; mark lower-confidence, never assert removal without a clear reason) | @@ -34,8 +34,9 @@ get to make silently: a dead config key or an unimplemented event may be an inte limit, an approval flow), and deleting the row buries the spec. So a contradicted verdict is **reported and deferred to `/context-constitution`** (its findings log owns the fix-vs-remove call), carried as `keep-but-verify` in this report — it is **excluded from the removable total and is never an `apply` candidate**. -The only line-level correction the scrubber suggests here is a pure *re-ground* (a drifted `path:line`), and even -that is a `/context-constitution` refresh job, not a scrubber trim. +The only line-level correction the scrubber suggests here is a pure *re-ground* (an anchor whose code moved, or a +legacy `path:line` to re-anchor — **CF-N13**), and even that is a `/context-constitution` refresh job, not a +scrubber trim. Plus two **file-level** signals (not per-line rows), both advisory — each points at what to review, never an automatic removal: @@ -99,9 +100,11 @@ blocks it found (so the report can note them) but never classifies a line inside The auditor is advisory; **you** are the only writer, and no verdict enters the findings file on the auditor's word alone. For each returned verdict, do the cheap confirmation: -- **Stale citation** — try to resolve the cited `path:line` yourself (Read the file at that line, or Grep for the - referenced symbol). Confirmed only if it genuinely doesn't resolve. If the code merely *moved*, note the new - location so the suggested action can be "re-ground to `path:line`" rather than "remove." +- **Stale citation** — try to resolve the cited **anchor** yourself by grepping its symbol/heading (or quoted + snippet) across the tree — **CF-N13**, never by reading a line number. Confirmed stale only if the anchor + genuinely resolves nowhere. If the anchor still resolves but its `~L` hint drifted, it is **not** stale — drop + it from the failing set (at most a silent hint re-stamp, owned by `/context-constitution`). If the code merely + *moved* (anchor now elsewhere), note the new location so the action is "re-ground to `path#anchor`" not "remove." - **Restated** — open the free-to-read source the auditor named and confirm it truly makes the context line redundant for an agent editing that file. - **Duplication** — read both sites and confirm they state the same thing; pick the keeper (highest in the tree — @@ -125,7 +128,7 @@ the git state this audit reflects — branch `git rev-parse --abbrev-ref HEAD` a reports `detached HEAD`, a non-git tree reports `unknown`). Every confirmed verdict lands in exactly one category section; each `keep-but-verify` lands in that section. Nothing grounded is discarded — the report is the durable home for everything the audit paid to find. One row per failing context line, cited on **both** sides (the context -`file:line` and the evidence it fails), with the category, a one-line why, and a suggested action +`file#anchor` and the evidence it fails), with the category, a one-line why, and a suggested action (`remove` / `trim` / `move-to-` / `keep-but-verify`). **Protected blocks** get their own transparency section (`## Protected blocks (reported, never trimmed)`) listing @@ -182,7 +185,7 @@ continue to `apply-protocol.md`. - **Read-only until the gate.** Phase 0 spawns read-only auditors and does read/inspect confirmation only; nothing is written before the Phase 1 gate, nothing trimmed before the Phase 2 gate. -- **Distill, don't dump.** Digests and rows are `file:line` + a one-line reason + a citation, never pasted file +- **Distill, don't dump.** Digests and rows are `file#anchor` + a one-line reason + a citation, never pasted file bodies. - **Grounded beats plausible.** A "stale"/"restated"/"contradicted" verdict requires the confirming evidence in hand; a hunch is `keep-but-verify`, phrased as a question. diff --git a/plugins/context-forge/skills/context-scrubber/reference/principles.md b/plugins/context-forge/skills/context-scrubber/reference/principles.md index c84fd41..0081035 100644 --- a/plugins/context-forge/skills/context-scrubber/reference/principles.md +++ b/plugins/context-forge/skills/context-scrubber/reference/principles.md @@ -40,9 +40,10 @@ skill to *resolve* it, or stop. A departure from a Norm must be answered (a fix, or a recorded, user-waived trade-off). -- **CF-N1 — Evidence-cited rules.** Every binding rule cites the `path:line` where the repo already - states or enforces it (a doc line, a CI step, a lint config, a branch/migration convention). A - rule with no home in the repo is a candidate, not a rule (see **CF-1**). +- **CF-N1 — Evidence-cited rules.** Every binding rule cites the **content anchor** (see **CF-N13**) + where the repo already states or enforces it (a doc line, a CI step, a lint config, a + branch/migration convention). A rule with no home in the repo is a candidate, not a rule + (see **CF-1**). - **CF-N2 — Behavior vs. fact separation.** The behavioral contract holds only the four repo-agnostic *behaviors* — how the agent should act. Repo-specific *facts* (build commands, ports, naming schemes, hard rules) stay in the constitution and the body of `CLAUDE.md`. Never fatten the @@ -88,8 +89,8 @@ A departure from a Norm must be answered (a fix, or a recorded, user-waived trad alignment contract) is a constitution rule or gotcha. A **defect** — a latent bug, dead/orphaned code, an unused config key, or **documentation that describes behavior the code does not have** — is NOT a rule (you don't govern "the audit route has an auth gap"); it goes to the **findings log** - (`context-constitution-findings.md`, sibling to the constitution) with its `path:line`/commit citation and a - suggested action, so it is actioned rather than frozen into governance. Both are durable outputs; + (`context-constitution-findings.md`, sibling to the constitution) with its **content-anchored** citation + (**CF-N13**) or commit and a suggested action, so it is actioned rather than frozen into governance. Both are durable outputs; neither is dropped. **The scrubber honors this in reverse:** a *contradicted-by-code* line that is such a defect (documented behavior the code lacks — a dead config key, a fictional dependency, an unimplemented event, a promised safety/risk control) is **routed** to the findings log and deferred to @@ -125,3 +126,25 @@ A departure from a Norm must be answered (a fix, or a recorded, user-waived trad and dismissed rows stay in the file, dated and reasoned; they just leave the *open* sections a human is meant to action. A resolved/dismissed disposition requires an actual re-check or an actual human answer, never a guess (**CF-1**). +- **CF-N13 — Citations are content-anchored, not line-keyed.** A raw `path:line` rots the instant any + edit lands above it, and in a large multi-tenant repo the *same* relative path shape recurs under many + tenants/modules, so a bare path + line is both fragile and ambiguous — the churn (and false-positive + "stale" flags) this toolkit exists to prevent. So every code citation an artifact emits names a **stable + content anchor**: a symbol grep can resolve (a function, type, const, migration id) or a doc heading, or + — only when no symbol fits — a **short unique quoted snippet**. Write it `path#anchor`, with `path` + **repo-root-relative and module-qualified** (never a tenant-ambiguous relative shape). A line number is + only ever an **approximate, regenerable hint**, appended as `(~L)` — never the citation's identity. + Consequences that bind both skills: + - **Staleness is anchor-resolution, not line-match.** A citation is **stale only when its anchor no + longer resolves** (renamed/deleted symbol, grep zero hits), never when the `~L` hint merely drifted. + A drifted hint is re-stamped in place as metadata (like the header provenance line) — not a rule + change (**CF-4**) and not a scrubber finding. This is the single change that stops constant re-flagging + in a churning repo. + - **Ambiguity is disambiguated or deduped, never guessed.** When an anchor resolves at **multiple** + sites, the citation carries the module-qualified path that singles one out (or the rule is deduped up + the tree, **CF-N3**). An unqualified anchor that resolves in more than one tenant is itself a citation + defect to fix, not valid grounding (**CF-1**). + - **Legacy citations stay valid input.** A pre-existing `path:line` is read as before; a `refresh` / + re-audit **re-grounds** it to `path#anchor` when it next touches that row, and treats a legacy + line-only citation whose file still exists but whose line drifted as **re-ground the anchor**, never + **retire**. Multi-site (`×N`) evidence anchors each of the N sites the same way. diff --git a/plugins/context-forge/skills/context-scrubber/templates/scrubber-findings.md b/plugins/context-forge/skills/context-scrubber/templates/scrubber-findings.md index cbfe8ee..8a3cd47 100644 --- a/plugins/context-forge/skills/context-scrubber/templates/scrubber-findings.md +++ b/plugins/context-forge/skills/context-scrubber/templates/scrubber-findings.md @@ -2,9 +2,11 @@ Template for the context-scrubber findings file — the durable report of every context line that FAILS the litmus test (CF-N4). Written to `scrubberFindingsPath` (default `context-scrubber-findings.md` at the repo root), or emitted inline in scratch mode. Rows are per context line, cited on BOTH sides: the context - `file:line`, and the evidence that it fails. Nothing grounded is dropped (CF-N8); anything unproven is a - `keep-but-verify` question, never asserted (CF-1). Order each section most-costly / most-certain first. - Do not copy this comment into the output. + `file#anchor` (its nearest heading + the quoted line), and the evidence that it fails (`path#anchor`). + Citations are content-anchored, not line-keyed — a citation is stale only when its anchor no longer + resolves, never when a `~L` line hint drifts (CF-N13). Nothing grounded is dropped (CF-N8); anything + unproven is a `keep-but-verify` question, never asserted (CF-1). Order each section most-costly / + most-certain first. Do not copy this comment into the output. --> # Context Scrub — Findings @@ -51,12 +53,13 @@ available this run; otherwise this table shows lines/characters, and any token n ## Stale citations -Citations in a context file that no longer resolve. Action `remove` only if the referenced knowledge is gone; -`re-ground to path:line` if the code merely moved. +Citations whose **content anchor** no longer resolves (**CF-N13**) — the symbol/heading was renamed or deleted, or +the file is gone. A citation whose anchor still resolves but whose `~L` hint merely drifted is **not** listed here. +Action `remove` only if the referenced knowledge is gone; `re-ground to path#anchor` if the code merely moved. | Context line | Citation it makes | Reality | Suggested action | |---|---|---|---| -| `path/CLAUDE.md:NN` — "" | `src/foo.go:120` | file/line no longer exists (grep: zero hits) | remove / re-ground to `src/bar.go:88` | +| `path/CLAUDE.md#
` — "" | `src/foo.go#fooHandler` | anchor no longer exists (grep: zero hits) | remove / re-ground to `src/bar.go#fooHandler` | ## Restated facts (agent reads for free) — fails CF-N4 @@ -65,7 +68,7 @@ loads. | Context line | What restates it (free to read) | Why it fails | Suggested action | |---|---|---|---| -| `CLAUDE.md:NN` — "" | `package.json:12` (the dependency list) | an agent editing here already loads it | remove | +| `CLAUDE.md#
` — "" | `package.json#dependencies` (the dependency list) | an agent editing here already loads it | remove | ## Cross-file duplication — CF-N3 @@ -74,7 +77,7 @@ or go. | Context line | Duplicate location(s) | Which copy to keep | Suggested action | |---|---|---|---| -| `apps/web/CLAUDE.md:NN` — "" | `CLAUDE.md:MM` (root) | root | remove from module / move-to-root | +| `apps/web/CLAUDE.md#
` — "" | `CLAUDE.md#
` (root) | root | remove from module / move-to-root | ## Contradicted by code @@ -85,7 +88,7 @@ from the removable total and **`apply` never deletes it**. ⚠-mark and order se | Context line | What the code does | Evidence | Suggested action | |---|---|---|---| -| ⚠ `CLAUDE.md:NN` — "" | no such validation runs | `src/auth.go:40` | route to findings log — implement the check, or remove the claim (via `/context-constitution`); never `apply`-deleted | +| ⚠ `CLAUDE.md#
` — "" | no such validation runs | `src/auth.go#authMiddleware` | route to findings log — implement the check, or remove the claim (via `/context-constitution`); never `apply`-deleted | ## Should be just-in-time (pre-loaded → pointer) @@ -94,7 +97,7 @@ rarely-needed detail that costs tokens every load. Misplaced, not redundant: rel | Context line(s) | Why it's mis-placed (narrow / rarely-needed) | On-demand home | Suggested action | |---|---|---|---| -| `CLAUDE.md:NN–MM` — "" | only relevant when touching `payments/`; loaded on every task | `payments/README.md` | move-to-`payments/README.md` + pointer | +| `CLAUDE.md#
` — "" | only relevant when touching `payments/`; loaded on every task | `payments/README.md` | move-to-`payments/README.md` + pointer | ## Brittle / over-specified (anti-altitude) @@ -103,7 +106,7 @@ heuristic would cover, and that rots as the code moves. Keep the intent as a heu | Context line(s) | Why it's brittle | Heuristic it should become | Suggested action | |---|---|---|---| -| `CLAUDE.md:NN–MM` — "" | enumerates cases a principle covers | "" | trim to a heuristic | +| `CLAUDE.md#
` — "" | enumerates cases a principle covers | "" | trim to a heuristic | ## Bloat / low-value prose @@ -111,7 +114,7 @@ Verbose filler that shapes no agent action and just spends the context budget. | Context line(s) | Why it is filler | Suggested action | |---|---|---| -| `CLAUDE.md:NN–MM` — "" | narrative with no directive an agent acts on | trim | +| `CLAUDE.md#
` — "" | narrative with no directive an agent acts on | trim | ## Context budget (file-level) @@ -134,16 +137,16 @@ Scanned: `` · excluded as symlinked-out: ``. | Skill (`SKILL.md:line`) | Invocation | What the description is missing | Suggested action | |---|---|---|---| -| `plugins/foo/skills/bar/SKILL.md:3` — "" | model-invocable | no when-to-use clause, no user-facing symptom or trigger phrasing — nothing a request matches | strengthen trigger surface (advisory; never `apply`-trimmed) | -| `.claude/skills/baz/SKILL.md:3` — "" | command-only | bare name-restatement — a human gets no cue for *when* to run it | strengthen trigger surface (advisory; never `apply`-trimmed) | +| `plugins/foo/skills/bar/SKILL.md#description` — "" | model-invocable | no when-to-use clause, no user-facing symptom or trigger phrasing — nothing a request matches | strengthen trigger surface (advisory; never `apply`-trimmed) | +| `.claude/skills/baz/SKILL.md#description` — "" | command-only | bare name-restatement — a human gets no cue for *when* to run it | strengthen trigger surface (advisory; never `apply`-trimmed) | ## Keep-but-verify (unconfirmed — CF-1) Suspected low-signal, but not grounded by evidence in this pass. Confirm before treating as removable — never trimmed by `apply`. -- `path/CLAUDE.md:NN` — "" — suspected ; what would confirm it: — status: **unverified** +- `path/CLAUDE.md#
` — "" — suspected ; what would confirm it: — status: **unverified** ## Protected blocks (reported, never trimmed) @@ -153,8 +156,8 @@ Sentinel-wrapped blocks owned by `/context-constitution` — listed for transpar | Block | Location | Marker | |---|---|---| -| behavioral contract | `CLAUDE.md:NN–MM` | `context-forge:behavioral-contract` | -| constitution pointer | `path/CLAUDE.md:NN–MM` | `context-forge:constitution-pointer` | +| behavioral contract | `CLAUDE.md` (by marker) | `context-forge:behavioral-contract` | +| constitution pointer | `path/CLAUDE.md` (by marker) | `context-forge:constitution-pointer` |