@bendyline/gilde 0.1.39 → 0.1.41

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

package/authoring/tactical/books/perf-optimization.json

@@ -0,0 +1,219 @@
+{
+  "id": "perf-optimization",
+  "name": "Targeted Performance Fix",
+  "description": "Make a measured, targeted performance improvement: baseline numbers recorded with their method before anything changes, one bottleneck fixed in reversible stages with the suite green, the same measurement re-run to prove the gain, and an enforced independent review.",
+  "category": "code-quality",
+  "role": "maintenance-review",
+  "tags": [
+    "performance",
+    "optimization",
+    "profiling",
+    "benchmark",
+    "speed",
+    "tests"
+  ],
+  "triggers": [
+    "optimize performance",
+    "make this faster",
+    "fix a slow function",
+    "profile and optimize",
+    "reduce latency",
+    "speed up the test suite",
+    "fix an n+1 pattern"
+  ],
+  "about": "Make code measurably faster without breaking it, and with every claim mechanically verified — because optimizing without measuring is guessing, and 'feels faster' is not a deliverable. First BASELINE: run the suite green, then measure the slow path with a repeatable method written down exactly (an operation counter, a timing harness, a suite duration, a query count), and pick the ONE bottleneck this run will attack. A number recorded without its method is a gate failure by construction. Then PLAN: a numeric target and small reversible stages that each leave the tree working. Then CHANGE: fix the bottleneck at the real sites — never by rewriting the measurement so the number looks better — keeping the suite green between stages. Then VERIFY: re-measure with the SAME method and quote both numbers side by side. Finally an independent reviewer grades the chain — method identical before and after, correctness held with receipts, no measurement theater — and a REVISE verdict routes the work back automatically with concrete findings. The scope can be any slow path: a hot function, an endpoint, an N+1 access pattern that re-fetches inside a loop, or a slow test suite — the discipline is identical for all of them: measure it, fix one bottleneck, re-measure it the same way. 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 optimize",
+          "description": "The slow path to work on: a function, an endpoint, an N+1 access pattern, a slow test suite. Leave empty when the task description carries it.",
+          "default": ""
+        }
+      }
+    },
+    "capabilityFloor": "medium",
+    "diffpackCapable": true,
+    "commands": [
+      {
+        "scope": "script",
+        "name": "test",
+        "reason": "Correctness is the guardrail: the suite must be green before the optimization starts, stay green between stages, and be green at the end. The gates verify the green-before/green-after receipts from real runs, not the author's claims."
+      }
+    ]
+  },
+  "workflow": {
+    "plan": "Record a green suite and baseline numbers with their exact method -> plan a numeric target and reversible stages -> fix the one bottleneck at the real sites with the suite green throughout -> re-measure with the same method and quote both numbers -> enforced independent review.",
+    "maxGateAttempts": 4,
+    "maxReviewRounds": 3,
+    "phases": [
+      {
+        "id": "baseline",
+        "name": "Measure the baseline",
+        "description": "Record the current numbers with a repeatable method, confirm the suite green, and pick the one bottleneck to attack.",
+        "suggestedRole": "performance engineer",
+        "capabilityFloor": "medium",
+        "prompt": "The optimization target: {{scope}}\n\nMeasure before you touch anything — a performance claim without a number is a guess, and this book's gates reject guesses by construction. Read the involved source and find how this project runs its tests (`list_package_scripts`). Run the suite with `run_package_script` (`test`) and confirm it is GREEN before the work starts; if it is already red, stop and report that honestly. If the command needs first-use approval, say so and wait rather than guessing.\n\nThen measure the slow path itself with a repeatable method you write down exactly: an operation counter the code exposes, a timing harness you run with `run_nodejs_script` (repeat it a few times and note the spread), the suite's own duration, a query or fetch count for an N+1 pattern. Record the numbers exactly as measured, with the command that produced them. Pick the ONE bottleneck this run will attack — reason from the measurements rather than guessing — and name its mechanism (quadratic rescan, repeated work inside a loop, per-item fetch, needless setup per test). One bottleneck at a time; park the rest in your notes.\n\nWrite `{{workPath}}/baseline.md` with exactly these sections: `## Current behavior` (what the slow path does and which tests pin its correctness), `## Measurements` (the numbers, the exact method and command used to gather them, and the chosen bottleneck with its mechanism), `## Guardrail` (what must not change: results on the same inputs, observable behavior, the suite staying green). Cite the real files involved with backtick paths.",
+        "output": {
+          "path": "{{workPath}}/baseline.md",
+          "minBytes": 500,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Current behavior",
+              "label": "Current behavior section"
+            },
+            {
+              "pattern": "^##\\s+Measurements[\\s\\S]*\\d",
+              "label": "Measurements section with recorded numbers"
+            },
+            {
+              "pattern": "^##\\s+Guardrail",
+              "label": "Guardrail section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/baseline.md",
+              "minCitations": 2,
+              "artifact": true
+            },
+            {
+              "kind": "commandEvidence",
+              "script": "test",
+              "expect": "pass",
+              "label": "green before the work starts"
+            }
+          ]
+        }
+      },
+      {
+        "id": "plan",
+        "name": "Plan the fix",
+        "description": "Set a numeric target for the one bottleneck and break the fix into reversible stages. No source edits.",
+        "suggestedRole": "performance engineer",
+        "capabilityFloor": "medium",
+        "prompt": "Read `{{workPath}}/baseline.md`, then plan the fix for the ONE bottleneck it names. State the target as a number wherever possible (an operation count under a budget, a duration under a threshold, one query per batch instead of one per item) and the mechanism of the improvement (a better data structure, hoisting repeated work out of the loop, batching the access, sharing expensive setup). Break the work into ordered stages where EACH stage is individually reversible and leaves the tree working with the suite green. Name the files each stage touches. State the acceptance criteria: the measured number reaching the target using the SAME method as the baseline, results identical on the same inputs, and the suite green after every stage. Do not edit any source in this phase.\n\nWrite `{{workPath}}/plan.md` with exactly these sections: `## Target` (the number to reach and the mechanism), `## Stages` (numbered, each reversible, each naming its files), `## Acceptance criteria`. Cite the real files with backtick paths.",
+        "output": {
+          "path": "{{workPath}}/plan.md",
+          "minBytes": 500,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Target",
+              "label": "Target section"
+            },
+            {
+              "pattern": "^##\\s+Stages",
+              "label": "Stages section"
+            },
+            {
+              "pattern": "^##\\s+Acceptance criteria",
+              "label": "Acceptance criteria section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/plan.md",
+              "minCitations": 2,
+              "artifact": true
+            }
+          ]
+        }
+      },
+      {
+        "id": "change",
+        "name": "Fix the bottleneck",
+        "description": "Execute the planned stages at the real sites, keeping the suite green and the measurement honest.",
+        "suggestedRole": "software engineer",
+        "capabilityFloor": "medium",
+        "prompt": "Read `{{workPath}}/plan.md` and `{{workPath}}/baseline.md`, then execute the stages in order at the REAL sites — edit the actual files with `read_file` plus `write_file`/`replace_in_file`; never a scratch copy, and never a rewrite of the measurement itself so the number looks better — fixing the measured path is the job, fixing the measurement is theater. After EACH stage, run the suite with `run_package_script` (`test`) and confirm it is still green before starting the next; a stage that goes red gets reverted or narrowed, not stacked on. Re-run the baseline's measurement as you go so you can see the number actually moving. Results must stay identical on the same inputs — speed that changes answers is a bug, not a win. Keep the code readable; do not obfuscate for a marginal gain.\n\nWrite `{{workPath}}/change-notes.md` with exactly these sections: `## Stages executed` (each stage, in order, with its suite-green confirmation and any interim measurement), `## Files touched` (backtick path per line), `## Deviations from plan` (anything done differently than plan.md and why; write `none` honestly when there are none).",
+        "output": {
+          "path": "{{workPath}}/change-notes.md",
+          "minBytes": 600,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Stages executed",
+              "label": "Stages executed section"
+            },
+            {
+              "pattern": "^##\\s+Files touched",
+              "label": "Files touched section"
+            },
+            {
+              "pattern": "^##\\s+Deviations from plan",
+              "label": "Deviations from plan section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/change-notes.md",
+              "minCitations": 2,
+              "artifact": true
+            }
+          ]
+        }
+      },
+      {
+        "id": "verify",
+        "name": "Re-measure and verify",
+        "description": "Re-measure with exactly the baseline's method, quote both numbers side by side, and record the suite green.",
+        "suggestedRole": "performance engineer",
+        "capabilityFloor": "medium",
+        "prompt": "Prove the speedup with fresh eyes. Read `{{workPath}}/baseline.md` and re-measure with EXACTLY the method and command it records — same workload, same counter, same harness; if the recorded method cannot be reproduced, that is a finding to report, not a license to substitute a friendlier one. Quote the baseline number and the new number side by side. Run the whole suite with `run_package_script` (`test`) and record the green result. Confirm results are identical to the baseline on the same inputs. Anything you could not actually re-run gets labeled unverified, never claimed.\n\nWrite `{{workPath}}/verification.md` with exactly these sections: `## Before / after` (the baseline figure and the re-measured figure side by side, same method, both quoted), `## Suite` (the full-suite result from the real run), `## Result` (target met or honestly missed, and anything unverified).",
+        "output": {
+          "path": "{{workPath}}/verification.md",
+          "minBytes": 400,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Before\\s*/\\s*after[\\s\\S]*\\d",
+              "label": "Before / after section with both numbers"
+            },
+            {
+              "pattern": "^##\\s+Suite",
+              "label": "Suite section"
+            },
+            {
+              "pattern": "^##\\s+Result",
+              "label": "Result section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "commandEvidence",
+              "script": "test",
+              "expect": "pass",
+              "label": "green after the optimization (verified run receipt)"
+            }
+          ]
+        }
+      }
+    ],
+    "review": {
+      "artifactPath": "{{workPath}}/verification.md",
+      "relatedPaths": [
+        "{{workPath}}/baseline.md",
+        "{{workPath}}/plan.md",
+        "{{workPath}}/change-notes.md"
+      ],
+      "reviewPath": "{{workPath}}/review.md",
+      "reviewerRole": "performance reviewer",
+      "repairRole": "software engineer",
+      "minReviewBytes": 400,
+      "enforce": {
+        "fixStepId": "repair"
+      },
+      "criteria": [
+        "baseline.md records real numbers with the exact method and command used to gather them — an adjective where a figure belongs fails this criterion — plus a green suite receipt from before the work started.",
+        "The change attacks the ONE bottleneck the baseline names, at the real site, by the mechanism the plan declared — open the touched files and check; do not grade from change-notes.md alone.",
+        "The measured target moved against the recorded baseline using the same method: verification.md quotes both numbers side by side, and the method is identical before and after — a changed workload, counter, or harness voids the comparison.",
+        "Observable behavior unchanged (or changed only as the plan declared): results are identical on the same inputs, and correctness held with receipts.",
+        "No stage left the suite red (receipts, not claims).",
+        "No measurement theater: the number measured is the number the user feels — the real operation, path, or suite got faster, not a synthetic proxy, and the measurement itself was not weakened to flatter the result."
+      ]
+    }
+  }
+}