Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion plugins/context-forge/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down
2 changes: 1 addition & 1 deletion plugins/context-forge/.codex-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down
2 changes: 1 addition & 1 deletion plugins/context-forge/.cursor-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down
21 changes: 14 additions & 7 deletions plugins/context-forge/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

Expand Down Expand Up @@ -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
Expand Down
11 changes: 8 additions & 3 deletions plugins/context-forge/skills/context-constitution/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
---

Expand Down Expand Up @@ -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 `<!-- context-forge:behavioral-contract:start -->` … `:end`.
If the markers are present, **replace the block in place** (never stack a copy); if the root has no
Expand All @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 -- <target dir>/<constitutionPath>
```
- **`R_head`** — the commit hash recorded in that constitution's own **header provenance line**
(`… at commit <short-sha>`), 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 <short-sha>^{commit}`), then take the floor as the **older (common ancestor) of the two**:

```
R = git log -1 --format=%H -- <target dir>/<constitutionPath>
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

Expand Down Expand Up @@ -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 `<!-- …:behavioral-contract… -->` 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
Expand All @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,9 @@
-->
# <Target name> — Constitution

Derived by `/context-constitution` (context-forge) on <ISO date | "unknown">. This file captures the
Derived by `/context-constitution` (context-forge) on <ISO date | "unknown"> from branch
`<branch | "detached HEAD">` at commit `<short-sha | "unknown">` — the repo state this analysis
reflects; a later `refresh` reruns against a newer commit. This file captures the
**non-obvious** — patterns this <repo|module> 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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,9 @@
-->
# <Target name> — Constitution Findings

Defects and drift surfaced by `/context-constitution` (context-forge) on <ISO date | "unknown"> 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 <ISO date | "unknown"> from
branch `<branch | "detached HEAD">` at commit `<short-sha | "unknown">` 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
Expand Down
3 changes: 2 additions & 1 deletion plugins/context-forge/skills/context-scrubber/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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-<file>` / `keep-but-verify`).
Expand Down
Loading
Loading