@bendyline/gilde 0.1.39 → 0.1.41

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."
+      ]
+    }
+  }
+}

package/authoring/tactical/books/dependency-upgrade.json

@@ -0,0 +1,196 @@
+{
+  "id": "dependency-upgrade",
+  "name": "Upgrade a Dependency",
+  "description": "Upgrade dependencies in reviewable stages with proof at every step: a green suite before any bump, smallest-risk-first ordering, call-site adaptations at their real locations, a real suite run between stages, and an honest revert for anything that cannot go green.",
+  "category": "code-quality",
+  "role": "maintenance-review",
+  "tags": [
+    "dependencies",
+    "upgrade",
+    "maintenance",
+    "supply-chain",
+    "tests",
+    "quality"
+  ],
+  "triggers": [
+    "upgrade the dependencies",
+    "bump the deps",
+    "update this package",
+    "dependency upgrade"
+  ],
+  "about": "Upgrade dependencies the way a careful maintainer would, with each claim mechanically verified. This is the applying sibling of the report-only Dependency Audit: where that book tells you what is risky, this one moves the versions. First SURVEY: read the real dependency state (manifest, lockfile, installed packages, or a vendored tree the repository documents), run the suite so green-before-any-bump is a recorded receipt, and read each candidate's breaking-change surface from what exists LOCALLY - changelogs and READMEs inside node_modules, or the repository's own upgrade notes. Release notes are never invented; a candidate whose changes cannot be read locally is staged conservatively and marked unknown. Then UPGRADE stage by stage, smallest-risk-first: apply the version change at its real location, adapt the call sites it breaks, and run the suite before the next stage begins. A stage that cannot go green is reverted and recorded with the reason, never forced through; a major that needs real design work is deferred honestly. Then VERIFY the final tree green and record a concrete rollback path. 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": "What to upgrade",
+          "description": "A single dependency, a patch-level sweep, or a named major upgrade. Leave empty to survey and pick the safest valuable set.",
+          "default": ""
+        }
+      }
+    },
+    "capabilityFloor": "medium",
+    "diffpackCapable": true,
+    "commands": [
+      {
+        "scope": "script",
+        "name": "test",
+        "reason": "each upgrade stage must leave the suite green - the gates read real run receipts"
+      }
+    ],
+    "runModes": {
+      "scheduled": "supported"
+    }
+  },
+  "workflow": {
+    "plan": "Survey the real dependency state and stage the work smallest-risk-first (green-suite receipt before any bump) -> execute stage by stage with the suite run between stages and honest reverts -> verify the final tree green and record the rollback path -> enforced independent review.",
+    "maxGateAttempts": 4,
+    "maxReviewRounds": 3,
+    "phases": [
+      {
+        "id": "survey",
+        "name": "Survey the dependency state",
+        "description": "Read the real dependency state and each candidate's locally-readable breaking-change surface, record the green baseline, and stage the work smallest-risk-first.",
+        "suggestedRole": "dependency auditor",
+        "capabilityFloor": "medium",
+        "prompt": "The upgrade scope: {{scope}}\n\nEstablish the REAL dependency state before changing anything. Read `package.json` (and the lockfile if one exists), run `list_packages`, and work out how this project consumes each dependency - registry installs, or a vendored tree the repository documents. Then run the suite with `run_package_script` (`test`) and record that it is green BEFORE any bump. If the suite is already red, record the failure honestly and stop - never upgrade on top of a red suite. If the command needs first-use approval, say so and wait rather than guessing.\n\nFor each upgrade candidate, read its breaking-change surface from what is available LOCALLY: changelogs and READMEs inside `node_modules/`, or the repository's own upgrade notes for vendored code. Never invent release notes you did not read - a candidate whose changes you cannot read locally gets staged conservatively and marked unknown. Order the stages smallest-risk-first: patches before minors before majors, one dependency (or one tightly-coupled group) per stage. If nothing is worth upgrading here, record that finding honestly and stop.\n\nWrite `{{workPath}}/survey.md` with exactly these sections: `## Current state` (what is installed, from the real manifest and lockfile), `## Candidates` (each candidate with its current and target version and where you read its notes), `## Breaking-change notes` (what actually changes, only from sources you read, each cited with a backtick path), `## Stage plan` (numbered stages, smallest-risk-first, with the reason for the order).",
+        "output": {
+          "path": "{{workPath}}/survey.md",
+          "minBytes": 600,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Current state",
+              "label": "Current state section"
+            },
+            {
+              "pattern": "^##\\s+Candidates",
+              "label": "Candidates section"
+            },
+            {
+              "pattern": "^##\\s+Breaking-change notes",
+              "label": "Breaking-change notes section"
+            },
+            {
+              "pattern": "^##\\s+Stage plan",
+              "label": "Stage plan section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/survey.md",
+              "minCitations": 2,
+              "artifact": true
+            },
+            {
+              "kind": "commandEvidence",
+              "script": "test",
+              "expect": "pass",
+              "label": "green before any bump"
+            }
+          ]
+        }
+      },
+      {
+        "id": "upgrade",
+        "name": "Execute the stages",
+        "description": "Apply each stage at its real location, adapt the call sites it breaks, and run the suite between stages; revert and record any stage that cannot go green.",
+        "suggestedRole": "software engineer",
+        "capabilityFloor": "medium",
+        "prompt": "Read `{{workPath}}/survey.md` and execute its stage plan one stage at a time. For each stage: apply the version change at its real location - edit the manifest and run `npm_install` for registry dependencies, or replace the vendored tree exactly as the repository's convention documents for vendored ones - then adapt every call site the change breaks at its real location with `read_file` plus `write_file`/`replace_in_file`, and run the suite with `run_package_script` (`test`) before starting the next stage. Never begin a stage while the previous one is red.\n\nA stage that cannot go green gets REVERTED - put the manifest, lockfile, and touched files back exactly as they were - and recorded with the concrete failure, never forced through by weakening tests or pinning over the breakage. A major that turns out to need real design work is deferred honestly, not hacked through. If every stage had to be reverted, record that outcome honestly and stop.\n\nWrite `{{workPath}}/change-notes.md` with exactly these sections: `## Stages executed` (each stage with its suite result), `## Files touched` (backtick path per line), `## Adaptations` (each call-site change and why the new version needs it), `## Reverted stages` (each with the concrete failure that forced the revert, or 'none').",
+        "output": {
+          "path": "{{workPath}}/change-notes.md",
+          "minBytes": 700,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Stages executed",
+              "label": "Stages executed section"
+            },
+            {
+              "pattern": "^##\\s+Files touched",
+              "label": "Files touched section"
+            },
+            {
+              "pattern": "^##\\s+Adaptations",
+              "label": "Adaptations section"
+            },
+            {
+              "pattern": "^##\\s+Reverted stages",
+              "label": "Reverted stages section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/change-notes.md",
+              "minCitations": 2,
+              "artifact": true
+            }
+          ]
+        }
+      },
+      {
+        "id": "verify",
+        "name": "Verify and record the rollback",
+        "description": "Re-run the whole suite on the final tree, spot-check the adaptations, and record a concrete rollback path.",
+        "suggestedRole": "software engineer",
+        "capabilityFloor": "medium",
+        "prompt": "Prove the result with fresh eyes. Re-run the whole suite with `run_package_script` (`test`) - it must be green on the final tree; if it is not, go back and fix or revert before verifying again. Re-read `{{workPath}}/change-notes.md` and spot-check each adaptation at its real location with `read_file`. Then record the rollback path: exactly which manifest and lockfile entries (or vendored files) to restore, and in what order, to return to the pre-upgrade state. Anything you could not actually run gets labeled unverified, never claimed.\n\nWrite `{{workPath}}/verification.md` with exactly these sections: `## Suite` (the full-suite command and its result), `## Adaptations verified` (which call sites you re-opened and what you confirmed), `## Rollback` (the concrete revert steps), `## Result` (upgraded and green, or what remains unverified and why).",
+        "output": {
+          "path": "{{workPath}}/verification.md",
+          "minBytes": 450,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Suite",
+              "label": "Suite section"
+            },
+            {
+              "pattern": "^##\\s+Adaptations verified",
+              "label": "Adaptations verified section"
+            },
+            {
+              "pattern": "^##\\s+Rollback",
+              "label": "Rollback section"
+            },
+            {
+              "pattern": "^##\\s+Result",
+              "label": "Result section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "commandEvidence",
+              "script": "test",
+              "expect": "pass",
+              "label": "the whole suite is green on the upgraded tree (verified run receipt)"
+            }
+          ]
+        }
+      }
+    ],
+    "review": {
+      "artifactPath": "{{workPath}}/verification.md",
+      "relatedPaths": [
+        "{{workPath}}/survey.md",
+        "{{workPath}}/change-notes.md"
+      ],
+      "reviewPath": "{{workPath}}/review.md",
+      "reviewerRole": "dependency reviewer",
+      "repairRole": "software engineer",
+      "minReviewBytes": 400,
+      "enforce": {
+        "fixStepId": "repair"
+      },
+      "criteria": [
+        "The stages in change-notes.md were real and ordered smallest-risk-first, matching the plan in survey.md or explaining every deviation.",
+        "Green between stages is receipts, not claims: the suite was genuinely run before the first bump and between stages - judged from the recorded runs, not the author's summary.",
+        "Breaking-change notes cite sources that were genuinely read locally; nothing is presented as a release note that was invented.",
+        "Every adaptation cites a real file, and the change at that site matches what the new version actually requires - open the touched files; do not grade from change-notes.md alone.",
+        "Stages that could not go green were reverted and recorded with concrete reasons; majors that need design work were deferred honestly, not hacked through.",
+        "verification.md records a concrete, runnable rollback path and the final suite run is green - judged from the recorded run receipts."
+      ]
+    }
+  }
+}