@bendyline/gilde 0.1.40 → 0.1.41

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

package/authoring/tactical/books/flaky-test-fix.json

@@ -0,0 +1,238 @@
+{
+  "id": "flaky-test-fix",
+  "name": "Fix a Flaky Test",
+  "description": "Hunt down an intermittently failing test and make it deterministic: reproduce the flake with real recorded runs, isolate the nondeterminism mechanism, remove it at the real site — never by deleting, skipping, or retrying the test — and prove stability with three consecutive green runs.",
+  "category": "code-quality",
+  "role": "maintenance-review",
+  "tags": [
+    "flaky-test",
+    "deflake",
+    "tests",
+    "nondeterminism",
+    "ci",
+    "debugging",
+    "quality"
+  ],
+  "triggers": [
+    "fix this flaky test",
+    "deflake",
+    "test fails intermittently",
+    "fails in CI but passes locally",
+    "intermittent test failure"
+  ],
+  "about": "Deflake a test the way a senior engineer would: by removing the nondeterminism, never by hiding it. First REPRODUCE statistically — run the real suite repeatedly with `run_package_script` until the intermittent failure is recorded in run receipts the gates can verify, and note the failure signature and the conditions it appears under (full suite versus alone, ordering, concurrency, timing). Then ISOLATE the mechanism with a targeted experiment — run the test alone versus in the suite, reorder, repeat — until you can name the defect site: the shared state, missing await, unseeded randomness, time dependence, or leaked resource that lets one run differ from the next. Then FIX at that real site with isolation or cleanup that covers every test — and never delete the test, skip it, weaken its assertion, widen a timeout, or wrap it in retries: those make the dashboard green while the bug ships. Finally PROVE stability: three consecutive green suite runs, read from real run receipts rather than the author's claims, then an independent reviewer checks that the mechanism itself was removed and a 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": "Flaky test to fix",
+          "description": "The flaky test, failure message, or suite area to chase. Leave empty when the task description already carries it.",
+          "default": ""
+        }
+      }
+    },
+    "capabilityFloor": "medium",
+    "diffpackCapable": true,
+    "commands": [
+      {
+        "scope": "script",
+        "name": "test",
+        "reason": "Statistical reproduction and the consecutive-green stability proof read real run receipts — the gates verify recorded runs, not claims."
+      }
+    ],
+    "runModes": {
+      "nightShift": "supported"
+    }
+  },
+  "workflow": {
+    "plan": "Reproduce the flake with recorded suite runs -> isolate the nondeterminism mechanism with a targeted experiment -> remove it at the real site (never skip, retry, or widen timeouts) -> prove stability with three consecutive green runs -> enforced independent review.",
+    "maxGateAttempts": 4,
+    "maxReviewRounds": 3,
+    "phases": [
+      {
+        "id": "reproduce",
+        "name": "Reproduce the flake with recorded runs",
+        "description": "Run the suite repeatedly until the intermittent failure is a recorded fact, and characterize when it appears.",
+        "suggestedRole": "debugging engineer",
+        "capabilityFloor": "medium",
+        "prompt": "The flaky test to fix: {{scope}}\n\nEstablish the flake as a recorded fact before theorizing. Find how this project runs its tests (`list_package_scripts`, then read the test layout). Run the suite with `run_package_script` (`test`) repeatedly — several runs if needed — until the intermittent failure is recorded, and keep the passing runs on record too: the pass/fail mix IS the evidence. Note the exact failure signature (test name, assertion, message) and the conditions it appears under — full suite versus alone, ordering, concurrency, timing, environment. If the command needs first-use approval, say so and wait rather than guessing. If the failure refuses to appear after many runs, record every run honestly and what you varied between them; do not fabricate a failing run.\n\nWrite `{{workPath}}/flake-evidence.md` with exactly these sections: `## Symptom` (which test fails, and how often out of how many runs), `## Runs observed` (each run and its outcome, with the failing output quoted from a real run), `## Failure signature` (the exact assertion and message), `## Suspected class` (ordering, shared state, timing, or environment — with the observation that points there). Cite the real test and source files with backtick paths.",
+        "output": {
+          "path": "{{workPath}}/flake-evidence.md",
+          "minBytes": 500,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Symptom",
+              "label": "Symptom section"
+            },
+            {
+              "pattern": "^##\\s+Runs observed",
+              "label": "Runs observed section"
+            },
+            {
+              "pattern": "^##\\s+Failure signature",
+              "label": "Failure signature section"
+            },
+            {
+              "pattern": "^##\\s+Suspected class",
+              "label": "Suspected class section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/flake-evidence.md",
+              "minCitations": 2,
+              "artifact": true
+            },
+            {
+              "kind": "commandEvidence",
+              "script": "test",
+              "expect": "fail",
+              "label": "at least one recorded failing run of the suite"
+            }
+          ]
+        }
+      },
+      {
+        "id": "isolate",
+        "name": "Isolate the mechanism",
+        "description": "Pin the nondeterminism with a targeted experiment and name the defect site. No fixes yet.",
+        "suggestedRole": "root-cause analyst",
+        "capabilityFloor": "medium",
+        "prompt": "Read `{{workPath}}/flake-evidence.md`, then pin the MECHANISM with a targeted experiment, not a guess. Good experiments: run the failing test alone versus in the full suite; temporarily reorder or comment out neighboring tests (and restore them afterwards); repeat runs to confirm the pattern is what you think it is. Read the test and the code under test until you can name the defect site precisely — the shared module state, missing await, unseeded randomness, time or filesystem dependence, or leaked resource that makes the outcome depend on anything besides the code under test. Check siblings: which neighboring tests share the same hazard? Undo every temporary experiment edit before finishing, and make no fix in this phase. If the experiments stay inconclusive, record what each one showed and ruled out — an honest unknown beats a confident guess.\n\nWrite `{{workPath}}/diagnosis.md` with exactly these sections: `## Mechanism` (the nondeterminism, named concretely), `## Experiment` (what you ran and what each variation showed), `## Defect site` (file and symbol, with backtick paths), `## Siblings checked` (neighboring tests that share or escape the hazard). Every path you cite must be real.",
+        "output": {
+          "path": "{{workPath}}/diagnosis.md",
+          "minBytes": 600,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Mechanism",
+              "label": "Mechanism section"
+            },
+            {
+              "pattern": "^##\\s+Experiment",
+              "label": "Experiment section"
+            },
+            {
+              "pattern": "^##\\s+Defect site",
+              "label": "Defect site section"
+            },
+            {
+              "pattern": "^##\\s+Siblings checked",
+              "label": "Siblings checked section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/diagnosis.md",
+              "minCitations": 2,
+              "artifact": true
+            }
+          ]
+        }
+      },
+      {
+        "id": "fix",
+        "name": "Remove the nondeterminism",
+        "description": "Make the outcome deterministic at the real site — isolation, cleanup, awaits, seeding — never masking.",
+        "suggestedRole": "software engineer",
+        "capabilityFloor": "medium",
+        "prompt": "Read `{{workPath}}/diagnosis.md` and remove the nondeterminism 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`. The right shapes: cleanup or isolation that runs for EVERY test (a beforeEach/afterEach reset, a fresh instance per test), an explicit await on work that was racing, seeded or injected randomness and time, releasing leaked resources. NEVER delete or skip the flaky test, never weaken its assertion, and never mask the flake with retries or widened timeouts — the test must still assert exactly what it asserted. A one-off reset inside the failing test alone is not cleanup; future tests inherit the same hazard, so fix it at the level every test shares. Cover the sibling hazards the diagnosis flagged. Re-run the suite with `run_package_script` (`test`) while you work.\n\nWrite `{{workPath}}/fix-notes.md` with exactly these sections: `## Problem` (one paragraph naming the mechanism), `## Change` (what you altered and why the outcome can no longer depend on order, timing, or luck), `## Files touched` (backtick path per line), `## Regression coverage` (why the flake cannot silently return — what fails if the cleanup is removed), `## Risk` (anything unverified, honestly), `## How to verify` (the exact commands a person runs).",
+        "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-stability",
+        "name": "Prove stability",
+        "description": "Three consecutive green suite runs, read from real receipts — one green run means nothing for a flake.",
+        "suggestedRole": "software engineer",
+        "capabilityFloor": "medium",
+        "prompt": "Prove the fix holds under repetition — one green run means nothing for a flake. Run the full suite with `run_package_script` (`test`) at least THREE times in a row; every run must be green, and the runs must be real receipts, not claims. If any run fails, the mechanism is not gone: record the failure honestly and route back through the evidence rather than re-rolling until you get lucky. Compare against `{{workPath}}/flake-evidence.md`: the once-flaky test must be present and passing in every run.\n\nWrite `{{workPath}}/validation.md` with exactly these sections: `## Runs` (each run and its result, in order), `## Result` (stability confirmed with the receipts, or what remains unstable and why).",
+        "output": {
+          "path": "{{workPath}}/validation.md",
+          "minBytes": 300,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Runs",
+              "label": "Runs section"
+            },
+            {
+              "pattern": "^##\\s+Result",
+              "label": "Result section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "commandEvidence",
+              "script": "test",
+              "expect": "pass",
+              "minRuns": 3,
+              "label": "three consecutive green suite runs (verified run receipts)"
+            }
+          ]
+        }
+      }
+    ],
+    "review": {
+      "artifactPath": "{{workPath}}/validation.md",
+      "relatedPaths": [
+        "{{workPath}}/flake-evidence.md",
+        "{{workPath}}/diagnosis.md",
+        "{{workPath}}/fix-notes.md"
+      ],
+      "reviewPath": "{{workPath}}/review.md",
+      "reviewerRole": "test reliability reviewer",
+      "repairRole": "software engineer",
+      "minReviewBytes": 400,
+      "enforce": {
+        "fixStepId": "repair"
+      },
+      "criteria": [
+        "flake-evidence.md records real runs with at least one genuine failure quoted from run output and names the conditions the failure appeared under — not a summary of a hunch.",
+        "diagnosis.md names a concrete nondeterminism mechanism and a defect site that exists in this codebase, supported by a targeted experiment whose causal story actually explains the observed pass/fail pattern.",
+        "The change removes the mechanism at that site — open the touched files and check it is isolation, cleanup, awaited work, or seeded inputs at the level every test shares, not a one-off patch inside the failing test.",
+        "No masking: the once-flaky test still exists and still asserts what it asserted — open the test file and compare its assertion against flake-evidence.md's failure signature; it gained no skip, retry loop, or widened timeout.",
+        "validation.md's three consecutive green runs are backed by real run receipts with the once-flaky test present and passing — judged from the recorded runs, not the author's claims.",
+        "fix-notes.md names every touched file with paths that exist, explains why the flake cannot silently return, and states residual risk honestly."
+      ]
+    }
+  }
+}

package/authoring/tactical/books/hotfix-flow.json

@@ -0,0 +1,187 @@
+{
+  "id": "hotfix-flow",
+  "name": "Hotfix Flow",
+  "description": "Stop a live failure with the smallest change that fixes it at the real site: reproduce with the least machinery that demonstrates the failure, patch minimally with the proper repair recorded as follow-up, validate with a rollback path, and pass an enforced review of the blast radius.",
+  "category": "code-quality",
+  "role": "maintenance-review",
+  "tags": [
+    "hotfix",
+    "bug-fix",
+    "tdd",
+    "release",
+    "patch",
+    "regression",
+    "incident",
+    "minimal-diff",
+    "rollback"
+  ],
+  "triggers": [
+    "hotfix this bug",
+    "urgent production fix",
+    "expedited patch",
+    "fix the live defect",
+    "out-of-band fix",
+    "emergency fix",
+    "stop the bleeding"
+  ],
+  "about": "The minimal-diff bug fix for when something is broken NOW. Urgency is not an excuse for guesswork, so the ordering still holds — but every step is sized for an emergency. First REPRODUCE with the LEAST machinery that honestly demonstrates the failure: the command the incident names, a few-line probe, a focused test only when it costs minutes — never new test infrastructure at midnight. A hotfix aimed at an unreproduced defect is a coin flip. Then PATCH: the smallest change at the real defect site that stops the failure, with refactors, renames, and the proper deeper repair explicitly deferred into a written Follow-up rather than attempted under pressure — the debt is recorded, not denied. Then VALIDATE: re-run the exact reproduction, exercise the immediate neighborhood cheaply, state plainly what was and was not verified, and write the rollback path before anyone needs it. Finally an independent reviewer grades the whole chain — blast radius counted in the touched files, evidence concrete, rollback runnable, debt recorded — and a REVISE verdict routes the work back automatically with findings. Deliberately requires no test suite or npm commands: it works on projects where nothing is runnable but the failure itself, which is exactly where hotfixes happen. 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": "Incident to hotfix",
+          "description": "The incident, bug report, or failing behavior to hotfix. Leave empty when the task description already carries it.",
+          "default": ""
+        }
+      }
+    },
+    "capabilityFloor": "small",
+    "diffpackCapable": true
+  },
+  "workflow": {
+    "plan": "Reproduce with the least machinery that demonstrates the failure -> smallest change that stops the bleeding at the real defect site (proper repair deferred to Follow-up) -> re-run the reproduction and record a rollback path -> enforced independent review of blast radius and honesty.",
+    "maxGateAttempts": 4,
+    "maxReviewRounds": 3,
+    "phases": [
+      {
+        "id": "reproduce",
+        "name": "Reproduce with the least machinery",
+        "description": "Establish the failure cheaply and concretely: a command, a probe, or a focused test — whatever demonstrates it fastest.",
+        "suggestedRole": "incident responder",
+        "capabilityFloor": "small",
+        "prompt": "The incident to hotfix: {{scope}}\n\nEstablish the failure with the LEAST machinery that honestly demonstrates it — this is an emergency, not the time to build test infrastructure. Read the incident report and the involved source with `read_file`. Choose the cheapest real reproduction: the command or entry point the report names, a few-line probe script, or a focused test only when the project already has an obvious test layout and it costs minutes. When a script-execution tool such as `run_nodejs_script` is wired this turn, actually run the reproduction and capture the output — the error text, the stack line, the wrong value. When no execution surface is available, say so plainly and pin the failure by reading the code to the exact line instead; never present a run you did not perform. Do not fix anything in this phase. If you cannot reproduce or locate the failure at all, record every attempt honestly rather than inventing a cause.\n\nWrite `{{workPath}}/repro.md` with exactly these sections: `## Symptom` (what is breaking, in the reporter's words), `## Repro command` (the exact command or probe that demonstrates it), `## Expected`, `## Actual` (the captured output or observed behavior — quote real text, and label anything you could not execute), `## Evidence` (the involved files with backtick paths, down to the line or symbol where the failure surfaces).",
+        "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+Evidence",
+              "label": "Evidence section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/repro.md",
+              "minCitations": 2,
+              "artifact": true
+            }
+          ]
+        }
+      },
+      {
+        "id": "patch",
+        "name": "Smallest change that stops the bleeding",
+        "description": "Fix the cause at the real defect site with the minimum blast radius; defer the proper repair into Follow-up.",
+        "suggestedRole": "software engineer",
+        "capabilityFloor": "small",
+        "prompt": "Read `{{workPath}}/repro.md`, find the defect site it points at, and stop the bleeding with the SMALLEST change that fixes the cause. There is no prescribed output path for source changes — edit the actual files with `read_file` plus `write_file`/`replace_in_file`. Hotfix discipline: touch only what stopping THIS failure requires — no refactors, no renames, no drive-by cleanup, no new abstractions. When the proper repair is bigger than the emergency allows, make the safe narrow change now and write the proper repair into Follow-up instead of attempting it. Never special-case the exact reproduction input just to silence it, and never hide the failure behind a blanket try/catch that swallows the error instead of preventing it. Re-check the reproduction as you work.\n\nWrite `{{workPath}}/fix-notes.md` with exactly these sections: `## Problem` (one paragraph), `## Change` (what you altered and why it stops the failure at its cause), `## Files touched` (backtick path per line), `## Risk` (what this patch could still break and anything you did not verify — be honest), `## How to verify` (the exact commands or checks a person runs to confirm), `## Follow-up` (the deferred proper fix and the debt this patch leaves, plus the backport note when other branches or releases need it).",
+        "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+Risk",
+              "label": "Risk section"
+            },
+            {
+              "pattern": "^##\\s+How to verify",
+              "label": "How to verify section"
+            },
+            {
+              "pattern": "^##\\s+Follow-up",
+              "label": "Follow-up section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/fix-notes.md",
+              "minCitations": 2,
+              "artifact": true
+            }
+          ]
+        }
+      },
+      {
+        "id": "validate",
+        "name": "Re-run the reproduction and record rollback",
+        "description": "Prove the failure is gone, be explicit about what was and was not verified, and write the escape route.",
+        "suggestedRole": "software engineer",
+        "capabilityFloor": "small",
+        "prompt": "Prove the patch did its one job, and write down the escape route. Read `{{workPath}}/repro.md` and re-run the EXACT reproduction it records — the failure must be gone. Exercise the immediate neighborhood the cheapest honest way you can (the same entry point on a healthy input, an existing script, a small probe) so the patch did not trade one failure for another. Anything you could not actually run is recorded as unverified, never claimed — and when no execution surface is available this turn, verify by re-reading the changed code against the reproduction and say plainly that the run itself is still owed. Then record the rollback: exactly how to undo this patch fast if it goes wrong after shipping.\n\nWrite `{{workPath}}/validation.md` with exactly these sections: `## Repro re-run` (the command and what happened, or the honest record of why it could not run), `## Result` (what is fixed, what was verified, what remains unverified), `## Rollback` (the concrete, runnable way to revert this patch — the exact files to restore or the commit to revert, plus any step that must accompany it).",
+        "output": {
+          "path": "{{workPath}}/validation.md",
+          "minBytes": 400,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Repro re-run",
+              "label": "Repro re-run section"
+            },
+            {
+              "pattern": "^##\\s+Result",
+              "label": "Result section"
+            },
+            {
+              "pattern": "^##\\s+Rollback",
+              "label": "Rollback section"
+            }
+          ]
+        }
+      }
+    ],
+    "review": {
+      "artifactPath": "{{workPath}}/validation.md",
+      "relatedPaths": [
+        "{{workPath}}/repro.md",
+        "{{workPath}}/fix-notes.md"
+      ],
+      "reviewPath": "{{workPath}}/review.md",
+      "reviewerRole": "incident reviewer",
+      "repairRole": "software engineer",
+      "minReviewBytes": 400,
+      "enforce": {
+        "fixStepId": "repair"
+      },
+      "criteria": [
+        "repro.md is concrete and honest: it quotes real captured output from a run that actually happened, or explicitly records that execution was unavailable and pins the failure to a line in the source — never an invented run.",
+        "The change is genuinely minimal: open every file fix-notes.md names and count the blast radius — nothing rode along beyond what stopping this one failure requires (no refactor, rename, or cleanup).",
+        "The patch fixes the cause at the real defect site rather than special-casing the reproduction input or swallowing the error with a blanket catch.",
+        "validation.md re-ran the original reproduction and the failure is gone — or states plainly what could not be run and why; nothing is claimed verified that was not.",
+        "The Rollback section is a real, runnable path: the exact files or commit to revert plus any accompanying step, not a vague instruction to undo the change.",
+        "The Follow-up section records the deferred proper fix and the debt this patch leaves, with a backport note when other branches or releases need it.",
+        "Every file path cited across repro.md, fix-notes.md, and validation.md exists in this project."
+      ]
+    }
+  }
+}