@bendyline/gilde 0.1.27 → 0.1.28

package/data/craftbook-templates/ci/ci-pipeline/versions/1.0.1/test.json

@@ -0,0 +1,162 @@
+{
+  "schemaVersion": 1,
+  "title": "CI Pipeline from Scratch smoke eval",
+  "objective": "Self-contained smoke eval for the CI Pipeline from Scratch craftbook using the external generic harness.",
+  "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": "CI Pipeline from Scratch Eval",
+    "about": "Self-contained eval project for ci-pipeline. Seeded inputs are under workspace/source or workspace/fixtures; final deliverable is workspace/automation.md.",
+    "missionObjectives": "Use the CI Pipeline from Scratch craftbook/template, read the seeded local fixtures, and write automation.md without network calls, real credentials, or live services.",
+    "files": [
+      {
+        "path": "source/brief.md",
+        "content": "# CI Pipeline from Scratch Eval Brief\n\nClient: Boreal Desk, a home-office accessories company.\nAudience: operations leads who need an artifact they can use this week.\n\nFixed source facts for grounding:\n- The returns desk pilot covered 18 SKUs.\n- Median first response improved from 18 hours to 6 hours.\n- Preventable refund leakage fell from 14.2% to 8.9%.\n- The top unresolved complaint is status silence after photo submission.\n- Required next actions are automated status emails, barcode-exception training, and a weekly Finance exception export.\n\nUse these facts when the task asks for prose, analysis, copy, UI content, or test data. Do not use live web services, real credentials, or current outside data.\n\nCraftbook under test: ci-pipeline - CI Pipeline from Scratch.\n"
+      }
+    ],
+    "worker": {
+      "name": "Jules",
+      "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": "automation.md",
+        "kind": "markdown-report",
+        "minBytes": 900,
+        "checks": [
+          {
+            "kind": "contains",
+            "file": "automation.md",
+            "pattern": "(?:^|\\n)#{1,3}\\s+\\S",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "automation.md",
+            "pattern": "DRY_RUN_OK|dry-run|dry run",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "automation.md",
+            "pattern": "fake-ci|fake-github|/api/bookings",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "automation.md",
+            "pattern": "no real|credentials|safety|guard",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "automation.md",
+            "pattern": "success|failure|retry|abort",
+            "flags": "i"
+          }
+        ]
+      }
+    ],
+    "mocks": [
+      {
+        "service": "ops",
+        "minRequests": 2,
+        "requiredPaths": [
+          "^/api/bookings/open$",
+          "^/api/bookings/dry-run$"
+        ]
+      }
+    ]
+  },
+  "rubric": {
+    "artifact": {
+      "path": "automation.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": [
+    "dry-run safety",
+    "fake tool mapping",
+    "side-effect containment"
+  ],
+  "extensions": {
+    "legacySimulators": [
+      {
+        "id": "ci-pipeline-fake-service-fixture",
+        "kind": "data-source",
+        "status": "implemented",
+        "description": "Seeded local fake service contract replacing live CLIs, HTTP APIs, credentials, and side effects."
+      }
+    ]
+  }
+}

package/data/craftbook-templates/ci/citation-audit/versions/1.0.1/craftbook.json

@@ -0,0 +1,146 @@
+{
+  "id": "citation-audit",
+  "name": "Citation Audit",
+  "description": "Audit an existing document's claims against its citations and report every mismatch: a reviewer pairs each cited claim with the citation it depends on and locks the audit rubric, a researcher opens each cited source and verifies the claim is actually supported, and a reviewer compiles a per-citation audit report with verdicts and fixes. The ordering matters because auditing without first pairing claims to citations misses unsupported claims, and a report without a fixed verdict scale is inconsistent; building the claim-citation pairing and rubric first makes the audit exhaustive and the report actionable. Use this for checking that citations support their claims, source-verification of a draft, catching citation drift or unsupported statements, and 'do these references actually back up the text' reviews.\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 audit (reviewer) — pair each cited claim to its citation + lock the rubric → gated on artifact `notes/scope.md` (markdown-notes)\n2. Verify each citation (researcher) — open each source, confirm it backs the paired claim → gated on artifact `notes/verify.md` (markdown-notes)\n3. Compile the audit report (reviewer) — per-citation verdicts, justifying quotes, and fixes → gated on artifact `audit.md` (markdown-report)\n\nSource discipline:\n\n- Audit only claims that appear in the supplied draft or source bundle.\n- Keep the draft's citation labels verbatim, such as `Claim [A]`, so each verdict is traceable.\n- Treat uncited factual sentences in the draft as `Uncited-Claim`; do not create new claims to make the report longer.\n- If a source excerpt is missing or contradicts the draft, say that directly and propose a correction or citation fix.\n\nThe gates never advance with an unmet criterion, and loop back to the\nowning phase to fix named gaps.\n",
+  "entryStepId": "scope",
+  "triggers": [
+    "audit the citations",
+    "check citations support the claims",
+    "verify the references in this doc",
+    "citation accuracy check",
+    "are these sources legit"
+  ],
+  "steps": [
+    {
+      "id": "scope",
+      "name": "Scope the audit",
+      "description": "pair each cited claim to its citation + lock the rubric",
+      "prompt": "1. Read the target document and build a pairing table in notes/scope.md: for every inline citation, record a pair id (P1, P2, ...), the exact claim sentence it supports, and the citation/reference it points to. 2. Also flag every factual claim that has NO citation as a candidate (these are audit findings too). 3. Lock the verdict rubric: Supported (source clearly backs the claim), Partially-Supported (source backs part / overstates), Not-Supported (source does not back it), Source-Missing/Dead (citation cannot be located), Uncited-Claim. 4. Write an acceptance-criteria checklist (e.g. 'every inline citation is paired and audited', 'uncited factual claims are listed', 'each pair gets exactly one verdict from the rubric', 'each Not-Supported/Partial verdict quotes the source to justify it', 'a fix is proposed per problem'). 5. Record decisions. Call write_task_note with the pairing table + rubric + checklist; write the same 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": "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": "verify"
+    },
+    {
+      "id": "verify",
+      "name": "Verify each citation",
+      "description": "open each source, confirm it backs the paired claim",
+      "prompt": "1. For each pair id, locate and open the cited source and read the relevant part. 2. Log to notes/verify.md: the pair id, whether the source was reachable, the exact passage/figure the claim relies on (quote it), and a proposed verdict from the locked rubric with a one-line reason. 3. Be strict: a source on the right topic that does not actually state the specific claim is Not-Supported, not Supported. 4. For dead or unfindable citations, record Source-Missing/Dead and what you searched. 5. For each problem, draft a concrete fix (correct the claim, swap the source, or add a citation). Good looks like a verify log where every pair's verdict is justified by a quote. Do not write the final report yet.\n\nThe deliverable `notes/verify.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": "researcher",
+      "advanceWhen": {
+        "file": "notes/verify.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "notes/verify.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "notes/verify.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "verify",
+        "maxAttempts": 3
+      },
+      "next": "report"
+    },
+    {
+      "id": "report",
+      "name": "Compile the audit report",
+      "description": "per-citation verdicts, justifying quotes, and fixes",
+      "prompt": "1. Write audit.md with a summary (counts per verdict, and the count of uncited claims) then one entry per pair id: the claim, the citation, the verdict from the rubric, the justifying quote from the source, and the proposed fix for any non-Supported verdict. 2. Add a dedicated 'Uncited claims' section listing factual statements that lack a citation. 3. Use ONLY rubric verdicts and base each strictly on notes/verify.md. 4. Make it actionable — an editor should be able to apply every fix directly. 5. On a loop-back, fix only the named gaps. 6. Call write_task_note with the report path and which criteria now pass.\n\nBefore working, open the artifact input `notes/verify.md` with `read_artifact`; do not look for it in the workspace.\n\nThe deliverable `audit.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/verify.md",
+          "artifact": true
+        }
+      ],
+      "advanceWhen": {
+        "file": "audit.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "audit.md",
+            "bytes": 1500,
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "audit.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 audit.md and check EACH criterion PASS/FAIL: (1) every citation paired in notes/scope.md has an audited entry — none skipped; (2) an uncited-claims section lists statements lacking citations; (3) each entry has exactly one rubric verdict; (4) every Not-Supported/Partially-Supported/Dead verdict is justified by a quoted source passage (spot-check 3 against notes/verify.md); (5) each problem has a concrete, applicable fix; (6) the summary counts match the entries. A report that marks a topically-related-but-non-supporting source as Supported, or skips a citation, FAILS.\n\nThe deliverable lives in the project's artifacts drawer — open `audit.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": "audit.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/ci/citation-audit/versions/1.0.1/test.json

@@ -0,0 +1,149 @@
+{
+  "schemaVersion": 1,
+  "title": "Citation audit over seeded draft and source excerpts",
+  "objective": "Measure whether the citation-audit craftbook pairs claims to citations and reports supported, partial, unsupported, dead, and uncited claims.",
+  "tags": [
+    "corpus"
+  ],
+  "prompt": "In the `Citation Audit Eval` project, read only `source/draft.md` and `source/source-excerpts.md`, then write `audit.md`. Audit exactly the four cited claims `Claim [A]` through `Claim [D]`, plus the uncited sentence about Finance receiving a weekly exception export. Do not add Claim [E], Claim [F], outside company metrics, or imagined source sections. Use verdicts Supported, Not-Supported, Source-Missing/Dead, and Uncited-Claim, with source quotes and concrete fixes.",
+  "setup": {
+    "projectName": "Citation Audit Eval",
+    "about": "Self-contained eval project for citation-audit. Draft and source excerpts are seeded under workspace/source.",
+    "missionObjectives": "Audit every citation and uncited factual claim with strict verdicts, quotes from source excerpts, and concrete fixes.",
+    "files": [
+      {
+        "path": "source/draft.md",
+        "content": "# Draft\n\nGuided returns intake reduced median first response from 18 hours to 6 hours [A]. The pilot covered every SKU in the catalog [B]. Customers were 34% more satisfied after photo evidence was required [C]. Finance now receives a weekly exception export. Warehouse teams need barcode exception training before national rollout [D].\n"
+      },
+      {
+        "path": "source/source-excerpts.md",
+        "content": "# Source excerpts\n\n[A] Pilot dashboard: median first response improved from 18 hours to 6 hours for the 18 pilot SKUs.\n[B] Rollout memo: March pilot covered 18 home-office accessory SKUs, not the full catalog.\n[C] Source missing: no satisfaction survey was run during the pilot.\n[D] Operations notes: warehouse teams need barcode exception training before national rollout.\n"
+      }
+    ],
+    "worker": {
+      "name": "Iris",
+      "role": "Reviewer"
+    }
+  },
+  "mocks": [],
+  "success": {
+    "summary": "workspace/audit.md audits all seeded citations and uncited claims with rubric verdicts, source quotes, counts, and fixes.",
+    "deliverables": [
+      {
+        "path": "audit.md",
+        "kind": "markdown-report",
+        "minBytes": 1200,
+        "checks": [
+          {
+            "kind": "contains",
+            "file": "audit.md",
+            "pattern": "(?:^|\\n)#{1,3}\\s+\\S",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "audit.md",
+            "pattern": "Supported|Partially-Supported|Not-Supported|Source-Missing|Uncited-Claim",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "audit.md",
+            "pattern": "\\[A\\]|\\[B\\]|\\[C\\]|\\[D\\]",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "audit.md",
+            "pattern": "Claim \\[A\\][\\s\\S]{0,500}Supported",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "audit.md",
+            "pattern": "Claim \\[B\\][\\s\\S]{0,500}Not-Supported",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "audit.md",
+            "pattern": "Claim \\[C\\][\\s\\S]{0,500}Source-Missing|Claim \\[C\\][\\s\\S]{0,500}Dead",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "audit.md",
+            "pattern": "Claim \\[D\\][\\s\\S]{0,500}Supported",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "audit.md",
+            "pattern": "Finance[\\s\\S]{0,500}Uncited-Claim|Uncited-Claim[\\s\\S]{0,500}Finance",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "audit.md",
+            "pattern": "18\\s*hours|6\\s*hours|18 home-office accessory SKUs|full catalog",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "audit.md",
+            "pattern": "34%|satisfaction survey",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "audit.md",
+            "pattern": "Finance|weekly exception export",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "audit.md",
+            "pattern": "fix|correction|replace|add a citation",
+            "flags": "i"
+          },
+          {
+            "kind": "notContains",
+            "file": "audit.md",
+            "pattern": "Claim \\[E\\]|Claim \\[F\\]|cost per return|50 concurrent|RESTful API|Q3|stress tests|Financial summary|System architecture|expansion of this report",
+            "flags": "i",
+            "label": "do not invent audit claims or source excerpts beyond the seeded draft"
+          }
+        ]
+      }
+    ]
+  },
+  "rubric": {
+    "artifact": {
+      "path": "audit.md",
+      "kind": "markdown"
+    },
+    "axes": [
+      {
+        "name": "grounding",
+        "description": "Seeded facts appear faithfully and the source is cited."
+      },
+      {
+        "name": "structure",
+        "description": "Sections progress logically for the artifact class."
+      },
+      {
+        "name": "completeness",
+        "description": "Required elements (risks, next actions, scope) are all present."
+      },
+      {
+        "name": "tone",
+        "description": "The register fits the audience and artifact class."
+      }
+    ]
+  },
+  "qualityFocus": [
+    "claim-citation pairing",
+    "strict verdicts",
+    "actionable fixes"
+  ]
+}

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

@@ -0,0 +1,147 @@
+{
+  "id": "cli-tool",
+  "name": "Command-Line Tool",
+  "description": "Build a command-line tool with subcommands, flags, arguments, help text, and proper exit codes. Designs the CLI UX FIRST — the command surface, flags with defaults, positional args, help/usage output, and exit-code conventions — because a CLI's contract is its interface, then implements argument parsing and command logic, then writes tests for parsing, help, happy paths, and error exits. Covers argv parsing, subcommands, --flags and -short forms, --help, stdin/stdout/stderr conventions, and non-zero exit codes on error.\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. CLI UX scope (planner) — lock the command surface, flags, args, exit codes → gated on artifact `notes/ux-scope.md` (markdown-notes)\n2. Build the CLI (developer) — implement parsing + command logic → gated on `src/cli.js` (code-module)\n3. Write CLI tests (developer) — test parsing, help, happy paths, error exits → gated on `src/cli.test.js` (code-with-tests)\n\nThe gates never advance with an unmet criterion, and loop back to the\nowning phase to fix named gaps.\n",
+  "entryStepId": "ux-scope",
+  "triggers": [
+    "build a cli tool",
+    "command line tool",
+    "make a terminal command",
+    "cli with subcommands",
+    "argv parser"
+  ],
+  "steps": [
+    {
+      "id": "ux-scope",
+      "name": "CLI UX scope",
+      "description": "lock the command surface, flags, args, exit codes",
+      "prompt": "Design the command-line interface before any logic — the interface IS the contract. Step 1: Enumerate the commands/subcommands and what each does. Step 2: For each, list the positional arguments (required vs optional) and the flags (`--long`, `-s` short form, type, default value, whether it takes a value). Step 3: Draft the exact `--help`/usage text the tool prints, including a one-line synopsis per command. Step 4: Define the IO and exit-code contract: what goes to stdout vs stderr, exit 0 on success, distinct non-zero codes for usage errors vs runtime errors. Step 5: Write a numbered acceptance-criteria checklist of 5-9 items (e.g. 'running with no args or --help prints usage and exits 0', 'an unknown flag prints an error to stderr and exits non-zero', 'the primary command produces the documented output'). `write_task_note` the command spec + checklist and write the same to the produces path. No implementation yet.\n\nThe deliverable `notes/ux-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/ux-scope.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "notes/ux-scope.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "notes/ux-scope.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "ux-scope",
+        "maxAttempts": 3
+      },
+      "next": "build"
+    },
+    {
+      "id": "build",
+      "name": "Build the CLI",
+      "description": "implement parsing + command logic",
+      "prompt": "Implement the CLI in a single runnable source file with a real entry point. Step 1: Parse argv into commands, positional args, and flags exactly as scoped — support both long and short flag forms and apply defaults. Step 2: Implement each command's logic; write normal output to stdout and diagnostics/errors to stderr. Step 3: Wire `--help` (and bare invocation) to print the usage text and exit 0; on unknown command/flag or missing required arg, print a clear error to stderr and exit non-zero. Step 4: Ensure the process exits with the documented code in every path. On a loop-back, fix only the named gaps without regressing working commands. `write_task_note` the file path and which criteria now pass.",
+      "suggestedRole": "developer",
+      "advanceWhen": {
+        "file": "src/cli.js",
+        "minBytes": 1,
+        "sniff": "nonempty"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "src/cli.js",
+            "bytes": 200
+          },
+          {
+            "kind": "sniff",
+            "file": "src/cli.js",
+            "sniff": "nonempty"
+          },
+          {
+            "kind": "esmImports",
+            "file": "src/cli.js"
+          },
+          {
+            "kind": "sourceParses",
+            "file": "src/cli.js"
+          }
+        ],
+        "onReject": "build",
+        "maxAttempts": 3
+      },
+      "next": "test"
+    },
+    {
+      "id": "test",
+      "name": "Write CLI tests",
+      "description": "test parsing, help, happy paths, error exits",
+      "prompt": "Write tests that invoke the CLI and inspect output + exit code. Step 1: Assert `--help` and bare invocation print usage and exit 0. Step 2: Assert each command's happy path produces the documented stdout and exits 0. Step 3: Assert error cases (unknown flag, missing required arg, bad value) print to stderr and exit non-zero with the right code. Step 4: Assert flag parsing handles long form, short form, and defaults. Capture stdout/stderr separately. `write_task_note` the test file path and pass/fail count.",
+      "suggestedRole": "developer",
+      "advanceWhen": {
+        "file": "src/cli.test.js",
+        "minBytes": 1,
+        "sniff": "nonempty"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "src/cli.js",
+            "bytes": 200
+          },
+          {
+            "kind": "sniff",
+            "file": "src/cli.js",
+            "sniff": "nonempty"
+          },
+          {
+            "kind": "esmImports",
+            "file": "src/cli.js"
+          },
+          {
+            "kind": "sourceParses",
+            "file": "src/cli.js"
+          }
+        ],
+        "onReject": "test",
+        "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": "Run the tests and invoke the CLI directly. For EACH acceptance criterion: confirm --help/usage works and exits 0, confirm each command's output matches the spec, confirm errors go to stderr with a non-zero exit, and confirm flag parsing (long, short, defaults) works. Write PASS/FAIL per criterion.\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: \"build\" })` 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": "src/cli.js"
+        }
+      ],
+      "next": "build"
+    },
+    {
+      "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.1.1",
+  "releasedAt": "2026-08-14T00:00:00Z"
+}