@bendyline/gilde 0.1.39 → 0.1.41

package/authoring/tactical/books/refactor-module.json

@@ -0,0 +1,217 @@
+{
+  "id": "refactor-module",
+  "name": "Behavior-Preserving Refactor",
+  "description": "Restructure code without changing what it does, with proof at every stage: a green suite recorded before anything moves (characterization tests pinned first when coverage is thin), small reversible stages that keep the tests green, a re-measured structure target, and an enforced independent review.",
+  "category": "code-quality",
+  "role": "maintenance-review",
+  "tags": [
+    "refactor",
+    "cleanup",
+    "code-quality",
+    "maintainability",
+    "duplication",
+    "tests"
+  ],
+  "triggers": [
+    "refactor this module",
+    "clean up the code",
+    "improve code structure",
+    "behavior-preserving refactor",
+    "reduce duplication"
+  ],
+  "about": "Restructure code with the discipline that makes refactoring safe, and with each claim mechanically verified. First BASELINE: run the suite and record it green before anything moves — and where the code about to be reshaped has no tests, write characterization tests FIRST, pinning CURRENT behavior bugs included, because a refactor without a behavioral pin is just hopeful editing. The baseline also records the structural measurements the refactor targets (duplicated blocks, function lengths, tangled responsibilities) with the method used to count them. Then PLAN: the target structure and a sequence of small stages, each individually reversible and each leaving the tree working. Then CHANGE: execute stage by stage at the real sites — never a prescribed scratch file — running the suite between stages so a red step is reverted or narrowed, not stacked on. Then VERIFY: re-measure with the SAME method, quote before and after side by side, and show the whole suite green. Finally an independent reviewer grades the chain against fixed criteria — behavior preserved, target genuinely moved, no stage left red — 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": "What to refactor",
+          "description": "The module, folder, duplication, or structural problem to work on. Leave empty when the task description already carries it.",
+          "default": ""
+        }
+      }
+    },
+    "capabilityFloor": "medium",
+    "diffpackCapable": true,
+    "commands": [
+      {
+        "scope": "script",
+        "name": "test",
+        "reason": "The suite is the guardrail: it must be green before any restructuring 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 baseline and the guardrail (characterization tests first when coverage is thin) -> plan small reversible stages -> restructure stage by stage with the suite green throughout -> re-measure with the same method and prove behavior held -> enforced independent review.",
+    "maxGateAttempts": 4,
+    "maxReviewRounds": 3,
+    "phases": [
+      {
+        "id": "baseline",
+        "name": "Capture the baseline",
+        "description": "Record the current truth before changing anything: suite green, structural measurements, and the guardrail — with characterization tests added first where coverage is thin.",
+        "suggestedRole": "software engineer",
+        "capabilityFloor": "medium",
+        "prompt": "The refactor scope: {{scope}}\n\nCapture the current truth before changing anything — measure BEFORE, so the improvement can be proven later with the same method. Read the involved source and find how this project runs its tests (`list_package_scripts`, then read the existing test layout). Run the suite with `run_package_script` (`test`) and confirm it is GREEN before any restructuring; if it is already red, stop and report that honestly instead of refactoring on a broken base. If the command needs first-use approval, say so and wait rather than guessing.\n\nWhere the code you are about to restructure lacks tests, write characterization tests FIRST: tests that pin the CURRENT behavior — bugs and quirks included — in the project's real test layout and style. They are the guardrail. Run them and record that they pass against today's code; do not fix anything they reveal.\n\nThen record the structural measurements this refactor targets, as numbers gathered by a stated method: duplicated blocks and where each copy lives, function lengths, file sizes, tangled responsibilities — counted, not adjectived.\n\nWrite `{{workPath}}/baseline.md` with exactly these sections: `## Current behavior` (what the code does today and which tests pin it, including any characterization tests you just added), `## Measurements` (the structural numbers and the exact method used to gather them), `## Guardrail` (what must not change: public API, observable behavior, and 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 reversible stages",
+        "description": "Design the target structure and an ordered sequence of small stages, each individually reversible and each leaving the tree working. No source edits.",
+        "suggestedRole": "software architect",
+        "capabilityFloor": "medium",
+        "prompt": "Read `{{workPath}}/baseline.md`, then design the restructure as a sequence of small stages. State the target structure concretely: what exists after the refactor that does not exist now, and what disappears. Break the work into ordered stages where EACH stage is individually reversible and leaves the tree working with the suite green — extract this function, move that block behind a seam, collapse the duplicate — never a big-bang rewrite. Name the files each stage touches. State the acceptance criteria: the measured target from the baseline moving (with the figures it should reach), the suite green after every stage, and the public API unchanged unless you explicitly declare a break here and say why. Do not edit any source in this phase.\n\nWrite `{{workPath}}/plan.md` with exactly these sections: `## Target` (the end structure), `## 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": "Restructure stage by stage",
+        "description": "Execute the planned stages at the real sites, keeping the suite green between stages.",
+        "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`; there is no prescribed output path for source changes and never a scratch copy. 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 until green, not stacked on. Keep behavior identical: no fixes or features smuggled in under cover of the restructure — if you find a genuine bug, record it in your notes for the user instead of silently changing behavior the tests pin. Keep the characterization tests from the baseline; they ride along as permanent guards.\n\nWrite `{{workPath}}/change-notes.md` with exactly these sections: `## Stages executed` (each stage, in order, with its suite-green confirmation), `## 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 the same method as the baseline, quote both figures, and record the suite green.",
+        "suggestedRole": "software engineer",
+        "capabilityFloor": "medium",
+        "prompt": "Prove the refactor with fresh eyes. Read `{{workPath}}/baseline.md` and re-measure the SAME structural numbers with the SAME method it records — the comparison is meaningless if the method moved. Quote the before figure from the baseline and the after figure side by side. Then run the whole suite with `run_package_script` (`test`) and record the green result. Check the guardrail: exports, signatures, and observable behavior unchanged unless plan.md declared a break. Anything you could not actually re-run gets labeled unverified, never claimed.\n\nWrite `{{workPath}}/verification.md` with exactly these sections: `## Before / after` (each baseline measurement quoted next to its re-measured value, same method), `## Suite` (the full-suite result from the real run), `## Result` (behavior preserved and target moved, or what remains unverified and why).",
+        "output": {
+          "path": "{{workPath}}/verification.md",
+          "minBytes": 400,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Before\\s*/\\s*after[\\s\\S]*\\d",
+              "label": "Before / after section with both figures"
+            },
+            {
+              "pattern": "^##\\s+Suite",
+              "label": "Suite section"
+            },
+            {
+              "pattern": "^##\\s+Result",
+              "label": "Result section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "commandEvidence",
+              "script": "test",
+              "expect": "pass",
+              "label": "green after the restructure (verified run receipt)"
+            }
+          ]
+        }
+      }
+    ],
+    "review": {
+      "artifactPath": "{{workPath}}/verification.md",
+      "relatedPaths": [
+        "{{workPath}}/baseline.md",
+        "{{workPath}}/plan.md",
+        "{{workPath}}/change-notes.md"
+      ],
+      "reviewPath": "{{workPath}}/review.md",
+      "reviewerRole": "refactoring reviewer",
+      "repairRole": "software engineer",
+      "minReviewBytes": 400,
+      "enforce": {
+        "fixStepId": "repair"
+      },
+      "criteria": [
+        "baseline.md records a genuinely green suite from a real run receipt before any restructuring, and pins the guardrail — with characterization tests written first (pinning current behavior, bugs included) wherever the touched area lacked coverage.",
+        "Observable behavior unchanged (or changed only as the plan declared): public API and outputs held, and the pinning tests still pass unmodified — open the touched files and the tests; do not grade from change-notes.md alone.",
+        "The measured target moved against the recorded baseline using the same method: verification.md quotes both figures side by side, and the duplication/structure improvement is visible in the real files, not just claimed.",
+        "No stage left the suite red (receipts, not claims): the recorded runs show green between stages and green at the end.",
+        "Every stage in change-notes.md matches a plan.md stage or an honestly recorded deviation, and every touched file it names exists.",
+        "The public API is unchanged unless plan.md explicitly declared a break, and no fix or feature was smuggled in under cover of the restructure."
+      ]
+    }
+  }
+}

package/authoring/tactical/books/schema-migration.json

@@ -0,0 +1,192 @@
+{
+  "id": "schema-migration",
+  "name": "Schema / Type Migration",
+  "description": "Migrate a schema or data shape with the expand/contract discipline: reads accept both shapes while the data moves, the old shape is dropped only after every record is transformed, and real suite runs between stages prove no record was ever stranded.",
+  "category": "code-quality",
+  "role": "maintenance-review",
+  "tags": [
+    "migration",
+    "schema",
+    "types",
+    "refactor",
+    "codemod",
+    "expand-contract"
+  ],
+  "triggers": [
+    "migrate a schema",
+    "change a type everywhere",
+    "multi-file migration",
+    "rename a model across the codebase",
+    "type migration"
+  ],
+  "about": "Change a data model, schema, or type across a codebase while the data stays alive at every moment - expand/contract is THE method, and each claim is mechanically verified. First PLAN from the real files: read the actual schema and data files and every accessor that touches the current shape, document the current and target shapes with fields taken from those files, and lay the work out as expand (readers accept both shapes), migrate (transform the stored data), contract (drop the old shape and retire the dual-read) - with per-stage data safety and a per-stage rollback. Then MIGRATE at the real sites the plan names, running the suite between stages so every green is a recorded receipt: expand must be green before the data moves, and the data must be fully transformed before contract lands. Then VERIFY that no record was stranded - the old shape is gone exactly where contract says, every record is readable in the target shape with its values intact, and the whole suite is 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": "What to migrate",
+          "description": "The schema or shape change to make: the current shape, the target shape, and where the data lives. Leave empty when the task description already carries it.",
+          "default": ""
+        }
+      }
+    },
+    "capabilityFloor": "medium",
+    "diffpackCapable": true,
+    "commands": [
+      {
+        "scope": "script",
+        "name": "test",
+        "reason": "every migration stage must keep reads working - receipts"
+      }
+    ]
+  },
+  "workflow": {
+    "plan": "Plan expand/migrate/contract from the real schema and data files (per-stage data safety and rollback) -> execute at the real sites with the suite green between stages and reads accepting both shapes while the data moves -> verify every record readable, the old shape gone where contract says, and the suite green -> enforced independent review.",
+    "maxGateAttempts": 4,
+    "maxReviewRounds": 3,
+    "phases": [
+      {
+        "id": "plan-migration",
+        "name": "Plan the expand/contract migration",
+        "description": "Document the current and target shapes from the real files and stage the work as expand, migrate, contract - with per-stage data safety and rollback.",
+        "suggestedRole": "migration planner",
+        "capabilityFloor": "medium",
+        "prompt": "The migration: {{scope}}\n\nPlan from the REAL files before changing anything. Read the actual schema definitions and the actual data files, and find every accessor that touches the current shape with real searches over the tree - never from memory. Document the current shape and the exact target shape with field names and types taken from those files. Then lay the work out as expand/contract stages - the data must stay readable through every stage: first EXPAND (readers accept both the old and the new shape), then MIGRATE (transform the stored data to the new shape), then CONTRACT (drop the old shape and retire the dual-read). For each stage, state what keeps every existing record readable while that stage is in flight, and the concrete rollback if it goes wrong. If the current shape cannot be determined from the real files, record what is missing honestly and stop.\n\nWrite `{{workPath}}/migration-plan.md` with exactly these sections: `## Current shape` (from the real files, cited with backtick paths), `## Target shape` (exact fields and types), `## Stages` (expand, migrate, contract - what each touches, in order), `## Data safety` (why no record becomes unreadable at any stage), `## Rollback per stage`.",
+        "output": {
+          "path": "{{workPath}}/migration-plan.md",
+          "minBytes": 700,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Current shape",
+              "label": "Current shape section"
+            },
+            {
+              "pattern": "^##\\s+Target shape",
+              "label": "Target shape section"
+            },
+            {
+              "pattern": "^##\\s+Stages",
+              "label": "Stages section"
+            },
+            {
+              "pattern": "^##\\s+Data safety",
+              "label": "Data safety section"
+            },
+            {
+              "pattern": "^##\\s+Rollback per stage",
+              "label": "Rollback per stage section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/migration-plan.md",
+              "minCitations": 2,
+              "artifact": true
+            }
+          ]
+        }
+      },
+      {
+        "id": "migrate",
+        "name": "Execute the stages",
+        "description": "Apply expand, migrate, contract at the real sites with the suite run between stages; reads accept both shapes until the plan retires the dual-read.",
+        "suggestedRole": "software engineer",
+        "capabilityFloor": "medium",
+        "prompt": "Read `{{workPath}}/migration-plan.md` and execute its stages in order at the real sites it names - the schema definition, the accessors, and the data transform - using `read_file` plus `write_file`/`replace_in_file`. Run the suite with `run_package_script` (`test`) between stages: expand must be green before the data moves, and the data must be fully transformed before contract drops the old shape. During expand, reads accept BOTH shapes, and the plan's contract stage says exactly when that dual-read retires - do not leave it behind as permanent fallback code, and do not remove it before the data has moved. Transform the stored data with a real, repeatable step (a script you ran, or an explicit recorded edit), never by retyping records from memory. If the command needs first-use approval, say so and wait rather than guessing. If a stage cannot keep the suite green, return the tree to the last green stage and record what blocked you honestly.\n\nWrite `{{workPath}}/change-notes.md` with exactly these sections: `## Stages executed` (each stage with its suite result), `## Files touched` (backtick path per line), `## Data transformed` (which records moved, how, and how you know none were lost), `## Deviations` (where execution departed from the plan and why, 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+Data transformed",
+              "label": "Data transformed section"
+            },
+            {
+              "pattern": "^##\\s+Deviations",
+              "label": "Deviations section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/change-notes.md",
+              "minCitations": 2,
+              "artifact": true
+            }
+          ]
+        }
+      },
+      {
+        "id": "verify",
+        "name": "Prove no record was stranded",
+        "description": "Check every record is in the target shape with values intact, the old shape is gone where contract says, and the whole suite is green.",
+        "suggestedRole": "software engineer",
+        "capabilityFloor": "medium",
+        "prompt": "Prove the migration with fresh eyes. Open the migrated data with `read_file` and check every record is in the target shape and none was lost - count records against the pre-migration state recorded in `{{workPath}}/change-notes.md`, and spot-check that values survived exactly. Search the real code for leftover reads of the old shape: the old field access must be gone exactly where the plan's contract stage says it should be gone. Re-run the whole suite with `run_package_script` (`test`) - it must be green. Anything you could not actually run or open gets labeled unverified, never claimed.\n\nWrite `{{workPath}}/verification.md` with exactly these sections: `## Old shape check` (the search you ran for leftover old-shape reads and what it found), `## Data integrity` (record counts and the spot-checked values), `## Suite` (the full-suite result), `## Result` (migrated with no record stranded, or what remains unverified and why).",
+        "output": {
+          "path": "{{workPath}}/verification.md",
+          "minBytes": 500,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Old shape check",
+              "label": "Old shape check section"
+            },
+            {
+              "pattern": "^##\\s+Data integrity",
+              "label": "Data integrity section"
+            },
+            {
+              "pattern": "^##\\s+Suite",
+              "label": "Suite section"
+            },
+            {
+              "pattern": "^##\\s+Result",
+              "label": "Result section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "commandEvidence",
+              "script": "test",
+              "expect": "pass",
+              "label": "the whole suite is green after the migration (verified run receipt)"
+            }
+          ]
+        }
+      }
+    ],
+    "review": {
+      "artifactPath": "{{workPath}}/verification.md",
+      "relatedPaths": [
+        "{{workPath}}/migration-plan.md",
+        "{{workPath}}/change-notes.md"
+      ],
+      "reviewPath": "{{workPath}}/review.md",
+      "reviewerRole": "migration reviewer",
+      "repairRole": "software engineer",
+      "minReviewBytes": 400,
+      "enforce": {
+        "fixStepId": "repair"
+      },
+      "criteria": [
+        "Every record stayed readable at every stage: the plan's expand stage genuinely accepted both shapes, and the recorded stage order never left data unreadable in between.",
+        "The contract stage landed only after the data moved: change-notes.md shows the transform completed (with a green suite) before the old shape was dropped.",
+        "Accessors changed at real sites: every path under Files touched exists and the change there matches the plan - open the touched files; do not grade from change-notes.md alone.",
+        "Data integrity is proven, not asserted: verification.md counts records against the pre-migration state and spot-checks that values survived exactly.",
+        "No old-shape read is left outside what the plan deliberately retains: the verification search is quoted and its result matches the contract stage.",
+        "Rollback per stage is genuine: each stage names a concrete restore path a person could actually follow, not a vague promise."
+      ]
+    }
+  }
+}

package/authoring/tactical/books/test-suite-backfill.json

@@ -0,0 +1,172 @@
+{
+  "id": "test-suite-backfill",
+  "name": "Test Suite Backfill",
+  "description": "Add tests that actually bite to untested code: rank the untested behavior by breakage cost, write tests in the project's real layout that a wrong implementation would fail, and prove the suite green with real run receipts — under an enforced independent review.",
+  "category": "code-quality",
+  "role": "maintenance-review",
+  "tags": [
+    "tests",
+    "coverage",
+    "testing",
+    "quality",
+    "regression"
+  ],
+  "triggers": [
+    "add tests to this code",
+    "backfill tests",
+    "increase test coverage",
+    "write tests for an untested module",
+    "test this function"
+  ],
+  "about": "Backfill a test suite that would actually catch a regression, not one that inflates a coverage number. First map the RISK: read the target modules and rank their untested behavior by breakage cost — what would hurt most if it went silently wrong — then choose concrete targets, because a suite built without that ranking pins the easy paths and misses the expensive ones. Then WRITE the tests in the project's real test layout and style, with one discipline above all others: every test must be able to FAIL. Assert actual values, actual errors, actual edge cases — never tautologies like expecting true, asserting a mock returns what it was told, or restating the implementation back at itself. The module under test does not change: if a test exposes what looks like a genuine bug, pin the current behavior or flag it honestly for the user instead of silently editing the source to match an expectation. Then VERIFY with the whole suite green — judged from real run receipts, not the author's summary — and a per-test statement of the regression each one guards. Finally an independent reviewer opens the tests themselves and grades the assertions against fixed criteria; a REVISE verdict routes the work back automatically with concrete findings. Needs a project whose tests run via `npm run test`. Suited to unattended night-shift runs. Works identically whether the run edits the project directly or drafts a change proposal for the user to apply.",
+  "doc": {
+    "capabilityFloor": "small",
+    "diffpackCapable": true,
+    "commands": [
+      {
+        "scope": "script",
+        "name": "test",
+        "reason": "The new tests must run green in the real suite — the verify gate checks real run receipts, not claims."
+      }
+    ],
+    "runModes": {
+      "nightShift": "supported"
+    }
+  },
+  "workflow": {
+    "plan": "Map untested behavior by breakage cost and choose targets -> write tests in the real layout that a wrong implementation would fail -> verify the whole suite green with run receipts -> enforced independent review of the assertions.",
+    "maxGateAttempts": 4,
+    "maxReviewRounds": 3,
+    "phases": [
+      {
+        "id": "risk-map",
+        "name": "Map the risk",
+        "description": "Read the target modules and rank untested behavior by breakage cost; choose concrete targets. No test writing yet.",
+        "suggestedRole": "quality engineer",
+        "capabilityFloor": "small",
+        "prompt": "Before writing any test, learn what is worth testing. Read the target module(s) named by the task with `read_file` — the whole file, not the signatures — and read the existing test layout (`list_dir` on the test folder, then the test files) to learn where tests live and how this project writes them. Rank the UNTESTED behavior by breakage cost: what would hurt users or downstream code most if it went silently wrong — boundary semantics, error contracts, arithmetic, state transitions — not what is easiest to cover. Then choose concrete targets: the specific functions and the specific behaviors of each you will pin, including the edge and error cases. Be honest about what you are deliberately leaving untested and why.\n\nWrite `{{workPath}}/risk-map.md` with exactly these sections: `## Modules` (each target module and what it does, with backtick paths), `## Risks ranked` (the untested behaviors ordered by breakage cost, with the cost stated), `## Chosen targets` (the tests you will write, each naming the behavior it pins). Every path you cite must be real.",
+        "output": {
+          "path": "{{workPath}}/risk-map.md",
+          "minBytes": 500,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Modules",
+              "label": "Modules section"
+            },
+            {
+              "pattern": "^##\\s+Risks ranked",
+              "label": "Risks ranked section"
+            },
+            {
+              "pattern": "^##\\s+Chosen targets",
+              "label": "Chosen targets section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/risk-map.md",
+              "minCitations": 2,
+              "artifact": true
+            }
+          ]
+        }
+      },
+      {
+        "id": "write-tests",
+        "name": "Write tests that can fail",
+        "description": "Add the tests in the project's real layout and style, asserting actual behavior — never tautologies.",
+        "suggestedRole": "software engineer",
+        "capabilityFloor": "small",
+        "prompt": "Read `{{workPath}}/risk-map.md` and write the chosen tests in the project's REAL test layout and style — the same folder, naming convention, and assertion idioms the existing tests use, added with `write_file`. There is no prescribed output path for the tests themselves; they live where this project's tests live. Every test must be able to FAIL: assert actual values, actual thrown errors, actual edge-case results. Never write tautologies — expecting true, asserting a mock returns what it was told, or asserting whatever the implementation currently returns without knowing why it is right. Backfill means tests, not source changes: do not modify the module under test. If a test exposes what you believe is a genuine bug, pin the current behavior with a characterization test or flag it honestly in your notes for the user — never silently edit the source to match your expectation. Run the suite with `run_package_script` (`test`) as you go and make each test pass for the right reason; if the command needs first-use approval, say so and wait rather than guessing.\n\nThen write `{{workPath}}/test-notes.md` with exactly these sections: `## Tests added` (the real path of every new test file, backtick path per line), `## Behaviors pinned` (each test and the exact behavior it asserts), `## How each test would catch a realistic break` (for each test, the plausible wrong implementation it would fail on).",
+        "output": {
+          "path": "{{workPath}}/test-notes.md",
+          "minBytes": 600,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Tests added",
+              "label": "Tests added section"
+            },
+            {
+              "pattern": "^##\\s+Behaviors pinned",
+              "label": "Behaviors pinned section"
+            },
+            {
+              "pattern": "^##\\s+How each test would catch a realistic break",
+              "label": "realistic-break section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/test-notes.md",
+              "minCitations": 2,
+              "artifact": true
+            }
+          ]
+        }
+      },
+      {
+        "id": "verify",
+        "name": "Verify the suite green",
+        "description": "Run the whole suite and record the real result, with a per-test statement of the regression it guards.",
+        "suggestedRole": "software engineer",
+        "capabilityFloor": "small",
+        "prompt": "Prove the backfill with a full, fresh run. Execute the whole suite with `run_package_script` (`test`) — every test, old and new, must pass. If anything fails, fix the TEST (or honestly report the module bug it exposed); do not touch the module under test to force green. Then account for the coverage: for each new test, one line stating the regression it now guards — what break it would catch that yesterday's suite would have missed. Compare against `{{workPath}}/risk-map.md`: any chosen target you did not cover gets an honest deferral with the reason, never silence.\n\nWrite `{{workPath}}/verification.md` with exactly these sections: `## Suite` (the exact command and the real full-suite result), `## Coverage summary` (per-test: the regression it guards; plus honest deferrals), `## Result` (green confirmed, or what remains open and why).",
+        "output": {
+          "path": "{{workPath}}/verification.md",
+          "minBytes": 400,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Suite",
+              "label": "Suite section"
+            },
+            {
+              "pattern": "^##\\s+Coverage summary",
+              "label": "Coverage summary section"
+            },
+            {
+              "pattern": "^##\\s+Result",
+              "label": "Result section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/verification.md",
+              "minCitations": 2,
+              "artifact": true
+            },
+            {
+              "kind": "commandEvidence",
+              "script": "test",
+              "expect": "pass",
+              "label": "the whole suite is green with the new tests (verified run receipt)"
+            }
+          ]
+        }
+      }
+    ],
+    "review": {
+      "artifactPath": "{{workPath}}/verification.md",
+      "relatedPaths": [
+        "{{workPath}}/risk-map.md",
+        "{{workPath}}/test-notes.md"
+      ],
+      "reviewPath": "{{workPath}}/review.md",
+      "reviewerRole": "test reviewer",
+      "repairRole": "software engineer",
+      "minReviewBytes": 400,
+      "enforce": {
+        "fixStepId": "repair"
+      },
+      "criteria": [
+        "The new tests live in the project's real test layout and follow its existing naming and assertion style — open the test files and check.",
+        "Each test pins observable behavior a wrong implementation would fail: open the assertions — expecting true, asserting a mock returns what it was told, or restating the implementation back at itself does not pass.",
+        "The edge and error cases the risk map ranked are covered, or honestly deferred with a stated reason — reconcile risk-map.md's chosen targets against test-notes.md and verification.md.",
+        "The whole suite is green by real run receipt, judged from the recorded runs rather than the author's summary.",
+        "The module under test was not modified to make tests pass — the only changes are new or updated test files and the working notes."
+      ]
+    }
+  }
+}