@bendyline/gilde 0.1.39 → 0.1.41

package/authoring/tactical/books/type-safety-pass.json

@@ -0,0 +1,185 @@
+{
+  "id": "type-safety-pass",
+  "name": "Type-Safety Pass",
+  "description": "Tighten a module against unsafe patterns — loose equality, implicit coercions, swallowed catches, untyped boundaries, any-casts — with counted evidence: an audit that inventories the patterns by a stated method, fixes that never silence a check to move a count, a same-method re-count, and an enforced independent review.",
+  "category": "code-quality",
+  "role": "maintenance-review",
+  "tags": [
+    "types",
+    "typescript",
+    "javascript",
+    "type-safety",
+    "strict",
+    "quality"
+  ],
+  "triggers": [
+    "tighten the types",
+    "kill any types",
+    "add type annotations",
+    "make this type-safe",
+    "fix type errors"
+  ],
+  "about": "Tighten code against the unsafe patterns that turn into 3am bugs, with the improvement proven by counting rather than claiming. First AUDIT: inventory the patterns in scope WITH COUNTS gathered by a stated, repeatable method (a grep per pattern, expressions quoted) — loose equality against null or undefined, implicit string/number coercions, swallowed catches that hide real errors, untyped or unvalidated boundaries, and in TypeScript projects any-casts and ignore-comments. The audit picks the concrete targets, names which behavioral consequences of these patterns are bugs this pass is expected to fix, records the guardrail, and captures the suite green before any change. Then CHANGE: fix pattern by pattern at the real sites — and never buy a lower count by weakening the code: no deleted assertions, no silenced error paths, no bare casts, no ignore-comments; a count that falls that way is a regression wearing a metric. Then VERIFY: re-count with exactly the audit's method, quote before and after per pattern, and show the suite green. Finally an independent reviewer grades the chain — counts genuinely fell by the same method, no suppression, behavior preserved except the declared consequence fixes — and a REVISE verdict routes the work back automatically with concrete findings. Small enough to run as night-shift work. 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": "Where to tighten",
+          "description": "The module, folder, or area to audit for unsafe patterns. Leave empty when the task description already carries it.",
+          "default": ""
+        }
+      }
+    },
+    "capabilityFloor": "small",
+    "diffpackCapable": true,
+    "runModes": {
+      "nightShift": "supported"
+    },
+    "commands": [
+      {
+        "scope": "script",
+        "name": "test",
+        "reason": "The suite is the guardrail: it must be green before the pass starts and green at the end, so tightened checks provably did not break pinned behavior. The gates verify the green-before/green-after receipts from real runs, not the author's claims."
+      }
+    ]
+  },
+  "workflow": {
+    "plan": "Audit the unsafe patterns with counts and a stated method, pick targets, record the guardrail and a green suite -> fix pattern by pattern at the real sites without silencing anything -> re-count with the same method, quote before/after, suite green -> enforced independent review.",
+    "maxGateAttempts": 4,
+    "maxReviewRounds": 3,
+    "phases": [
+      {
+        "id": "audit",
+        "name": "Audit with counts",
+        "description": "Inventory the unsafe patterns in scope with counts by a stated method, pick concrete targets, record the guardrail, and capture the suite green.",
+        "suggestedRole": "code auditor",
+        "capabilityFloor": "small",
+        "prompt": "The area to tighten: {{scope}}\n\nInventory the unsafe patterns before fixing any of them — the improvement will be proven by re-counting later, so the counts and the exact method are the deliverable here. Read the involved source, then count each pattern class in scope with a stated, repeatable method (a grep per pattern works; quote the exact expressions you used): loose equality against null or undefined (`==`/`!=` where a strict check belongs), implicit string/number coercions (arithmetic or concatenation on values that may arrive as strings), swallowed catches (a catch that hides the error and carries on as if nothing failed), untyped or unvalidated boundaries (inputs used without a shape check), and in TypeScript projects `any`-casts and ignore-comments. Record the count per pattern and where each hit lives.\n\nPick the concrete targets for this pass and state the guardrail: which behavior is pinned by tests and must not change, and which behavioral CONSEQUENCES of these patterns are bugs this pass is expected to fix — name each one. Then find how the project runs its tests (`list_package_scripts`), run the suite with `run_package_script` (`test`), and record it green before any change; 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\nWrite `{{workPath}}/audit.md` with exactly these sections: `## Inventory` (counts by pattern with the exact method and grep expressions used), `## Targets` (the hits this pass will fix, with backtick paths), `## Guardrail` (what must not change, and the declared consequence fixes that may). Cite the real files with backtick paths.",
+        "output": {
+          "path": "{{workPath}}/audit.md",
+          "minBytes": 600,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Inventory[\\s\\S]*\\d",
+              "label": "Inventory section with counts"
+            },
+            {
+              "pattern": "^##\\s+Targets",
+              "label": "Targets section"
+            },
+            {
+              "pattern": "^##\\s+Guardrail",
+              "label": "Guardrail section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/audit.md",
+              "minCitations": 2,
+              "artifact": true
+            },
+            {
+              "kind": "commandEvidence",
+              "script": "test",
+              "expect": "pass",
+              "label": "green before the work starts"
+            }
+          ]
+        }
+      },
+      {
+        "id": "change",
+        "name": "Fix pattern by pattern",
+        "description": "Fix the targeted patterns at the real sites, never silencing a check or weakening an assertion to move a count.",
+        "suggestedRole": "software engineer",
+        "capabilityFloor": "small",
+        "prompt": "Read `{{workPath}}/audit.md` and fix the targeted patterns at the REAL sites with `read_file` plus `write_file`/`replace_in_file`, pattern by pattern. Replace loose equality with strict checks that state what they mean; normalize or validate values at the boundary they cross instead of coercing mid-calculation; make swallowed catches surface the error — rethrow, or report it the way the audit's guardrail declares — rather than carrying on as if nothing failed. Never buy a lower count by weakening the code: no deleting an assertion, no silencing an error path, no bare casts, and in TypeScript no `any` or ignore-comment to make a diagnostic disappear — a count that falls that way is a regression wearing a metric. Behavior changes only where the audit declared a consequence fix, and each one gets named in your notes. Run the suite with `run_package_script` (`test`) as you go and keep it green; a change that goes red gets narrowed, not stacked on. If a targeted hit turns out to be correct as written, record why and leave it — honesty beats a moved count.\n\nWrite `{{workPath}}/change-notes.md` with exactly these sections: `## Patterns addressed` (each pattern class, what the fix was, and any declared consequence fix it delivered), `## Files touched` (backtick path per line), `## Deviations` (targets handled differently than the audit planned, or `none`, honestly).",
+        "output": {
+          "path": "{{workPath}}/change-notes.md",
+          "minBytes": 600,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Patterns addressed",
+              "label": "Patterns addressed section"
+            },
+            {
+              "pattern": "^##\\s+Files touched",
+              "label": "Files touched section"
+            },
+            {
+              "pattern": "^##\\s+Deviations",
+              "label": "Deviations section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/change-notes.md",
+              "minCitations": 2,
+              "artifact": true
+            }
+          ]
+        }
+      },
+      {
+        "id": "verify",
+        "name": "Re-count and verify",
+        "description": "Re-count every pattern with exactly the audit's method, quote before/after counts, and record the suite green.",
+        "suggestedRole": "software engineer",
+        "capabilityFloor": "small",
+        "prompt": "Prove the pass with fresh eyes. Read `{{workPath}}/audit.md` and RE-COUNT every pattern with EXACTLY the method and grep expressions it records — same expressions, same scope; a changed method voids the comparison, and if the recorded method cannot be reproduced that is a finding to report, not a license to substitute one. Quote the audit's count and the new count for each pattern side by side. Run the whole suite with `run_package_script` (`test`) and record the green result. Spot-check the fixed sites: the checks got stronger, not deleted, and no cast or ignore-comment crept in. Anything you could not actually re-run gets labeled unverified, never claimed.\n\nWrite `{{workPath}}/verification.md` with exactly these sections: `## Before / after counts` (per pattern, the audit count next to the re-count, same greps), `## Suite` (the full-suite result from the real run), `## Result` (which declared consequences are now fixed, and anything unverified).",
+        "output": {
+          "path": "{{workPath}}/verification.md",
+          "minBytes": 400,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Before\\s*/\\s*after counts[\\s\\S]*\\d",
+              "label": "Before / after counts with figures"
+            },
+            {
+              "pattern": "^##\\s+Suite",
+              "label": "Suite section"
+            },
+            {
+              "pattern": "^##\\s+Result",
+              "label": "Result section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "commandEvidence",
+              "script": "test",
+              "expect": "pass",
+              "label": "green after the pass (verified run receipt)"
+            }
+          ]
+        }
+      }
+    ],
+    "review": {
+      "artifactPath": "{{workPath}}/verification.md",
+      "relatedPaths": [
+        "{{workPath}}/audit.md",
+        "{{workPath}}/change-notes.md"
+      ],
+      "reviewPath": "{{workPath}}/review.md",
+      "reviewerRole": "code-quality reviewer",
+      "repairRole": "software engineer",
+      "minReviewBytes": 400,
+      "enforce": {
+        "fixStepId": "repair"
+      },
+      "criteria": [
+        "audit.md counts real patterns in real files with the exact method recorded (grep expressions quoted), and a green suite receipt exists from before the work started.",
+        "Counts genuinely fell and the re-count method matches the audit's exactly: verification.md quotes before and after per pattern — the measured target moved against the recorded baseline using the same method.",
+        "No suppression bought the improvement: open the touched files and confirm no assertion was weakened, no check deleted, no error path silenced, and no cast or ignore-comment introduced to move a count.",
+        "Observable behavior unchanged (or changed only as the audit declared): each consequence fix the audit named happened and is recorded in change-notes.md, and nothing else moved.",
+        "No stage left the suite red (receipts, not claims): green before the pass and green after it, from real runs.",
+        "change-notes.md names every touched file (paths that exist) and records its deviations honestly, including targets left alone because they were correct as written."
+      ]
+    }
+  }
+}

package/authoring/tactical/books/ux-update.json

@@ -0,0 +1,178 @@
+{
+  "id": "ux-update",
+  "name": "Implement a UX Change",
+  "description": "Deliver a described UX change the disciplined way: capture the before state from the real markup, make the smallest coherent change at the real sites in the product's own conventions, and prove the after state with the existing behaviors still working — under an enforced independent review.",
+  "category": "code-build",
+  "role": "general",
+  "tags": [
+    "ux",
+    "ui",
+    "frontend",
+    "user-experience",
+    "polish"
+  ],
+  "triggers": [
+    "make this ux change",
+    "move the button",
+    "improve this flow",
+    "update the ui"
+  ],
+  "about": "Implement a UX change the way a careful product engineer would — grounded in the real code at every step, not in a redescription of it. First UNDERSTAND: restate the requested change as the user would experience it, find the involved surfaces in the actual pages, components, styles, and scripts, and capture the BEFORE state by quoting the real markup and wiring — including every behavior attached to those surfaces (handlers, keyboard shortcuts, ids, state), because each must still work afterwards. Then IMPLEMENT the smallest coherent change at those real sites, matching the surrounding product's conventions — its spacing, naming, and markup patterns — rather than inventing a new style, and moving existing behaviors with the elements rather than dropping them. Then VALIDATE by walking the changed flow and building a concrete before/after comparison grounded in the files, honest about what was inspected versus actually exercised. Finally an independent reviewer grades the delivered change as a user would judge it — request delivered, conventions respected, nothing that worked before broken — and a REVISE verdict routes the work back automatically with concrete findings. This is the fix-applying sibling of the report-only codebase UX review: that book tells you what is wrong, this one delivers the change. Works identically whether the run edits the project directly or drafts a change proposal for the user to apply.",
+  "doc": {
+    "paramSchema": {
+      "type": "object",
+      "properties": {
+        "scope": {
+          "type": "string",
+          "title": "The UX change",
+          "description": "What should change for the user, in plain words. Leave empty when the task description carries it.",
+          "default": ""
+        }
+      }
+    },
+    "capabilityFloor": "small",
+    "diffpackCapable": true
+  },
+  "workflow": {
+    "plan": "Understand the request and capture the before state from the real code -> implement the smallest coherent change at the real sites in the product's own conventions -> validate the flow with a concrete before/after -> enforced independent review.",
+    "maxGateAttempts": 4,
+    "maxReviewRounds": 3,
+    "phases": [
+      {
+        "id": "understand",
+        "name": "Understand and capture the before state",
+        "description": "Restate the change as the user experiences it, find the real surfaces, and quote the current markup and wiring.",
+        "suggestedRole": "product engineer",
+        "capabilityFloor": "small",
+        "prompt": "The UX change to deliver: {{scope}}\n\nUnderstand before touching anything. Restate the requested change as the USER would experience it — what they see and do today, what they should see and do afterwards. Then find the involved surfaces in the REAL code: read the actual pages, components, styles, and scripts with `read_file` until you can point at the exact markup and wiring behind the current experience. Capture the BEFORE state from those files — quote the relevant snippets (the current markup, the handler, the shortcut wiring) so the change can later be judged against reality rather than memory. Catalogue every behavior attached to the surfaces you will touch — handlers, keyboard shortcuts, element ids other code references, state — because each of them must still work afterwards. If the request is ambiguous, record the reading you chose and why; if the described surface cannot be located in this codebase at all, say so honestly and stop rather than inventing one.\n\nWrite `{{workPath}}/before.md` with exactly these sections: `## Request` (the change in the user's terms), `## Current behavior` (what happens today, with the quoted snippets), `## Surfaces involved` (each file and the part it plays, with backtick paths). Every path you cite must be real.",
+        "output": {
+          "path": "{{workPath}}/before.md",
+          "minBytes": 500,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Request",
+              "label": "Request section"
+            },
+            {
+              "pattern": "^##\\s+Current behavior",
+              "label": "Current behavior section"
+            },
+            {
+              "pattern": "^##\\s+Surfaces involved",
+              "label": "Surfaces involved section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/before.md",
+              "minCitations": 2,
+              "artifact": true
+            }
+          ]
+        }
+      },
+      {
+        "id": "implement",
+        "name": "Implement the smallest coherent change",
+        "description": "Deliver the request at the real sites, in the product's own conventions, keeping existing behaviors wired.",
+        "suggestedRole": "frontend engineer",
+        "capabilityFloor": "small",
+        "prompt": "Read `{{workPath}}/before.md` and deliver the SMALLEST coherent change at the real sites it names — edit the actual files with `read_file` plus `write_file`/`replace_in_file`; there is no prescribed output path for the change itself. Match the surrounding product's conventions: reuse its spacing, naming, class patterns, and markup style rather than inventing a new one — open neighboring code to see how this product already does the same kind of thing. Keep every existing behavior working: the handlers, keyboard shortcuts, element ids, and state catalogued in before.md must still be wired when you are done — move them with the element rather than dropping or duplicating them. Do not smuggle in unrequested changes; polish beyond the request is scope creep, not generosity.\n\nThen write `{{workPath}}/fix-notes.md` with exactly these sections: `## Problem` (the request, one paragraph), `## Change` (what you altered and how it delivers the request), `## Files touched` (backtick path per line), `## Consistency notes` (which existing conventions you followed and where you saw them), `## Risk` (what could break; be honest about anything unverified), `## How to verify` (the exact steps a person follows to see the new experience).",
+        "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+Consistency notes",
+              "label": "Consistency notes 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 the changed flow",
+        "description": "Walk the new experience and build a concrete before/after grounded in the real files.",
+        "suggestedRole": "product engineer",
+        "capabilityFloor": "small",
+        "prompt": "Prove the change as the user would experience it. Read `{{workPath}}/before.md` and `{{workPath}}/fix-notes.md`, then re-open the changed files with `read_file` and walk the flow: where the element lives now, what happens on each interaction, where focus goes, what each shortcut does. Build a concrete before/after comparison grounded in the real files — quote the after state next to the before state that before.md recorded. Re-check every behavior from before.md's catalogue: each handler, shortcut, and id must be verifiably still wired in the current code. Say plainly which parts you INSPECTED (read the code) versus EXERCISED (actually ran or interacted with) — anything that is neither is unverified and must be named, never claimed.\n\nWrite `{{workPath}}/validation.md` with exactly these sections: `## Before / after` (the concrete comparison, quoting both states), `## What was exercised` (inspected versus exercised, honestly), `## Result` (delivered as requested, or what remains open and why).",
+        "output": {
+          "path": "{{workPath}}/validation.md",
+          "minBytes": 500,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Before\\s*/\\s*after",
+              "label": "Before / after section"
+            },
+            {
+              "pattern": "^##\\s+What was exercised",
+              "label": "What was exercised 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}}/before.md",
+        "{{workPath}}/fix-notes.md"
+      ],
+      "reviewPath": "{{workPath}}/review.md",
+      "reviewerRole": "ux reviewer",
+      "repairRole": "frontend engineer",
+      "minReviewBytes": 400,
+      "enforce": {
+        "fixStepId": "repair"
+      },
+      "criteria": [
+        "The delivered change matches the request as a user would judge it — open the changed files and walk the flow; do not grade from fix-notes.md alone.",
+        "The change respects the surrounding product's conventions — open neighboring code and compare naming, spacing, and markup patterns; a one-off new style where an existing pattern served does not pass.",
+        "Nothing that worked before broke: every handler, keyboard shortcut, and id catalogued in before.md is still wired in the current code — check the wiring, not the claim.",
+        "before.md quotes the real prior state and validation.md's before/after is grounded in the current files, not reconstructed from memory.",
+        "The change is minimal: no unrequested alterations rode along with it."
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,230 @@
+{
+  "schemaVersion": 1,
+  "title": "Accessibility retrofit on a seeded page",
+  "objective": "The craftbook drives a real accessibility retrofit of a page seeded with five concrete violations: missing alt text on two meaningful images, a placeholder-as-label email input, a div-as-button control with no keyboard path, a heading jump from h1 to h4, and a decorative divider whose empty alt must survive untouched. Every repair is verified mechanically by string-parsing the fixed markup.",
+  "tags": [
+    "code",
+    "accessibility",
+    "a11y",
+    "tactical-fleet"
+  ],
+  "prompt": "Use the Accessibility Retrofit craftbook on this site: readers using screen readers and keyboards report the Field Notes page is unusable — images carry no descriptions, the signup field has no label, and the Join the list control cannot be reached or activated with the keyboard. Audit index.html, fix every violation at its real site in the markup, and verify the result.",
+  "setup": {
+    "projectName": "Acme Field Notes",
+    "about": "A small static newsletter site: index.html plus styles.css and a few inline SVG images. No build step and no test suite.",
+    "files": [
+      {
+        "path": "package.json",
+        "content": "{\n  \"name\": \"field-notes\",\n  \"private\": true,\n  \"version\": \"1.0.0\",\n  \"type\": \"module\"\n}\n"
+      },
+      {
+        "path": "index.html",
+        "content": "<!doctype html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\">\n<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n<title>Acme Field Notes</title>\n<link rel=\"stylesheet\" href=\"styles.css\">\n</head>\n<body>\n<div class=\"masthead\">\n  <h1>Acme Field Notes</h1>\n  <img src=\"images/divider.svg\" class=\"divider\" alt=\"\">\n</div>\n<div class=\"content\">\n  <h4>Latest dispatch</h4>\n  <img src=\"images/harvest-crew.svg\" class=\"feature\">\n  <p>The harvest crew finished the north field on Tuesday, two days ahead of schedule, and moved on to the orchard rows.</p>\n  <h4>Sign up for dispatches</h4>\n  <p>Get the weekly note by email.</p>\n  <input type=\"email\" placeholder=\"Your email address\">\n  <div class=\"button\" onclick=\"joinList()\">Join the list</div>\n  <p id=\"joined-note\" hidden>You are on the list.</p>\n  <h4>From the archive</h4>\n  <img src=\"images/seed-chart.svg\" class=\"feature\">\n  <p>Germination rates for the last five seasons, charted by seed lot and sowing week.</p>\n</div>\n<script>\nfunction joinList() {\n  document.getElementById('joined-note').hidden = false;\n}\n</script>\n</body>\n</html>\n"
+      },
+      {
+        "path": "styles.css",
+        "content": "body { margin: 0; font-family: Georgia, serif; color: #222; background: #faf8f4; }\n.masthead { padding: 2rem 1.5rem 0; }\n.divider { width: 100%; height: 12px; }\n.content { max-width: 40rem; padding: 1rem 1.5rem 3rem; }\n.feature { max-width: 100%; }\n.button { display: inline-block; padding: 0.5rem 1rem; background: #2e5d3b; color: #fff; cursor: pointer; }\n.button:hover { background: #234a2e; }\ninput[type=\"email\"] { padding: 0.5rem; width: 16rem; }\n"
+      },
+      {
+        "path": "images/harvest-crew.svg",
+        "content": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 320 180\"><rect width=\"320\" height=\"180\" fill=\"#dce8d8\"/><text x=\"16\" y=\"95\" font-size=\"16\">Harvest crew walking the north field at dawn</text></svg>\n"
+      },
+      {
+        "path": "images/seed-chart.svg",
+        "content": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 320 180\"><rect width=\"320\" height=\"180\" fill=\"#e8e2d4\"/><text x=\"16\" y=\"95\" font-size=\"16\">Germination rate by season, 2021 to 2025</text></svg>\n"
+      },
+      {
+        "path": "images/divider.svg",
+        "content": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 320 12\"><line x1=\"0\" y1=\"6\" x2=\"320\" y2=\"6\" stroke=\"#b8b0a0\" stroke-width=\"2\"/></svg>\n"
+      },
+      {
+        "path": "tests/verify-retrofit.mjs",
+        "surface": "harness",
+        "content": "import assert from 'node:assert/strict';\nimport { readFileSync } from 'node:fs';\n\nconst html = readFileSync('index.html', 'utf8');\n\nfunction imgTag(src) {\n  const tags = [...html.matchAll(/<img\\b[^>]*>/gi)].map((m) => m[0]);\n  const tag = tags.find((t) => t.includes(src));\n  assert.ok(tag, `an img referencing ${src} still exists`);\n  return tag;\n}\nfunction altOf(tag, src) {\n  const alt = tag.match(/\\balt\\s*=\\s*(\"([^\"]*)\"|'([^']*)')/i);\n  assert.ok(alt, `image ${src} carries an alt attribute`);\n  return alt[2] ?? alt[3] ?? '';\n}\n\n// 1) Meaningful images: specific, non-empty alt text.\nfor (const src of ['harvest-crew', 'seed-chart']) {\n  const alt = altOf(imgTag(src), src).trim();\n  assert.ok(alt.length >= 10, `alt for ${src} must be specific, got \"${alt}\"`);\n  assert.ok(!/^(image|photo|picture|graphic|img)$/i.test(alt), `alt for ${src} must not be filler`);\n  assert.ok(!/^(an? )?(image|photo|picture) of/i.test(alt), `alt for ${src} must not open with \"image of\"`);\n}\nconsole.log('A11YRETRO_ORACLE alts ok');\n\n// 2) The decorative divider keeps an EMPTY alt - no sprayed description.\nassert.equal(altOf(imgTag('divider'), 'divider').trim(), '', 'decorative divider keeps alt=\"\"');\nconsole.log('A11YRETRO_ORACLE decorative ok');\n\n// 3) The email input is labeled by a real label whose for resolves to its id.\nconst labels = [...html.matchAll(/<label\\b[^>]*\\bfor\\s*=\\s*[\"']([^\"']+)[\"'][^>]*>/gi)];\nassert.ok(labels.length >= 1, 'a label element with a for attribute exists');\nconst paired = labels.filter((m) => new RegExp(`<input\\\\b[^>]*\\\\bid\\\\s*=\\\\s*[\"']${m[1]}[\"']`, 'i').test(html));\nassert.ok(paired.length >= 1, \"a label's for attribute resolves to a real input id\");\nconsole.log('A11YRETRO_ORACLE label ok');\n\n// 4) The join control is a real button, or carries complete ARIA button semantics.\nconst join = html.match(/<([a-z0-9]+)\\b([^>]*)>\\s*Join the list/i);\nassert.ok(join, 'the \"Join the list\" control still exists');\nconst [, joinTag, joinAttrs] = join;\nif (joinTag.toLowerCase() !== 'button') {\n  assert.ok(/\\brole\\s*=\\s*[\"']button[\"']/i.test(joinAttrs), 'non-button control carries role=\"button\"');\n  assert.ok(/\\btabindex\\s*=\\s*[\"']0[\"']/i.test(joinAttrs), 'non-button control is focusable via tabindex=\"0\"');\n  const keyWired = /\\bonkey(?:down|up|press)\\s*=/i.test(joinAttrs) || /addEventListener\\s*\\(\\s*[\"']key(?:down|up|press)[\"']/i.test(html);\n  assert.ok(keyWired, 'non-button control has keyboard activation wired');\n}\nconsole.log('A11YRETRO_ORACLE control ok');\n\n// 5) Heading order is monotonic from a single h1.\nconst levels = [...html.matchAll(/<h([1-6])\\b[^>]*>/gi)].map((m) => Number(m[1]));\nassert.ok(levels.length >= 3, 'the page keeps its headings');\nassert.equal(levels[0], 1, 'the page starts at h1');\nfor (let i = 1; i < levels.length; i++) {\n  assert.ok(levels[i] <= levels[i - 1] + 1, `heading level jumps from h${levels[i - 1]} to h${levels[i]}`);\n}\nconsole.log('A11YRETRO_ORACLE headings ok');\n\n// 6) The join behavior target survives the retrofit.\nassert.ok(/joined-note/.test(html), 'the joined-note behavior target survives');\nconsole.log('A11YRETRO_ORACLE done');\n"
+      }
+    ],
+    "craftbookParams": {
+      "workPath": "tasks/eval"
+    }
+  },
+  "success": {
+    "summary": "All five seeded violations are repaired at their real sites in index.html — specific alts on the meaningful images, an empty alt preserved on the decorative divider, a paired label, a keyboard-operable join control, monotonic headings — and every fleet artifact exists with honest citations.",
+    "deliverables": [
+      {
+        "path": "tasks/eval/audit.md",
+        "kind": "markdown-notes",
+        "artifact": true,
+        "minBytes": 600,
+        "checks": [
+          {
+            "kind": "contains",
+            "file": "tasks/eval/audit.md",
+            "pattern": "^##\\s+Scope[\\s\\S]*^##\\s+Violations[\\s\\S]*^##\\s+Priorities",
+            "flags": "im",
+            "label": "audit sections in order"
+          },
+          {
+            "kind": "tableShape",
+            "file": "tasks/eval/audit.md",
+            "requiredColumns": [
+              "File",
+              "Issue",
+              "Priority"
+            ],
+            "minRows": 3,
+            "artifact": true
+          },
+          {
+            "kind": "citationsResolve",
+            "file": "tasks/eval/audit.md",
+            "minCitations": 2,
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/audit.md",
+            "pattern": "index\\.html",
+            "label": "the audit names the real page"
+          }
+        ]
+      },
+      {
+        "path": "tasks/eval/fix-notes.md",
+        "kind": "markdown-notes",
+        "artifact": true,
+        "minBytes": 700,
+        "checks": [
+          {
+            "kind": "contains",
+            "file": "tasks/eval/fix-notes.md",
+            "pattern": "^##\\s+Problem[\\s\\S]*^##\\s+Change[\\s\\S]*^##\\s+Files touched[\\s\\S]*^##\\s+Per-violation disposition[\\s\\S]*^##\\s+Risk[\\s\\S]*^##\\s+How to verify",
+            "flags": "im",
+            "label": "fix-notes sections in order"
+          },
+          {
+            "kind": "citationsResolve",
+            "file": "tasks/eval/fix-notes.md",
+            "minCitations": 2,
+            "artifact": true
+          }
+        ]
+      },
+      {
+        "path": "tasks/eval/validation.md",
+        "kind": "markdown-notes",
+        "artifact": true,
+        "minBytes": 500,
+        "checks": [
+          {
+            "kind": "contains",
+            "file": "tasks/eval/validation.md",
+            "pattern": "^##\\s+Per-item verification[\\s\\S]*^##\\s+Keyboard walk[\\s\\S]*^##\\s+Result",
+            "flags": "im",
+            "label": "validation sections in order"
+          }
+        ]
+      },
+      {
+        "path": "tasks/eval/review.md",
+        "kind": "markdown-report",
+        "artifact": true,
+        "minBytes": 400,
+        "checks": [
+          {
+            "kind": "contains",
+            "file": "tasks/eval/review.md",
+            "pattern": "Verdict:\\s*(?:PASS|REVISE)",
+            "flags": "i",
+            "label": "explicit reviewer verdict"
+          }
+        ]
+      }
+    ],
+    "checks": [
+      {
+        "kind": "notContains",
+        "file": "index.html",
+        "pattern": "<img\\b(?![^>]*\\balt\\s*=)[^>]*>",
+        "label": "no image is missing its alt attribute"
+      },
+      {
+        "kind": "htmlLint",
+        "file": "index.html"
+      },
+      {
+        "kind": "nodeScriptPasses",
+        "script": "tests/verify-retrofit.mjs",
+        "timeoutMs": 60000,
+        "requiredOutput": [
+          {
+            "pattern": "A11YRETRO_ORACLE alts ok",
+            "label": "meaningful images carry specific alt text"
+          },
+          {
+            "pattern": "A11YRETRO_ORACLE decorative ok",
+            "label": "the decorative divider keeps its empty alt"
+          },
+          {
+            "pattern": "A11YRETRO_ORACLE label ok",
+            "label": "the label's for pairs with a real input id"
+          },
+          {
+            "pattern": "A11YRETRO_ORACLE control ok",
+            "label": "the join control is keyboard-operable"
+          },
+          {
+            "pattern": "A11YRETRO_ORACLE headings ok",
+            "label": "heading order is monotonic"
+          }
+        ]
+      }
+    ],
+    "taskNotes": {
+      "minBytes": 120,
+      "checks": [
+        {
+          "kind": "contains",
+          "file": "task-notes.md",
+          "pattern": "\\bDONE\\b[\\s\\S]*(validation\\.md|fix-notes\\.md|audit\\.md)",
+          "flags": "i",
+          "label": "DONE note names the deliverables"
+        }
+      ]
+    },
+    "taskGraph": {
+      "requireCraftbookTask": true,
+      "requireTerminalStep": true
+    },
+    "unchangedFixtures": [
+      "package.json",
+      "images/harvest-crew.svg",
+      "images/seed-chart.svg",
+      "images/divider.svg"
+    ]
+  },
+  "rubric": {
+    "artifact": {
+      "path": "tasks/eval/fix-notes.md",
+      "kind": "markdown"
+    },
+    "axes": [
+      {
+        "name": "Real-site repair",
+        "description": "Violations were fixed in the actual markup with semantic elements preferred over ARIA bolt-ons — a real button and a real label rather than aria-label sprayed on divs."
+      },
+      {
+        "name": "Classification judgment",
+        "description": "Meaningful versus decorative images were classified correctly: specific purposeful alt text for the content images, an empty alt preserved on the divider, and the decorative call stated in the notes."
+      },
+      {
+        "name": "Honest verification trail",
+        "description": "Audit, fix-notes, and validation reconcile item for item, and validation separates what was inspected in the code from what was actually exercised."
+      }
+    ]
+  },
+  "qualityFocus": [
+    "real-site fixes over ARIA theater",
+    "content vs decorative image judgment",
+    "enforced review loop"
+  ]
+}