@bendyline/gilde 0.1.27 → 0.1.28

package/data/craftbook-templates/li/library-package/versions/1.0.1/craftbook.json

@@ -0,0 +1,147 @@
+{
+  "id": "library-package",
+  "name": "Reusable Library Package",
+  "description": "Build a reusable library/SDK with a clean public API surface, sensible defaults, and published documentation. Designs the public API FIRST — exported functions/classes, signatures, types, error contract, and what stays internal — because a library's API is a long-lived promise, then implements it, then writes user-facing docs with installation, quickstart, and a worked example per public function. Covers public-vs-private surface, function signatures, JSDoc/typedoc, README, semantic versioning posture, and usage examples.\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. Public API design (planner) — lock exports, signatures, types, error contract → gated on artifact `notes/api-design.md` (markdown-notes)\n2. Build the library (developer) — implement the public API + internals → gated on `src/index.js` (code-module)\n3. Write the docs (copywriter) — README with install, quickstart, per-function examples → gated on `README.md` (markdown-doc)\n\nThe gates never advance with an unmet criterion, and loop back to the\nowning phase to fix named gaps.\n",
+  "entryStepId": "api-design",
+  "triggers": [
+    "build a library",
+    "create an sdk",
+    "make a reusable package",
+    "publish a module",
+    "library with a public api"
+  ],
+  "steps": [
+    {
+      "id": "api-design",
+      "name": "Public API design",
+      "description": "lock exports, signatures, types, error contract",
+      "prompt": "Design the public API surface before implementation — it is a long-lived promise to callers. Step 1: List exactly what the library exports (functions, classes, constants) and what stays internal. Step 2: For each export, write its full signature: parameter names, types, defaults, and return type. Step 3: Define the error contract — what each function throws or returns on bad input/failure, and any shared error type. Step 4: Decide naming, module layout, and the minimal surface (resist over-exporting). Step 5: Write a numbered acceptance-criteria checklist of 5-9 items (e.g. 'every documented export exists with the documented signature', 'invalid input is rejected per the error contract', 'no internal helper leaks into the public surface'). `write_task_note` the API spec + checklist and write the same to the produces path. No implementation yet.\n\nThe deliverable `notes/api-design.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/api-design.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "notes/api-design.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "notes/api-design.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "api-design",
+        "maxAttempts": 3
+      },
+      "next": "build"
+    },
+    {
+      "id": "build",
+      "name": "Build the library",
+      "description": "implement the public API + internals",
+      "prompt": "Implement the library in a source module exporting exactly the designed surface. Step 1: Implement every public export with the locked signature and behavior; keep helpers unexported. Step 2: Validate inputs and honor the error contract precisely. Step 3: Add inline doc comments (JSDoc/TSDoc) on each public export describing params, return, and throws. Step 4: Include a few assertions or a small example to self-verify the happy paths. On a loop-back, fix only the named gaps without changing the public signatures unless the design changed. `write_task_note` the file path and which criteria now pass.",
+      "suggestedRole": "developer",
+      "advanceWhen": {
+        "file": "src/index.js",
+        "minBytes": 1,
+        "sniff": "nonempty"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "src/index.js",
+            "bytes": 200
+          },
+          {
+            "kind": "sniff",
+            "file": "src/index.js",
+            "sniff": "nonempty"
+          },
+          {
+            "kind": "esmImports",
+            "file": "src/index.js"
+          },
+          {
+            "kind": "sourceParses",
+            "file": "src/index.js"
+          }
+        ],
+        "onReject": "build",
+        "maxAttempts": 3
+      },
+      "next": "docs"
+    },
+    {
+      "id": "docs",
+      "name": "Write the docs",
+      "description": "README with install, quickstart, per-function examples",
+      "prompt": "Write the user-facing documentation as a README. Step 1: Open with a one-paragraph what-and-why and an install line. Step 2: Add a quickstart: the smallest runnable example that produces a result. Step 3: Document EVERY public export with its signature, a one-line description, and a short worked code example. Step 4: Add an errors/edge-cases section matching the error contract, and a versioning note. Examples must match the real signatures exactly — copy them from the API spec, do not invent parameters. `write_task_note` the README path.",
+      "suggestedRole": "copywriter",
+      "advanceWhen": {
+        "file": "README.md",
+        "minBytes": 1,
+        "sniff": "nonempty"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "src/index.js",
+            "bytes": 200
+          },
+          {
+            "kind": "sniff",
+            "file": "src/index.js",
+            "sniff": "nonempty"
+          },
+          {
+            "kind": "esmImports",
+            "file": "src/index.js"
+          },
+          {
+            "kind": "sourceParses",
+            "file": "src/index.js"
+          }
+        ],
+        "onReject": "docs",
+        "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": "Check the library against the API spec and the docs against the library. For EACH acceptance criterion: confirm every documented export exists with the exact signature, confirm inputs are validated per the error contract, confirm no internal helper leaked, and confirm every README example matches a real signature and would run. Write PASS/FAIL per criterion. If the docs reference a function/parameter the code does not have, that is a FAIL.\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/index.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.0.1",
+  "releasedAt": "2026-08-14T00:00:00Z"
+}

package/data/craftbook-templates/li/library-package/versions/1.0.1/test.json

@@ -0,0 +1,92 @@
+{
+  "schemaVersion": 1,
+  "title": "Reusable Library Package smoke eval",
+  "objective": "Self-contained smoke eval for the Reusable Library Package craftbook using the code generic harness.",
+  "tags": [
+    "code"
+  ],
+  "prompt": "We need a small Node helper for this — the requirments are in source/requirements.md. Put it in src/solution.mjs.",
+  "setup": {
+    "projectName": "Reusable Library Package Eval",
+    "about": "Self-contained eval project for library-package. Seeded inputs are under workspace/source or workspace/fixtures; final deliverable is workspace/src/solution.mjs.",
+    "missionObjectives": "Use the Reusable Library Package craftbook/template, read the seeded local fixtures, and write src/solution.mjs without network calls, real credentials, or live services.",
+    "files": [
+      {
+        "path": "source/brief.md",
+        "content": "# Reusable Library Package 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: library-package - Reusable Library Package.\n"
+      },
+      {
+        "path": "source/requirements.md",
+        "content": "# Runner Requirements\n\nBuild a dependency-free Node ESM helper for Boreal Desk support operations. Export at least one function. Include a tiny self-test section using node:assert or an equivalent assertion helper. Use fixture values for 18 -> 6 hour response time and 14.2 -> 8.9 refund leakage.\n"
+      }
+    ],
+    "worker": {
+      "name": "Jules",
+      "role": "Developer"
+    }
+  },
+  "mocks": [],
+  "success": {
+    "summary": "src/solution.mjs is a local ESM module with basic self-test scaffolding.",
+    "deliverables": [
+      {
+        "path": "src/solution.mjs",
+        "kind": "code-with-tests",
+        "minBytes": 1500,
+        "checks": [
+          {
+            "kind": "esmImports",
+            "file": "src/solution.mjs"
+          },
+          {
+            "kind": "contains",
+            "file": "src/solution.mjs",
+            "pattern": "export\\s+(function|const|class)|export\\s*\\{",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "src/solution.mjs",
+            "pattern": "assert|test|describe|it|expect",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "src/solution.mjs",
+            "pattern": "18|6|14\\.2|8\\.9|Boreal",
+            "flags": "i"
+          }
+        ]
+      }
+    ]
+  },
+  "rubric": {
+    "artifact": {
+      "path": "src/solution.mjs",
+      "kind": "typescript"
+    },
+    "axes": [
+      {
+        "name": "correctness",
+        "description": "The module does what the requirements ask, with sensible edge handling."
+      },
+      {
+        "name": "verification",
+        "description": "Self-tests exercise real behavior, not trivial truths."
+      },
+      {
+        "name": "clarity",
+        "description": "Exports, naming, and structure make the module usable without reading every line."
+      },
+      {
+        "name": "robustness",
+        "description": "Invalid input and boundary cases fail loudly rather than silently."
+      }
+    ]
+  },
+  "qualityFocus": [
+    "runnable ESM",
+    "test scaffolding",
+    "local fixtures"
+  ]
+}

package/data/craftbook-templates/li/literature-review/versions/1.0.1/craftbook.json

@@ -0,0 +1,146 @@
+{
+  "id": "literature-review",
+  "name": "Literature Review",
+  "description": "Survey the existing literature on a topic and synthesize it into a structured review: a planner sets the scope, inclusion criteria, and the themes to organize around, then a researcher gathers and characterizes each source (method, finding, quality), then a copywriter synthesizes them thematically rather than source-by-source, surfacing consensus, disagreement, and gaps. The ordering matters because a review written without inclusion criteria becomes an arbitrary pile, and one written source-by-source reads like a list of summaries instead of a synthesis; locking themes and a source matrix first forces the comparative analysis that makes a real lit review. Use this for academic-style literature surveys, state-of-the-art reviews, 'what does the research say' questions, and synthesizing a body of papers or articles.\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 review (planner) — topic boundaries, inclusion criteria, organizing themes → gated on artifact `notes/scope.md` (markdown-notes)\n2. Gather & characterize sources (researcher) — build the source matrix: method, finding, quality per source → gated on artifact `notes/sources.md` (markdown-notes)\n3. Synthesize the review (copywriter) — write a thematic synthesis with consensus, conflict, gaps → gated on artifact `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": [
+    "literature review",
+    "what does the research say",
+    "survey the literature",
+    "state of the art review",
+    "summarize the papers on"
+  ],
+  "steps": [
+    {
+      "id": "scope",
+      "name": "Scope the review",
+      "description": "topic boundaries, inclusion criteria, organizing themes",
+      "prompt": "1. State the review topic and its boundaries in one sentence (what is in and out of scope). 2. Define inclusion criteria: source types accepted (peer-reviewed, official reports, etc.), recency window, and a minimum source count (aim 6+). 3. Decide 3-5 organizing themes or dimensions the review will be structured around (NOT source-by-source) plus a source-characterization matrix schema (columns like source, year, method, key finding, quality/limitation). 4. Write an acceptance-criteria checklist (e.g. 'review is organized by theme not by source', 'each source appears in the matrix with all columns filled', 'consensus vs disagreement is explicitly called out', 'a gaps/future-work section exists', 'minimum source count met'). 5. Record decisions. Call write_task_note with the themes, matrix schema, and checklist, and 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": "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": "gather"
+    },
+    {
+      "id": "gather",
+      "name": "Gather & characterize sources",
+      "description": "build the source matrix: method, finding, quality per source",
+      "prompt": "1. Find sources meeting the inclusion criteria, prioritizing seminal and recent work. 2. For each source, add a row to the matrix in notes/sources.md with every scoped column filled: citation key [n], title/author/year, method or evidence type, key finding (with the figure or claim), and a one-line quality note or limitation. 3. As you go, tag which organizing theme(s) each source speaks to so the writer can group them. 4. Note where sources agree and where they conflict on the same question. 5. Flag anything you could not verify as UNVERIFIED. Good looks like a matrix where the comparative structure of the field is already visible. Do not write the prose review yet.\n\nThe deliverable `notes/sources.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/sources.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "notes/sources.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "notes/sources.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "gather",
+        "maxAttempts": 3
+      },
+      "next": "synthesize"
+    },
+    {
+      "id": "synthesize",
+      "name": "Synthesize the review",
+      "description": "write a thematic synthesis with consensus, conflict, gaps",
+      "prompt": "1. Write review.md organized by the locked themes (one section per theme), NOT one section per source. 2. In each theme, synthesize across sources: state what is established, cite the supporting sources [n], then explicitly note where sources disagree and why. 3. Open with an introduction framing the topic and scope, and close with a 'Gaps & future directions' section. 4. Add a numbered References list built from notes/sources.md so every [n] resolves. 5. Keep it comparative and analytical, not a chain of one-paragraph summaries. 6. On a loop-back, fix only the named gaps. 7. Call write_task_note with the review path and which criteria now pass.\n\nBefore working, open the artifact input `notes/sources.md` with `read_artifact`; do not look for it in the workspace.\n\nThe deliverable `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": "copywriter",
+      "consumes": [
+        {
+          "file": "notes/sources.md",
+          "artifact": true
+        }
+      ],
+      "advanceWhen": {
+        "file": "review.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "review.md",
+            "bytes": 1500,
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "review.md",
+            "pattern": "(?:^|\\n)#{1,3}\\s+\\S",
+            "flags": "i",
+            "label": "at least one markdown heading",
+            "artifact": true
+          }
+        ],
+        "onReject": "synthesize",
+        "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 review.md and check EACH criterion PASS/FAIL: (1) the review is organized by theme, not source-by-source; (2) every source in notes/sources.md is cited and every matrix column was actually used to inform the prose; (3) consensus AND disagreement are explicitly surfaced for at least the main themes; (4) a gaps/future-work section exists; (5) the minimum source count is met and inclusion criteria respected; (6) every inline [n] resolves to the References list. A pile of per-source summaries with no synthesis FAILS even if every source is present.\n\nThe deliverable lives in the project's artifacts drawer — open `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: \"synthesize\" })` 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": "review.md",
+          "artifact": true
+        }
+      ],
+      "next": "synthesize"
+    },
+    {
+      "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/li/literature-review/versions/1.0.1/test.json

@@ -0,0 +1,110 @@
+{
+  "schemaVersion": 1,
+  "title": "Literature Review smoke eval",
+  "objective": "Self-contained smoke eval for the Literature Review craftbook using the corpus generic harness.",
+  "tags": [
+    "corpus"
+  ],
+  "prompt": "We need a literature review for the returns-desk work. The backgound info is in source/brief.md — have a look and write it up in report.md.",
+  "setup": {
+    "projectName": "Literature Review Eval",
+    "about": "Self-contained eval project for literature-review. Seeded inputs are under workspace/source or workspace/fixtures; final deliverable is workspace/report.md.",
+    "missionObjectives": "Use the Literature Review craftbook/template, read the seeded local fixtures, and write report.md without network calls, real credentials, or live services.",
+    "files": [
+      {
+        "path": "source/brief.md",
+        "content": "# Literature Review 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: literature-review - Literature Review.\n"
+      }
+    ],
+    "worker": {
+      "name": "Jules",
+      "role": "Writer"
+    }
+  },
+  "mocks": [],
+  "success": {
+    "summary": "report.md is a source-grounded markdown artifact with required facts and actions.",
+    "deliverables": [
+      {
+        "path": "report.md",
+        "kind": "markdown-report",
+        "minBytes": 1000,
+        "checks": [
+          {
+            "kind": "contains",
+            "file": "report.md",
+            "pattern": "(?:^|\\n)#{1,3}\\s+\\S",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "report.md",
+            "pattern": "source/brief\\.md|Brief",
+            "flags": "i",
+            "label": "cite or name the seeded source"
+          },
+          {
+            "kind": "contains",
+            "file": "report.md",
+            "pattern": "18\\b[\\s\\S]{0,30}\\bSKUs",
+            "flags": "i",
+            "label": "include the 18-SKU pilot scope"
+          },
+          {
+            "kind": "contains",
+            "file": "report.md",
+            "pattern": "18\\s*hours|6\\s*hours",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "report.md",
+            "pattern": "14\\.2%|8\\.9%",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "report.md",
+            "pattern": "status silence|photo submission",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "report.md",
+            "pattern": "automated status emails|barcode|Finance",
+            "flags": "i"
+          }
+        ]
+      }
+    ]
+  },
+  "rubric": {
+    "artifact": {
+      "path": "report.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": [
+    "source-grounded prose",
+    "section structure",
+    "next-action clarity"
+  ]
+}

package/data/craftbook-templates/li/live-browser-qa/versions/1.0.1/craftbook.json

@@ -0,0 +1,141 @@
+{
+  "id": "live-browser-qa",
+  "name": "Live Browser QA Pass",
+  "description": "Run a hands-on quality-assurance pass on a running web app or page by actually exercising it in a browser, then emit a defect report with reproduction steps and severity. First derives a test plan and acceptance criteria from the app's intended behavior (happy paths, edge cases, error states, responsive/console health), then drives the UI step-by-step clicking and typing through each flow while watching the console and network for errors, then writes a bug report where every defect has numbered repro steps, expected vs actual, and severity. Use this for QA, manual testing, smoke testing, exploratory testing, click-testing a build, or verifying a feature works in the real browser before shipping — it finds broken flows, console errors, and visual breakage that unit tests miss.\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. Plan the QA pass (reviewer) — enumerate flows + acceptance criteria to exercise → gated on artifact `notes/plan.md` (markdown-notes)\n2. Exercise the app (reviewer) — drive each flow in a browser, capture defects → gated on artifact `notes/exercise.md` (markdown-notes)\n3. Write the QA report (reviewer) — emit a defect report with repro + severity → gated on artifact `qa-report.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": "plan",
+  "triggers": [
+    "qa this",
+    "run a qa pass",
+    "test this in the browser",
+    "smoke test the app",
+    "click through the app",
+    "manual test the feature"
+  ],
+  "steps": [
+    {
+      "id": "plan",
+      "name": "Plan the QA pass",
+      "description": "enumerate flows + acceptance criteria to exercise",
+      "prompt": "Step 1: Identify what the app/page is supposed to do and how to reach it (URL, dev server, or open the file). Step 2: Enumerate the user flows to exercise: each happy path (e.g. 'submit the form with valid data'), the key edge cases (empty input, very long input, invalid data), and the error states (network failure, 404). Step 3: List the cross-cutting checks: no console errors on load or interaction, no broken images/links, responsive at mobile and desktop widths, keyboard operability of primary controls. Step 4: Write an acceptance-criteria checklist of 6-10 concrete, checkable behaviors, e.g. 'submitting valid data shows a success state', 'submitting empty data shows an inline validation error, not a crash', 'no red console errors during any flow'. Step 5: Note test data to use and any setup needed. Write the flow list + checklist to `write_task_note` AND `notes/plan.md`. No testing yet.\n\nThe deliverable `notes/plan.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/plan.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "notes/plan.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "notes/plan.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "plan",
+        "maxAttempts": 3
+      },
+      "next": "exercise"
+    },
+    {
+      "id": "exercise",
+      "name": "Exercise the app",
+      "description": "drive each flow in a browser, capture defects",
+      "prompt": "Step 1: Open the app (use the browser/automation capability if available — navigate, click, type, screenshot; otherwise trace the rendered DOM and JS by reading the source and reason about each interaction). Step 2: Run each planned flow step-by-step, recording the exact actions taken. Step 3: After every action, check the result against the acceptance criterion AND watch the console/network for errors or failed requests. Step 4: For every defect, capture: the flow, numbered reproduction steps, the EXPECTED result, the ACTUAL result, the severity (critical = blocks the flow / major = wrong but workaroundable / minor = cosmetic), and a screenshot or console excerpt if available. Step 5: Also record what PASSED so the report shows coverage, not just failures. Good looks like: a defect a developer can reproduce on the first try from your steps. Stage findings to `write_task_note` as you go. Do not write the final report yet.\n\nThe deliverable `notes/exercise.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/exercise.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "notes/exercise.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "notes/exercise.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "exercise",
+        "maxAttempts": 3
+      },
+      "next": "report"
+    },
+    {
+      "id": "report",
+      "name": "Write the QA report",
+      "description": "emit a defect report with repro + severity",
+      "prompt": "Step 1: Open `qa-report.md` and write a top-line verdict: Pass / Pass-with-issues / Fail, plus the count of defects by severity. Step 2: Add a '## Defects' section; for each defect write `### [SEVERITY] short title` followed by numbered repro steps, an Expected line, an Actual line, and any console/screenshot evidence. Order by severity. Step 3: Add a '## Passed' section listing the flows that worked, so coverage is visible. Step 4: Add a '## Not tested' section for anything you could not reach and why. Every defect must have reproducible steps and an expected-vs-actual — no vague 'it seems broken'. On a loop-back, fix only the named gaps without dropping verified defects. `write_task_note` the report path and the defect counts by severity.\n\nThe deliverable `qa-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",
+      "advanceWhen": {
+        "file": "qa-report.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "qa-report.md",
+            "bytes": 1500,
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "qa-report.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 `qa-report.md` and grade it against the plan checklist. Check EACH criterion and write PASS/FAIL with a one-line reason: (1) every planned flow is marked tested with a result; (2) each defect has numbered, reproducible steps; (3) each defect states Expected vs Actual; (4) each defect has a severity; (5) console/network health was actually checked, not assumed; (6) a Passed section shows coverage and a Not-tested section is honest; (7) the verdict matches the findings (no 'Pass' with an open critical). If any criterion fails, name the exact gap.\n\nThe deliverable lives in the project's artifacts drawer — open `qa-report.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": "qa-report.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"
+}