@bendyline/gilde 0.1.26 → 0.1.28

package/data/craftbook-templates/de/dependency-audit/versions/1.1.1/test.json

@@ -0,0 +1,108 @@
+{
+  "schemaVersion": 1,
+  "title": "Dependency Audit evidence-discipline eval",
+  "objective": "Measure whether the audit prioritizes supplied vulnerability and license evidence without inventing package facts or patch versions.",
+  "tags": [
+    "corpus"
+  ],
+  "prompt": "Use the Dependency Audit craftbook for the weekly maintenance review. Treat evidence/dependencies.json as authoritative and write dependency-audit.md. Do not use the network or modify package files.",
+  "setup": {
+    "projectName": "Dependency Maintenance Eval",
+    "about": "A package fixture with authoritative offline dependency evidence.",
+    "missionObjectives": "Prioritize the no-patch critical dependency, exact license issue, maintenance-only upgrade, and clean defer correctly.",
+    "files": [
+      {
+        "path": "package.json",
+        "content": "{\n  \"name\": \"returns-desk\",\n  \"dependencies\": {\n    \"legacy-parser\": \"1.2.0\",\n    \"chart-kit\": \"2.0.0\",\n    \"stable-lib\": \"4.2.0\"\n  }\n}\n"
+      },
+      {
+        "path": "evidence/dependencies.json",
+        "content": "[\n  {\"name\":\"legacy-parser\",\"installed\":\"1.2.0\",\"latest\":\"1.2.0\",\"advisory\":\"CVE-2026-4242\",\"severity\":\"critical\",\"patchedVersion\":null,\"reachableFrom\":\"src/import.ts\",\"replacement\":\"safe-parser 3.x\",\"license\":\"MIT\"},\n  {\"name\":\"chart-kit\",\"installed\":\"2.0.0\",\"latest\":\"3.1.0\",\"advisory\":null,\"maintenance\":\"major version available\",\"license\":\"GPL-3.0-only\",\"replacement\":\"chart.js 4.x\"},\n  {\"name\":\"stable-lib\",\"installed\":\"4.2.0\",\"latest\":\"4.2.0\",\"advisory\":null,\"maintenance\":null,\"license\":\"MIT\"}\n]\n"
+      },
+      {
+        "path": "src/import.ts",
+        "content": "import { parse } from 'legacy-parser';\nexport const importRows = (text: string) => parse(text);\n"
+      }
+    ],
+    "worker": {
+      "name": "Rae",
+      "role": "Reviewer"
+    }
+  },
+  "mocks": [],
+  "success": {
+    "summary": "dependency-audit.md follows the evidence, orders the critical no-patch action first, and handles license and clean dependencies honestly.",
+    "deliverables": [
+      {
+        "path": "dependency-audit.md",
+        "kind": "markdown-report",
+        "minBytes": 1300,
+        "checks": [
+          {
+            "kind": "contains",
+            "file": "dependency-audit.md",
+            "pattern": "legacy-parser[\\s\\S]{0,300}CVE-2026-4242",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "dependency-audit.md",
+            "pattern": "safe-parser 3\\.x|no patched version|contain",
+            "flags": "i",
+            "label": "no-patch action"
+          },
+          {
+            "kind": "contains",
+            "file": "dependency-audit.md",
+            "pattern": "chart-kit[\\s\\S]{0,300}GPL-3\\.0-only",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "dependency-audit.md",
+            "pattern": "chart\\.js 4\\.x",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "dependency-audit.md",
+            "pattern": "stable-lib[\\s\\S]{0,200}(defer|no action|current)",
+            "flags": "i"
+          },
+          {
+            "kind": "notContains",
+            "file": "dependency-audit.md",
+            "pattern": "legacy-parser[\\s\\S]{0,120}(patch upgrade|upgrade to 1\\.)",
+            "flags": "i",
+            "label": "do not invent a patch"
+          }
+        ]
+      }
+    ]
+  },
+  "rubric": {
+    "artifact": {
+      "path": "dependency-audit.md",
+      "kind": "markdown"
+    },
+    "axes": [
+      {
+        "name": "evidence discipline",
+        "description": "Package facts and versions come only from supplied evidence."
+      },
+      {
+        "name": "prioritization",
+        "description": "Risk, reachability, license, and migration cost drive a sensible order."
+      },
+      {
+        "name": "actionability",
+        "description": "Each package receives an exact upgrade, replace, contain, or defer action."
+      }
+    ]
+  },
+  "qualityFocus": [
+    "offline evidence fidelity",
+    "no-patch handling",
+    "license accuracy"
+  ]
+}

package/data/craftbook-templates/de/deploy-checklist/versions/1.0.1/craftbook.json

@@ -0,0 +1,159 @@
+{
+  "id": "deploy-checklist",
+  "name": "Deploy Checklist",
+  "description": "Author and then actually execute a pre-deploy verification checklist for shipping a release to production — the concrete gates that must be green before the deploy button is pressed: tests passing, build clean, migrations reviewed, config/secrets present, feature flags set, rollback path confirmed, and observability/alerts ready. A planner scopes the checklist tailored to this service and risk level, a developer runs each item and records real evidence (command output, links, screenshots) for pass or fail, and a reviewer signs off go/no-go. Use this before a production deploy, a release cut-over, or any 'are we ready to ship?' gate where skipping a step causes outages.\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. Scope the checklist (planner) — define the go/no-go gates for THIS service and release → gated on artifact `notes/scope.md` (markdown-notes)\n2. Verify each gate (developer) — execute every checklist item and record real evidence → gated on `deploy-checklist.md` (markdown-doc)\n3. Sign off go/no-go (reviewer) — audit the evidence and confirm the go/no-go decision → gated on artifact `notes/report.md` (markdown-notes)\n\nThe gates never advance with an unmet criterion, and loop back to the\nowning phase to fix named gaps.\n",
+  "entryStepId": "scope",
+  "triggers": [
+    "pre-deploy checklist",
+    "are we ready to deploy",
+    "go/no-go for release",
+    "production deploy checklist",
+    "ship readiness check"
+  ],
+  "steps": [
+    {
+      "id": "scope",
+      "name": "Scope the checklist",
+      "description": "define the go/no-go gates for THIS service and release",
+      "prompt": "1. Identify what is being deployed (service, version, target environment) and its blast radius / risk level. 2. Build the checklist of pre-deploy gates tailored to this service — at minimum: CI green (tests + lint + build), schema/data migrations reviewed and reversible, required config and secrets present in the target env, feature flags in their intended state, dependencies/external services healthy, a confirmed rollback path, and observability (dashboards, alerts, on-call) ready. 3. Drop any gate that genuinely does not apply and note why; add service-specific gates (cache warmups, queue drains, third-party rate limits) that do. 4. For each gate, write the EXACT verification step (the command to run, the URL to check, the artifact to inspect) and the explicit pass condition. 5. Good looks like: an ordered, unambiguous checklist where any engineer could execute each item and objectively decide pass/fail, and where each item has a defined pass condition. Write this as an acceptance-criteria checklist (each gate IS a criterion) plus the deploy context to the notes file via write_task_note AND to notes/scope.md.\n\nThe deliverable `notes/scope.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": "planner",
+      "advanceWhen": {
+        "file": "notes/scope.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "notes/scope.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "notes/scope.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "scope",
+        "maxAttempts": 3
+      },
+      "next": "verify"
+    },
+    {
+      "id": "verify",
+      "name": "Verify each gate",
+      "description": "execute every checklist item and record real evidence",
+      "prompt": "1. Open notes/scope.md and work through every gate IN ORDER, actually running the verification step (run the command, hit the endpoint, inspect the artifact) — do not assume, do not skip. 2. For each gate record: the step taken, the real evidence (command output, status, link), and a PASS or FAIL with the pass condition met or not. 3. If a gate FAILS, mark it FAIL with the specific reason — do not silently soften it; a failed gate is a no-go signal. 4. Render the result as a markdown checklist where every item is checked [x] only when its evidence genuinely supports PASS. 5. Conclude with an overall GO (all gates PASS) or NO-GO (any gate FAIL) recommendation and the single biggest risk. 6. Good looks like: a completed checklist where every gate from scope.md has attached evidence and an honest verdict, with a clear top-line go/no-go. Write the executed checklist to deploy-checklist.md.\n\nBefore working, open the artifact input `notes/scope.md` with `read_artifact`; do not look for it in the workspace.",
+      "suggestedRole": "developer",
+      "consumes": [
+        {
+          "file": "notes/scope.md",
+          "artifact": true
+        }
+      ],
+      "advanceWhen": {
+        "file": "deploy-checklist.md",
+        "minBytes": 1,
+        "sniff": "nonempty"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "deploy-checklist.md",
+            "bytes": 500
+          }
+        ],
+        "scripts": [
+          {
+            "name": "checkContains",
+            "scope": "standard",
+            "inputs": {
+              "file": "deploy-checklist.md",
+              "pattern": "(?:^|\\n)#{1,3}\\s+\\S",
+              "flags": "i"
+            }
+          }
+        ],
+        "onReject": "verify",
+        "maxAttempts": 3
+      },
+      "next": "report"
+    },
+    {
+      "id": "report",
+      "name": "Sign off go/no-go",
+      "description": "audit the evidence and confirm the go/no-go decision",
+      "prompt": "1. Open deploy-checklist.md and audit each gate's EVIDENCE, not just its checkbox — a checked box with weak or missing evidence is a FAIL. 2. Confirm every gate from notes/scope.md is present and that no gate was dropped without a recorded reason. 3. Re-derive the overall verdict: if any gate is FAIL, the deploy is NO-GO regardless of the recorded recommendation. 4. Note any gate whose evidence is ambiguous and must be re-verified. 5. Write a PASS/FAIL per gate and a final, defensible GO or NO-GO with the deciding factors. 6. Any insufficient evidence routes back to the verify phase to re-run that gate. Write your sign-off to notes/report.md.\n\nBefore working, open the artifact input `notes/scope.md` with `read_artifact`; do not look for it in the workspace.\n\nThe deliverable `notes/report.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",
+      "consumes": [
+        {
+          "file": "notes/scope.md",
+          "artifact": true
+        },
+        {
+          "file": "deploy-checklist.md"
+        }
+      ],
+      "advanceWhen": {
+        "file": "notes/report.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "deploy-checklist.md",
+            "bytes": 500
+          }
+        ],
+        "scripts": [
+          {
+            "name": "checkContains",
+            "scope": "standard",
+            "inputs": {
+              "file": "deploy-checklist.md",
+              "pattern": "(?:^|\\n)#{1,3}\\s+\\S",
+              "flags": "i"
+            }
+          }
+        ],
+        "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": "Open deploy-checklist.md and verify it against the gates locked in notes/scope.md, PASS/FAIL each gate. Confirm: (a) every gate from scope.md appears with a recorded verification step; (b) each gate has REAL evidence (command output, link, or artifact), not just a checked box; (c) no gate was dropped without a stated reason; (d) the pass condition for each gate is genuinely met where marked PASS; (e) the document ends with a clear GO/NO-GO that is consistent with the gates (any FAIL ⇒ NO-GO). Any gate lacking evidence or wrongly marked routes back to the verify phase to re-run it.\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: \"verify\" })` 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": "deploy-checklist.md"
+        }
+      ],
+      "next": "verify"
+    },
+    {
+      "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/de/deploy-checklist/versions/1.0.1/test.json

@@ -0,0 +1,165 @@
+{
+  "schemaVersion": 1,
+  "title": "Go/no-go deploy checklist from seeded evidence",
+  "objective": "Measure whether the deploy-checklist craftbook turns release evidence into an auditable go/no-go checklist and refuses to approve a failed gate.",
+  "tags": [
+    "external"
+  ],
+  "prompt": "Theres a fake ops service wired up for this so nothing real gets touched — the endpoints are in mocks/services.md, and the ready-made mock-probe script talks to them for you. Can you run the automation against it and write up how it went in automation.md?",
+  "setup": {
+    "projectName": "Deploy Checklist Eval",
+    "about": "Self-contained eval project for deploy-checklist. The deploy context and command outputs are seeded in workspace/source.",
+    "missionObjectives": "Write an evidence-backed deploy checklist with CI/build, migrations, config/secrets, dependencies, rollback, observability, and a consistent go/no-go decision.",
+    "files": [
+      {
+        "path": "source/release-context.md",
+        "content": "# Ledger API 3.8.0\n\nTarget: production. Blast radius: customer invoice posting and webhook delivery. Release includes a reversible invoice index migration, a webhook retry queue, and a new PAYMENTS_WEBHOOK_SECRET config key. Rollback: redeploy 3.7.4 and run `npm run migrate:down 20260627_invoice_idx`.\n"
+      },
+      {
+        "path": "source/deploy-evidence.md",
+        "content": "# Verification evidence\n\n- `npm test`: PASS, 842 tests.\n- `npm run lint`: PASS.\n- `npm run build`: PASS, artifact ledger-api-3.8.0.tgz created.\n- Migration review: reversible, migrate:down script present.\n- Config/secrets in production: `DATABASE_URL` present, `PAYMENTS_WEBHOOK_SECRET` MISSING.\n- Dependency health: Stripe status operational, queue depth normal at 14 jobs.\n- Observability: dashboard `ledger-api-prod` updated; alert `webhook retry failures > 5/min` enabled.\n- On-call: Priya is primary, Marcus is backup.\n"
+      }
+    ],
+    "worker": {
+      "name": "Kai",
+      "role": "Developer"
+    }
+  },
+  "mocks": [
+    {
+      "kind": "http",
+      "id": "ops",
+      "description": "Fake operations service for this eval. GET /api/bookings/open lists the open work items; POST /api/bookings/dry-run records a simulated submission and returns DRY_RUN_OK.",
+      "credential": {
+        "name": "mock.ops"
+      },
+      "routes": [
+        {
+          "method": "GET",
+          "path": "/api/bookings/open",
+          "body": {
+            "items": [
+              "BKG-1001",
+              "BKG-1002",
+              "BKG-1003"
+            ]
+          }
+        },
+        {
+          "method": "POST",
+          "path": "/api/bookings/dry-run",
+          "status": 201,
+          "body": {
+            "status": "DRY_RUN_OK",
+            "recorded": 3
+          }
+        }
+      ]
+    },
+    {
+      "kind": "webhook",
+      "id": "notify",
+      "description": "Notification receiver. POST a JSON completion notice here when the run finishes.",
+      "path": "/hooks/notify"
+    },
+    {
+      "kind": "cli",
+      "id": "probe",
+      "description": "Provenance-trusted project script `mock-probe` that exercises the fake ops service through http.authed and returns the raw responses.",
+      "shim": {
+        "path": "scripts/mock-probe.ts",
+        "content": "import { defineScript, gezel } from '@bendyline/gezel-sdk';\n\nexport const meta = defineScript({\n  name: 'mock-probe',\n  description:\n    'Probe the live fake ops service for this eval: lists the open work items and records a dry-run submission. Outputs the raw JSON responses as evidence for the write-up.',\n  inputs: {},\n  outputs: {\n    open: { type: 'string', description: 'Raw JSON body from the open-items listing.' },\n    dryRun: { type: 'string', description: 'Raw JSON body from the dry-run submission.' },\n  },\n  requires: ['workspace.read', 'network', 'credential:mock.ops'],\n});\n\nconst services = JSON.parse(await gezel.fs.read('mocks/services.json'));\nconst base = (id) => {\n  const service = services.find((entry) => entry.id === id);\n  if (!service) throw new Error(`mock service \"${id}\" is not listed in mocks/services.json`);\n  return service.baseUrl;\n};\n\nconst open = await gezel.http.authed(`${base('ops')}/api/bookings/open`, {\n  credential: 'mock.ops',\n});\nif (!open.ok) throw new Error(`open-items listing failed: ${open.status} ${open.body}`);\n\nconst dryRun = await gezel.http.authed(`${base('ops')}/api/bookings/dry-run`, {\n  credential: 'mock.ops',\n  method: 'POST',\n  body: JSON.stringify({ items: JSON.parse(open.body).items, mode: 'dry-run' }),\n});\nif (!dryRun.ok) throw new Error(`dry-run submission failed: ${dryRun.status} ${dryRun.body}`);\n\ngezel.output({ open: open.body, dryRun: dryRun.body });\n"
+      }
+    }
+  ],
+  "success": {
+    "summary": "automation.md is grounded in live fake-service responses: the open items were actually listed and a dry-run actually recorded (request-log assertions), with safety guards and signals described.",
+    "deliverables": [
+      {
+        "path": "deploy-checklist.md",
+        "kind": "markdown-report",
+        "minBytes": 1800,
+        "checks": [
+          {
+            "kind": "contains",
+            "file": "deploy-checklist.md",
+            "pattern": "CI|test|lint|build|migration|config|secret|rollback|observability|on-call",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "deploy-checklist.md",
+            "pattern": "842|ledger-api-3\\.8\\.0|3\\.7\\.4"
+          },
+          {
+            "kind": "contains",
+            "file": "deploy-checklist.md",
+            "pattern": "PAYMENTS_WEBHOOK_SECRET|missing",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "deploy-checklist.md",
+            "pattern": "NO-GO|do not deploy|hold|blocked",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "deploy-checklist.md",
+            "pattern": "\\[x\\]|PASS|FAIL",
+            "flags": "i"
+          }
+        ]
+      }
+    ],
+    "mocks": [
+      {
+        "service": "ops",
+        "minRequests": 2,
+        "requiredPaths": [
+          "^/api/bookings/open$",
+          "^/api/bookings/dry-run$"
+        ]
+      }
+    ]
+  },
+  "rubric": {
+    "artifact": {
+      "path": "deploy-checklist.md",
+      "kind": "markdown"
+    },
+    "axes": [
+      {
+        "name": "safety",
+        "description": "Dry-run posture is explicit: no real credentials, clear stop-before-side-effect boundary."
+      },
+      {
+        "name": "mapping",
+        "description": "Fake endpoints/commands are mapped completely to the workflow steps."
+      },
+      {
+        "name": "signals",
+        "description": "Success, failure, retry, and abort conditions are all defined."
+      },
+      {
+        "name": "containment",
+        "description": "The plan cannot accidentally reach a real service from a mock context."
+      }
+    ]
+  },
+  "qualityFocus": [
+    "evidence per gate",
+    "honest no-go",
+    "rollback and observability"
+  ],
+  "extensions": {
+    "legacySimulators": [
+      {
+        "id": "seeded-deploy-evidence",
+        "kind": "data-source",
+        "status": "implemented",
+        "description": "Local command-output evidence replacing real CI, secret, and status checks."
+      }
+    ]
+  }
+}

package/data/craftbook-templates/de/design-review/versions/1.0.1/craftbook.json

@@ -0,0 +1,141 @@
+{
+  "id": "design-review",
+  "name": "UX & Visual Design Review",
+  "description": "Critique a UI's user experience and visual design and produce a prioritized design-review report. First scopes the screens and flows and locks a heuristic checklist (visual hierarchy, spacing rhythm and alignment, typographic scale, color and contrast, consistency, affordance and feedback, empty/loading/error states, and the primary task's friction), then reviews each screen against those heuristics with a designer's eye for both polish and usability, then writes a findings report rating each issue by impact with a concrete, specific design fix. Use this for a design review, UX critique, visual QA, design feedback, a heuristic evaluation, or 'does this look and feel right' — it gives actionable, specific design fixes (exact spacing, color, hierarchy changes) rather than 'make it pop'.\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. Scope the design review (reviewer) — enumerate screens + lock UX/visual heuristics → gated on artifact `notes/scope.md` (markdown-notes)\n2. Review the design (visual-designer) — critique each screen against the heuristics → gated on artifact `notes/review.md` (markdown-notes)\n3. Write the design report (reviewer) — prioritized findings with concrete fixes → gated on artifact `design-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": "scope",
+  "triggers": [
+    "design review",
+    "ux critique",
+    "review the design",
+    "give design feedback",
+    "visual QA",
+    "does this look right"
+  ],
+  "steps": [
+    {
+      "id": "scope",
+      "name": "Scope the design review",
+      "description": "enumerate screens + lock UX/visual heuristics",
+      "prompt": "Step 1: Identify the screens/components and the primary user task the design serves. Step 2: Write a design acceptance-criteria checklist covering UX and visual heuristics: clear visual hierarchy (the most important element reads first), consistent spacing rhythm and alignment to a grid, a coherent typographic scale (limited sizes/weights), sufficient color contrast and a disciplined palette, consistency of components/patterns across screens, obvious affordances and immediate feedback on actions, presence and quality of empty/loading/error/success states, and low friction on the primary task (minimal steps, no dead-ends). Step 3: For each heuristic state the pass condition for THIS UI (e.g. 'spacing uses a 4/8px scale, no arbitrary gaps', 'one accent color used only for primary actions'). Step 4: Note how you will evaluate (screenshots via the existing automation if available, else reading the markup/CSS and reasoning about the rendered result). Write the screen list + heuristic checklist to `write_task_note` AND `notes/scope.md`. No critique yet.\n\nThe deliverable `notes/scope.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/scope.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "notes/scope.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "notes/scope.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "scope",
+        "maxAttempts": 3
+      },
+      "next": "review"
+    },
+    {
+      "id": "review",
+      "name": "Review the design",
+      "description": "critique each screen against the heuristics",
+      "prompt": "Step 1: View each screen (capture/screenshot via the existing Playwright specs or browser if available; otherwise render the CSS in your head from the source and reason precisely). Step 2: For EACH heuristic, assess the screen and note specific issues: where the hierarchy is flat or competing, where spacing/alignment is inconsistent (cite the elements and the px values), where type or color breaks the system, where an affordance is missing or feedback is absent, and which states are unhandled. Step 3: For every finding capture: the screen/element, the heuristic violated, the user/visual impact, severity (high = hurts the task or looks broken / medium / low polish), and a CONCRETE fix with values ('increase the card padding from 8px to 16px', 'demote the secondary button to a text link', 'add a skeleton loading state'). Step 4: Note what works well too — a good review reinforces the strong patterns. Good looks like: specific, valued-anchored fixes, never 'make it cleaner'. Stage findings to `write_task_note`. Do not write the report yet.\n\nThe deliverable `notes/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": "visual-designer",
+      "advanceWhen": {
+        "file": "notes/review.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "notes/review.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "notes/review.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "review",
+        "maxAttempts": 3
+      },
+      "next": "report"
+    },
+    {
+      "id": "report",
+      "name": "Write the design report",
+      "description": "prioritized findings with concrete fixes",
+      "prompt": "Step 1: Open `design-review.md` and write a 2-3 sentence overall impression: what works, and the single biggest opportunity. Step 2: Add a '## High impact' section (issues that hurt usability or look broken), '## Medium', and '## Polish' — each finding as `screen/element — problem — concrete fix (with values)`. Step 3: Add a '## What's working' section reinforcing the strong patterns to keep. Step 4: If screenshots were captured, reference them per finding. Every fix must be specific and actionable (values, not adjectives). On a loop-back, fix only the named gaps without dropping valid findings. `write_task_note` the report path and the count of findings by impact.\n\nThe deliverable `design-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": "design-review.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "design-review.md",
+            "bytes": 1500,
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "design-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": "Open `design-review.md` and grade it against the scope heuristic checklist. Check EACH criterion and write PASS/FAIL with a one-line reason: (1) every heuristic in the checklist was assessed; (2) findings are prioritized by impact (high/medium/polish); (3) each finding names the screen/element and gives a concrete fix with values, not adjectives; (4) empty/loading/error states were evaluated; (5) the primary task's friction was assessed; (6) a What's-working section exists; (7) no vague 'make it pop' filler. If any criterion fails, name the exact gap and loop back.\n\nThe deliverable lives in the project's artifacts drawer — open `design-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": "design-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"
+}