@bendyline/gilde 0.1.37 → 0.1.39

package/data/craftbook-templates/te/technical-documentation/versions/2.0.4/test.json

@@ -0,0 +1,177 @@
+{
+  "schemaVersion": 1,
+  "title": "Technical Documentation — rate limiter Diataxis set",
+  "objective": "Exercise the Technical Documentation craftbook on a small real code surface and require a coherent, cross-linked Diataxis documentation set grounded in source behavior.",
+  "tags": [
+    "workflow",
+    "documentation",
+    "diataxis",
+    "typescript"
+  ],
+  "prompt": "Use the Technical Documentation craftbook to document the dependency-free rate limiter in this workspace. Inspect the source and test rather than guessing. Produce the craftbook inventory and plan plus a coherent set under `docs/`: `documentation-index.md`, `tutorial-rate-limit.md`, `how-to-configure-rate-limit.md`, `reference-rate-limit.md`, and `explanation-fixed-window.md`. The index must clearly organize tutorials, how-to, reference, and explanation, link to every page, cite the implementation/test where claims come from, and state how the documented examples were verified.",
+  "setup": {
+    "projectName": "Rate limiter documentation",
+    "about": "A hermetic TypeScript library documentation exercise. There are no external APIs or package dependencies.",
+    "missionObjectives": "Create accurate, navigable documentation that helps a first-time adopter use `createFixedWindowLimiter` and understand its tradeoffs without reading all source code.",
+    "files": [
+      {
+        "path": "README.md",
+        "content": "# tiny-limit\n\nA dependency-free fixed-window request limiter. Public behavior is defined by `src/rate-limit.ts` and its test. Documentation is intentionally incomplete.\n"
+      },
+      {
+        "path": "src/rate-limit.ts",
+        "content": "export interface RateLimitOptions {\n  windowMs: number;\n  max: number;\n}\n\nexport interface RateLimitDecision {\n  allowed: boolean;\n  remaining: number;\n  resetAt: number;\n}\n\nexport function createFixedWindowLimiter(options: RateLimitOptions) {\n  if (!Number.isInteger(options.max) || options.max < 1) throw new RangeError('max must be a positive integer');\n  if (!Number.isFinite(options.windowMs) || options.windowMs <= 0) throw new RangeError('windowMs must be positive');\n  const buckets = new Map<string, { count: number; resetAt: number }>();\n\n  return function check(key: string, now = Date.now()): RateLimitDecision {\n    const current = buckets.get(key);\n    const bucket = !current || now >= current.resetAt\n      ? { count: 0, resetAt: now + options.windowMs }\n      : current;\n    bucket.count += 1;\n    buckets.set(key, bucket);\n    return {\n      allowed: bucket.count <= options.max,\n      remaining: Math.max(0, options.max - bucket.count),\n      resetAt: bucket.resetAt,\n    };\n  };\n}\n"
+      },
+      {
+        "path": "test/rate-limit.test.ts",
+        "content": "import { strict as assert } from 'node:assert';\nimport { createFixedWindowLimiter } from '../src/rate-limit.js';\n\nconst check = createFixedWindowLimiter({ windowMs: 1000, max: 2 });\nassert.deepEqual(check('ada', 100), { allowed: true, remaining: 1, resetAt: 1100 });\nassert.deepEqual(check('ada', 200), { allowed: true, remaining: 0, resetAt: 1100 });\nassert.deepEqual(check('ada', 300), { allowed: false, remaining: 0, resetAt: 1100 });\nassert.deepEqual(check('ada', 1100), { allowed: true, remaining: 1, resetAt: 2100 });\n"
+      }
+    ],
+    "craftbookParams": {
+      "workPath": "tasks/eval"
+    }
+  },
+  "mocks": [],
+  "success": {
+    "summary": "The craftbook produces a complete, grounded five-page Diataxis set with a navigable index and terminal task evidence.",
+    "deliverables": [
+      {
+        "path": "docs/documentation-index.md",
+        "kind": "markdown-doc",
+        "minBytes": 850,
+        "checks": [
+          {
+            "kind": "contains",
+            "file": "docs/documentation-index.md",
+            "pattern": "^#{1,3}\\s+Tutorials?\\b[\\s\\S]*^#{1,3}\\s+How-to guides?\\b[\\s\\S]*^#{1,3}\\s+Reference\\b[\\s\\S]*^#{1,3}\\s+Explanation\\b[\\s\\S]*^#{1,3}\\s+Verification\\b",
+            "flags": "im",
+            "label": "Diataxis map and verification"
+          },
+          {
+            "kind": "contains",
+            "file": "docs/documentation-index.md",
+            "pattern": "tutorial-rate-limit\\.md[\\s\\S]*how-to-configure-rate-limit\\.md[\\s\\S]*reference-rate-limit\\.md[\\s\\S]*explanation-fixed-window\\.md",
+            "flags": "i",
+            "label": "all requested pages linked"
+          },
+          {
+            "kind": "citationsResolve",
+            "file": "docs/documentation-index.md",
+            "minCitations": 4
+          }
+        ]
+      },
+      {
+        "path": "docs/tutorial-rate-limit.md",
+        "kind": "markdown-doc",
+        "minBytes": 650,
+        "checks": [
+          {
+            "kind": "contains",
+            "file": "docs/tutorial-rate-limit.md",
+            "pattern": "createFixedWindowLimiter[\\s\\S]*windowMs[\\s\\S]*max[\\s\\S]*(allowed|remaining|resetAt)",
+            "label": "runnable API walkthrough"
+          }
+        ]
+      },
+      {
+        "path": "docs/how-to-configure-rate-limit.md",
+        "kind": "markdown-doc",
+        "minBytes": 550,
+        "checks": [
+          {
+            "kind": "contains",
+            "file": "docs/how-to-configure-rate-limit.md",
+            "pattern": "windowMs[\\s\\S]*max[\\s\\S]*(positive|greater than|at least)[\\s\\S]*(integer|finite)",
+            "flags": "i",
+            "label": "configuration constraints"
+          }
+        ]
+      },
+      {
+        "path": "docs/reference-rate-limit.md",
+        "kind": "markdown-doc",
+        "minBytes": 650,
+        "checks": [
+          {
+            "kind": "contains",
+            "file": "docs/reference-rate-limit.md",
+            "pattern": "RateLimitOptions[\\s\\S]*RateLimitDecision[\\s\\S]*allowed[\\s\\S]*remaining[\\s\\S]*resetAt",
+            "label": "public type reference"
+          }
+        ]
+      },
+      {
+        "path": "docs/explanation-fixed-window.md",
+        "kind": "markdown-doc",
+        "minBytes": 600,
+        "checks": [
+          {
+            "kind": "contains",
+            "file": "docs/explanation-fixed-window.md",
+            "pattern": "fixed[- ]window[\\s\\S]*(boundary|burst|trade[- ]?off)[\\s\\S]*(memory|Map|process)",
+            "flags": "i",
+            "label": "mechanism and tradeoffs"
+          }
+        ]
+      }
+    ],
+    "checks": [
+      {
+        "kind": "fileCount",
+        "ext": [
+          ".md"
+        ],
+        "min": 5,
+        "dir": "docs"
+      }
+    ],
+    "taskNotes": {
+      "minBytes": 180,
+      "checks": [
+        {
+          "kind": "contains",
+          "file": "task-notes.md",
+          "pattern": "\\bDONE\\b[\\s\\S]*docs/documentation-index\\.md[\\s\\S]*(5|five)\\s+(pages|documents)",
+          "flags": "i",
+          "label": "terminal note records the documentation set"
+        }
+      ],
+      "requireCraftbookTask": true
+    },
+    "taskGraph": {
+      "requireCraftbookTask": true,
+      "requireTerminalStep": true
+    },
+    "unchangedFixtures": [
+      "README.md",
+      "src/rate-limit.ts",
+      "test/rate-limit.test.ts"
+    ]
+  },
+  "rubric": {
+    "artifact": {
+      "path": "docs/documentation-index.md",
+      "kind": "markdown"
+    },
+    "axes": [
+      {
+        "name": "Source fidelity",
+        "description": "Claims, examples, inputs, outputs, and edge cases agree with the supplied implementation and test."
+      },
+      {
+        "name": "Diataxis separation",
+        "description": "Tutorial, how-to, reference, and explanation pages each serve their distinct reader need without becoming duplicate summaries."
+      },
+      {
+        "name": "Navigation and verification",
+        "description": "The set is cross-linked, easy to scan, and transparent about how examples and factual claims were checked."
+      }
+    ]
+  },
+  "qualityFocus": [
+    "Every public option and result field matches the source",
+    "Each Diataxis page has a distinct job",
+    "The index links the complete set and explains verification"
+  ]
+}

package/data/craftbook-templates/te/test-coverage-review/versions/1.1.2/craftbook.json

@@ -0,0 +1,153 @@
+{
+  "id": "test-coverage-review",
+  "name": "Test Coverage Review",
+  "description": "Review a codebase or module's test suite for real coverage and quality, then produce a gap report and a prioritized backlog of tests to add. First scopes the units under review and locks a coverage standard distinguishing line coverage from behavioral coverage (critical paths, branches, edge cases, error handling, and regression protection), then audits the existing tests for what they actually assert and which behaviors and branches are untested or weakly tested, then writes a report ranking the highest-value missing or low-quality tests with a concrete description of each. Use this for a test coverage review, finding test gaps, auditing test quality, deciding what to test next, or assessing whether a module is well-tested — it distinguishes meaningful behavioral coverage from a green coverage number and returns a prioritized testing backlog rather than 'add more tests'.\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 coverage standard (reviewer) — lock units in scope + a behavioral coverage bar → gated on artifact `{{workPath}}/scope.md` (markdown-notes)\n2. Audit the test suite (reviewer) — find untested behavior + weak assertions → gated on artifact `{{workPath}}/audit.md` (markdown-notes)\n3. Write the coverage report (reviewer) — prioritized test backlog + quality findings → gated on artifact `{{workPath}}/coverage-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": [
+    "test coverage review",
+    "where are the test gaps",
+    "is this well tested",
+    "what should I test next",
+    "audit the test suite",
+    "test quality review"
+  ],
+  "steps": [
+    {
+      "id": "scope",
+      "name": "Scope the coverage standard",
+      "description": "lock units in scope + a behavioral coverage bar",
+      "prompt": "Step 1: Identify the modules/units under review and their behavioral surface — the public functions, the critical paths, the branches, and the failure modes that matter. Step 2: Run the coverage tool if available (`vitest --coverage`, `pytest --cov`, etc.) to get the line/branch numbers as a starting signal — but treat it as a floor, not the goal. Step 3: Write a coverage acceptance-criteria checklist that distinguishes LINE coverage from BEHAVIORAL coverage: 'every critical path has a test that asserts its outcome', 'each conditional branch is exercised', 'edge cases (empty/null/boundary/large) are tested', 'error and exception paths are tested', 'tests assert behavior, not just that code runs without throwing', 'a regression in core logic would fail at least one test'. Step 4: State the target for THIS code (e.g. 'core domain logic ~90% branch + behavioral; glue code lighter'). Write the units + the coverage bar to `write_task_note` AND `{{workPath}}/scope.md`. No audit yet.\n\nThe deliverable `{{workPath}}/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": "{{workPath}}/scope.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/scope.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "{{workPath}}/scope.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "scope",
+        "maxAttempts": 3
+      },
+      "next": "audit"
+    },
+    {
+      "id": "audit",
+      "name": "Audit the test suite",
+      "description": "find untested behavior + weak assertions",
+      "prompt": "Step 1: Map the existing tests to the behavioral surface — for each unit, what is tested and what does each test actually ASSERT. Step 2: Flag the gaps: untested public functions, untested branches, missing edge cases (empty/null/boundary/error), and missing regression protection on core logic. Step 3: Flag WEAK tests — tests that only check 'it runs' without asserting outcomes, over-mocked tests that would pass even if the real logic broke, snapshot-only tests of meaningful logic, and tests coupled to implementation rather than behavior. Step 4: Cross-check the coverage numbers: where lines are 'covered' but no assertion verifies the result, call it out (covered ≠ tested). Step 5: For each gap, draft the test to add: the unit, the scenario/input, and the expected assertion. Step 6: Rank by value — core/critical logic and error paths first. Good looks like: 'parseAmount() has no test for negative or non-numeric input → add a test asserting it throws/returns Err', not 'add more tests'. Stage the gap list to `write_task_note`. Do not write the report yet.\n\nThe deliverable `{{workPath}}/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",
+      "advanceWhen": {
+        "file": "{{workPath}}/audit.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/audit.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "{{workPath}}/audit.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "audit",
+        "maxAttempts": 3
+      },
+      "next": "report"
+    },
+    {
+      "id": "report",
+      "name": "Write the coverage report",
+      "description": "prioritized test backlog + quality findings",
+      "prompt": "Step 1: Open `{{workPath}}/coverage-review.md` and write a '## Summary': the coverage numbers, an honest behavioral-coverage assessment, and the biggest gap. Step 2: Add a '## Missing tests' backlog ranked by value; each entry: the unit, the untested scenario, and the assertion the new test should make. Step 3: Add a '## Weak tests' section listing low-value/misleading tests with how to strengthen them. Step 4: Add a '## Well-covered' section noting what is solidly tested (so effort goes where it's needed). Step 5: Add a '## Quick wins' callout for high-value, easy tests to add first. Every recommendation must name a concrete test and its assertion — no 'increase coverage'. On a loop-back, fix only the named gaps. `write_task_note` the report path and the count of missing high-value tests.\n\nThe deliverable `{{workPath}}/coverage-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": "{{workPath}}/coverage-review.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/coverage-review.md",
+            "bytes": 1500,
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/coverage-review.md",
+            "pattern": "(?:^|\\n)#{1,3}\\s+\\S",
+            "flags": "i",
+            "label": "at least one markdown heading",
+            "artifact": true
+          }
+        ],
+        "onReject": "report",
+        "maxAttempts": 4
+      },
+      "next": "evaluate"
+    },
+    {
+      "id": "evaluate",
+      "name": "Evaluate",
+      "description": "Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.",
+      "prompt": "Open `{{workPath}}/coverage-review.md` and grade it against the scope coverage bar. Check EACH criterion and write PASS/FAIL with a one-line reason: (1) the review distinguishes line coverage from behavioral coverage rather than chasing a number; (2) untested critical paths, branches, edge cases, and error paths are identified; (3) each missing test is described concretely with the scenario and the assertion to make; (4) weak/misleading tests are flagged with how to strengthen them; (5) the backlog is prioritized by value with quick-wins called out; (6) a well-covered section keeps effort focused; (7) no vague 'add more tests' filler. If any criterion fails, name the exact gap and loop back.\n\nThe deliverable lives in the project's artifacts drawer — open `{{workPath}}/coverage-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": "{{workPath}}/coverage-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.1.2",
+  "releasedAt": "2026-08-21T00:00:00Z",
+  "paramSchema": {
+    "type": "object",
+    "properties": {
+      "workPath": {
+        "type": "string",
+        "title": "Working folder",
+        "description": "Per-task working folder in the artifacts drawer. Defaults to this task's own folder so runs never collide; override with a stable name when you deliberately want runs to share files.",
+        "default": "{{task.dir}}"
+      }
+    }
+  },
+  "minGezelVersion": "1.26233"
+}

package/data/craftbook-templates/te/test-coverage-review/versions/1.1.2/test.json

@@ -0,0 +1,116 @@
+{
+  "schemaVersion": 1,
+  "title": "Test Coverage Review behavioral eval",
+  "objective": "Measure whether the review distinguishes executed lines from meaningful assertions and proposes concrete high-value tests.",
+  "tags": [
+    "corpus"
+  ],
+  "prompt": "Use the Test Coverage Review craftbook for a whole-codebase test-health pass. Review src/price.ts and test/price.test.ts, then write tasks/eval/coverage-review.md. Do not add or change tests.",
+  "setup": {
+    "projectName": "Test Health Maintenance Eval",
+    "about": "A small pricing module with branches and error behavior but one weak happy-path test.",
+    "missionObjectives": "Find the missing boundary/error behaviors and weak assertion; leave a prioritized backlog with exact assertions.",
+    "files": [
+      {
+        "path": "src/price.ts",
+        "content": "export function finalPrice(cents: number, coupon?: string): number {\n  if (!Number.isInteger(cents) || cents < 0) throw new Error('invalid cents');\n  if (coupon === 'HALF') return Math.round(cents / 2);\n  if (coupon && coupon !== 'SAVE10') throw new Error('unknown coupon');\n  return coupon === 'SAVE10' ? Math.round(cents * 0.9) : cents;\n}\n"
+      },
+      {
+        "path": "test/price.test.ts",
+        "content": "import { test, expect } from 'vitest';\nimport { finalPrice } from '../src/price';\ntest('returns a price', () => {\n  expect(finalPrice(1000)).toBeDefined();\n});\n"
+      },
+      {
+        "path": "coverage-summary.txt",
+        "content": "src/price.ts: lines 100%, branches 25%, functions 100%\n"
+      }
+    ],
+    "worker": {
+      "name": "Rae",
+      "role": "Reviewer"
+    },
+    "craftbookParams": {
+      "workPath": "tasks/eval"
+    }
+  },
+  "mocks": [],
+  "success": {
+    "summary": "tasks/eval/coverage-review.md exposes the misleading line coverage and specifies exact branch, boundary, and error assertions.",
+    "deliverables": [
+      {
+        "path": "tasks/eval/coverage-review.md",
+        "kind": "markdown-report",
+        "minBytes": 1300,
+        "checks": [
+          {
+            "kind": "contains",
+            "file": "tasks/eval/coverage-review.md",
+            "pattern": "src/price\\.ts|test/price\\.test\\.ts",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/coverage-review.md",
+            "pattern": "100%[\\s\\S]{0,120}25%|line coverage[\\s\\S]{0,120}branch",
+            "flags": "i",
+            "label": "coverage is not behavior"
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/coverage-review.md",
+            "pattern": "toBeDefined|weak assertion|assert.*exact",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/coverage-review.md",
+            "pattern": "negative|invalid cents",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/coverage-review.md",
+            "pattern": "HALF|SAVE10",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/coverage-review.md",
+            "pattern": "unknown coupon|toThrow",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/coverage-review.md",
+            "pattern": "Quick wins|priority|high",
+            "flags": "i"
+          }
+        ]
+      }
+    ]
+  },
+  "rubric": {
+    "artifact": {
+      "path": "tasks/eval/coverage-review.md",
+      "kind": "markdown"
+    },
+    "axes": [
+      {
+        "name": "behavioral analysis",
+        "description": "The review distinguishes line execution from asserted behavior."
+      },
+      {
+        "name": "gap coverage",
+        "description": "Critical branches, boundaries, and error paths are mapped to missing tests."
+      },
+      {
+        "name": "backlog quality",
+        "description": "Each proposed test states its input, behavior, and exact assertion."
+      }
+    ]
+  },
+  "qualityFocus": [
+    "behavioral coverage",
+    "weak assertion detection",
+    "concrete test backlog"
+  ]
+}

package/data/craftbook-templates/te/test-suite-backfill/versions/1.0.2/craftbook.json

@@ -0,0 +1,132 @@
+{
+  "id": "test-suite-backfill",
+  "name": "Test Suite Backfill",
+  "description": "Add a meaningful test suite to existing untested (or under-tested) code, prioritizing the highest-risk behavior and edge cases over vanity coverage. Scopes coverage FIRST — the public surface, the critical paths, the edge/error cases, and the target the tests must hit — then writes characterization and edge-case tests that pin real behavior and would catch real regressions. Covers test prioritization, characterization tests, edge/error-case coverage, arrange-act-assert structure, and coverage-that-matters over line-count chasing.\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. Coverage scope (planner) — lock the surface, critical paths, edge cases, target → gated on artifact `{{workPath}}/coverage-scope.md` (markdown-notes)\n2. Write the tests (developer) — characterization + edge-case tests that catch regressions → gated on `src/module.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": "coverage-scope",
+  "triggers": [
+    "add tests to this code",
+    "backfill tests",
+    "increase test coverage",
+    "write tests for an untested module",
+    "test this function"
+  ],
+  "steps": [
+    {
+      "id": "coverage-scope",
+      "name": "Coverage scope",
+      "description": "lock the surface, critical paths, edge cases, target",
+      "prompt": "Decide WHAT to test before writing tests — coverage that matters beats line-count chasing. Step 1: Map the public surface of the code under test and what each function is supposed to do. Step 2: Rank by risk: which paths are critical/complex/most likely to break, and which are trivial. Step 3: For the high-risk paths, enumerate the cases that must be covered: happy path, boundary values, empty/null inputs, error conditions, and any tricky branches. Step 4: Set the target (the specific behaviors covered, or a coverage threshold if one was requested). Step 5: Write a numbered acceptance-criteria checklist of 5-9 items (e.g. 'every public function has at least a happy-path test', 'each error condition is asserted', 'boundary/empty inputs are covered', 'tests would fail if the behavior regressed'). `write_task_note` the test plan + checklist and write the same to the produces path.\n\nThe deliverable `{{workPath}}/coverage-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": "{{workPath}}/coverage-scope.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/coverage-scope.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "{{workPath}}/coverage-scope.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "coverage-scope",
+        "maxAttempts": 3
+      },
+      "next": "write-tests"
+    },
+    {
+      "id": "write-tests",
+      "name": "Write the tests",
+      "description": "characterization + edge-case tests that catch regressions",
+      "prompt": "Write the test suite to the plan. Step 1: For each public function, write a happy-path test using clear arrange-act-assert structure with meaningful assertions (assert the actual value/shape, not just 'did not throw'). Step 2: Add the edge and error cases from the plan — boundaries, empty/null, and each error condition (assert it throws/returns the right error). Step 3: Where behavior is undocumented, write characterization tests that pin the CURRENT behavior so future changes are caught. Step 4: Run the suite and confirm it passes against the real code; a test that cannot fail is worthless, so sanity-check that each would fail if behavior changed. Write the tests to the produces path. On a loop-back, add only the missing cases the reviewer named. `write_task_note` the test file path and the case count.",
+      "suggestedRole": "developer",
+      "advanceWhen": {
+        "file": "src/module.test.js",
+        "minBytes": 1,
+        "sniff": "nonempty"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "src/module.test.js",
+            "bytes": 300
+          },
+          {
+            "kind": "sniff",
+            "file": "src/module.test.js",
+            "sniff": "nonempty"
+          },
+          {
+            "kind": "esmImports",
+            "file": "src/module.test.js"
+          },
+          {
+            "kind": "sourceParses",
+            "file": "src/module.test.js"
+          }
+        ],
+        "scripts": [
+          {
+            "name": "checkContains",
+            "scope": "standard",
+            "inputs": {
+              "file": "src/module.test.js",
+              "pattern": "\\b(test|describe|it|assert|expect)\\b",
+              "flags": "i"
+            }
+          }
+        ],
+        "onReject": "write-tests",
+        "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 test suite. For EACH acceptance criterion: confirm every public function has a happy-path test with a real assertion, confirm each error condition and boundary/empty case is covered, confirm the tests pass against the current code, and judge whether the tests would actually catch a regression (not just smoke tests). Write PASS/FAIL per criterion; trivial assertions that cannot fail count as a FAIL of the coverage-that-matters 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: \"write-tests\" })` 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/module.test.js"
+        }
+      ],
+      "next": "write-tests"
+    },
+    {
+      "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.2",
+  "releasedAt": "2026-08-21T00:00:00Z",
+  "paramSchema": {
+    "type": "object",
+    "properties": {
+      "workPath": {
+        "type": "string",
+        "title": "Working folder",
+        "description": "Per-task working folder in the artifacts drawer. Defaults to this task's own folder so runs never collide; override with a stable name when you deliberately want runs to share files.",
+        "default": "{{task.dir}}"
+      }
+    }
+  },
+  "minGezelVersion": "1.26233"
+}