canon-ai 3.1.2 → 3.2.0

package/CHANGELOG.md

@@ -4,6 +4,22 @@
 
 ## [Unreleased]
 
+## [3.2.0] — 2026-09-11
+
+### Added
+
+- **New `/canon-sweep` skill triages the lessons-learned buffer.** It walks every entry with a prune-or-keep default, prefers the smallest carrier (a site comment, a test, or a clause on an existing rule) over a new rule, and proposes a per-entry verdict table for human approval before writing anything. Installed by `canon init` / `canon upgrade` and checked by `canon doctor`.
+
+## [3.1.3] — 2026-09-08
+
+### Added
+
+- **Code review and handoff guidance now cover three adopter-hit traps.** The anchored code-review lens checks sibling call sites sharing a fixed cross-cutting invariant before closing a round; the handoff template warns against backticking bare directory paths and against citing in-diff files in an out-of-diff `Fail` row's notes.
+
+### Changed
+
+- **Spec-authoring guidance now calls out ACs that pin exact operation counts across an unrelated async subsystem's own activity**, extending the existing "behavioral contracts, not mechanics" rule of thumb.
+
 ## [3.1.2] — 2026-09-08
 
 ### Fixed

package/README.md

@@ -130,6 +130,7 @@ The other installed skills (auto-trigger on natural-language phrases — see eac
 | `/canon-spec` | Authoring a new task — "let's add X", "start a task for…" |
 | `/canon-spec-review` | Pre-flighting a spec before invoking the pipeline |
 | `/canon-inline-review` | Independent cross-review of inline or below-pipeline changes before commit or PR |
+| `/canon-sweep` | Triaging `docs/lessons-learned.md` — promote, keep, or prune, human-approved |
 | `/canon-pipeline` | Driving an existing task forward (`canon run`, `--pr`, `--ship`, recovery) |
 | `/canon-status` | "Where are we?" — surfaces phases and blockers across in-flight tasks |
 | `/canon-changelog` | Drafting release notes (projects that version their releases) |
@@ -211,7 +212,9 @@ Canon drives a lot of `git`, `gh`, `codex`, and `npm` invocations, plus short sh
       "Skill(canon-spec-review)",
       "Skill(canon-spec-review:*)",
       "Skill(canon-inline-review)",
-      "Skill(canon-inline-review:*)"
+      "Skill(canon-inline-review:*)",
+      "Skill(canon-sweep)",
+      "Skill(canon-sweep:*)"
     ]
   }
 }
@@ -308,7 +311,7 @@ Drop this into any repo and you have:
 - Agent rules and per-agent guidance delivered just-in-time via per-phase prompt templates (`src/orchestrator/prompts/templates/`) and the `/canon-*` skills; adopters generate their own `AGENTS.md` / `CLAUDE.md` with the built-in `/init`
 - `docs/` — knowledge corpus templates with detailed scaffolding
 - `.claude/settings.json` — Claude Code permissions + SessionStart hook
-- Claude Code skills installed by `canon init`: `/canon-init` (knowledge-corpus bootstrap), `/canon-spec` (new task authoring), `/canon-spec-review` (pre-flight a spec), `/canon-inline-review` (independent cross-review of below-pipeline work), `/canon-pipeline` (drive an existing task), `/canon-status` (in-flight task map), `/canon-changelog` (release notes for versioned projects)
+- Claude Code skills installed by `canon init`: `/canon-init` (knowledge-corpus bootstrap), `/canon-spec` (new task authoring), `/canon-spec-review` (pre-flight a spec), `/canon-inline-review` (independent cross-review of below-pipeline work), `/canon-pipeline` (drive an existing task), `/canon-status` (in-flight task map), `/canon-changelog` (release notes for versioned projects), `/canon-sweep` (triage the lessons-learned buffer)
 - Unit-test suite covering the policy module, orchestrator extractors, and validation parsers (`npm test`)
 
 ## Where to Go Deeper

package/dist/cli/index.js

@@ -1117,7 +1117,9 @@ var RECOMMENDED_ALLOW = [
   "Skill(canon-spec-review)",
   "Skill(canon-spec-review:*)",
   "Skill(canon-inline-review)",
-  "Skill(canon-inline-review:*)"
+  "Skill(canon-inline-review:*)",
+  "Skill(canon-sweep)",
+  "Skill(canon-sweep:*)"
 ];
 var RECOMMENDED_NUDGE = [
   "This project uses canon, a spec-first multi-agent pipeline.",
@@ -1245,7 +1247,7 @@ function checkTemplates(cwd) {
 }
 function checkCanonVersion(cwd) {
   const versionPath = join(cwd, ".canon", "version");
-  const installedVersion = "3.1.2";
+  const installedVersion = "3.2.0";
   if (!existsSync(versionPath)) {
     return { label: ".canon/version", status: "warn", detail: "missing \u2014 run `canon upgrade`" };
   }
@@ -1268,7 +1270,7 @@ function checkSkills(cwd) {
       detail: "canon-init skill missing \u2014 run `canon init` or `canon upgrade`"
     };
   }
-  const skillNames = ["canon-spec", "canon-pipeline", "canon-status", "canon-changelog", "canon-spec-review", "canon-inline-review"];
+  const skillNames = ["canon-spec", "canon-pipeline", "canon-status", "canon-changelog", "canon-spec-review", "canon-inline-review", "canon-sweep"];
   const missing = skillNames.filter((s) => !existsSync(join(cwd, ".claude", "skills", s, "SKILL.md")));
   if (missing.length > 0) {
     return {
@@ -1742,7 +1744,7 @@ function initCmd(_args) {
 }
 function writeCanonVersion(cwd) {
   const versionPath = join2(cwd, ".canon", "version");
-  const version = "3.1.2";
+  const version = "3.2.0";
   mkdirSync(dirname2(versionPath), { recursive: true });
   writeFileSync(versionPath, version + "\n");
 }
@@ -2751,7 +2753,7 @@ function isInstalledSourcePath(sourcePath) {
   return sourcePath.includes("/node_modules/") || sourcePath.includes("\\node_modules\\") || sourcePath.includes("/_npx/") || sourcePath.includes("\\_npx\\");
 }
 function resolveCanonVersion(explicit) {
-  return explicit ?? "3.1.2" ?? "dev";
+  return explicit ?? "3.2.0" ?? "dev";
 }
 function resolveOrchestratorCommit(repoRoot, upstreamCommit, runGitAt) {
   const ownToplevel = captureGitOutput(repoRoot, ["rev-parse", "--show-toplevel"], runGitAt);
@@ -4877,7 +4879,7 @@ function currentPinFromManifest(manifest) {
   return "unknown";
 }
 function bakedVersion() {
-  return "3.1.2";
+  return "3.2.0";
 }
 function ownPackageName(pkgDir) {
   try {
@@ -5089,6 +5091,7 @@ var CANON_OWNED = [
   ".claude/skills/canon-changelog/SKILL.md",
   ".claude/skills/canon-spec-review/SKILL.md",
   ".claude/skills/canon-inline-review/SKILL.md",
+  ".claude/skills/canon-sweep/SKILL.md",
   ".claude/agents/code-review-anchored.md",
   ".claude/agents/code-review-cold.md",
   ".canon/templates/status.json",
@@ -5351,7 +5354,7 @@ function runUpgrade(cwd, pkgDir, options = {}) {
     cutoverWarnings.push(docsRefsCheckRel);
   }
   const versionPath = join5(cwd, ".canon", "version");
-  const newVersion = "3.1.2";
+  const newVersion = "3.2.0";
   const currentVersion = existsSync5(versionPath) ? readFileSync4(versionPath, "utf8").trim() : null;
   if (currentVersion !== newVersion) {
     pending.push({ rel: ".canon/version", projectPath: versionPath, content: newVersion + "\n" });
@@ -5659,7 +5662,7 @@ Global:
 `);
 }
 function printVersion() {
-  console.log("3.1.2");
+  console.log("3.2.0");
 }
 switch (command) {
   case "doctor":

package/dist/orchestrator/run-task.js

@@ -4961,7 +4961,7 @@ function isInstalledSourcePath(sourcePath) {
   return sourcePath.includes("/node_modules/") || sourcePath.includes("\\node_modules\\") || sourcePath.includes("/_npx/") || sourcePath.includes("\\_npx\\");
 }
 function resolveCanonVersion(explicit) {
-  return explicit ?? "3.1.2" ?? "dev";
+  return explicit ?? "3.2.0" ?? "dev";
 }
 function resolveOrchestratorCommit(repoRoot, upstreamCommit, runGitAt) {
   const ownToplevel = captureGitOutput(repoRoot, ["rev-parse", "--show-toplevel"], runGitAt);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canon-ai",
-  "version": "3.1.2",
+  "version": "3.2.0",
   "type": "module",
   "description": "A spec-first, multi-agent coding pipeline you drop into any repo. The law your agents work under.",
   "engines": {
@@ -27,14 +27,14 @@
   },
   "devDependencies": {
     "@types/mustache": "^4.2.6",
-    "@types/node": "^22.20.1",
-    "eslint": "^10.8.1",
+    "@types/node": "^24.13.3",
+    "eslint": "^10.10.0",
     "mustache": "^4.2.0",
-    "simple-git-hooks": "^2.13.1",
+    "simple-git-hooks": "^2.14.0",
     "tsup": "^8.5.1",
-    "tsx": "^4.23.12",
+    "tsx": "^4.23.13",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.66.0"
+    "typescript-eslint": "^8.70.0"
   },
   "simple-git-hooks": {
     "pre-commit": "npm run sync-templates -- --stage"

package/templates/.canon/templates/handoff.md

@@ -12,6 +12,8 @@
 >
 > **Deleting a file?** In this table use the `[path/to/file.ext](path/to/file.ext)` markdown-link form — **not** backticks and **not** bare prose. Backticks trip `docs-refs-check` (a backtick path-ref to a now-missing path under a `validDirs` dir reads as broken); bare prose fails this table's path parse (the first column must be a backtick-path or a markdown-link). The markdown-link is the one form that satisfies both.
 
+> **Never backtick a bare directory path** anywhere in this file (e.g. write "the app source tree (apps/app/src)", not `` `apps/app/src` ``). `docs-refs-check` treats a backticked path as a file reference and aborts the pipeline's auto-commit with "missing file" when it is a directory. Backtick only real files.
+
 | File | What Changed |
 |---|---|
 
@@ -71,6 +73,7 @@ Cross-reference each Acceptance Criterion from spec.md and confirm it is met. AC
 > | `deferred_by_spec` | Explicitly out of scope per spec. Requires a spec citation in Notes (e.g., `Spec: §Non-Goals — explicitly defers this`). |
 > | `blocked` | Check would have run but infrastructure was unavailable (CI down, network out). Triage required — distinct from `Fail`. |
 >
+> A `Fail` row whose cause lies outside this task's diff: name the result `Fail – unrelated` explicitly, and Notes must cite a specific file reference outside this task's affected files (a sibling worktree path, a fixed-port test's own file, an unrelated spec's path) — the code reviewer only accepts `Fail – unrelated` when Notes names such a reference credibly. Pre-flight's own check is textual — naming a changed file in that row, even to say it passed, can reclassify the whole row as task-owned and reject the handoff. Don't rely on an unqualified filename escaping the check; keep Notes free of any path from this task's diff.
 > Record every check in spec.md's Validation Required section here, plus any extra checks you ran. Required checks should not be marked `N/A` or `not_configured` — run the check or adjust the spec; the code reviewer verifies coverage against the spec. The `Check` cell is for human readability (the pre-flight gate no longer string-matches it against the spec), so write whatever names the check clearly — but keep a check's label identical across a baseline row and any later `### Re-run validation` row so its result updates in place.
 
 | Check | Result | Notes |

package/templates/.claude/agents/code-review-anchored.md

@@ -34,6 +34,7 @@ Report every issue you find, including ones you are uncertain about or consider
 - **Verify handoff claims by running `git diff HEAD -- <file>`**: the auto-commit step can silently drop edits not in the handoff Changes table — don't trust the handoff claim; diff the working tree to confirm fixes landed.
 - **Delicate-task review must audit cross-cutting guards at every mutation entry point**: when a `delicate: true` task refactors a state/data layer, explicitly verify that auth, gating, and payment guards still hold at every mutation chokepoint — not just at the call sites the spec called out.
 - **Don't infer one git invariant from another**: `git status --porcelain` empty ≠ origin matches HEAD; `origin/<branch>` exists ≠ origin matches HEAD. Do the actual check directly, not a proxy.
+- **A cross-cutting invariant fix isn't verified until every sibling call site with the same shape has been checked**: a captured reference that must be revalidated, or a guard that must run, because an intervening `await` can invalidate it, is the kind of defect that recurs wherever the same shape appears. Once a round establishes the violation is real at one call site, a byte-identical-to-base sibling branch elsewhere in the same file is not "out of scope" — it shares the same shape. Grep the file for every other site matching the pattern before accepting the fix and closing the round.
 
 ## Return Format
 

package/templates/.claude/skills/canon-init/SKILL.md

@@ -135,7 +135,9 @@ By default, Claude Code prompts on every `git`, `gh`, `codex`, and `canon` subpr
            "Skill(canon-pipeline)", "Skill(canon-pipeline:*)",
            "Skill(canon-status)", "Skill(canon-status:*)",
            "Skill(canon-changelog)", "Skill(canon-changelog:*)",
-           "Skill(canon-spec-review)", "Skill(canon-spec-review:*)"
+           "Skill(canon-spec-review)", "Skill(canon-spec-review:*)",
+           "Skill(canon-inline-review)", "Skill(canon-inline-review:*)",
+           "Skill(canon-sweep)", "Skill(canon-sweep:*)"
          ]
        }
      }

package/templates/.claude/skills/canon-spec/SKILL.md

@@ -152,7 +152,7 @@ Self-check before presenting:
 - **Prefer positive or structural assertions** over prose negations for load-bearing constraints. Back a "must not" with a grep AC or positive reframe.
 - **Symbols in ACs must exist** — grep for every named function or symbol; verify return shape matches the spec's assumed data contract.
 - **Enumerate every caller and classify its execution context before asserting how a mechanism works.** "Counter X only increments on event Y" or "this writer can only be invoked from surface Z" is a control-flow claim, and control-flow claims need every caller traced — a helper named for one trigger routinely serves several, and whether a call site runs inside an agent's own session or in the orchestrator's process is invisible from the function body. Grep every caller of the function or counter (including skills and docs, not just source) and classify each site as in-agent-session or orchestrator-context before the spec asserts anything about it.
-- **Behavioral contracts, not mechanics** — ACs describe observable behavior; defer implementation mechanics to plan/implement. If review rounds start re-litigating literal regexes, exact file layouts, or verbatim command strings, the spec has dropped to code altitude and each round's "underspecified" finding just adds more reviewable surface: move the mechanics into a clearly-labeled non-binding *Implementation Notes* subsection owned by plan/implement, rather than wording the same mechanism more precisely.
+- **Behavioral contracts, not mechanics** — ACs describe observable behavior; defer implementation mechanics to plan/implement. If review rounds start re-litigating literal regexes, exact file layouts, or verbatim command strings, the spec has dropped to code altitude and each round's "underspecified" finding just adds more reviewable surface: move the mechanics into a clearly-labeled non-binding *Implementation Notes* subsection owned by plan/implement, rather than wording the same mechanism more precisely. The recurring form of this trap is an AC that pins exact operation counts over a fixture in which an unchanged async subsystem (a generation queue, a worker pool) performs its own reads inside the measurement window — an adopter spec took five review rounds on one such AC because each revision worded the same brittle count more precisely instead of removing the dependency; make the side effects inert or assert the discriminating deltas, do not itemize the subsystem's arithmetic.
 - **Bug and flake-fix specs need a confirmed mechanism and red-first test**: For a bug or flake fix, the spec author must state, in *Problem*, both the confirmed mechanism and how it was confirmed — not merely a plausible cause. Evidence must match the mechanism class: a deterministic mechanism (fixed inputs hit the same wrong branch every run) may cite a trace with the verified trigger values; a runtime-dependent mechanism (race, timing, environment/config interaction) needs executed confirmation — a throwaway prototype-fix spike that makes the symptom vanish, or a deterministic forced repro. The author must satisfy that checkpoint before the spec is marked done; on fast-tier (XS, non-delicate) tasks the `spec_review` checkpoint is skipped, so no reviewer will catch an unverified mechanism. The *Acceptance Criteria* must include a red-first regression-test AC: a test that fails on the pre-fix code for the stated reason and passes after the fix. If the mechanism is environment-bound and a faithful repro is impractical, *Problem* must say so and name a deterministic alternative (integration fixture or documented manual repro) instead of skipping verification silently.
 - **At ≥3 spec_review iterations, read the rounds' content, not the count.** Label each round *edge-fine-tune* (it narrows an already-identified case — converging, safe to finish once the findings are addressed) or *scope-expansion* (it names a **new** structural case the spec hadn't covered — a real design gap). Round count alone is not the signal; a 6-round run of successive fine-tunes is convergence. On genuine scope-expansion, don't refine again: check whether the last two rejections share one structural root, and whether an existing layer already owns the concern. Dropping the whole mechanism class — or deleting the mechanism in favor of the layer that already owns it — is usually cheaper than another round of hardening.
 - **Refactor specs need hard structural caps**: size cap, explicit deletion expectations per symbol, grep AC for disappeared symbols.

package/templates/.claude/skills/canon-sweep/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: canon-sweep
+description: Use when the human asks to sweep, triage, or prune `docs/lessons-learned.md` — phrases like "sweep the lessons buffer", "let's do a lessons sweep", "promote or prune lessons learned", or explicit `/canon-sweep` invocation. Human-invoked only. A QA "buffer exceeds ~15 entries" note in a task's `done.md` or a just-closed release milestone are reasons to *suggest* a sweep to the human, never to start one. The skill proposes a verdict and the exact promoted text per entry and writes nothing until the human confirms. Not for appending new lessons (the QA phase does that) or for editing task notes.
+allowed-tools: Read Glob Grep Edit Write Bash(git log *) Bash(git status *) Bash(git branch *) Bash(git diff *) Bash(git show *) Bash(git worktree list) Bash(canon task list)
+effort: medium
+---
+
+# Lessons Sweep
+
+Use this skill to triage the lessons-learned buffer: decide, entry by entry, whether each one is promoted into a permanent doc, kept in the buffer, or pruned. The buffer is a staging area, not an archive. The sweep exists to keep it small and to keep the permanent docs from bloating.
+
+**Promotion is rare.** Every line promoted is read by every agent on every future task, so it must earn that recurring cost. Most entries end as keep or prune. But the threshold that prompted the sweep is a reason to pay attention, not a target: never manufacture a prune to hit a count.
+
+## When to use
+
+- The human asks for a sweep.
+- You notice a reason to suggest one: a task's `done.md` carries the QA signal that the buffer exceeds ~15 entries, or a release milestone just closed. Suggest it in one line and wait. Never start a sweep on your own.
+
+## Preconditions
+
+Triage (Steps 1 to 3) is read-only and can run from any checkout. Before **applying** anything (Step 4), run this preflight and stop if any check fails:
+
+- `git status` is clean and `git branch --show-current` is a dedicated non-default branch.
+- `git worktree list` shows the current directory as the main working tree, not a linked worktree. A task worktree is where a pipeline edits code; shared docs must not change there.
+- `canon task list` shows no task with a phase in progress. A pipeline running in another worktree would otherwise pick up or collide with the sweep's edits to shared docs at merge time. If one is in flight, wait for it to reach `human_review` or stop it before applying. The sweep touches shared docs and should ship as its own small change through the normal review path.
+
+Read before triaging:
+
+1. `docs/lessons-learned.md` in full, including the HTML sweep comments at the bottom. They record what was kept with a re-evaluation condition and what was already promoted; they are the cheapest way to avoid redoing work.
+2. The candidate destinations, so you can check coverage: `docs/patterns.md`, `docs/decisions.md`, `docs/architecture.md`, and the project's agent instruction files (`AGENTS.md`, `CLAUDE.md`) if it keeps them.
+3. `git log docs/lessons-learned.md` since the last sweep comment, and the task IDs shipped in that window, so you can tell "did not recur" from "had no chance to recur."
+
+## Step 1 — Triage every entry
+
+Walk each entry through this sequence. Stop at the first stage that decides it, and write a one-line reason.
+
+### Stage A — Is it already settled? → Prune
+
+- **Already covered.** Grep the permanent docs for the concept, not the exact words. A restatement of an existing pitfall, decision, or rule is a prune.
+- **Obsolete.** The code path, tool, or convention it describes no longer exists.
+- **Self-evident.** A competent agent with no doc at all would already do this. Reminders of general good practice are not lessons.
+- **Its prevention has landed.** A test, lint check, or gate now enforces it, or a tracked follow-up (an issue, a backlog item the project actually works from) has explicitly taken ownership. A note in a sweep comment is not ownership; do not prune an unresolved structural lesson on the promise of a future test.
+
+### Stage B — Is the evidence sufficient? → Evaluate promotion
+
+Promotion is on the table when either holds:
+
+- **Recurrence.** It has bitten at least twice, in independent tasks. Check archived task notes and prior sweep comments for the second occurrence before claiming it.
+- **Severity.** It bit once, but the cost of one more occurrence clearly exceeds the recurring cost of a rule read on every task. Say why in the reason.
+
+And both of these hold:
+
+- **Surprising or project-specific.** The reader could not have derived it from general experience.
+- **Not already absorbed.** If an existing rule can take it as a clause, that is still a promotion, as an extension (Step 2). Only a brand-new rule requires that no nearby rule exists.
+
+If the evidence is sufficient, go to Step 2 to pick the carrier. If it is not, fall through.
+
+### Stage C — Otherwise → Keep, with a condition
+
+- **Happened once, not severe.** Leave it and see whether it bites again.
+- **Borderline and adjacent to an existing rule.** Note which rule, so the next sweep can decide on a one-clause graft without re-reading.
+- **Kept before, with no chance to recur.** If no task since the last sweep touched the area the lesson is about, the absence of recurrence is not evidence. Keep it. Prune on "no recurrence" only when there was relevant exposure and it still did not bite, or the human decides to let it go. This never applies to an unresolved structural lesson: one whose prevention is a test, lint check, or gate that has not landed and has no tracked owner stays until it does (Stage A), regardless of recurrence.
+
+A kept entry always carries an explicit condition: "re-evaluate if X recurs in a different task" or "prune at the next sweep if tasks touching Y ship without hitting this." "Keep, unsure" is not a verdict.
+
+## Step 2 — Choose the smallest carrier
+
+Promotion does not mean "write a new rule." Choose the lightest form that would have prevented the incident, in this order of preference:
+
+1. **A comment at the site.** If the trap is local to one function, file, or config block, a one-line comment where the next person will trip is better than a rule read by every agent on every task.
+2. **A test, lint check, or gate.** If the lesson can be enforced mechanically, prefer that over prose. If writing it is out of scope for the sweep, the entry stays in the buffer until the check lands or a tracked follow-up owns it (Stage A).
+3. **Extending an existing rule.** Add a clause, a trigger-table row, or a second example to a rule that already exists. This is the most common shape of a real promotion.
+4. **A new rule.** Only when no existing rule is close enough to absorb it. Keep it to the rule and its concrete prevention; cut the story of how it was discovered.
+
+When the carrier is a doc, match the doc to the kind of truth:
+
+| Kind of lesson | Home |
+|---|---|
+| A pitfall: something that looks right and silently isn't | `docs/patterns.md` (and its trigger table, if the project keeps one) |
+| A settled decision or an explicit rule the project has chosen | `docs/decisions.md` |
+| A command, validation, or environment gotcha | `docs/architecture.md`, validation section |
+| A workflow rule every agent must know on every task, no matter what it is working on | The project's agent instruction files, if it keeps them. This is the highest bar: those files load into every session, so a rule lands here only when it is unconditionally load-bearing |
+
+Rules of thumb for the promoted text:
+
+- **Write the rule, not the war story.** Title names the rule. Body is rule, failure mode in one sentence, concrete prevention. Drop dates, task IDs, and the narrative of discovery; those stay in the buffer's git history.
+- **Generalize past the incident.** The promoted form should read correctly to someone working on an unrelated feature. If it only makes sense with the original task in mind, it is not ready.
+- **Verify anything executable.** If the entry prescribes a command, flag, or path, run it or check it exists before promoting. The buffer can carry an error for weeks; a permanent doc will carry it for years.
+- **Lessons about the pipeline itself go upstream.** If the lesson is about canon's own behavior rather than this project's code, it belongs in a report to the canon-ai maintainers, not in this project's docs. Canon-managed files are overwritten on upgrade, so a rule written into one is lost. If this repository *is* the canon-ai source, upstream is here: the promotion lands in the managed file's authoritative copy and follows the project's own mirror-sync workflow.
+- **A rule in the wrong home is nearly as bad as no rule.** Agents read docs just in time; a spec rule buried in a pitfalls doc is never read at spec time.
+
+## Step 3 — Propose before writing
+
+Present the human with a verdict table before touching any file:
+
+```
+| # | Entry (title) | Verdict | Carrier / condition | Why (one line) |
+```
+
+**For every promote row, also show the exact text you intend to add and exactly where it goes** (file and section, or the existing rule being extended, with the new clause in place). The permanent rule is the most consequential output of the sweep; the human approves the words, not just the classification.
+
+Then ask for approval with `AskUserQuestion`, offering: approve all, approve with changes (the human names which rows to flip or which text to edit), or stop. Do not write until the human has confirmed. If the human flips a verdict or rewrites a rule, accept it and move on.
+
+## Step 4 — Apply
+
+Run the preflight above, then for each approved row:
+
+- **Promote:** land the approved carrier, then delete the entry from the buffer. For a doc, make the edit exactly as approved. For a site comment, write the comment at the approved location. For a test, lint check, or gate, the entry leaves the buffer only once the check is actually in place; if it is deferred, the row is a keep, not a promote.
+- **Prune:** delete the entry.
+- **Keep:** leave the entry in place, byte for byte.
+
+Then update the HTML sweep comments at the bottom of `docs/lessons-learned.md`. Add one comment for this sweep in the same shape as the existing ones:
+
+```html
+<!-- Buffer swept YYYY-MM-DD (N entries reviewed: A promoted, B kept in buffer, C pruned).
+     Promotions → <destination>: <what was added, one line each>.
+     Kept in buffer: <entry> — re-evaluate if <condition>.
+     Pruned: <entry> — <reason>.
+     Unresolved follow-ups: <structural fixes not yet landed, upstream reports not yet filed>.
+     Prior entries are in git history. -->
+```
+
+Keep the comment block bounded, or it becomes the archive this file says it is not. Carry forward only what the next sweep needs: the current keep conditions and any unresolved follow-ups. Drop older comments whose promotions and prunes are fully settled; git history retains them.
+
+## Step 5 — Hand off
+
+Report to the human:
+
+- the counts, and the number of entries remaining in the buffer. If it is still near or above the QA signal threshold, say why (approved keeps, unresolved structural follow-ups) rather than treating that as a failure;
+- each promotion and where it landed;
+- each follow-up that needs a decision: a test to write, an issue to file upstream, an entry waiting on ownership;
+- the verification you ran on any command or path you promoted.
+
+Do not commit. The human decides how the change ships, and it should get an independent review like any other below-pipeline edit.
+
+## What this skill does not do
+
+- Append new lessons. That is the QA phase's job, and its entry format is its own concern.
+- Set the sweep threshold. The buffer's own "How to use" section owns that.
+- Rewrite or reorganize entries it is keeping.
+- Start a sweep without a human asking.