@bendyline/gilde 0.1.26 → 0.1.28

package/data/craftbook-templates/do/dockerize-app/versions/1.0.1/craftbook.json

@@ -0,0 +1,148 @@
+{
+  "id": "dockerize-app",
+  "name": "Containerize a Service",
+  "description": "Containerize an application with a production-grade Dockerfile — small, secure, reproducible, and buildable — plus the supporting files to run it. Scopes the container contract FIRST — base image, build vs runtime stages, dependencies, exposed port, entrypoint, env config, and the size/security bar — then writes the Dockerfile + .dockerignore + compose, then a reviewer confirms it builds, runs, and meets the bar. Covers multi-stage builds, slim base images, layer caching, non-root user, .dockerignore, healthchecks, EXPOSE/ENTRYPOINT, and reproducible image builds.\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 container (planner) — lock base image, stages, port, entrypoint, bar → gated on artifact `notes/scope.md` (markdown-notes)\n2. Write the Dockerfile (developer) — implement the multi-stage Dockerfile + support files → gated on `Dockerfile` (code-module)\n3. Verify the image (reviewer) — confirm it builds, runs, and meets the bar → gated on artifact `notes/verify.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": [
+    "dockerize this app",
+    "write a dockerfile",
+    "containerize a service",
+    "create a docker image",
+    "docker compose setup"
+  ],
+  "steps": [
+    {
+      "id": "scope",
+      "name": "Scope the container",
+      "description": "lock base image, stages, port, entrypoint, bar",
+      "prompt": "Scope the container before writing the Dockerfile. Step 1: Identify the runtime (language/version) and pick a slim, pinned base image. Step 2: Decide the build strategy: a multi-stage build (build deps in one stage, copy only artifacts to a slim runtime stage) and what gets copied forward. Step 3: List the dependencies to install, the port to EXPOSE, the ENTRYPOINT/CMD, and the env vars the app needs at runtime. Step 4: Set the bar: run as a non-root user, a .dockerignore that excludes junk, a healthcheck, and a rough image-size target. Step 5: Write a numbered acceptance-criteria checklist of 5-9 items (e.g. 'docker build succeeds from a clean context', 'the container starts and serves on the exposed port', 'runs as non-root', 'final image uses a multi-stage slim base'). `write_task_note` the scope + checklist and write the same to the produces path.\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": "build"
+    },
+    {
+      "id": "build",
+      "name": "Write the Dockerfile",
+      "description": "implement the multi-stage Dockerfile + support files",
+      "prompt": "Author the containerization files to the scope. Step 1: Write a multi-stage `Dockerfile` — a build stage that installs deps and builds, then a slim runtime stage that copies only the needed artifacts. Step 2: Order layers for cache efficiency (copy manifest + install deps BEFORE copying source), pin the base image, set a non-root USER, EXPOSE the port, and define ENTRYPOINT/CMD and a HEALTHCHECK. Step 3: Write a `.dockerignore` that excludes node_modules, .git, build output, and secrets. Step 4: If a service needs orchestration, add a minimal compose/run file. Step 5: Build the image and confirm it succeeds and the container starts. Write the Dockerfile to the produces path. On a loop-back, fix only the named gaps. `write_task_note` the file paths and which criteria now pass.",
+      "suggestedRole": "developer",
+      "advanceWhen": {
+        "file": "Dockerfile",
+        "minBytes": 1,
+        "sniff": "nonempty"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "Dockerfile",
+            "bytes": 200
+          },
+          {
+            "kind": "sniff",
+            "file": "Dockerfile",
+            "sniff": "nonempty"
+          },
+          {
+            "kind": "esmImports",
+            "file": "Dockerfile"
+          },
+          {
+            "kind": "sourceParses",
+            "file": "Dockerfile"
+          }
+        ],
+        "onReject": "build",
+        "maxAttempts": 3
+      },
+      "next": "verify"
+    },
+    {
+      "id": "verify",
+      "name": "Verify the image",
+      "description": "confirm it builds, runs, and meets the bar",
+      "prompt": "Verify the container build. Step 1: Build the image from a clean context and confirm the build succeeds. Step 2: Run the container and confirm it starts and serves on the exposed port (hit the healthcheck/endpoint). Step 3: Confirm the bar: multi-stage slim base, non-root user, a real .dockerignore, pinned base image, and a sane final size. Step 4: Confirm no secrets or junk were baked into the image layers. Write a verification note with the build result, run check, and size to the produces path.\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": "reviewer",
+      "advanceWhen": {
+        "file": "notes/verify.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "Dockerfile",
+            "bytes": 200
+          },
+          {
+            "kind": "sniff",
+            "file": "Dockerfile",
+            "sniff": "nonempty"
+          },
+          {
+            "kind": "esmImports",
+            "file": "Dockerfile"
+          },
+          {
+            "kind": "sourceParses",
+            "file": "Dockerfile"
+          }
+        ],
+        "onReject": "verify",
+        "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": "Build and run the image. For EACH acceptance criterion: confirm `docker build` succeeds from a clean context, confirm the container starts and serves on the exposed port, confirm it runs as non-root with a multi-stage slim base and a .dockerignore, and confirm no secrets/junk were baked in. 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": "Dockerfile"
+        }
+      ],
+      "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/do/dockerize-app/versions/1.0.1/test.json

@@ -0,0 +1,92 @@
+{
+  "schemaVersion": 1,
+  "title": "Containerize a Service smoke eval",
+  "objective": "Self-contained smoke eval for the Containerize a Service 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": "Containerize a Service Eval",
+    "about": "Self-contained eval project for dockerize-app. Seeded inputs are under workspace/source or workspace/fixtures; final deliverable is workspace/src/solution.mjs.",
+    "missionObjectives": "Use the Containerize a Service 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": "# Containerize a Service 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: dockerize-app - Containerize a Service.\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/do/docs-site/versions/1.0.1/craftbook.json

@@ -0,0 +1,143 @@
+{
+  "id": "docs-site",
+  "name": "Documentation Site",
+  "description": "Build a single-page documentation site with a sidebar table of contents, anchored sections, code blocks, and in-page navigation — the kind of reference page a library or API ships. Locks the information architecture (the section tree and ordering) first, then a readable docs visual design with good typography and code styling, then builds the HTML with working anchor links and a sticky sidebar. Getting the IA right before layout is what makes docs findable; a small model that jumps straight to HTML produces an unnavigable wall of text.\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. Information architecture (planner) — section tree, ordering, anchors → gated on artifact `notes/ia.md` (markdown-notes)\n2. Visual design (designer) — docs typography, code styling, sidebar layout → gated on artifact `notes/visual-design.md` (markdown-notes)\n3. Build (developer) — implement index.html with sidebar + anchors → gated on `index.html` (html-page)\n\nThe gates never advance with an unmet criterion, and loop back to the\nowning phase to fix named gaps.\n",
+  "entryStepId": "ia",
+  "triggers": [
+    "documentation site",
+    "docs page",
+    "api reference page",
+    "build docs",
+    "developer documentation",
+    "guide page"
+  ],
+  "steps": [
+    {
+      "id": "ia",
+      "name": "Information architecture",
+      "description": "section tree, ordering, anchors",
+      "prompt": "Design the information architecture. (1) Define the top-level sections (e.g. Overview, Install, Quickstart, API, Examples, FAQ) and any sub-sections, in a logical learning order. (2) Assign each section a stable anchor id. (3) Decide what belongs in the sidebar TOC and the nesting depth. (4) Note which sections need code blocks. (5) Write an acceptance-criteria checklist of 5-8 items, e.g. 'every sidebar link scrolls to its section', 'sections follow the locked order', 'code blocks are visually distinct', 'sidebar stays visible while scrolling on desktop', 'responsive collapse on mobile', 'no broken anchors'. Write the section tree and checklist to notes/ia.md and via write_task_note. No design or HTML yet.\n\nThe deliverable `notes/ia.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/ia.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "notes/ia.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "notes/ia.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "ia",
+        "maxAttempts": 3
+      },
+      "next": "visual-design"
+    },
+    {
+      "id": "visual-design",
+      "name": "Visual design",
+      "description": "docs typography, code styling, sidebar layout",
+      "prompt": "Design for readability. (1) Pick a content palette (hex) with strong text contrast and a max content width for comfortable line length. (2) Choose a type scale for headings/body and a monospace treatment for inline and block code (background, padding, overflow). (3) Lay out the sticky sidebar TOC and the main content column, and how they reflow on mobile (collapsible nav). (4) Specify link, active-section, and heading-anchor styles. (5) Self-contained CSS, no external assets. Write the visual spec to notes/visual-design.md and via write_task_note. No HTML yet.\n\nThe deliverable `notes/visual-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": "designer",
+      "advanceWhen": {
+        "file": "notes/visual-design.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "notes/visual-design.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "notes/visual-design.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "visual-design",
+        "maxAttempts": 3
+      },
+      "next": "build"
+    },
+    {
+      "id": "build",
+      "name": "Build",
+      "description": "implement index.html with sidebar + anchors",
+      "prompt": "Implement index.html with inline CSS/JS to the IA and visual spec. (1) Render the sidebar TOC with links to each section's anchor id. (2) Render the sections in the locked order with the right heading levels and anchor ids so links jump correctly. (3) Style code blocks distinctly with overflow handling. (4) Make the sidebar sticky on desktop and collapsible on mobile (a small JS toggle is fine); optionally highlight the active section on scroll. (5) Constrain content width; responsive at 375px and 1280px; vanilla only, no CDN. On a loop-back, fix only the named gaps without regressing passing criteria. write_task_note the path and passing criteria.",
+      "suggestedRole": "developer",
+      "advanceWhen": {
+        "file": "index.html",
+        "minBytes": 1,
+        "sniff": "html-complete"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "index.html",
+            "bytes": 800
+          },
+          {
+            "kind": "htmlLint",
+            "file": "index.html"
+          }
+        ],
+        "scripts": [
+          {
+            "name": "checkHtmlComplete",
+            "scope": "standard",
+            "inputs": {
+              "file": "index.html"
+            }
+          }
+        ],
+        "onReject": "build",
+        "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": "Evaluate the docs site. Open/render index.html, click every sidebar link, and resize to 375px and 1280px. Check EACH criterion from notes/ia.md and write PASS/FAIL with a reason: does every sidebar link scroll to its section (no broken anchors), are sections in the locked order, are code blocks distinct, does the sidebar stay visible on desktop and collapse on mobile, is line length comfortable? Any broken anchor is a FAIL — loop back to build.\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": "index.html"
+        }
+      ],
+      "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/do/docs-site/versions/1.0.1/test.json

@@ -0,0 +1,97 @@
+{
+  "schemaVersion": 1,
+  "title": "Documentation Site smoke eval",
+  "objective": "Self-contained smoke eval for the Documentation Site craftbook using the html-page generic harness.",
+  "tags": [
+    "html-page"
+  ],
+  "prompt": "Can you biuld us a little page for this? The content notes are in source/page-content.md. Save it as index.html — one file, nothing fancy needed on our end.",
+  "setup": {
+    "projectName": "Documentation Site Eval",
+    "about": "Self-contained eval project for docs-site. Seeded inputs are under workspace/source or workspace/fixtures; final deliverable is workspace/index.html.",
+    "missionObjectives": "Use the Documentation Site craftbook/template, read the seeded local fixtures, and write index.html without network calls, real credentials, or live services.",
+    "files": [
+      {
+        "path": "source/brief.md",
+        "content": "# Documentation Site 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: docs-site - Documentation Site.\n"
+      },
+      {
+        "path": "source/page-content.md",
+        "content": "# Boreal Desk Support Board\n\nBuild content around a support operations board. Required labels: Open issues, Status silence, Response time, Refund leakage, Next action. Required metric text: 18 hours to 6 hours and 14.2% to 8.9%.\n"
+      }
+    ],
+    "worker": {
+      "name": "Jules",
+      "role": "Developer"
+    }
+  },
+  "mocks": [],
+  "success": {
+    "summary": "index.html is a source-grounded self-contained HTML page/tool.",
+    "deliverables": [
+      {
+        "path": "index.html",
+        "kind": "html-page",
+        "minBytes": 3000,
+        "checks": [
+          {
+            "kind": "cssMinBytes",
+            "bytes": 650,
+            "file": "index.html"
+          },
+          {
+            "kind": "jsParses",
+            "file": "index.html"
+          },
+          {
+            "kind": "contains",
+            "file": "index.html",
+            "pattern": "Boreal|Support Board|returns",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "index.html",
+            "pattern": "18\\s*hours|6\\s*hours|14\\.2%|8\\.9%",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "index.html",
+            "pattern": "button|input|filter|tab|card|section|nav",
+            "flags": "i"
+          }
+        ]
+      }
+    ]
+  },
+  "rubric": {
+    "artifact": {
+      "path": "index.html",
+      "kind": "html"
+    },
+    "axes": [
+      {
+        "name": "structure",
+        "description": "Layout and hierarchy fit the content; sections are scannable and coherent."
+      },
+      {
+        "name": "grounding",
+        "description": "Seeded source content is used faithfully — no invented facts or dropped requirements."
+      },
+      {
+        "name": "interactivity",
+        "description": "Controls and states the page claims to offer actually work."
+      },
+      {
+        "name": "polish",
+        "description": "Styling is intentional and responsive rather than unstyled or broken."
+      }
+    ]
+  },
+  "qualityFocus": [
+    "self-contained UI",
+    "source grounding",
+    "responsive structure"
+  ]
+}

package/data/craftbook-templates/do/documentation-drift-review/versions/1.0.1/craftbook.json

@@ -0,0 +1,153 @@
+{
+  "id": "documentation-drift-review",
+  "name": "Documentation Drift Review",
+  "description": "Review project documentation against the code, configuration, commands, API surface, and shipped behavior to find stale or misleading guidance. Uses the indexed docs and source map to verify examples and references instead of proofreading in isolation, then leaves a prioritized morning report with exact doc locations, source-of-truth evidence, corrected text, owners, and a prevention plan. Use for a weekly docs-health sweep, documentation accuracy review, stale README audit, or finding runbook and API-documentation drift.\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. Inventory documentation contracts (reviewer) — map docs to the source-of-truth surfaces they claim to describe → gated on artifact `notes/docs/traceability.md` (markdown-notes)\n2. Verify documented behavior (reviewer) — check commands, examples, links, schemas, defaults, and architecture claims → gated on artifact `notes/docs/evidence.md` (markdown-notes)\n3. Write the documentation drift report (reviewer) — prioritized corrections and prevention work for morning triage → gated on artifact `documentation-drift-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": "inventory",
+  "triggers": [
+    "documentation drift review",
+    "find stale docs",
+    "weekly docs review",
+    "check docs against code",
+    "audit the readme and runbooks",
+    "nightly documentation sweep"
+  ],
+  "toolsets": [
+    {
+      "toolsetId": "builtin.code-intel",
+      "autoAllow": true,
+      "reason": "compare documented behavior with indexed symbols, configs, routes, and entrypoints"
+    },
+    {
+      "toolsetId": "builtin.code-execution",
+      "autoAllow": true,
+      "reason": "safely verify documented package commands and examples when available"
+    }
+  ],
+  "steps": [
+    {
+      "id": "inventory",
+      "name": "Inventory documentation contracts",
+      "description": "map docs to the source-of-truth surfaces they claim to describe",
+      "prompt": "Call `map_repo`, `list_file_issues`, and `search_code` to inventory user/admin/developer docs: README and setup guides, API references, CLI help/examples, configuration/environment-variable docs, architecture/decision docs, runbooks, migration/release guides, and inline examples. Build a traceability matrix mapping each important claim to its source of truth (package script, schema, route, exported symbol, config default, CLI definition, or runtime behavior). Prioritize high-harm docs used during install, deploy, recovery, security, and API integration. Record index coverage, generated docs that should not be hand-edited, and the verification plan in `notes/docs/traceability.md`.\n\nThe deliverable `notes/docs/traceability.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/docs/traceability.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "notes/docs/traceability.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "notes/docs/traceability.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "inventory",
+        "maxAttempts": 3
+      },
+      "next": "verify"
+    },
+    {
+      "id": "verify",
+      "name": "Verify documented behavior",
+      "description": "check commands, examples, links, schemas, defaults, and architecture claims",
+      "prompt": "Verify the high-priority claims against real source. Use `outline_file`/`read_symbol` for definitions and `find_references`/`search_code` for renamed concepts. Compare documented commands to package scripts/CLI help, env vars and defaults to schemas/config readers, API examples to route schemas and status codes, file paths to the workspace, and architecture statements to current dependencies/entrypoints. Run safe documented commands or examples when practical and capture exit codes; otherwise mark them statically verified or not verified. Check internal links and code/file references. For each confirmed drift item record doc file:line, exact stale claim, source-of-truth file:line or command evidence, reader impact, severity, corrected wording, and likely owner. Record true positives, false positives, and verified-current docs in `notes/docs/evidence.md`.\n\nThe deliverable `notes/docs/evidence.md` lands in the project's artifacts drawer — write it with `write_artifact` and read it back with `read_artifact`; the shipped workspace stays untouched.",
+      "suggestedRole": "reviewer",
+      "advanceWhen": {
+        "file": "notes/docs/evidence.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "notes/docs/evidence.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "notes/docs/evidence.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "verify",
+        "maxAttempts": 3
+      },
+      "next": "report"
+    },
+    {
+      "id": "report",
+      "name": "Write the documentation drift report",
+      "description": "prioritized corrections and prevention work for morning triage",
+      "prompt": "Write `documentation-drift-review.md` with `## Verdict`, `## Coverage`, `## Drift findings`, `## Verified current`, `## Not verified`, `## Corrections by owner`, and `## Prevention`. Every finding must cite the doc file:line and source-of-truth evidence, explain the reader harm, and include corrected text or an exact update. Rank broken install/deploy/recovery/security/API guidance above tone or grammar. Distinguish stale docs from missing docs and generated docs. Recommend durable prevention such as tested snippets, generated reference sections, link checks, or ownership near source—only where it addresses an observed class of drift. On a loop-back, repair only named gaps.\n\nThe deliverable `documentation-drift-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": "documentation-drift-review.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "documentation-drift-review.md",
+            "bytes": 1800,
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "documentation-drift-review.md",
+            "pattern": "(?:^|\\n)#{1,3}\\s+\\S",
+            "flags": "i",
+            "label": "at least one markdown heading",
+            "artifact": true
+          }
+        ],
+        "onReject": "report",
+        "maxAttempts": 4
+      },
+      "next": "evaluate"
+    },
+    {
+      "id": "evaluate",
+      "name": "Evaluate",
+      "description": "Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.",
+      "prompt": "Grade `documentation-drift-review.md`: (1) high-harm doc classes are covered; (2) every drift finding cites doc file:line plus source-of-truth file:line or command evidence; (3) commands, examples, links, API/config/default claims, and architecture references were checked where relevant; (4) findings include reader impact and exact corrected text; (5) stale, missing, generated, verified-current, and not-verified docs are distinguished; (6) ownership and priority are actionable; (7) prevention recommendations address observed drift patterns. PASS all or loop back.\n\nThe deliverable lives in the project's artifacts drawer — open `documentation-drift-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": "documentation-drift-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"
+}