@bendyline/gilde 0.1.27 → 0.1.28

package/data/craftbook-templates/cl/cli-tool/versions/1.1.1/test.json

@@ -0,0 +1,128 @@
+{
+  "schemaVersion": 1,
+  "title": "Small CSV summary CLI",
+  "objective": "Measure whether the cli-tool craftbook scopes command UX, writes a runnable Node CLI, and includes tests/examples.",
+  "tags": [
+    "html-page"
+  ],
+  "prompt": "In the `CLI Tool Eval` project, build a small dependency-free Node ESM CLI named `summarize-orders`. Write `src/cli.js` and `src/cli.test.js`. The CLI should accept `--input <csv>`, `--format table|json`, and `--min-total <number>`, parse order rows with customer,status,total fields, filter by minimum total, and print either a text table or JSON summary. The test file should use Node assert or a tiny test harness and cover JSON output, table output, and min-total filtering.",
+  "setup": {
+    "projectName": "CLI Tool Eval",
+    "about": "Self-contained eval project for cli-tool. Deliverables are workspace/src/cli.js and workspace/src/cli.test.js.",
+    "missionObjectives": "Produce a small dependency-free Node CLI with argument parsing, CSV parsing, JSON/table output, and tests.",
+    "files": [],
+    "worker": {
+      "name": "Koen",
+      "role": "Developer"
+    }
+  },
+  "mocks": [],
+  "success": {
+    "summary": "src/cli.js implements argument parsing/output modes and src/cli.test.js covers the core CLI behavior.",
+    "deliverables": [
+      {
+        "path": "src/cli.js",
+        "kind": "code-module",
+        "minBytes": 1600,
+        "checks": [
+          {
+            "kind": "contains",
+            "file": "src/cli.js",
+            "pattern": "process\\.argv|argv",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "src/cli.js",
+            "pattern": "--input",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "src/cli.js",
+            "pattern": "--format",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "src/cli.js",
+            "pattern": "--min-total",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "src/cli.js",
+            "pattern": "read_file|fs",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "src/cli.js",
+            "pattern": "JSON\\.stringify|console\\.log",
+            "flags": "i"
+          }
+        ]
+      },
+      {
+        "path": "src/cli.test.js",
+        "kind": "code-with-tests",
+        "minBytes": 900,
+        "checks": [
+          {
+            "kind": "contains",
+            "file": "src/cli.test.js",
+            "pattern": "assert|describe|it|test",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "src/cli.test.js",
+            "pattern": "json",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "src/cli.test.js",
+            "pattern": "table",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "src/cli.test.js",
+            "pattern": "min-total|filter",
+            "flags": "i"
+          }
+        ]
+      }
+    ]
+  },
+  "rubric": {
+    "artifact": {
+      "path": "src/cli.js",
+      "kind": "typescript"
+    },
+    "axes": [
+      {
+        "name": "structure",
+        "description": "Layout and hierarchy fit the content; sections are scannable and coherent."
+      },
+      {
+        "name": "grounding",
+        "description": "Seeded source content is used faithfully — no invented facts or dropped requirements."
+      },
+      {
+        "name": "interactivity",
+        "description": "Controls and states the page claims to offer actually work."
+      },
+      {
+        "name": "polish",
+        "description": "Styling is intentional and responsive rather than unstyled or broken."
+      }
+    ]
+  },
+  "qualityFocus": [
+    "CLI UX scope",
+    "argument parsing",
+    "test coverage"
+  ]
+}

package/data/craftbook-templates/co/codebase-refactoring-review/versions/1.0.1/craftbook.json

@@ -0,0 +1,153 @@
+{
+  "id": "codebase-refactoring-review",
+  "name": "Codebase Refactoring Review",
+  "description": "Review an entire codebase for the least cogent, highest-leverage refactoring opportunities without changing source. Uses the repository map and per-file AI health index to rank weak areas, then verifies each lead in the real code and leaves a file-and-line-cited morning report with sequenced refactor plans, risk, effort, and tests that must protect behavior. Use for a weekly code-health sweep, refactoring review, technical-debt triage, finding code smells, or deciding which files should be refactored first.\n\nA gallery craftbook generated from an archetype spec. It runs\n`phase → (per-phase gate) → … → evaluate → (loop) → finish`. Each build\nphase that produces a checkable artifact is followed by a **runtime\ngate-checkpoint** — the runtime verifies the artifact and routes with no\nmodel turn, looping back to redo the phase on a miss. The final `evaluate`\nstep holds a static deliverable gate plus a reviewer QA pass. What it adds\nover the generic `build-loop`: a specialist role per phase, a\ndomain-correct ordering, and a concrete per-phase quality bar.\n\nDeliverables marked \"artifact\" land in the project's artifacts drawer (`write_artifact` / `read_artifact`), not the shipped workspace — review output is not product source.\n\nPhases:\n\n1. Rank weak areas (reviewer) — use the repo map and per-file health index to build a coverage-aware candidate list → gated on artifact `notes/refactoring/candidates.md` (markdown-notes)\n2. Verify refactoring candidates (reviewer) — inspect candidate symbols, responsibilities, callers, and tests in real source → gated on artifact `notes/refactoring/verified.md` (markdown-notes)\n3. Write the refactoring report (reviewer) — prioritized code-health report with safe, sequenced refactor plans → gated on artifact `refactoring-review.md` (markdown-report)\n\nThe gates never advance with an unmet criterion, and loop back to the\nowning phase to fix named gaps.\n",
+  "entryStepId": "rank",
+  "triggers": [
+    "codebase refactoring review",
+    "what should we refactor",
+    "find the least cogent code",
+    "weekly code health review",
+    "technical debt sweep",
+    "nightly refactoring review"
+  ],
+  "toolsets": [
+    {
+      "toolsetId": "builtin.code-intel",
+      "autoAllow": true,
+      "reason": "rank indexed file-health leads and inspect only the relevant symbols"
+    },
+    {
+      "toolsetId": "builtin.git",
+      "autoAllow": true,
+      "reason": "read-only history and churn evidence for prioritizing refactors"
+    }
+  ],
+  "steps": [
+    {
+      "id": "rank",
+      "name": "Rank weak areas",
+      "description": "use the repo map and per-file health index to build a coverage-aware candidate list",
+      "prompt": "Start with `map_repo` and record the indexed review coverage (reviewed/eligible), average health, major-issue count, and worst files. Call `list_file_issues` across the repo, then use `search_code` for cross-cutting duplication, oversized orchestration, unclear ownership, error handling, and tightly coupled state. If git history is available, use read-only `run_git` queries to add churn/fix-frequency evidence; missing history is not a failure. Rank candidate files or cohesive areas using explicit factors: low indexed health, confirmed major issues, too many responsibilities, coupling/fan-out, duplication, change frequency, test difficulty, and blast radius. Do not call an indexed lead a finding yet and do not modify source. Write the coverage statement, ranking method, and top candidates to `notes/refactoring/candidates.md`.\n\nThe deliverable `notes/refactoring/candidates.md` lands in the project's artifacts drawer — write it with `write_artifact` and read it back with `read_artifact`; the shipped workspace stays untouched.",
+      "suggestedRole": "reviewer",
+      "advanceWhen": {
+        "file": "notes/refactoring/candidates.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "notes/refactoring/candidates.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "notes/refactoring/candidates.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "rank",
+        "maxAttempts": 3
+      },
+      "next": "verify"
+    },
+    {
+      "id": "verify",
+      "name": "Verify refactoring candidates",
+      "description": "inspect candidate symbols, responsibilities, callers, and tests in real source",
+      "prompt": "Verify every shortlisted candidate in source. Call `file_review` for the indexed rationale, `outline_file` before reading a large file, `read_symbol` for the implicated units, and `find_references` to understand callers and blast radius. Locate tests with `search_code`/`grep_files`. For each confirmed candidate record real file:line evidence, the current responsibilities, the specific cohesion/coupling/duplication/testability problem, why it matters, a bounded refactor seam, dependencies and migration order, behavior-preserving tests required first, effort, risk, and expected payoff. Reject false-positive index leads explicitly. Prefer a smaller ranked list of verified opportunities over a long smell inventory. Write the evidence matrix to `notes/refactoring/verified.md`; do not change code.\n\nThe deliverable `notes/refactoring/verified.md` lands in the project's artifacts drawer — write it with `write_artifact` and read it back with `read_artifact`; the shipped workspace stays untouched.",
+      "suggestedRole": "reviewer",
+      "advanceWhen": {
+        "file": "notes/refactoring/verified.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "notes/refactoring/verified.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "notes/refactoring/verified.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "verify",
+        "maxAttempts": 3
+      },
+      "next": "report"
+    },
+    {
+      "id": "report",
+      "name": "Write the refactoring report",
+      "description": "prioritized code-health report with safe, sequenced refactor plans",
+      "prompt": "Write `refactoring-review.md` for an admin to read in the morning. Use these exact sections: `## Executive summary`, `## Index coverage`, `## Ranked opportunities`, `## Cross-cutting themes`, `## Defer or leave alone`, and `## Recommended sequence`. Each ranked opportunity must cite real file:line evidence; state why the area is insufficiently cogent; name the proposed seam and steps; list behavior-preserving tests; and include impact, effort, risk, and dependencies. Separate systemic themes from individual files. State index gaps and unreviewed areas so a quiet report is not mistaken for a clean codebase. Do not include style-only churn or recommend rewrites without a migration boundary. On a loop-back, repair only the named report gaps.\n\nThe deliverable `refactoring-review.md` lands in the project's artifacts drawer — write it with `write_artifact` and read it back with `read_artifact`; the shipped workspace stays untouched.",
+      "suggestedRole": "reviewer",
+      "advanceWhen": {
+        "file": "refactoring-review.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "refactoring-review.md",
+            "bytes": 1800,
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "refactoring-review.md",
+            "pattern": "(?:^|\\n)#{1,3}\\s+\\S",
+            "flags": "i",
+            "label": "at least one markdown heading",
+            "artifact": true
+          }
+        ],
+        "onReject": "report",
+        "maxAttempts": 4
+      },
+      "next": "evaluate"
+    },
+    {
+      "id": "evaluate",
+      "name": "Evaluate",
+      "description": "Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.",
+      "prompt": "Grade `refactoring-review.md`: (1) index coverage and limitations are explicit; (2) every ranked item was verified in source and cites a real file:line; (3) ranking uses impact, evidence, effort, risk, and blast radius rather than file size alone; (4) each recommendation names a bounded seam, sequence, and behavior-preserving tests; (5) systemic themes are distinguished from local smells; (6) false positives and areas to leave alone are recorded; (7) no source was changed and no vague rewrite advice remains. PASS every item or loop back with exact gaps.\n\nThe deliverable lives in the project's artifacts drawer — open `refactoring-review.md` with `read_artifact`, not `read_file`.\n\nThen route — this is the whole point of the loop:\n\n- **Every criterion PASSES →** call `advance_task_step({ ref, stepId: \"evaluate\", next: \"finish\" })`.\n- **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: \"evaluate\", next: \"report\" })` to loop back. The builder fixes exactly those gaps.\n\nNever route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in.",
+      "suggestedRole": "reviewer",
+      "consumes": [
+        {
+          "file": "refactoring-review.md",
+          "artifact": true
+        }
+      ],
+      "next": "report"
+    },
+    {
+      "id": "finish",
+      "name": "Finish",
+      "description": "All acceptance criteria met. Stamp a short summary and report DONE.",
+      "prompt": "Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.",
+      "suggestedRole": "developer",
+      "terminal": true
+    }
+  ],
+  "version": "1.0.1",
+  "releasedAt": "2026-08-14T00:00:00Z"
+}

package/data/craftbook-templates/co/codebase-refactoring-review/versions/1.0.1/test.json

@@ -0,0 +1,116 @@
+{
+  "schemaVersion": 1,
+  "title": "Codebase Refactoring Review hotspot eval",
+  "objective": "Measure whether the review ranks and verifies a low-cohesion hotspot, proposes bounded seams, and protects behavior with tests.",
+  "tags": [
+    "corpus"
+  ],
+  "prompt": "Use the Codebase Refactoring Review craftbook for the weekly code-health sweep. Find the least cogent areas in this fixture and write refactoring-review.md. Do not change source.",
+  "setup": {
+    "projectName": "Refactoring Maintenance Eval",
+    "about": "A small order service with one deliberate multi-responsibility hotspot and a thin caller/test surface.",
+    "missionObjectives": "Verify refactoring candidates in source, rank them, and propose behavior-preserving seams rather than a rewrite.",
+    "files": [
+      {
+        "path": "src/order-service.ts",
+        "content": "export async function processOrder(input, db, mailer, audit) {\n  if (!input.customerId) throw new Error('customer required');\n  let total = 0;\n  for (const line of input.lines) {\n    const item = await db.inventory.find(line.sku);\n    if (!item || item.stock < line.qty) throw new Error('out of stock');\n    total += item.price * line.qty;\n    await db.inventory.update(line.sku, { stock: item.stock - line.qty });\n  }\n  if (input.coupon === 'SAVE10') total *= 0.9;\n  const order = await db.orders.insert({ ...input, total, status: 'paid' });\n  try {\n    await mailer.sendReceipt(input.email, order);\n    await audit.write('order.created', order);\n  } catch (_err) {\n    // Order succeeds even when both side effects disappear.\n  }\n  return order;\n}\n"
+      },
+      {
+        "path": "src/order-controller.ts",
+        "content": "import { processOrder } from './order-service';\nexport const postOrder = deps => async (req, res) => {\n  const order = await processOrder(req.body, deps.db, deps.mailer, deps.audit);\n  res.status(201).json(order);\n};\n"
+      },
+      {
+        "path": "test/order-service.test.ts",
+        "content": "test('creates an order', async () => {\n  const result = await processOrder(sample, fakeDb, fakeMailer, fakeAudit);\n  expect(result.status).toBe('paid');\n});\n"
+      }
+    ],
+    "worker": {
+      "name": "Rae",
+      "role": "Reviewer"
+    }
+  },
+  "mocks": [],
+  "success": {
+    "summary": "refactoring-review.md verifies the processOrder hotspot and proposes sequenced, test-protected seams with explicit coverage limitations.",
+    "deliverables": [
+      {
+        "path": "refactoring-review.md",
+        "kind": "markdown-report",
+        "minBytes": 1500,
+        "checks": [
+          {
+            "kind": "contains",
+            "file": "refactoring-review.md",
+            "pattern": "src/order-service\\.ts:[0-9]+|src/order-service\\.ts",
+            "flags": "i",
+            "label": "source evidence"
+          },
+          {
+            "kind": "contains",
+            "file": "refactoring-review.md",
+            "pattern": "processOrder",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "refactoring-review.md",
+            "pattern": "cohesion|responsibilit|coupling",
+            "flags": "i",
+            "label": "cogency diagnosis"
+          },
+          {
+            "kind": "contains",
+            "file": "refactoring-review.md",
+            "pattern": "extract|seam|split",
+            "flags": "i",
+            "label": "bounded refactor"
+          },
+          {
+            "kind": "contains",
+            "file": "refactoring-review.md",
+            "pattern": "test[\\s\\S]{0,120}(stock|coupon|mailer|audit|failure)",
+            "flags": "i",
+            "label": "behavior protection"
+          },
+          {
+            "kind": "contains",
+            "file": "refactoring-review.md",
+            "pattern": "impact|effort|risk",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "refactoring-review.md",
+            "pattern": "Index coverage|coverage|not reviewed",
+            "flags": "i"
+          }
+        ]
+      }
+    ]
+  },
+  "rubric": {
+    "artifact": {
+      "path": "refactoring-review.md",
+      "kind": "markdown"
+    },
+    "axes": [
+      {
+        "name": "ranking",
+        "description": "Candidates are prioritized by evidence, impact, effort, risk, and blast radius."
+      },
+      {
+        "name": "diagnosis",
+        "description": "The report explains the concrete cohesion, coupling, and testability problems."
+      },
+      {
+        "name": "safe plan",
+        "description": "Recommendations name bounded seams, sequencing, and behavior-preserving tests."
+      }
+    ]
+  },
+  "qualityFocus": [
+    "least-cogent areas",
+    "verified hotspots",
+    "safe refactor sequencing"
+  ]
+}

package/data/craftbook-templates/co/codebase-ux-review/versions/1.0.1/craftbook.json

@@ -0,0 +1,153 @@
+{
+  "id": "codebase-ux-review",
+  "name": "Codebase UX Review",
+  "description": "Review the user experience implemented across a codebase and, when runnable, exercise the key flows in a real browser. Starts from the indexed UI surface rather than one screenshot, traces primary journeys and state transitions, then leaves a prioritized morning report covering information architecture, comprehension, feedback, recovery, consistency, responsive behavior, and user impact with source or runtime evidence. Use for a weekly UX sweep, product usability review, interaction review, or finding the highest-impact friction in an application.\n\nA gallery craftbook generated from an archetype spec. It runs\n`phase → (per-phase gate) → … → evaluate → (loop) → finish`. Each build\nphase that produces a checkable artifact is followed by a **runtime\ngate-checkpoint** — the runtime verifies the artifact and routes with no\nmodel turn, looping back to redo the phase on a miss. The final `evaluate`\nstep holds a static deliverable gate plus a reviewer QA pass. What it adds\nover the generic `build-loop`: a specialist role per phase, a\ndomain-correct ordering, and a concrete per-phase quality bar.\n\nDeliverables marked \"artifact\" land in the project's artifacts drawer (`write_artifact` / `read_artifact`), not the shipped workspace — review output is not product source.\n\nPhases:\n\n1. Map the experience (reviewer) — inventory surfaces, actors, journeys, states, and review coverage from the index → gated on artifact `notes/ux/surface-map.md` (markdown-notes)\n2. Exercise and inspect journeys (reviewer) — walk key flows and verify indexed leads in source or a browser → gated on artifact `notes/ux/evidence.md` (markdown-notes)\n3. Write the UX report (reviewer) — prioritized, journey-centered usability report for morning triage → gated on artifact `ux-review.md` (markdown-report)\n\nThe gates never advance with an unmet criterion, and loop back to the\nowning phase to fix named gaps.\n",
+  "entryStepId": "map",
+  "triggers": [
+    "codebase ux review",
+    "weekly ux review",
+    "review the product experience",
+    "find usability problems",
+    "nightly ux sweep",
+    "review the user journeys"
+  ],
+  "toolsets": [
+    {
+      "toolsetId": "builtin.code-intel",
+      "autoAllow": true,
+      "reason": "map routes, components, state, and indexed per-file UX leads"
+    },
+    {
+      "toolsetId": "builtin.browser-automation",
+      "autoAllow": true,
+      "reason": "exercise runnable journeys and capture real interaction evidence"
+    }
+  ],
+  "steps": [
+    {
+      "id": "map",
+      "name": "Map the experience",
+      "description": "inventory surfaces, actors, journeys, states, and review coverage from the index",
+      "prompt": "Call `map_repo`, `list_file_issues`, and targeted `search_code` queries to inventory the implemented experience: routes/views, navigation, dialogs, forms, onboarding, settings, empty/loading/error/success states, destructive actions, and responsive breakpoints. Read product/UX guidance already in the workspace before applying generic taste. Identify primary actors and 3-7 highest-value journeys with their start, goal, and risky transitions. Record which surfaces are runnable and which can only be reviewed statically. Write the surface map, journey matrix, local design principles, index coverage, and test plan to `notes/ux/surface-map.md`. No findings yet.\n\nThe deliverable `notes/ux/surface-map.md` lands in the project's artifacts drawer — write it with `write_artifact` and read it back with `read_artifact`; the shipped workspace stays untouched.",
+      "suggestedRole": "reviewer",
+      "advanceWhen": {
+        "file": "notes/ux/surface-map.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "notes/ux/surface-map.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "notes/ux/surface-map.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "map",
+        "maxAttempts": 3
+      },
+      "next": "exercise"
+    },
+    {
+      "id": "exercise",
+      "name": "Exercise and inspect journeys",
+      "description": "walk key flows and verify indexed leads in source or a browser",
+      "prompt": "Walk every prioritized journey. When the app is runnable, use `run_playwright_script` to test it at representative desktop and mobile sizes while checking navigation, focus, validation, loading, empty, error, success, cancellation, and recovery states. When it is not runnable, trace the relevant route/component/state symbols with `outline_file`, `read_symbol`, and `find_references`; label static inferences honestly. Verify indexed leads rather than repeating them. For each confirmed issue capture journey, step, evidence (screenshot/selector or file:line), expected vs actual experience, affected users, severity, frequency, and a concrete design/change recommendation. Also record strengths and tested-clean states. Write the evidence log to `notes/ux/evidence.md`.\n\nThe deliverable `notes/ux/evidence.md` lands in the project's artifacts drawer — write it with `write_artifact` and read it back with `read_artifact`; the shipped workspace stays untouched.",
+      "suggestedRole": "reviewer",
+      "advanceWhen": {
+        "file": "notes/ux/evidence.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "notes/ux/evidence.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "notes/ux/evidence.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "exercise",
+        "maxAttempts": 3
+      },
+      "next": "report"
+    },
+    {
+      "id": "report",
+      "name": "Write the UX report",
+      "description": "prioritized, journey-centered usability report for morning triage",
+      "prompt": "Write `ux-review.md` with: `## Verdict`, `## Coverage`, `## Journey scorecard`, `## Findings`, `## Strengths`, `## Not verified`, and `## Morning action list`. Order findings by user harm × frequency, not visual polish. Every finding must cite a journey step and runtime or file:line evidence, explain the user consequence, and give a concrete recommendation with effort. Cover information architecture, comprehension, feedback/state visibility, error prevention/recovery, consistency, and responsive behavior. Keep accessibility defects cross-referenced rather than duplicating the a11y audit. State when a judgment is a static inference. On a loop-back, fix only named gaps.\n\nThe deliverable `ux-review.md` lands in the project's artifacts drawer — write it with `write_artifact` and read it back with `read_artifact`; the shipped workspace stays untouched.",
+      "suggestedRole": "reviewer",
+      "advanceWhen": {
+        "file": "ux-review.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "ux-review.md",
+            "bytes": 1800,
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "ux-review.md",
+            "pattern": "(?:^|\\n)#{1,3}\\s+\\S",
+            "flags": "i",
+            "label": "at least one markdown heading",
+            "artifact": true
+          }
+        ],
+        "onReject": "report",
+        "maxAttempts": 4
+      },
+      "next": "evaluate"
+    },
+    {
+      "id": "evaluate",
+      "name": "Evaluate",
+      "description": "Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.",
+      "prompt": "Grade `ux-review.md`: (1) the important surfaces and journeys are covered; (2) findings cite a journey step plus runtime or real file:line evidence; (3) static inference is distinguished from exercised behavior; (4) loading, empty, error, success, cancellation, and recovery states were considered; (5) severity follows user harm and frequency; (6) recommendations are concrete and effort-aware; (7) strengths, unverified areas, and an actionable morning list are present. PASS all or loop back with exact gaps.\n\nThe deliverable lives in the project's artifacts drawer — open `ux-review.md` with `read_artifact`, not `read_file`.\n\nThen route — this is the whole point of the loop:\n\n- **Every criterion PASSES →** call `advance_task_step({ ref, stepId: \"evaluate\", next: \"finish\" })`.\n- **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: \"evaluate\", next: \"report\" })` to loop back. The builder fixes exactly those gaps.\n\nNever route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in.",
+      "suggestedRole": "reviewer",
+      "consumes": [
+        {
+          "file": "ux-review.md",
+          "artifact": true
+        }
+      ],
+      "next": "report"
+    },
+    {
+      "id": "finish",
+      "name": "Finish",
+      "description": "All acceptance criteria met. Stamp a short summary and report DONE.",
+      "prompt": "Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.",
+      "suggestedRole": "developer",
+      "terminal": true
+    }
+  ],
+  "version": "1.0.1",
+  "releasedAt": "2026-08-14T00:00:00Z"
+}