@bendyline/gilde 0.1.39 → 0.1.41

package/authoring/tactical/books/accessibility-retrofit.json

@@ -0,0 +1,188 @@
+{
+  "id": "accessibility-retrofit",
+  "name": "Accessibility Retrofit",
+  "description": "Audit real pages for concrete accessibility violations — alt text, labels, heading order, keyboard and focus, landmarks, contrast — then fix each one at its real site in the markup and verify it, with an enforced independent review that rejects accessibility theater.",
+  "category": "code-review",
+  "role": "maintenance-review",
+  "tags": [
+    "accessibility",
+    "a11y",
+    "wcag",
+    "retrofit",
+    "html",
+    "alt-text",
+    "images"
+  ],
+  "triggers": [
+    "accessibility fix",
+    "make it accessible",
+    "wcag compliance",
+    "a11y retrofit",
+    "fix accessibility",
+    "screen reader friendly",
+    "add alt text",
+    "generate alt text for images",
+    "make images accessible",
+    "alt text for my site",
+    "wcag image descriptions"
+  ],
+  "about": "Retrofit real pages to be genuinely accessible, with the discipline that separates repair from theater. First AUDIT: exercise the pages and markup the project actually serves and inventory concrete violations by class — missing or empty alt text on meaningful images, placeholder text doing a label's job, heading levels that jump, div-as-button controls a keyboard cannot reach, missing landmark structure, and contrast problems where the colors are derivable from the code — each violation recorded with its file, the concrete issue, and a priority. Then FIX every violation at its real site in the markup, styles, or components, preferring semantic elements over ARIA bolt-ons, real labels paired by for/id over placeholders, and specific purposeful alt text — with alt=\"\" reserved for genuinely decorative images and stated as such. Then VALIDATE by re-inspecting every fixed item and walking the keyboard path where runnable, saying plainly what was inspected versus actually exercised. Finally an independent reviewer grades the whole chain against fixed criteria — every label's for resolving to a real input id, monotonic heading order, no aria-label sprayed where a semantic element was the fix — and a REVISE verdict routes the work back automatically with concrete findings. This book also carries the full alt-text pass: classifying content versus decorative images and writing purposeful descriptions is part of the audit and fix, not a separate chore. Works identically whether the run edits the project directly or drafts a change proposal for the user to apply.",
+  "doc": {
+    "capabilityFloor": "small",
+    "diffpackCapable": true
+  },
+  "workflow": {
+    "plan": "Audit the real pages and inventory violations by class -> fix each violation at its real site with semantic markup -> validate every item with an honest keyboard walk -> enforced independent review.",
+    "maxGateAttempts": 4,
+    "maxReviewRounds": 3,
+    "phases": [
+      {
+        "id": "audit",
+        "name": "Audit the real pages",
+        "description": "Exercise the pages the project actually serves and inventory concrete violations, each with its file, issue, and priority.",
+        "suggestedRole": "accessibility reviewer",
+        "capabilityFloor": "small",
+        "prompt": "Audit the REAL pages before anything is repaired. Find the markup this project actually serves — HTML files, templates, components — and read every involved file with `read_file`. Inventory concrete violations by class: meaningful images with missing or empty alt text; form fields labeled only by placeholder text (no `label` element paired to the input's `id` via `for`); heading order that jumps levels; keyboard and focus failures (a `div` or `span` styled and clicked like a button with no `role`, `tabindex`, or key handling); missing or wrong landmark structure (`header`/`nav`/`main`/`footer`); and contrast problems where the colors are derivable from the code. Also classify genuinely decorative images — those must carry `alt=\"\"`, not a description. Record every violation with the exact file, the concrete issue, and a priority (high/medium/low by user harm). Do not fix anything in this phase, and never pad the list — where an area is clean, say so honestly.\n\nWrite `{{workPath}}/audit.md` with exactly these sections: `## Scope` (which pages and files you exercised, with backtick paths), `## Violations` (a markdown table with columns `| File | Issue | Priority |`, one row per violation), `## Priorities` (the fix order and why). Every path you cite must be real.",
+        "output": {
+          "path": "{{workPath}}/audit.md",
+          "minBytes": 600,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Scope",
+              "label": "Scope section"
+            },
+            {
+              "pattern": "^##\\s+Violations",
+              "label": "Violations section"
+            },
+            {
+              "pattern": "^##\\s+Priorities",
+              "label": "Priorities section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "tableShape",
+              "file": "{{workPath}}/audit.md",
+              "requiredColumns": [
+                "File",
+                "Issue",
+                "Priority"
+              ],
+              "minRows": 1,
+              "artifact": true
+            },
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/audit.md",
+              "minCitations": 2,
+              "artifact": true
+            }
+          ]
+        }
+      },
+      {
+        "id": "fix",
+        "name": "Fix each violation at its real site",
+        "description": "Repair every audited violation in the actual markup, styles, or components — semantic elements over ARIA bolt-ons.",
+        "suggestedRole": "frontend engineer",
+        "capabilityFloor": "small",
+        "prompt": "Read `{{workPath}}/audit.md` and repair every violation at its REAL site in the markup, styles, or components. There is no prescribed output path for the repairs — edit the actual files from the audit with `read_file` plus `write_file`/`replace_in_file`. Choose the semantic fix over the ARIA bolt-on: a real `button` element rather than `role` and `tabindex` sprayed on a `div` (where the surrounding code allows it), a real `label` paired to the input's `id` via `for` rather than placeholder text doing a label's job, corrected heading levels that restore monotonic order rather than CSS that fakes it. Write meaningful, specific alt text for images that carry content; give genuinely decorative images `alt=\"\"` and state why each is decorative. Keep existing behavior working — handlers, ids, and styling hooks on elements you touch must still be wired afterwards. A violation you deliberately leave unfixed gets an honest deferral with a reason, never silence.\n\nThen write `{{workPath}}/fix-notes.md` with exactly these sections: `## Problem` (one paragraph), `## Change` (what you altered, per class of violation), `## Files touched` (backtick path per line), `## Per-violation disposition` (every audit row: fixed or deferred, with the reason), `## Risk` (what could still be wrong; be honest about anything unverified), `## How to verify` (concrete steps a person follows to confirm, keyboard included).",
+        "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+Per-violation disposition",
+              "label": "Per-violation disposition section"
+            },
+            {
+              "pattern": "^##\\s+Risk",
+              "label": "Risk section"
+            },
+            {
+              "pattern": "^##\\s+How to verify",
+              "label": "How to verify section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/fix-notes.md",
+              "minCitations": 2,
+              "artifact": true
+            }
+          ]
+        }
+      },
+      {
+        "id": "validate",
+        "name": "Validate every fix",
+        "description": "Re-inspect each fixed item against the current markup and walk the keyboard path, honest about inspected versus exercised.",
+        "suggestedRole": "accessibility reviewer",
+        "capabilityFloor": "small",
+        "prompt": "Verify with fresh eyes. Read `{{workPath}}/audit.md` and `{{workPath}}/fix-notes.md`, then re-open every touched file with `read_file` and check each audit row against the current markup: is the alt text present and specific, does each `label`'s `for` resolve to a real input `id`, is the heading sequence monotonic now, does the once-div control carry real button semantics and keyboard operability, are the landmarks in place. Walk the keyboard path as far as the code lets you: trace tab order, focusability, and key handlers through the markup and scripts. Say plainly which items you INSPECTED (read the code) versus EXERCISED (actually ran or interacted with) — anything that is neither is unverified, and you must say so rather than claim it.\n\nWrite `{{workPath}}/validation.md` with exactly these sections: `## Per-item verification` (each audit row and what you found in the current file), `## Keyboard walk` (the path a keyboard user takes and where focus goes), `## Result` (all clear, or what remains open and why).",
+        "output": {
+          "path": "{{workPath}}/validation.md",
+          "minBytes": 500,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Per-item verification",
+              "label": "Per-item verification section"
+            },
+            {
+              "pattern": "^##\\s+Keyboard walk",
+              "label": "Keyboard walk section"
+            },
+            {
+              "pattern": "^##\\s+Result",
+              "label": "Result section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/validation.md",
+              "minCitations": 2,
+              "artifact": true
+            }
+          ]
+        }
+      }
+    ],
+    "review": {
+      "artifactPath": "{{workPath}}/validation.md",
+      "relatedPaths": [
+        "{{workPath}}/audit.md",
+        "{{workPath}}/fix-notes.md"
+      ],
+      "reviewPath": "{{workPath}}/review.md",
+      "reviewerRole": "accessibility reviewer",
+      "repairRole": "frontend engineer",
+      "minReviewBytes": 400,
+      "enforce": {
+        "fixStepId": "repair"
+      },
+      "criteria": [
+        "Every violation in audit.md is either fixed at its real site or honestly deferred with a stated reason — open the touched files and check the current markup; do not grade from fix-notes.md alone.",
+        "No accessibility theater: where a semantic element was the right fix (a real button, a real label), the markup uses it — aria-label sprayed over a non-semantic element does not pass.",
+        "Every label's for attribute resolves to a real input id in the current markup, and placeholder text no longer stands in for a label.",
+        "The heading sequence in the fixed markup is monotonic — no level is skipped on the way down.",
+        "Meaningful images carry specific, non-empty alt text; genuinely decorative images carry alt=\"\" with the decorative call stated in the notes.",
+        "The dispositions reconcile across audit.md, fix-notes.md, and validation.md — the same items, none silently dropped — and validation.md separates inspected from exercised honestly."
+      ]
+    }
+  }
+}

package/authoring/tactical/books/apply-review-findings.json

@@ -0,0 +1,189 @@
+{
+  "id": "apply-review-findings",
+  "name": "Apply Review Findings",
+  "description": "Take an existing review's findings and close them for real: triage each one against the current code, fix the real ones at their actual sites with the smallest correct change, verify per finding, and account for every finding end to end under an enforced review.",
+  "category": "code-quality",
+  "role": "general",
+  "tags": [
+    "review-findings",
+    "follow-up",
+    "bug-fix",
+    "triage",
+    "quality",
+    "maintenance"
+  ],
+  "triggers": [
+    "apply the review findings",
+    "fix the findings",
+    "address the review",
+    "fix these issues"
+  ],
+  "about": "Close out a review the way the reviewer hoped someone would: every finding read, judged against the code as it stands TODAY, fixed at its real site or deferred with a reason a person can respect — and nothing silently dropped. First TRIAGE: read the findings (a findings JSON, a report with a findings table, or issue refs), open the cited code, and sort each finding — real, already fixed, stale, or out of scope — because reviews age and fixing a ghost is churn. Cluster the will-fix findings that belong together so one change closes them cleanly. Then FIX cluster by cluster: the smallest correct change per finding at the actual site, never a suppression or a cosmetic edit, with a per-finding disposition kept as the work happens. Then VALIDATE each addressed finding the way its report suggested — run what is runnable, probe what is probeable, and say plainly what could only be verified by reading. The enforced review then reconciles the ledger: the same finding ids must flow through triage, fix notes, and verification with consistent outcomes, because a finding lost between documents is a finding lost. Built for unattended work: findings arrive as a file or refs, dispositions come back as documents, and no runnable test suite is required. Works identically whether the run edits the project directly or drafts a change proposal for the user to apply.",
+  "doc": {
+    "paramSchema": {
+      "type": "object",
+      "properties": {
+        "findingsPath": {
+          "type": "string",
+          "title": "Findings file",
+          "description": "Artifacts-drawer path of the review findings to apply (a findings JSON array or a markdown report with a findings table). Leave empty when issueRefs or the task description carries them.",
+          "default": ""
+        },
+        "issueRefs": {
+          "type": "string",
+          "title": "Issue refs",
+          "description": "Comma-separated issue refs to address (e.g. BW-3,BW-8). Leave empty when findingsPath carries the work.",
+          "default": ""
+        }
+      }
+    },
+    "capabilityFloor": "small",
+    "diffpackCapable": true,
+    "runModes": {
+      "nightShift": "supported"
+    }
+  },
+  "workflow": {
+    "plan": "Triage every finding against the current code (real, already fixed, stale, out of scope) -> fix cluster by cluster at the real sites with a per-finding disposition -> verify each addressed finding the way its report suggested -> enforced review reconciles the full ledger.",
+    "maxGateAttempts": 4,
+    "maxReviewRounds": 3,
+    "phases": [
+      {
+        "id": "triage",
+        "name": "Triage the findings against current code",
+        "description": "Read every finding, judge it against the code as it stands now, and sort real work from ghosts.",
+        "suggestedRole": "code reviewer",
+        "capabilityFloor": "small",
+        "prompt": "Findings file (artifacts drawer): \"{{findingsPath}}\". Issue refs: \"{{issueRefs}}\". When both are empty, the task description carries the findings.\n\nRead every finding before fixing anything. Use `read_artifact` for the findings file when one is named; otherwise take the findings from the refs or the task description. Then judge each finding against the code as it stands NOW — open the cited files with `read_file` — and sort it: REAL (the problem is present today), ALREADY FIXED (the code moved on), STALE (the cited site no longer exists or the finding no longer applies), or OUT OF SCOPE (real but not this task's to change — say whose it is). Reviews age; never fix a ghost. Give every finding a stable id — keep the ids the findings already carry, or number them F-1, F-2, ... in reading order — and carry those ids through every later document. Cluster the will-fix findings that belong together so one change closes them cleanly. If the findings source cannot be found or holds no findings, record that honestly and stop rather than inventing work.\n\nWrite `{{workPath}}/triage.md` with exactly these sections: `## Findings read` (every finding: id, one-line summary, the cited site as a backtick path), `## Will fix` (the ids, each with the problem confirmed in the current code), `## Deferred` (the ids with an honest reason: already fixed, stale, or out of scope — write None when everything is real), `## Clusters` (which will-fix ids travel together and why).",
+        "output": {
+          "path": "{{workPath}}/triage.md",
+          "minBytes": 600,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Findings read",
+              "label": "Findings read section"
+            },
+            {
+              "pattern": "^##\\s+Will fix",
+              "label": "Will fix section"
+            },
+            {
+              "pattern": "^##\\s+Deferred",
+              "label": "Deferred section"
+            },
+            {
+              "pattern": "^##\\s+Clusters",
+              "label": "Clusters section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/triage.md",
+              "minCitations": 2,
+              "artifact": true
+            }
+          ]
+        }
+      },
+      {
+        "id": "fix",
+        "name": "Fix cluster by cluster at the real sites",
+        "description": "The smallest correct change per finding, at the actual cited site, with a per-finding disposition ledger.",
+        "suggestedRole": "software engineer",
+        "capabilityFloor": "small",
+        "prompt": "Read `{{workPath}}/triage.md` and work the will-fix clusters one at a time, at the real sites. There is no prescribed output path for source changes — edit the actual files the findings point at with `read_file` plus `write_file`/`replace_in_file`. For each finding, make the smallest correct change that genuinely fixes what the finding describes — not a suppression, not a comment, not a workaround that leaves the problem alive. Keep surrounding behavior intact: a findings pass that breaks the neighborhood trades one review for another. Keep the per-finding ledger as you go. If a finding turns out unfixable as described, move it to a deferral with the honest reason instead of pretending — never claim a fix you did not make.\n\nWrite `{{workPath}}/fix-notes.md` with exactly these sections: `## Problem` (one paragraph: what this findings pass covered), `## Change` (per cluster: what you altered and why it closes those findings), `## Files touched` (backtick path per line), `## Per-finding disposition` (every id from triage: fixed at which path, or deferred with the reason), `## Risk` (what could break, honestly), `## How to verify` (per finding: the check its report suggested, or the closest runnable equivalent).",
+        "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+Per-finding disposition",
+              "label": "Per-finding disposition section"
+            },
+            {
+              "pattern": "^##\\s+Risk",
+              "label": "Risk section"
+            },
+            {
+              "pattern": "^##\\s+How to verify",
+              "label": "How to verify section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/fix-notes.md",
+              "minCitations": 2,
+              "artifact": true
+            }
+          ]
+        }
+      },
+      {
+        "id": "validate",
+        "name": "Verify each finding the way its report suggested",
+        "description": "Re-check every addressed finding at its site, run what is runnable, and restate the deferrals.",
+        "suggestedRole": "software engineer",
+        "capabilityFloor": "small",
+        "prompt": "Re-check every addressed finding the way its report suggested. Read `{{workPath}}/fix-notes.md`, then verify each fixed finding at its site: re-read the changed code, and run what is runnable — the project's own scripts, or a small probe when a script-execution tool such as `run_nodejs_script` is wired this turn. When nothing is runnable, verify by reading and say so plainly — an unrun check is recorded as unverified, never claimed. Confirm the deferred findings still carry their reasons. Every finding id from triage must appear here with its outcome; a finding that vanished between documents is a finding dropped.\n\nWrite `{{workPath}}/validation.md` with exactly these sections: `## Per-finding verification` (every id: how it was re-checked and what was observed, with deferrals restated), `## Result` (closed versus deferred counts, what was verified by running versus by reading, and anything still owed).",
+        "output": {
+          "path": "{{workPath}}/validation.md",
+          "minBytes": 450,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Per-finding verification",
+              "label": "Per-finding verification section"
+            },
+            {
+              "pattern": "^##\\s+Result",
+              "label": "Result section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/validation.md",
+              "minCitations": 2,
+              "artifact": true
+            }
+          ]
+        }
+      }
+    ],
+    "review": {
+      "artifactPath": "{{workPath}}/validation.md",
+      "relatedPaths": [
+        "{{workPath}}/triage.md",
+        "{{workPath}}/fix-notes.md"
+      ],
+      "reviewPath": "{{workPath}}/review.md",
+      "reviewerRole": "findings auditor",
+      "repairRole": "software engineer",
+      "minReviewBytes": 400,
+      "enforce": {
+        "fixStepId": "repair"
+      },
+      "criteria": [
+        "Every finding from the source appears in triage.md's Findings read with an id and a cited site — count them against the findings source; a finding missing from the ledger is an automatic REVISE.",
+        "Each Will fix finding is genuinely addressed at a real site: open the touched files and confirm the change fixes what the finding describes, not a suppression, comment, or cosmetic edit.",
+        "Each Deferred finding carries an honest, specific reason (already fixed, stale, or out of scope) that holds up when you open the cited code.",
+        "The ledger reconciles: the same ids flow through triage.md, fix-notes.md's Per-finding disposition, and validation.md's Per-finding verification with consistent outcomes — no finding silently dropped or relabeled between documents.",
+        "validation.md re-checked each addressed finding the way its report suggested where runnable, and plainly labels anything verified only by reading — nothing claimed run that was not.",
+        "Every path cited across the three documents exists in this project, and fix-notes.md's Files touched matches the changes actually made."
+      ]
+    }
+  }
+}

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

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