diff --git a/plugins/context-forge/.claude-plugin/plugin.json b/plugins/context-forge/.claude-plugin/plugin.json index a17db42..7e08834 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.7.0", + "version": "0.8.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 4c328f9..b34b19a 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.7.0", + "version": "0.8.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 a17db42..7e08834 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.7.0", + "version": "0.8.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 96e06aa..bc07814 100644 --- a/plugins/context-forge/README.md +++ b/plugins/context-forge/README.md @@ -49,6 +49,9 @@ Turns a repo's non-obvious knowledge into two durable artifacts: of accumulating unread. - **Handles monorepos**: one constitution + contract **per module**, then a **repo-wide** pass at the root whose special focus is the cross-module contracts. Repo-wide rules live once at the root. +- **Pins the analyzed commit**: each `context-constitution.md` (and its findings log) header records the + date plus the **branch and commit hash** the analysis ran against, so a reader knows exactly which + repo state the rules reflect and `refresh` reruns from a known point. ```shell /context-constitution # full flow: scan → synthesize → (gated) write @@ -58,11 +61,14 @@ Turns a repo's non-obvious knowledge into two durable artifacts: /context-constitution refresh check # CI/linter: report drift, write nothing ``` -`refresh` is the keep-it-current mode: it diffs each target from **git** — the last commit that wrote -that target's `context-constitution.md`, so a manual edit is respected like any other commit — -re-derives only the changed areas, flags rules (and open findings) whose citations went stale, and -applies approved deltas, including retiring resolved findings and gating new ones for triage. -`refresh … check` reports drift and writes nothing, so it is safe in CI. +`refresh` is the keep-it-current mode: it diffs each target from **git** — the older of the last commit +that wrote that target's `context-constitution.md` and the **commit recorded in the file's header**, so +the scan starts from the exact state last analyzed and a cosmetic edit can't shove the baseline past +real code changes (a manual edit is still respected like any other commit; an older constitution with +no header SHA falls back to the last-write commit). It re-derives only the changed areas, flags rules +(and open findings) whose citations went stale, and applies approved deltas, including retiring +resolved findings and gating new ones for triage. `refresh … check` reports drift and writes nothing, +so it is safe in CI. ### Optional: library-doc cross-referencing @@ -94,8 +100,9 @@ what an agent would find for free and is therefore dead weight in an auto-loaded their fix is *adding*, so `apply` never touches them. - **Primary output** is an evidence-cited `context-scrubber-findings.md` — one row per failing line, cited on both sides, with the category, why it fails, and a suggested action - (remove / trim / move / keep-but-verify). Anything unproven is a `keep-but-verify` question, never - asserted (**CF-1**); nothing grounded is dropped (**CF-N8**). + (remove / trim / move / keep-but-verify). Its header records the date plus the **branch and commit + hash** the audit ran against, so the report is pinned to a known repo state. Anything unproven is a + `keep-but-verify` question, never asserted (**CF-1**); nothing grounded is dropped (**CF-N8**). - **Optional gated trim** (`apply` mode): after you approve the findings *and* a second edit-set gate, it trims the approved lines **in place** — non-destructive and sentinel-safe. It never trims inside `context-constitution`'s behavioral-contract or constitution-pointer blocks, and never deletes on its diff --git a/plugins/context-forge/skills/context-constitution/SKILL.md b/plugins/context-forge/skills/context-constitution/SKILL.md index a2a7128..ba50cae 100644 --- a/plugins/context-forge/skills/context-constitution/SKILL.md +++ b/plugins/context-forge/skills/context-constitution/SKILL.md @@ -2,7 +2,7 @@ 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." 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 *) mcp__Context7__resolve-library-id mcp__Context7__query-docs +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 --- @@ -162,7 +162,11 @@ Only after Approve, and never in `scan` mode. Per target: 1. **Constitution.** If none exists at `constitutionPath`, write it from the synthesized content. If one exists, **merge** (**CF-4**): keep every existing rule and ID, append newly-found rules under - their tier, and show the user the added lines — never rewrite or renumber existing rules. + their tier, and show the user the added lines — never rewrite or renumber existing rules. Either + way, stamp the header's provenance line with the date **and** the branch + commit captured in + Phase 0 (scan-protocol step 5) — the repo state this analysis reflects. On a merge, refresh that + one line in place to the current ref (it is metadata, not a governance rule, so this is not a CF-4 + overwrite); never touch the existing rules. 2. **Behavioral contract — root `CLAUDE.md` only (CF-N11).** Prepend the contract to the **root** target's `CLAUDE.md`, wrapped in `` … `:end`. If the markers are present, **replace the block in place** (never stack a copy); if the root has no @@ -176,7 +180,8 @@ Only after Approve, and never in `scan` mode. Per target: auto-loaded. If the host has a `CLAUDE.md` index/table of what-to-read (a "Context Guide"), add the constitution as a row there instead of a loose line, matching the host's style. 4. **Findings log.** If Step 2b routed any defects here, write/merge them into `context-constitution-findings.md` - beside the constitution (`templates/findings.md`), non-destructively. Skip the file only when the + beside the constitution (`templates/findings.md`), non-destructively — its header carries the same + 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 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 1cd333e..e2f48a0 100644 --- a/plugins/context-forge/skills/context-constitution/reference/refresh-protocol.md +++ b/plugins/context-forge/skills/context-constitution/reference/refresh-protocol.md @@ -5,25 +5,50 @@ as the code evolves, **incrementally** — it re-derives only what changed since constitution was last written, reports drift, and applies only the deltas. It is the mode you'd run periodically or in CI; `refresh … check` is the write-nothing linter form. -## The baseline is git, not stored state +## The baseline is git — the header SHA sharpens it -Refresh keeps **no persisted baseline**. Each target's "last forged" point is simply the last commit -that wrote its `context-constitution.md`: +Refresh keeps **no separate persisted baseline file**. Each target's diff floor is derived from git, +from two signals combined so the result is never less safe than the older one alone: + +- **`R_write`** — the last commit that wrote its `context-constitution.md`: + ``` + R_write = git log -1 --format=%H -- / + ``` +- **`R_head`** — the commit hash recorded in that constitution's own **header provenance line** + (`… at commit `), i.e. the exact repo state the last analysis actually ran against. + +Resolve `R_head` to a full commit and confirm it exists in this checkout (`git rev-parse --verify +--quiet ^{commit}`), then take the floor as the **older (common ancestor) of the two**: ``` -R = git log -1 --format=%H -- / +R = git merge-base R_head R_write # the older of the analyzed point and the last write ``` -This is per-target for free (each file has its own history), survives **manual edits** (a hand-edit + -commit to the constitution advances R naturally — no config to keep in sync), and works in CI / -detached HEAD. If that git query is empty — the constitution was never committed (or doesn't exist) — -there is no baseline: treat the target as a fresh forge (full scan via the normal scan protocol) and -say so. If *nothing* in scope has a committed constitution, tell the user to run `write` first. +and scan `R..HEAD`. Taking the older is the safety property: a purely cosmetic edit to the +constitution advances `R_write` past real code changes, but `R_head` still points at the last commit +*actually analyzed*, so the merge-base floor never lets those changes slip the new-pattern hunt. +Normally `R_head == R_write` (the write commits the file it just analyzed), so the merge-base is just +that commit and the diff is as tight as possible. + +**Fallbacks (backward-compatible — a constitution forged before the header carried a SHA simply has +no `R_head`):** +- `R_head` missing / `unknown` / not resolvable in this checkout (shallow clone, or the commit was + rebased or GC'd away, or a force-push rewrote it) → fall back to `R = R_write` (the prior behavior, + unchanged). +- `R_write` empty — the constitution was never committed (or doesn't exist) → no baseline: treat the + target as a **fresh forge** (full scan via the normal scan protocol) and say so. +- Nothing in scope has a committed constitution → tell the user to run `write` first. + +This stays per-target for free (each file has its own history + its own header), works in CI / +detached HEAD, and still survives **manual edits**: a hand-edit + commit advances `R_write`; if it +didn't also touch the header, `R_head` holds the last tool-analyzed point, so the merge-base simply +scans from there — wider than the manual edit alone, but always safe. The next refresh write restamps +the header to the new HEAD. > Correctness does **not** depend on R being perfectly placed. The staleness check below validates the > existing rules against the current code regardless of the diff window; R only *scopes the hunt for -> new patterns*. A purely cosmetic edit to a constitution can advance R past some code changes, so the -> new-pattern hunt might skip them — but any rule those changes broke is still caught as stale. +> new patterns*. The header SHA makes R **tighter and more honest** — the real analyzed point, not a +> point a cosmetic edit shoved forward — never less safe. ## Scope @@ -99,7 +124,10 @@ On **Apply deltas**, per target actually written: 1. Merge the approved deltas into `context-constitution.md` (append additions; apply approved retire/re-ground edits; promote/drop resolved candidates). Refresh the `` block in - place only if the behaviors or cited IDs changed. + place only if the behaviors or cited IDs changed. Update the header's provenance line to this run's + ref — the date plus branch `git rev-parse --abbrev-ref HEAD` and commit `git rev-parse --short HEAD` + — so the file records the commit this refresh reran against (metadata, not a rule, so refreshing it + is not a CF-4 overwrite). Do the same for `context-constitution-findings.md` when this run writes it. 2. **Merge findings (CF-N12).** Append approved new-findings rows to their matching open section in `context-constitution-findings.md` (create it from `templates/findings.md` if this target had none yet). Move approved findings-resolved rows to `## Resolved`, dated, with how the re-check confirmed @@ -124,9 +152,13 @@ modify the repo — and since it needs no stored state, it works on any checkout ## Guardrails -- **Git is the baseline — persist nothing.** Never reintroduce a stored last-forged ref; derive it - from `git log` on the constitution file each run. This is what makes manual edits and refreshes - interchangeable and keeps the plugin from duplicating state git already holds. +- **Git is the baseline — no side-channel state file.** Never reintroduce a separate stored + last-forged ref. Derive the floor each run from git: the last commit that wrote the constitution + (`git log`), taken as the older (`git merge-base`) of it and the analyzed commit recorded in the + constitution's own header — provenance that lives *in the artifact*, not a duplicated state file, + and only ever an augmenting floor, never the sole source of truth. When the header SHA is absent or + unresolvable, fall back to the git-log point alone. This keeps manual edits and refreshes + 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 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 cfcbc78..6b30446 100644 --- a/plugins/context-forge/skills/context-constitution/reference/scan-protocol.md +++ b/plugins/context-forge/skills/context-constitution/reference/scan-protocol.md @@ -57,7 +57,14 @@ finding earns a durable home. 4. **Detect merge targets.** For each target dir, note whether a `CLAUDE.md` and `context-constitution.md` already exist (the scout reports these) — inputs to synthesis, not overwrite targets. -5. **Do not synthesize yet.** Phase 0 only gathers. Clustering, the inclusion cut, tiering, and the +5. **Capture the provenance ref (once, repo-wide).** Record the git state this scan reflects so the + written artifacts pin the exact commit analysed — branch `git rev-parse --abbrev-ref HEAD` and + commit `git rev-parse --short HEAD` (both covered by the allowed `Bash(git rev-parse *)`). A + detached HEAD reports `detached HEAD` for the branch; if it isn't a git repo (both queries fail), + record `unknown`. Capture it **once** — the same branch/commit stamps every target's header in a + monorepo. This is the point a later `refresh` moves forward from. + +6. **Do not synthesize yet.** Phase 0 only gathers. Clustering, the inclusion cut, tiering, and the human-Q&A gate happen in Phase 1, once the whole evidence set is in hand. ## Guardrails 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 7f9f273..295f718 100644 --- a/plugins/context-forge/skills/context-constitution/templates/context-constitution.md +++ b/plugins/context-forge/skills/context-constitution/templates/context-constitution.md @@ -6,7 +6,9 @@ --> # — Constitution -Derived by `/context-constitution` (context-forge) on . This file captures the +Derived by `/context-constitution` (context-forge) on from branch +`` at commit `` — the repo state this analysis +reflects; a later `refresh` reruns against a newer commit. This file captures the **non-obvious** — patterns this follows but never wrote down, the places that break those patterns, the contracts between modules, and the scars behind them — the things an agent would otherwise miss and get wrong. It does **not** restate what the docs already say or CI already diff --git a/plugins/context-forge/skills/context-constitution/templates/findings.md b/plugins/context-forge/skills/context-constitution/templates/findings.md index 2bc7dbb..278df71 100644 --- a/plugins/context-forge/skills/context-constitution/templates/findings.md +++ b/plugins/context-forge/skills/context-constitution/templates/findings.md @@ -7,8 +7,9 @@ --> # — Constitution Findings -Defects and drift surfaced by `/context-constitution` (context-forge) on while -deriving the constitution — the things an agent trusting the docs or the surface would get **wrong**. +Defects and drift surfaced by `/context-constitution` (context-forge) on from +branch `` at commit `` while deriving the +constitution — the things an agent trusting the docs or the surface would get **wrong**. These are for triage/fixing (feed them to your issue tracker), not governance: a defect is not a rule. Every entry cites the code. This log is maintained, not write-only (**CF-N12**): re-running `/context-constitution refresh` re-verifies every open row below against current code and retires the diff --git a/plugins/context-forge/skills/context-scrubber/SKILL.md b/plugins/context-forge/skills/context-scrubber/SKILL.md index 2adcac8..03bb5e4 100644 --- a/plugins/context-forge/skills/context-scrubber/SKILL.md +++ b/plugins/context-forge/skills/context-scrubber/SKILL.md @@ -146,7 +146,8 @@ Continue to Phase 1. ## PHASE 1 — REPORT (verdicts → findings file) Synthesize one findings file from `templates/scrubber-findings.md` (written to `scrubberFindingsPath`, or inline -in scratch mode): +in scratch mode). Its header records the audit date plus the branch + commit this audit reflects (captured via +`git rev-parse` — see `reference/audit-protocol.md` Step 4): 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 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 d10c162..be65f94 100644 --- a/plugins/context-forge/skills/context-scrubber/reference/audit-protocol.md +++ b/plugins/context-forge/skills/context-scrubber/reference/audit-protocol.md @@ -119,8 +119,11 @@ A verdict that fails confirmation is dropped from the "fails" set and, if still ## Step 4 — Route into the findings file (Phase 1; no drops — CF-N8) -Fill `templates/scrubber-findings.md`. 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 +Fill `templates/scrubber-findings.md`. Stamp its header's provenance line with the audit date **and** +the git state this audit reflects — branch `git rev-parse --abbrev-ref HEAD` and commit +`git rev-parse --short HEAD` (both covered by the allowed `Bash(git rev-parse *)`; a detached HEAD +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 (`remove` / `trim` / `move-to-` / `keep-but-verify`). 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 37b806b..cbfe8ee 100644 --- a/plugins/context-forge/skills/context-scrubber/templates/scrubber-findings.md +++ b/plugins/context-forge/skills/context-scrubber/templates/scrubber-findings.md @@ -8,7 +8,9 @@ --> # Context Scrub — Findings -Low-signal context surfaced by `/context-scrubber` on . Each row is a line in an +Low-signal context surfaced by `/context-scrubber` on from branch +`` at commit `` — the repo state this audit reflects. +Each row is a line in an **auto-loaded** context file (CLAUDE.md, AGENTS.md, context-constitution.md, `.cursor/rules/*`, …) that an agent would find for free, that no longer resolves, that is duplicated, or that the code now contradicts — dead weight paid for on every load. This is a report for triage; trimming is **gated** (`/context-scrubber apply`), never