@bendyline/gilde 0.1.38 → 0.1.39

package/data/craftbook-templates/co/codebase-refactoring-review/versions/1.0.2/test.json

@@ -0,0 +1,119 @@
+{
+  "schemaVersion": 1,
+  "title": "Codebase Refactoring Review hotspot eval",
+  "objective": "Measure whether the review ranks and verifies a low-cohesion hotspot, proposes bounded seams, and protects behavior with tests.",
+  "tags": [
+    "corpus"
+  ],
+  "prompt": "Use the Codebase Refactoring Review craftbook for the weekly code-health sweep. Find the least cogent areas in this fixture and write tasks/eval/refactoring-review.md. Do not change source.",
+  "setup": {
+    "projectName": "Refactoring Maintenance Eval",
+    "about": "A small order service with one deliberate multi-responsibility hotspot and a thin caller/test surface.",
+    "missionObjectives": "Verify refactoring candidates in source, rank them, and propose behavior-preserving seams rather than a rewrite.",
+    "files": [
+      {
+        "path": "src/order-service.ts",
+        "content": "export async function processOrder(input, db, mailer, audit) {\n  if (!input.customerId) throw new Error('customer required');\n  let total = 0;\n  for (const line of input.lines) {\n    const item = await db.inventory.find(line.sku);\n    if (!item || item.stock < line.qty) throw new Error('out of stock');\n    total += item.price * line.qty;\n    await db.inventory.update(line.sku, { stock: item.stock - line.qty });\n  }\n  if (input.coupon === 'SAVE10') total *= 0.9;\n  const order = await db.orders.insert({ ...input, total, status: 'paid' });\n  try {\n    await mailer.sendReceipt(input.email, order);\n    await audit.write('order.created', order);\n  } catch (_err) {\n    // Order succeeds even when both side effects disappear.\n  }\n  return order;\n}\n"
+      },
+      {
+        "path": "src/order-controller.ts",
+        "content": "import { processOrder } from './order-service';\nexport const postOrder = deps => async (req, res) => {\n  const order = await processOrder(req.body, deps.db, deps.mailer, deps.audit);\n  res.status(201).json(order);\n};\n"
+      },
+      {
+        "path": "test/order-service.test.ts",
+        "content": "test('creates an order', async () => {\n  const result = await processOrder(sample, fakeDb, fakeMailer, fakeAudit);\n  expect(result.status).toBe('paid');\n});\n"
+      }
+    ],
+    "worker": {
+      "name": "Rae",
+      "role": "Reviewer"
+    },
+    "craftbookParams": {
+      "workPath": "tasks/eval"
+    }
+  },
+  "mocks": [],
+  "success": {
+    "summary": "tasks/eval/refactoring-review.md verifies the processOrder hotspot and proposes sequenced, test-protected seams with explicit coverage limitations.",
+    "deliverables": [
+      {
+        "path": "tasks/eval/refactoring-review.md",
+        "kind": "markdown-report",
+        "minBytes": 1500,
+        "checks": [
+          {
+            "kind": "contains",
+            "file": "tasks/eval/refactoring-review.md",
+            "pattern": "src/order-service\\.ts:[0-9]+|src/order-service\\.ts",
+            "flags": "i",
+            "label": "source evidence"
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/refactoring-review.md",
+            "pattern": "processOrder",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/refactoring-review.md",
+            "pattern": "cohesion|responsibilit|coupling",
+            "flags": "i",
+            "label": "cogency diagnosis"
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/refactoring-review.md",
+            "pattern": "extract|seam|split",
+            "flags": "i",
+            "label": "bounded refactor"
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/refactoring-review.md",
+            "pattern": "test[\\s\\S]{0,120}(stock|coupon|mailer|audit|failure)",
+            "flags": "i",
+            "label": "behavior protection"
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/refactoring-review.md",
+            "pattern": "impact|effort|risk",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/refactoring-review.md",
+            "pattern": "Index coverage|coverage|not reviewed",
+            "flags": "i"
+          }
+        ]
+      }
+    ]
+  },
+  "rubric": {
+    "artifact": {
+      "path": "tasks/eval/refactoring-review.md",
+      "kind": "markdown"
+    },
+    "axes": [
+      {
+        "name": "ranking",
+        "description": "Candidates are prioritized by evidence, impact, effort, risk, and blast radius."
+      },
+      {
+        "name": "diagnosis",
+        "description": "The report explains the concrete cohesion, coupling, and testability problems."
+      },
+      {
+        "name": "safe plan",
+        "description": "Recommendations name bounded seams, sequencing, and behavior-preserving tests."
+      }
+    ]
+  },
+  "qualityFocus": [
+    "least-cogent areas",
+    "verified hotspots",
+    "safe refactor sequencing"
+  ]
+}

package/data/craftbook-templates/co/codebase-ux-review/versions/1.0.2/craftbook.json

@@ -0,0 +1,165 @@
+{
+  "id": "codebase-ux-review",
+  "name": "Codebase UX Review",
+  "description": "Review the user experience implemented across a codebase and, when runnable, exercise the key flows in a real browser. Starts from the indexed UI surface rather than one screenshot, traces primary journeys and state transitions, then leaves a prioritized morning report covering information architecture, comprehension, feedback, recovery, consistency, responsive behavior, and user impact with source or runtime evidence. Use for a weekly UX sweep, product usability review, interaction review, or finding the highest-impact friction in an application.\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. Map the experience (reviewer) — inventory surfaces, actors, journeys, states, and review coverage from the index → gated on artifact `{{workPath}}/ux/surface-map.md` (markdown-notes)\n2. Exercise and inspect journeys (reviewer) — walk key flows and verify indexed leads in source or a browser → gated on artifact `{{workPath}}/ux/evidence.md` (markdown-notes)\n3. Write the UX report (reviewer) — prioritized, journey-centered usability report for morning triage → gated on artifact `{{workPath}}/ux-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": "map",
+  "triggers": [
+    "codebase ux review",
+    "weekly ux review",
+    "review the product experience",
+    "find usability problems",
+    "nightly ux sweep",
+    "review the user journeys"
+  ],
+  "toolsets": [
+    {
+      "toolsetId": "builtin.code-intel",
+      "autoAllow": true,
+      "reason": "map routes, components, state, and indexed per-file UX leads"
+    },
+    {
+      "toolsetId": "builtin.browser-automation",
+      "autoAllow": true,
+      "reason": "exercise runnable journeys and capture real interaction evidence"
+    }
+  ],
+  "steps": [
+    {
+      "id": "map",
+      "name": "Map the experience",
+      "description": "inventory surfaces, actors, journeys, states, and review coverage from the index",
+      "prompt": "Call `map_repo`, `list_file_issues`, and targeted `search_code` queries to inventory the implemented experience: routes/views, navigation, dialogs, forms, onboarding, settings, empty/loading/error/success states, destructive actions, and responsive breakpoints. Read product/UX guidance already in the workspace before applying generic taste. Identify primary actors and 3-7 highest-value journeys with their start, goal, and risky transitions. Record which surfaces are runnable and which can only be reviewed statically. Write the surface map, journey matrix, local design principles, index coverage, and test plan to `{{workPath}}/ux/surface-map.md`. No findings yet.\n\nThe deliverable `{{workPath}}/ux/surface-map.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}}/ux/surface-map.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/ux/surface-map.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "{{workPath}}/ux/surface-map.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "map",
+        "maxAttempts": 3
+      },
+      "next": "exercise"
+    },
+    {
+      "id": "exercise",
+      "name": "Exercise and inspect journeys",
+      "description": "walk key flows and verify indexed leads in source or a browser",
+      "prompt": "Walk every prioritized journey. When the app is runnable, use `run_playwright_script` to test it at representative desktop and mobile sizes while checking navigation, focus, validation, loading, empty, error, success, cancellation, and recovery states. When it is not runnable, trace the relevant route/component/state symbols with `outline_file`, `read_symbol`, and `find_references`; label static inferences honestly. Verify indexed leads rather than repeating them. For each confirmed issue capture journey, step, evidence (screenshot/selector or file:line), expected vs actual experience, affected users, severity, frequency, and a concrete design/change recommendation. Also record strengths and tested-clean states. Write the evidence log to `{{workPath}}/ux/evidence.md`.\n\nThe deliverable `{{workPath}}/ux/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": "{{workPath}}/ux/evidence.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/ux/evidence.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "{{workPath}}/ux/evidence.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "exercise",
+        "maxAttempts": 3
+      },
+      "next": "report"
+    },
+    {
+      "id": "report",
+      "name": "Write the UX report",
+      "description": "prioritized, journey-centered usability report for morning triage",
+      "prompt": "Write `{{workPath}}/ux-review.md` with: `## Verdict`, `## Coverage`, `## Journey scorecard`, `## Findings`, `## Strengths`, `## Not verified`, and `## Morning action list`. Order findings by user harm × frequency, not visual polish. Every finding must cite a journey step and runtime or file:line evidence, explain the user consequence, and give a concrete recommendation with effort. Cover information architecture, comprehension, feedback/state visibility, error prevention/recovery, consistency, and responsive behavior. Keep accessibility defects cross-referenced rather than duplicating the a11y audit. State when a judgment is a static inference. On a loop-back, fix only named gaps.\n\nThe deliverable `{{workPath}}/ux-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}}/ux-review.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/ux-review.md",
+            "bytes": 1800,
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/ux-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 `{{workPath}}/ux-review.md`: (1) the important surfaces and journeys are covered; (2) findings cite a journey step plus runtime or real file:line evidence; (3) static inference is distinguished from exercised behavior; (4) loading, empty, error, success, cancellation, and recovery states were considered; (5) severity follows user harm and frequency; (6) recommendations are concrete and effort-aware; (7) strengths, unverified areas, and an actionable morning list are present. PASS all or loop back with exact gaps.\n\nThe deliverable lives in the project's artifacts drawer — open `{{workPath}}/ux-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}}/ux-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.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/co/codebase-ux-review/versions/1.0.2/test.json

@@ -0,0 +1,122 @@
+{
+  "schemaVersion": 1,
+  "title": "Codebase UX Review journey eval",
+  "objective": "Measure whether the review traces a seeded user journey and reports high-impact state, recovery, and destructive-action problems with source evidence.",
+  "tags": [
+    "corpus"
+  ],
+  "prompt": "Use the Codebase UX Review craftbook for a weekly product-experience pass. The app is not running, so trace the seeded source honestly and write tasks/eval/ux-review.md. Do not edit the UI.",
+  "setup": {
+    "projectName": "UX Maintenance Eval",
+    "about": "A returns dashboard with deliberate loading, empty, error, recovery, and destructive-action friction.",
+    "missionObjectives": "Leave a journey-centered UX report and clearly label static inference versus runtime evidence.",
+    "files": [
+      {
+        "path": "src/ReturnsPage.tsx",
+        "content": "export function ReturnsPage({ api }) {\n  const [query, setQuery] = useState('');\n  const [items, setItems] = useState([]);\n  async function search(e) {\n    e.preventDefault();\n    setQuery('');\n    try { setItems(await api.search(query)); }\n    catch (_err) { alert('Something went wrong'); }\n  }\n  return <main>\n    <h1>Returns</h1>\n    <form onSubmit={search}><input value={query} onChange={e => setQuery(e.target.value)} /><button>Go</button></form>\n    <button aria-label=\"action\" onClick={() => api.deleteAll()}>🗑</button>\n    <ul>{items.map(item => <li key={item.id}>{item.name}</li>)}</ul>\n  </main>;\n}\n"
+      },
+      {
+        "path": "src/nav.ts",
+        "content": "export const nav = [{ label: 'Desk', href: '/' }, { label: 'Things', href: '/returns' }, { label: 'More', href: '/settings' }];\n"
+      },
+      {
+        "path": "docs/product.md",
+        "content": "# Primary journey\n\nAn operations lead searches by order number, reviews matches, and deletes only a selected invalid return after confirmation. Search errors should preserve the query and explain how to retry.\n"
+      }
+    ],
+    "worker": {
+      "name": "Rae",
+      "role": "Reviewer"
+    },
+    "craftbookParams": {
+      "workPath": "tasks/eval"
+    }
+  },
+  "mocks": [],
+  "success": {
+    "summary": "tasks/eval/ux-review.md covers the primary journey, static-evidence limits, missing states, recovery loss, and unsafe delete-all control.",
+    "deliverables": [
+      {
+        "path": "tasks/eval/ux-review.md",
+        "kind": "markdown-report",
+        "minBytes": 1500,
+        "checks": [
+          {
+            "kind": "contains",
+            "file": "tasks/eval/ux-review.md",
+            "pattern": "src/ReturnsPage\\.tsx|docs/product\\.md",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/ux-review.md",
+            "pattern": "journey|search by order",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/ux-review.md",
+            "pattern": "loading|pending",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/ux-review.md",
+            "pattern": "empty state|no results",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/ux-review.md",
+            "pattern": "preserv(e|ing).*query|setQuery|retry",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/ux-review.md",
+            "pattern": "deleteAll|confirmation|destructive",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/ux-review.md",
+            "pattern": "static|not verified|not runnable",
+            "flags": "i",
+            "label": "honest evidence"
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/ux-review.md",
+            "pattern": "Morning action|priority|severity",
+            "flags": "i"
+          }
+        ]
+      }
+    ]
+  },
+  "rubric": {
+    "artifact": {
+      "path": "tasks/eval/ux-review.md",
+      "kind": "markdown"
+    },
+    "axes": [
+      {
+        "name": "journey coverage",
+        "description": "The review follows the primary task through success and failure states."
+      },
+      {
+        "name": "evidence honesty",
+        "description": "Static inference is clearly separated from exercised runtime behavior."
+      },
+      {
+        "name": "prioritization",
+        "description": "Findings are ranked by user harm and frequency with concrete remedies."
+      }
+    ]
+  },
+  "qualityFocus": [
+    "journey-centered review",
+    "state and recovery UX",
+    "runtime-vs-static honesty"
+  ]
+}

package/data/craftbook-templates/co/cohort-analysis/versions/1.0.2/craftbook.json

@@ -0,0 +1,153 @@
+{
+  "id": "cohort-analysis",
+  "name": "Cohort / Retention Analysis",
+  "description": "Analyze retention or behavior by cohort to reveal whether the product is getting stickier over time. Defines the cohort key, the activity event, and the retention window FIRST (so 'retained' has one unambiguous meaning), then builds the cohort/retention table and computes retention curves and trends as a data-analyst, then writes a readout on what the cohorts reveal. Use this for retention analysis, cohort tables, churn/stickiness analysis, a retention curve, or 'are newer users retaining better than older ones'.\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 cohorts (data-analyst) — lock the cohort key, activity event, and retention window → gated on artifact `{{workPath}}/scope.md` (markdown-notes)\n2. Build the cohort table (data-analyst) — compute the retention matrix and curves → gated on `data/cohorts.json` (json)\n3. Write the readout (copywriter) — explain what the cohorts reveal about retention → gated on artifact `{{workPath}}/readout.md` (markdown-report)\n\nData output discipline:\n\n- `data/cohorts.json` must be valid JSON only: no Markdown fences, comments, formulas, or ratio strings.\n- Use stable keys such as `signup_week`, `total_users`, and `retention`.\n- Store retention rates as numeric decimals rounded consistently, for example `0.67`, not `\"2/3\"` or `\"66.7%\"`.\n- Distinguish observed zero retention from incomplete future periods: use `0` when the period is observed and no cohort users were active, and `null` when the period is outside the observed window.\n\nThe gates never advance with an unmet criterion, and loop back to the\nowning phase to fix named gaps.\n",
+  "entryStepId": "scope",
+  "triggers": [
+    "cohort analysis",
+    "retention curve",
+    "are newer users retaining better",
+    "churn analysis",
+    "retention table"
+  ],
+  "steps": [
+    {
+      "id": "scope",
+      "name": "Scope the cohorts",
+      "description": "lock the cohort key, activity event, and retention window",
+      "prompt": "Define retention unambiguously before computing anything. Step 1: choose the cohort key — usually signup/first-activity period (weekly or monthly), and state the period. Step 2: define the ACTIVITY that counts as 'retained' (logged in, made a purchase, used core feature) and the unit (a user, an account). Step 3: define the retention window and periods (W0..W8, or M0..M6) and whether it's classic (active in period N) or rolling/unbounded. Step 4: state filters (exclude test accounts, a minimum-tenure cutoff so incomplete recent cohorts are flagged). Step 5: write an acceptance-criteria checklist ('cohort key and activity are precisely defined', 'retention table has cohorts as rows and periods as columns', 'period 0 is 100% by construction', 'incomplete recent cohorts are flagged', 'a trend across cohorts is reported'). Call write_task_note and write the definitions + checklist to {{workPath}}/scope.md.\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": "data-analyst",
+      "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": "analyze"
+    },
+    {
+      "id": "analyze",
+      "name": "Build the cohort table",
+      "description": "compute the retention matrix and curves",
+      "prompt": "Compute the cohort retention matrix from the defined rules. Step 1: assign each user/account to its cohort by the cohort key. Step 2: for each cohort and each retention period, compute the share of the cohort that performed the activity in that period; period 0 is 100% by construction. Step 3: build the triangular retention matrix (cohorts x periods), the cohort sizes, and the average retention curve across cohorts. Step 4: compute the trend — are later cohorts retaining better at the same period age than earlier ones? Step 5: flag cohorts too recent to have full data. Emit data/cohorts.json (matrix, sizes, average curve, trend) and call write_task_note with the headline retention numbers and the trend.",
+      "suggestedRole": "data-analyst",
+      "advanceWhen": {
+        "file": "data/cohorts.json",
+        "minBytes": 1,
+        "sniff": "json-valid"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "data/cohorts.json",
+            "bytes": 2
+          }
+        ],
+        "scripts": [
+          {
+            "name": "checkJsonValid",
+            "scope": "standard",
+            "inputs": {
+              "file": "data/cohorts.json"
+            }
+          }
+        ],
+        "onReject": "analyze",
+        "maxAttempts": 3
+      },
+      "next": "write"
+    },
+    {
+      "id": "write",
+      "name": "Write the readout",
+      "description": "explain what the cohorts reveal about retention",
+      "prompt": "Write the retention readout from the computed matrix — no invented figures. Step 1: lead with the headline: the typical W1/M1 retention and where the curve flattens (the 'sticky' floor). Step 2: present the retention table (cohorts as rows, periods as columns) and read it for the reader. Step 3: state the cross-cohort trend in plain language ('M1 retention improved from 22% to 31% over the last 6 cohorts'). Step 4: call out the best and worst cohorts and any inflection. Step 5: caveat the incomplete recent cohorts and suggest one next action. Write the readout to {{workPath}}/readout.md and call write_task_note with the path. On a loop-back, fix only the named gaps.\n\nThe deliverable `{{workPath}}/readout.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",
+      "advanceWhen": {
+        "file": "{{workPath}}/readout.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/readout.md",
+            "bytes": 1500,
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/readout.md",
+            "pattern": "(?:^|\\n)#{1,3}\\s+\\S",
+            "flags": "i",
+            "label": "at least one markdown heading",
+            "artifact": true
+          }
+        ],
+        "onReject": "write",
+        "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": "Read {{workPath}}/readout.md and cross-check against {{workPath}}/scope.md and data/cohorts.json. Verify: the cohort key and activity are precisely defined and used; the retention table has cohorts as rows and periods as columns with period 0 = 100%; incomplete recent cohorts are flagged; and a cross-cohort trend is reported with numbers. Re-check the headline W1/M1 retention and the trend against the cohort data. Confirm no cohort's retention exceeds 100% or rises impossibly. Write PASS/FAIL per criterion; any FAIL loops back to write.\n\nThe deliverable lives in the project's artifacts drawer — open `{{workPath}}/readout.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: \"write\" })` 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}}/readout.md",
+          "artifact": true
+        }
+      ],
+      "next": "write"
+    },
+    {
+      "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"
+}