The lessons ledger

Every rule records the mistake that created it. .groundwork/LESSONS.md is the one place those mistakes live, and each one climbs a ladder only when it has to.

The ladderCopy Anchor Link

A lesson moves up only when its mistake repeats — never on a single signal:

### L-004 · No AI attribution trailers in commits
- Level: GUARD (`guards/no-ai-trailers.mjs`)
- Origin: 7 commits in one session despite a written rule.
- History: note (09-02) → rule (09-10, repeated) → guard (09-20, repeated again)

GuardsCopy Anchor Link

A guard is a small Node module that receives a proposed action — a shell command or a file write — and returns allow or block, with a reason:

export function check(action) {
  if (action.kind === "command" && /--no-verify/.test(action.command)) {
    return { block: true, reason: "Don't skip hooks with --no-verify." };
  }
  return { block: false };
}

Guards are listed in .groundwork/config.json. New installs start with no-ai-trailers on; "guards": [] means none run. Adapters wire them into the tool's hooks: in Claude Code a PreToolUse hook runs them before every shell command and file write, and a guard that blocks exits with code 2. groundwork doctor flags a guard listed in config without a matching file, or a hook missing from the adapter's settings.

A guard is code, so /gw-retro proposes one as a card to plan — it isn't written on the spot.

Retro: noticing repeated mistakesCopy Anchor Link

groundwork retro collects signals from git history and Groundwork's own files and writes .groundwork/retro.md:

• Reverts, and fixes committed soon after a card, touching the same files;
• Rejections and their reasons;
• Send-backs by the reviewer;
• Calls later rejected — a judgment call the agent made that you later turned down;
• Signals per lesson cited, so you can see which rules keep coming up.

Then /gw-retro reads the report, groups signals that describe the same mistake, and proposes one change per repeated mistake: a new note, a note → rule, or a rule → guard. It also proposes archiving lessons nothing has touched in a long time. Nothing changes without your OK, and each lesson gets a History line naming where it repeated.

/gw suggests a retro at the end of every phase; you can also run one whenever something keeps going wrong.

Doctor: keeping the ledger honestCopy Anchor Link

npx groundwork-ai doctor

• Measures the always-loaded files against tokenBudget and shows the real number (about 400 tokens on a fresh install; the default budget is 2,000).
• Flags a lesson that's never cited in a card or in AGENTS.md — a candidate to archive.
• Flags a rule in AGENTS.md that has no lesson ID, because every rule should trace back to the mistake it prevents.
• Checks the install: missing guards, missing hooks, adapter files that drifted, a project behind the CLI.

Imported rulesCopy Anchor Link

Bringing an existing project under Groundwork? Rules from its current CLAUDE.md or AGENTS.md are imported as lessons with origin imported — and you're asked which ones must stay always-on. Those become RULEs in AGENTS.md with their lesson ID; the rest stay NOTEs. Nothing is dropped or demoted without showing you first.