@bendyline/gilde 0.1.40 → 0.1.41

package/authoring/tactical/books/bug-fix-tdd.json

@@ -0,0 +1,237 @@
+{
+  "id": "bug-fix-tdd",
+  "name": "Reproduce-Then-Fix a Bug",
+  "description": "Fix a bug the disciplined way, with proof at every step: a failing test that reproduces it (verified red by a real test run), the smallest change at the real defect site, a green suite afterwards, and an enforced independent review of the fix.",
+  "category": "code-quality",
+  "role": "maintenance-review",
+  "tags": [
+    "bug-fix",
+    "tdd",
+    "regression-test",
+    "debugging",
+    "tests",
+    "quality"
+  ],
+  "triggers": [
+    "fix this bug",
+    "reproduce and fix",
+    "tdd bug fix",
+    "write a regression test",
+    "debug and fix"
+  ],
+  "about": "Fix a bug with the discipline a senior engineer would demand, and with each claim mechanically verified. First REPRODUCE: write a focused failing test in the project's real test layout and run the suite so the failure is recorded — a bug you cannot reproduce you cannot prove fixed, and this book's gates read the actual run receipts, not the author's summary. Then LOCATE the defect site and its causal chain before touching anything. Then make the SMALLEST change at that real site — never a prescribed scratch file — keeping the new test as a permanent regression guard. Then VALIDATE by re-running the original reproduction and the whole suite, which must now be green. Finally an independent reviewer grades the whole chain against fixed criteria and their REVISE verdict routes the work back automatically with concrete findings. Needs a project whose tests run via `npm run test`. Works identically whether the run edits the project directly or drafts a change proposal for the user to apply.",
+  "doc": {
+    "paramSchema": {
+      "type": "object",
+      "properties": {
+        "scope": {
+          "type": "string",
+          "title": "Bug to fix",
+          "description": "The bug report, failing behavior, or area to focus on. Leave empty when the task description already carries it.",
+          "default": ""
+        }
+      }
+    },
+    "capabilityFloor": "small",
+    "diffpackCapable": true,
+    "commands": [
+      {
+        "scope": "script",
+        "name": "test",
+        "reason": "Red-then-green proof: the reproduction must actually fail against the current code, and the whole suite must pass after the fix. The gates verify real run receipts."
+      }
+    ]
+  },
+  "workflow": {
+    "plan": "Reproduce with a failing test (verified red by a real run) -> locate the defect site and causal chain -> smallest fix at the real site -> validate red-to-green with the original reproduction -> enforced independent review.",
+    "maxGateAttempts": 4,
+    "maxReviewRounds": 3,
+    "phases": [
+      {
+        "id": "reproduce",
+        "name": "Reproduce with a failing test",
+        "description": "Establish the failure on the real code, as a running test that fails for the right reason.",
+        "suggestedRole": "debugging engineer",
+        "capabilityFloor": "small",
+        "prompt": "The bug to fix: {{scope}}\n\nEstablish the failure on the REAL code before changing anything. Read the bug description and the involved source. Find how this project runs its tests (`list_package_scripts`, then read the existing test layout). Write ONE focused test that captures the exact wrong behavior, in the project's real test layout and style — never a scratch file like `src/bug.test.js`. Then run the suite with `run_package_script` (`test`) and confirm it FAILS because of your new test, for the right reason — quote the failing assertion. If the command needs first-use approval, say so and wait rather than guessing. If you cannot reproduce the bug at all, record every attempt honestly; do not invent a cause.\n\nWrite `{{workPath}}/repro.md` with exactly these sections: `## Symptom` (what the user sees, in their words), `## Repro command` (the exact command you ran), `## Expected`, `## Actual`, `## Red evidence` (the failing test's path and the quoted failing output from the real run). Cite the real files involved with backtick paths.",
+        "output": {
+          "path": "{{workPath}}/repro.md",
+          "minBytes": 500,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Symptom",
+              "label": "Symptom section"
+            },
+            {
+              "pattern": "^##\\s+Repro command",
+              "label": "Repro command section"
+            },
+            {
+              "pattern": "^##\\s+Expected",
+              "label": "Expected section"
+            },
+            {
+              "pattern": "^##\\s+Actual",
+              "label": "Actual section"
+            },
+            {
+              "pattern": "^##\\s+Red evidence",
+              "label": "Red evidence section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/repro.md",
+              "minCitations": 2,
+              "artifact": true
+            },
+            {
+              "kind": "commandEvidence",
+              "script": "test",
+              "expect": "fail",
+              "label": "the suite genuinely fails (red) with the new reproduction test"
+            }
+          ]
+        }
+      },
+      {
+        "id": "locate",
+        "name": "Locate the defect",
+        "description": "Name the defect site and the causal chain from it to the symptom. No source edits.",
+        "suggestedRole": "root-cause analyst",
+        "capabilityFloor": "small",
+        "prompt": "Read `{{workPath}}/repro.md`, then trace the failure to its source. Name the defect site precisely: file, symbol, and the first place state or logic goes wrong. Explain the causal chain from that site to the observed symptom, step by step. Check sibling cases: does the same defect pattern appear in neighboring code paths that just have no test yet? Do not edit any source in this phase.\n\nWrite `{{workPath}}/diagnosis.md` with exactly these sections: `## Defect site` (the file and symbol, with backtick paths), `## Causal chain`, `## Siblings checked` (which neighboring paths you inspected and what you found). Every path you cite must be real.",
+        "output": {
+          "path": "{{workPath}}/diagnosis.md",
+          "minBytes": 600,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Defect site",
+              "label": "Defect site section"
+            },
+            {
+              "pattern": "^##\\s+Causal chain",
+              "label": "Causal chain section"
+            },
+            {
+              "pattern": "^##\\s+Siblings checked",
+              "label": "Siblings checked section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/diagnosis.md",
+              "minCitations": 2,
+              "artifact": true
+            }
+          ]
+        }
+      },
+      {
+        "id": "fix",
+        "name": "Make the smallest fix",
+        "description": "Change the real defect site, minimally, keeping the new test as a regression guard.",
+        "suggestedRole": "software engineer",
+        "capabilityFloor": "small",
+        "prompt": "Read `{{workPath}}/diagnosis.md` and make the SMALLEST correct change at the defect site it names. There is no prescribed output path for source changes — edit the actual files from the diagnosis with `read_file` plus `write_file`/`replace_in_file`. Never special-case the reproduction's exact input just to silence the test; fix the cause. Cover the sibling cases the diagnosis flagged, and keep (or strengthen) the reproduction test so it becomes the permanent regression guard. Re-run the focused test while you work.\n\nThen write `{{workPath}}/fix-notes.md` with exactly these sections: `## Problem` (one paragraph), `## Change` (what you altered and why it breaks the causal chain), `## Files touched` (backtick path per line), `## Regression coverage` (which test now guards this), `## Risk` (what could still go wrong; be honest about anything unverified), `## How to verify` (the exact commands a person runs to confirm).",
+        "output": {
+          "path": "{{workPath}}/fix-notes.md",
+          "minBytes": 700,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Problem",
+              "label": "Problem section"
+            },
+            {
+              "pattern": "^##\\s+Change",
+              "label": "Change section"
+            },
+            {
+              "pattern": "^##\\s+Files touched",
+              "label": "Files touched section"
+            },
+            {
+              "pattern": "^##\\s+Regression coverage",
+              "label": "Regression coverage section"
+            },
+            {
+              "pattern": "^##\\s+Risk",
+              "label": "Risk section"
+            },
+            {
+              "pattern": "^##\\s+How to verify",
+              "label": "How to verify section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/fix-notes.md",
+              "minCitations": 2,
+              "artifact": true
+            }
+          ]
+        }
+      },
+      {
+        "id": "validate",
+        "name": "Validate red-to-green",
+        "description": "Re-run the original reproduction and the whole suite; record the real results.",
+        "suggestedRole": "software engineer",
+        "capabilityFloor": "small",
+        "prompt": "Prove the fix with fresh eyes. Read `{{workPath}}/repro.md` and re-run the EXACT reproduction command it records with `run_package_script` (the suite runs ONLY through `run_package_script` with script name \"test\"; `run_installed_script` is for named ops scripts and is NOT the test runner) — the previously failing test must now pass, and the whole suite must be green. Anything you could not actually run gets labeled unverified, never claimed. If something regressed, your fix was too broad — go back and narrow it before validating again.\n\nWrite `{{workPath}}/validation.md` with exactly these sections: `## Repro re-run` (the command and what happened to the once-failing test), `## Suite` (the full-suite result), `## Result` (red-to-green confirmed, or what remains unverified and why).",
+        "output": {
+          "path": "{{workPath}}/validation.md",
+          "minBytes": 400,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Repro re-run",
+              "label": "Repro re-run section"
+            },
+            {
+              "pattern": "^##\\s+Suite",
+              "label": "Suite section"
+            },
+            {
+              "pattern": "^##\\s+Result",
+              "label": "Result section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "commandEvidence",
+              "script": "test",
+              "expect": "pass",
+              "label": "the whole suite is green after the fix (verified run receipt)"
+            }
+          ]
+        }
+      }
+    ],
+    "review": {
+      "artifactPath": "{{workPath}}/validation.md",
+      "relatedPaths": [
+        "{{workPath}}/repro.md",
+        "{{workPath}}/diagnosis.md",
+        "{{workPath}}/fix-notes.md"
+      ],
+      "reviewPath": "{{workPath}}/review.md",
+      "reviewerRole": "debugging reviewer",
+      "repairRole": "software engineer",
+      "minReviewBytes": 400,
+      "enforce": {
+        "fixStepId": "repair"
+      },
+      "criteria": [
+        "The failure was reproduced with recorded red evidence: repro.md quotes a real failing run of a test that lives in the project's actual test layout, or the run stopped honestly at needs-user.",
+        "diagnosis.md names a defect site that exists in this codebase and a causal chain that actually explains the symptom.",
+        "The change is at that defect site, is minimal, and covers the sibling cases the diagnosis flagged — open the touched files and check; do not grade from fix-notes.md alone.",
+        "validation.md re-ran the original reproduction command and the once-failing test now passes with the whole suite green — judged from the recorded runs, not the author's summary.",
+        "The reproduction test survives as a permanent regression guard: it exists in the test layout and would fail again if the fix were reverted.",
+        "fix-notes.md names every touched file (paths that exist), states residual risk honestly, and gives runnable verification steps."
+      ]
+    }
+  }
+}

package/authoring/tactical/books/ci-pipeline.json

@@ -0,0 +1,168 @@
+{
+  "id": "ci-pipeline",
+  "name": "CI Pipeline from Scratch",
+  "description": "Author a CI pipeline grounded in what the repo actually has: inventory the real package scripts, write the workflow at the conventional location with caching and merge-gating on green, and verify every command it invokes against the manifests — honest that CI itself cannot run locally. Adds a publish-on-tag release job only when the repo shows one.",
+  "category": "code-release",
+  "role": "maintenance-review",
+  "tags": [
+    "ci",
+    "devops",
+    "pipeline",
+    "automation",
+    "github-actions",
+    "cd",
+    "release",
+    "yaml"
+  ],
+  "triggers": [
+    "set up ci",
+    "create a ci pipeline",
+    "github actions workflow",
+    "build a ci/cd pipeline",
+    "add automated testing on push",
+    "set up a release pipeline",
+    "ci/cd for releases",
+    "publish on tag workflow",
+    "github actions release",
+    "automate the release"
+  ],
+  "about": "Set up continuous integration the way it survives contact with a real repo: every stage grounded in a command that actually exists, and no claim that local reading cannot back. First INVENTORY: read package.json and the repo layout, record the scripts that genuinely exist with their exact lines quoted, and decide the stages — install, lint, typecheck, test, build, whichever subset is real here — plus caching keyed to the lockfile and the triggers the work calls for. The cardinal sin this book exists to prevent is the invented command: a `run:` line calling a script the repo does not have turns the whole pipeline red on its first push, so nothing enters the plan without a quoted manifest line behind it. A release or publish stage is planned only when the repo shows one — publish config, a release script, a tag convention — and when present it is gated behind the green test/build stages and the tag trigger so publishing can never run before the checks pass. Then AUTHOR the real workflow file(s) at the conventional location for the detected host (`.github/workflows/ci.yml` for GitHub Actions by default): minimal, cached, actions pinned to major versions, gating merges on green, with no fabricated secrets or inputs. Then VERIFY by reading the workflow back and matching EVERY command it invokes to the quoted manifest line that provides it — and by being plain that CI cannot be executed locally, so the notes must say what reading verified and what only a live run on the host can prove. Finally an independent reviewer checks the same ground truth — commands exist, stages ordered, triggers match, nothing invented — and a REVISE verdict routes the work back automatically with concrete findings. Works identically whether the run edits the project directly or drafts a change proposal for the user to apply.",
+  "doc": {
+    "capabilityFloor": "small",
+    "diffpackCapable": true
+  },
+  "workflow": {
+    "plan": "Inventory the repo's real commands and decide the stages -> author the workflow at the conventional location, cached and merge-gating -> verify every invoked command against the manifests, honest about what only a live CI run can prove -> enforced independent review.",
+    "maxGateAttempts": 4,
+    "maxReviewRounds": 3,
+    "phases": [
+      {
+        "id": "inventory",
+        "name": "Inventory the repo",
+        "description": "Read the real scripts and layout, then plan stages, caching, and triggers — never a command that does not exist.",
+        "suggestedRole": "devops engineer",
+        "capabilityFloor": "small",
+        "prompt": "Learn what this repo actually needs before writing a line of YAML. Read `package.json` (and any workspace manifests) with `read_file` and record the scripts that genuinely exist — their exact names and the exact lines. Read the repo layout with `list_dir`: the lockfile (which package manager), the language, build outputs, and any existing workflow files. NEVER invent a command: a stage enters your plan only when a matching script or standard invocation exists in the repo — install, lint, typecheck, test, build, in whatever subset is real here, and nothing for tools the repo does not use. Decide caching from the lockfile and package manager, and the triggers the task calls for (typically pushes to the default branch and pull requests). Plan a release or publish stage ONLY when the repo shows one — a publish configuration, a release script, an existing tag convention; when nothing shows one, say so and leave it out. Note the CI host the repo points at (existing workflow files, hosting hints); default to GitHub Actions when nothing says otherwise.\n\nWrite `{{workPath}}/ci-plan.md` with exactly these sections: `## Detected commands` (each script name with the exact line quoted from `package.json`), `## Pipeline stages` (the stages in order and why each exists here), `## Caching` (what is cached and what it is keyed on), `## Triggers` (the events and why). Cite the real files with backtick paths.",
+        "output": {
+          "path": "{{workPath}}/ci-plan.md",
+          "minBytes": 500,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Detected commands",
+              "label": "Detected commands section"
+            },
+            {
+              "pattern": "^##\\s+Pipeline stages",
+              "label": "Pipeline stages section"
+            },
+            {
+              "pattern": "^##\\s+Caching",
+              "label": "Caching section"
+            },
+            {
+              "pattern": "^##\\s+Triggers",
+              "label": "Triggers section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/ci-plan.md",
+              "minCitations": 2,
+              "artifact": true
+            }
+          ]
+        }
+      },
+      {
+        "id": "author",
+        "name": "Author the workflow",
+        "description": "Write the real workflow file(s) at the conventional location — minimal, cached, pinned, gating merges on green.",
+        "suggestedRole": "devops engineer",
+        "capabilityFloor": "small",
+        "prompt": "Read `{{workPath}}/ci-plan.md` and write the REAL workflow file(s) with `write_file` at the conventional location for the detected host — for GitHub Actions, `.github/workflows/ci.yml` unless the repo already has its own convention. Keep it minimal and fast: the planned stages in order, dependency caching wired to the lockfile, and the workflow triggering on the planned pushes and pull requests so merges gate on green. Pin every action to a major version (for example `actions/checkout@v4`); do not invent action names, inputs, or secrets. Every `run:` line must invoke a command the plan detected — nothing else. Add a release or publish job ONLY if ci-plan.md called for one, and gate it behind the green build/test stages and the tag trigger so a publish can never run before the checks pass; if the plan named no release stage, do not add one.\n\nThen write `{{workPath}}/ci-notes.md` with exactly these sections: `## Files written` (the real path of every workflow file, backtick path per line), `## Stages` (each job and step, and the detected command it runs), `## Choices explained` (caching, triggers, pinning, and anything you deliberately left out — including a release job when the repo showed no evidence for one).",
+        "output": {
+          "path": "{{workPath}}/ci-notes.md",
+          "minBytes": 500,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Files written",
+              "label": "Files written section"
+            },
+            {
+              "pattern": "^##\\s+Stages",
+              "label": "Stages section"
+            },
+            {
+              "pattern": "^##\\s+Choices explained",
+              "label": "Choices explained section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/ci-notes.md",
+              "minCitations": 2,
+              "artifact": true
+            }
+          ]
+        }
+      },
+      {
+        "id": "verify",
+        "name": "Verify against the manifests",
+        "description": "Read the workflow back and match every invoked command to the manifest line that provides it; honest about what only a live run proves.",
+        "suggestedRole": "devops engineer",
+        "capabilityFloor": "small",
+        "prompt": "Verify the workflow the only honest way available without a CI run: read it back and check every claim against the repo. Open each workflow file named in `{{workPath}}/ci-notes.md` with `read_file`, and for EVERY command it invokes, find and quote the `package.json` line (or manifest entry) that provides it — a `run:` line with no matching script is a defect: fix it now at the workflow's real site, not in prose. Confirm the triggers match `{{workPath}}/ci-plan.md`. Confirm every action reference is pinned to a major version, and every secret the workflow references is a standard one (`GITHUB_TOKEN`) or one the user explicitly named — an invented secret is a defect. Be plain about the limit of this verification: CI cannot be executed locally, so state what reading verified and what only a real run on the host can prove — never claim the pipeline ran.\n\nWrite `{{workPath}}/verification.md` with exactly these sections: `## Workflow files` (each file checked, backtick paths), `## Commands verified against package.json` (each workflow command with the quoted manifest line that provides it), `## Result` (what reading verified, what only a live CI run can prove, and any defects found and fixed).",
+        "output": {
+          "path": "{{workPath}}/verification.md",
+          "minBytes": 500,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Workflow files",
+              "label": "Workflow files section"
+            },
+            {
+              "pattern": "^##\\s+Commands verified against package\\.json",
+              "label": "Commands verified section"
+            },
+            {
+              "pattern": "^##\\s+Result",
+              "label": "Result section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/verification.md",
+              "minCitations": 2,
+              "artifact": true
+            }
+          ]
+        }
+      }
+    ],
+    "review": {
+      "artifactPath": "{{workPath}}/verification.md",
+      "relatedPaths": [
+        "{{workPath}}/ci-plan.md",
+        "{{workPath}}/ci-notes.md"
+      ],
+      "reviewPath": "{{workPath}}/review.md",
+      "reviewerRole": "devops reviewer",
+      "repairRole": "devops engineer",
+      "minReviewBytes": 400,
+      "enforce": {
+        "fixStepId": "repair"
+      },
+      "criteria": [
+        "Every command the workflow invokes exists in the repo — open package.json (and any other manifests) and check each run: line yourself; a script the repo does not have fails this criterion.",
+        "The stages are ordered sensibly (dependencies installed before lint/test/build) and dependency caching is wired to the real lockfile.",
+        "The triggers match ci-plan.md, and a release or publish job exists only where the plan showed repo evidence for one — gated behind the green stages and the tag trigger when present.",
+        "Nothing is invented: every action is pinned to a major version, no fabricated action inputs, and no secrets beyond standard ones or those the user explicitly named.",
+        "verification.md is honest about the limit of local verification — what reading proved versus what only a live CI run can prove — and the accounts reconcile across ci-plan.md, ci-notes.md, and verification.md."
+      ]
+    }
+  }
+}

package/authoring/tactical/books/codemod-sweep.json

@@ -0,0 +1,182 @@
+{
+  "id": "codemod-sweep",
+  "name": "Codemod Sweep",
+  "description": "Make a mechanical change everywhere it applies - a rename, an API-call migration, dead-code removal: enumerate every site first, apply the change under stated invariants, then re-scan to prove zero un-excluded sites remain, with counts that reconcile exactly and a green suite as receipts.",
+  "category": "code-quality",
+  "role": "general",
+  "tags": [
+    "codemod",
+    "rename",
+    "refactor",
+    "sweep",
+    "mechanical-change",
+    "quality"
+  ],
+  "triggers": [
+    "rename across the repo",
+    "codemod",
+    "migrate every call",
+    "remove the dead code"
+  ],
+  "about": "Run a mechanical, wide change - a rename, an API-call migration, a dead-code removal - the way a careful engineer runs a codemod: completeness IS the product, and each claim is mechanically verified. First ENUMERATE: work out the concrete search pattern for the old form, run real searches over the actual tree, count every site (definitions, re-exports, imports, call sites, and string mentions such as log lines when the change covers them), and list explicit exclusions - files that must keep the old form, such as changelogs - each with a defensible reason. Then APPLY the change at every listed site while holding the stated invariants (no behavior change beyond the declared one), handling the shapes that break naive sweeps - re-exports, aliased imports, strings - and running the suite as you go. Then VERIFY by re-running the exact search: zero un-excluded sites may remain, the found/changed/excluded counts must reconcile exactly, and the whole suite must be green. Finally an independent reviewer grades the chain against fixed criteria, and their REVISE verdict routes the work back automatically with concrete findings. Needs a project whose tests run via `npm run test`. Works identically whether the run edits the project directly or drafts a change proposal for the user to apply.",
+  "doc": {
+    "paramSchema": {
+      "type": "object",
+      "properties": {
+        "scope": {
+          "type": "string",
+          "title": "The mechanical change",
+          "description": "What to sweep: a rename, an API-call migration, dead-code removal. Name the old and new forms when you can.",
+          "default": ""
+        }
+      }
+    },
+    "capabilityFloor": "small",
+    "diffpackCapable": true,
+    "commands": [
+      {
+        "scope": "script",
+        "name": "test",
+        "reason": "the sweep must not change behavior - receipts"
+      }
+    ],
+    "runModes": {
+      "nightShift": "supported"
+    }
+  },
+  "workflow": {
+    "plan": "Enumerate every site with real searches (a count plus the list, and exclusions with reasons) -> apply the mechanical change at every listed site under the stated invariants with the suite run as you go -> re-scan to zero un-excluded sites, reconcile the counts, prove the suite green -> enforced independent review.",
+    "maxGateAttempts": 4,
+    "maxReviewRounds": 3,
+    "phases": [
+      {
+        "id": "enumerate",
+        "name": "Enumerate every site",
+        "description": "Find every site with real searches before touching one; count them and list explicit exclusions with reasons. No edits in this phase.",
+        "suggestedRole": "codebase analyst",
+        "capabilityFloor": "small",
+        "prompt": "The mechanical change: {{scope}}\n\nFind EVERY site before touching one - the sweep's completeness is the product. Work out the concrete search pattern (or patterns) that finds the old form: the definition, re-exports, imports, call sites, and string mentions such as log lines when the change covers them. Run real searches over the actual tree with `list_dir` and `read_file`, and record the exact pattern you used. Count the sites and list every one with a backtick path. List explicit exclusions - files that genuinely must keep the old form, such as changelogs or other historical records - each with a reason a reviewer could defend. If the old form cannot be found at all, record that honestly and stop. Do not change anything in this phase.\n\nWrite `{{workPath}}/sites.md` with exactly these sections: `## Pattern` (the exact search pattern or patterns), `## Sites found` (the count on its own line, then the list with a backtick path per site and what is at it), `## Exclusions` (each excluded file with its reason, or 'none').",
+        "output": {
+          "path": "{{workPath}}/sites.md",
+          "minBytes": 500,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Pattern",
+              "label": "Pattern section"
+            },
+            {
+              "pattern": "^##\\s+Sites found",
+              "label": "Sites found section"
+            },
+            {
+              "pattern": "^##\\s+Exclusions",
+              "label": "Exclusions section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/sites.md",
+              "minCitations": 2,
+              "artifact": true
+            }
+          ]
+        }
+      },
+      {
+        "id": "apply",
+        "name": "Apply the change at every site",
+        "description": "Make the mechanical change at every listed site, holding the stated invariants; leave exclusions untouched and run the suite as you go.",
+        "suggestedRole": "software engineer",
+        "capabilityFloor": "small",
+        "prompt": "Read `{{workPath}}/sites.md` and make the mechanical change at every listed site with `read_file` plus `write_file`/`replace_in_file`, holding the stated invariants: no behavior change beyond the declared one, and no listed site skipped. Handle the shapes that break naive sweeps deliberately - re-exports, aliased imports, and string mentions such as log lines when the declared change covers them. Leave every excluded file untouched. Run the suite with `run_package_script` (`test`) as you go and finish green; if the suite was red before you started, record that honestly and stop rather than sweeping on top of it. If the command needs first-use approval, say so and wait rather than guessing. A site that cannot take the change without altering behavior gets recorded with its reason, not forced.\n\nWrite `{{workPath}}/change-notes.md` with exactly these sections: `## Sites changed` (the count on its own line - it must reconcile with sites.md, with any difference explained), `## Files touched` (backtick path per line), `## Invariants held` (the declared change and why nothing else changed).",
+        "output": {
+          "path": "{{workPath}}/change-notes.md",
+          "minBytes": 500,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Sites changed",
+              "label": "Sites changed section"
+            },
+            {
+              "pattern": "^##\\s+Files touched",
+              "label": "Files touched section"
+            },
+            {
+              "pattern": "^##\\s+Invariants held",
+              "label": "Invariants held section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/change-notes.md",
+              "minCitations": 2,
+              "artifact": true
+            }
+          ]
+        }
+      },
+      {
+        "id": "verify",
+        "name": "Re-scan and reconcile",
+        "description": "Re-run the exact search to zero un-excluded sites, reconcile the counts across all three documents, and prove the suite green.",
+        "suggestedRole": "software engineer",
+        "capabilityFloor": "small",
+        "prompt": "Prove completeness with fresh eyes. Re-run the exact search pattern recorded in `{{workPath}}/sites.md` over the real tree - zero un-excluded sites may remain - and quote the re-scan and its result. Reconcile the counts: sites found in `{{workPath}}/sites.md`, sites changed in `{{workPath}}/change-notes.md`, and sites remaining now must add up exactly, with every exclusion accounted for. Open a few changed files with `read_file` and confirm the invariants held - nothing changed beyond the declared change. Re-run the whole suite with `run_package_script` (`test`) - it must be green. If the re-scan finds a missed site, fix it and re-scan again; if it cannot be fixed under the invariants, record it honestly instead of hiding it.\n\nWrite `{{workPath}}/verification.md` with exactly these sections: `## Residual scan` (the exact pattern re-run and what it found), `## Counts reconciled` (found vs changed vs excluded, adding up exactly), `## Suite` (the full-suite result), `## Result` (sweep complete, or what remains and why).",
+        "output": {
+          "path": "{{workPath}}/verification.md",
+          "minBytes": 450,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Residual scan",
+              "label": "Residual scan section"
+            },
+            {
+              "pattern": "^##\\s+Counts reconciled",
+              "label": "Counts reconciled section"
+            },
+            {
+              "pattern": "^##\\s+Suite",
+              "label": "Suite section"
+            },
+            {
+              "pattern": "^##\\s+Result",
+              "label": "Result section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "commandEvidence",
+              "script": "test",
+              "expect": "pass",
+              "label": "the suite is green after the sweep (verified run receipt)"
+            }
+          ]
+        }
+      }
+    ],
+    "review": {
+      "artifactPath": "{{workPath}}/verification.md",
+      "relatedPaths": [
+        "{{workPath}}/sites.md",
+        "{{workPath}}/change-notes.md"
+      ],
+      "reviewPath": "{{workPath}}/review.md",
+      "reviewerRole": "sweep reviewer",
+      "repairRole": "software engineer",
+      "minReviewBytes": 400,
+      "enforce": {
+        "fixStepId": "repair"
+      },
+      "criteria": [
+        "The re-scan in verification.md is quoted and shows zero un-excluded sites remaining for the exact pattern sites.md declared - re-run it yourself if anything looks off.",
+        "The counts reconcile exactly across sites.md, change-notes.md, and verification.md: found, changed, excluded, and remaining add up with no unexplained gap.",
+        "The invariants held: open a few changed files and confirm nothing changed beyond the declared mechanical change - do not grade from change-notes.md alone.",
+        "Tricky shapes were genuinely handled: re-exports, aliased imports, and covered string mentions were changed, not skipped as too hard.",
+        "Every exclusion has a defensible reason, and the excluded files are untouched.",
+        "The suite is green after the sweep - judged from the recorded run receipts, not the author's summary."
+      ]
+    }
+  }
+}