@bendyline/gilde 0.1.38 → 0.1.39

package/data/craftbook-templates/da/data-dictionary/versions/1.0.2/craftbook.json

@@ -0,0 +1,119 @@
+{
+  "id": "data-dictionary",
+  "name": "Data Dictionary",
+  "description": "Document a dataset's schema as a clear, complete data dictionary so others can use it without guessing. Inspects the data FIRST to derive each column's real type, value domain, null rate, units, and relationships from the actual values (not assumptions), then writes a readable dictionary with one entry per column plus dataset-level context. Use this for documenting a schema, building a data dictionary, a column glossary, a table reference, or onboarding docs for a dataset.\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. Inspect the schema (data-analyst) — derive each column's real type, domain, and relationships from values → gated on artifact `{{workPath}}/inspect.md` (markdown-notes)\n2. Write the dictionary (copywriter) — produce a readable per-column dictionary with dataset context → gated on `data-dictionary.md` (markdown-doc)\n\nThe gates never advance with an unmet criterion, and loop back to the\nowning phase to fix named gaps.\n",
+  "entryStepId": "inspect",
+  "triggers": [
+    "document a dataset",
+    "build a data dictionary",
+    "describe the columns",
+    "schema documentation",
+    "column glossary"
+  ],
+  "steps": [
+    {
+      "id": "inspect",
+      "name": "Inspect the schema",
+      "description": "derive each column's real type, domain, and relationships from values",
+      "prompt": "Profile the dataset to learn each column's TRUE characteristics from the data itself. Step 1: list every column. Step 2: for each, derive the data type, the value domain (range for numerics, the enumerated set for low-cardinality categoricals, format/pattern for strings like dates or IDs), the null/blank rate, the unit of measure, and an example value. Step 3: infer the likely meaning of each column and flag any whose name is ambiguous. Step 4: identify keys (unique columns), likely foreign keys, and any computed/derived columns. Step 5: write an acceptance-criteria checklist ('one entry per column', 'each entry has type + description + example', 'enumerated columns list their allowed values', 'keys and relationships are documented', 'units are stated where relevant'). Call write_task_note and write the per-column profile + checklist to {{workPath}}/inspect.md.\n\nThe deliverable `{{workPath}}/inspect.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}}/inspect.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/inspect.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "{{workPath}}/inspect.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "inspect",
+        "maxAttempts": 3
+      },
+      "next": "write"
+    },
+    {
+      "id": "write",
+      "name": "Write the dictionary",
+      "description": "produce a readable per-column dictionary with dataset context",
+      "prompt": "Write the data dictionary from the inspection profile — only describe what the data actually shows. Step 1: open with a dataset overview: what it is, the grain (one row = ?), the source, and the row/column counts. Step 2: produce a Markdown table with one row per column: Column, Type, Description, Allowed values / range, Nullable, Unit, Example. Step 3: write plain-English descriptions a newcomer understands; expand ambiguous names. Step 4: add a short 'Keys & relationships' section and a 'Notes / caveats' section (quirks, deprecated columns, derived fields). Step 5: ensure every column from the inspection appears. Write the dictionary to data-dictionary.md and call write_task_note with the path and column count. On a loop-back, fix only the named gaps.",
+      "suggestedRole": "copywriter",
+      "advanceWhen": {
+        "file": "data-dictionary.md",
+        "minBytes": 1,
+        "sniff": "nonempty"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "data-dictionary.md",
+            "bytes": 500
+          }
+        ],
+        "scripts": [
+          {
+            "name": "checkContains",
+            "scope": "standard",
+            "inputs": {
+              "file": "data-dictionary.md",
+              "pattern": "(?:^|\\n)#{1,3}\\s+\\S",
+              "flags": "i"
+            }
+          }
+        ],
+        "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 data-dictionary.md and cross-check it against {{workPath}}/inspect.md and the dataset. Verify: there is exactly one entry per column (count them against the data); each entry has a type, a plain description, and an example; enumerated columns list their allowed values; nullability and units are stated where relevant; and keys/relationships are documented. Spot-check 3 columns' types and value domains against the actual data. Write PASS/FAIL per criterion; any FAIL loops back to write.\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": "data-dictionary.md"
+        }
+      ],
+      "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"
+}

package/data/craftbook-templates/da/data-dictionary/versions/1.0.2/test.json

@@ -0,0 +1,104 @@
+{
+  "schemaVersion": 1,
+  "title": "Dataset schema dictionary from CSV",
+  "objective": "Measure whether the data-dictionary craftbook inspects a seeded CSV and writes per-column definitions, types, null/domain notes, and dataset context.",
+  "tags": [
+    "data"
+  ],
+  "prompt": "In the `Data Dictionary Eval` project, inspect `data/orders.csv` and write `data-dictionary.md`. Include dataset context plus one entry per column: order_id, channel, region, discount_code, net_revenue, shipped_at, returned. For each column provide type, meaning, example values, allowed/domain notes, and null/blank behavior. Ground domain notes only in column names and observed CSV values; do not invent business rules, currencies, fees, fulfillment lifecycle, customer-interaction details, or systems not present in the CSV.",
+  "setup": {
+    "projectName": "Data Dictionary Eval",
+    "about": "Self-contained eval project for the data-dictionary craftbook. The dataset is workspace/data/orders.csv.",
+    "missionObjectives": "Inspect the CSV values and document every column with type, meaning, examples, domain/null notes, and dataset context. Use only observed values and column names for domain notes; avoid invented business rules, currencies, fees, fulfillment lifecycle, or customer-interaction details.",
+    "files": [
+      {
+        "path": "data/orders.csv",
+        "content": "order_id,channel,region,discount_code,net_revenue,shipped_at,returned\nO-1001,web,West,WELCOME10,84.50,2026-05-01,false\nO-1002,marketplace,East,,142.00,2026-05-02,true\nO-1003,web,North,SPRING15,57.25,2026-05-03,false\nO-1004,retail,West,,233.10,2026-05-05,false\nO-1005,marketplace,South,SPRING15,19.99,2026-05-07,true\n"
+      }
+    ],
+    "worker": {
+      "name": "Iris",
+      "role": "Data Analyst"
+    },
+    "craftbookParams": {
+      "workPath": "tasks/eval"
+    }
+  },
+  "mocks": [],
+  "success": {
+    "summary": "workspace/data-dictionary.md documents every seeded column with type, meaning, examples, and null/domain behavior.",
+    "deliverables": [
+      {
+        "path": "data-dictionary.md",
+        "kind": "markdown-doc",
+        "minBytes": 1800,
+        "checks": [
+          {
+            "kind": "contains",
+            "file": "data-dictionary.md",
+            "pattern": "order_id|channel|region|discount_code|net_revenue|shipped_at|returned"
+          },
+          {
+            "kind": "contains",
+            "file": "data-dictionary.md",
+            "pattern": "type|meaning|example|domain|null|blank",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "data-dictionary.md",
+            "pattern": "web|marketplace|retail"
+          },
+          {
+            "kind": "contains",
+            "file": "data-dictionary.md",
+            "pattern": "WELCOME10|SPRING15|blank|empty",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "data-dictionary.md",
+            "pattern": "84\\.50|233\\.10|boolean|true|false",
+            "flags": "i"
+          },
+          {
+            "kind": "notContains",
+            "file": "data-dictionary.md",
+            "pattern": "tax(?:es)?|order placement date|warehouse|fulfillment center|completed transactions?|sequential number|source field|core financial outcome|shipping fees?|returns?/shipping fees?|local currency|operational efficiency|fulfilled orders?|order lifecycle|customer interacted|physical stores?",
+            "flags": "i",
+            "label": "avoid invented operational context not present in the seeded CSV columns or values"
+          }
+        ]
+      }
+    ]
+  },
+  "rubric": {
+    "artifact": {
+      "path": "data-dictionary.md",
+      "kind": "markdown"
+    },
+    "axes": [
+      {
+        "name": "accuracy",
+        "description": "Computed figures are correct against the seeded records."
+      },
+      {
+        "name": "grounding",
+        "description": "Every claim traces to the seeded data — nothing invented."
+      },
+      {
+        "name": "structure",
+        "description": "Tables and sections make the analysis checkable at a glance."
+      },
+      {
+        "name": "actionability",
+        "description": "Recommendations follow from the findings and are concretely doable."
+      }
+    ]
+  },
+  "qualityFocus": [
+    "schema inspection",
+    "null/domain notes",
+    "dataset documentation"
+  ]
+}

package/data/craftbook-templates/da/data-export-migrate/versions/1.0.2/craftbook.json

@@ -0,0 +1,160 @@
+{
+  "id": "data-export-migrate",
+  "name": "Migrate Data Between Tools",
+  "description": "Migrate records from a source tool/format to a destination tool/format — CRM to CRM, spreadsheet to app, JSON export to a new API — with a field mapping, value transforms, and a reconciliation that proves nothing was lost or corrupted. Locks the source→destination field map, the transform/normalization rules, and the reconciliation criteria FIRST, then builds the extract-transform-load with a dry-run preview, then verifies record counts match, key fields round-trip, and a diff report flags any mismatch. Mapping-and-reconciliation-before-load is the discipline that makes a migration trustworthy rather than a one-shot leap of faith.\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 migration (planner) — field map, transforms, reconciliation criteria → gated on artifact `{{workPath}}/scope.md` (markdown-notes)\n2. Build the migration (developer) — extract, transform, dry-run, load, reconcile → gated on `migrate.py` (code-module)\n3. Verify the migration (reviewer) — counts reconcile, fields round-trip, diff clean → gated on artifact `{{workPath}}/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": [
+    "migrate data between tools",
+    "move my CRM data",
+    "import an export into another app",
+    "convert and load records",
+    "migrate a spreadsheet to an app"
+  ],
+  "steps": [
+    {
+      "id": "scope",
+      "name": "Scope the migration",
+      "description": "field map, transforms, reconciliation criteria",
+      "prompt": "Define the migration contract before moving data. Step 1: profile the source (format, record count, fields, key) and the destination (target schema, required fields, the key/upsert semantics). Step 2: build the source→destination field map, including fields that split/merge/rename, and list destination required-fields with no source — each needs a default or makes the record invalid. Step 3: define per-field transforms (date/format normalization, enum remapping, unit conversion) and the validation rules a destination record must satisfy. Step 4: define the reconciliation criteria — counts match (in vs out vs rejected), a chosen key set round-trips, and key totals/sums match. Step 5: write an acceptance-criteria checklist ('every source record is loaded or explicitly rejected with a reason', 'field map applied, no unmapped data dropped silently', 'transforms produce valid destination values', 'counts reconcile', 'a dry-run preview exists before any write', 'a diff report lists every mismatch'). Call write_task_note with the map + transforms + reconciliation + checklist and write {{workPath}}/scope.md. No load 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": "planner",
+      "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": "build"
+    },
+    {
+      "id": "build",
+      "name": "Build the migration",
+      "description": "extract, transform, dry-run, load, reconcile",
+      "prompt": "Implement the migration to the locked map. Step 1: extract all source records. Step 2: transform each record through the field map and transforms into a destination-shaped object; validate it, and on failure route it to a rejected list with the reason rather than dropping it. Step 3: produce a DRY-RUN preview first — the transformed records and a summary (to-load / rejected counts) — and write it before any destination write. Step 4: load into the destination using the upsert key so a re-run is idempotent (no duplicates). Step 5: run reconciliation — produce a diff report comparing source vs destination on counts and the chosen key fields, listing every mismatch — and write the migration module plus the diff report. Call write_task_note with the module path, the diff-report path, and the loaded/rejected counts.",
+      "suggestedRole": "developer",
+      "advanceWhen": {
+        "file": "migrate.py",
+        "minBytes": 1,
+        "sniff": "nonempty"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "migrate.py",
+            "bytes": 200
+          },
+          {
+            "kind": "sniff",
+            "file": "migrate.py",
+            "sniff": "nonempty"
+          },
+          {
+            "kind": "esmImports",
+            "file": "migrate.py"
+          },
+          {
+            "kind": "sourceParses",
+            "file": "migrate.py"
+          }
+        ],
+        "onReject": "build",
+        "maxAttempts": 3
+      },
+      "next": "verify"
+    },
+    {
+      "id": "verify",
+      "name": "Verify the migration",
+      "description": "counts reconcile, fields round-trip, diff clean",
+      "prompt": "Verify the migration against scope. Step 1: confirm the module runs and produces both a dry-run preview and a diff report. Step 2: confirm coverage — every source record is either loaded or in the rejected list with a reason; loaded + rejected equals the source count. Step 3: confirm the field map applied with no silent data loss, and that destination records pass the validation rules. Step 4: confirm reconciliation — counts match and the chosen key fields round-trip (spot-check 5 records source↔destination), and the diff report has no unexplained mismatches. Step 5: confirm idempotency — a re-run via the upsert key creates no duplicates. Write PASS/FAIL per criterion to {{workPath}}/verify.md and task notes; on failure, name the records and loop back to build.\n\nThe deliverable `{{workPath}}/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": "{{workPath}}/verify.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "migrate.py",
+            "bytes": 200
+          },
+          {
+            "kind": "sniff",
+            "file": "migrate.py",
+            "sniff": "nonempty"
+          },
+          {
+            "kind": "esmImports",
+            "file": "migrate.py"
+          },
+          {
+            "kind": "sourceParses",
+            "file": "migrate.py"
+          }
+        ],
+        "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": "Run migrate.py in dry-run and load modes (or trace it) and verify every criterion from {{workPath}}/scope.md: a dry-run preview precedes any write, every source record is loaded or rejected-with-reason (loaded+rejected = source count), the field map applied with no silent loss, destination records validate, counts reconcile and key fields round-trip (spot-check 5), the diff report has no unexplained mismatches, and a re-run via the upsert key creates no duplicates. Write PASS/FAIL per criterion; on any failure, name the records and 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": "migrate.py"
+        }
+      ],
+      "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.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/da/data-export-migrate/versions/1.0.2/test.json

@@ -0,0 +1,107 @@
+{
+  "schemaVersion": 1,
+  "title": "Migrate Data Between Tools smoke eval",
+  "objective": "Self-contained smoke eval for the Migrate Data Between Tools craftbook using the data generic harness.",
+  "tags": [
+    "data"
+  ],
+  "prompt": "I dropped our numbers in source/records.csv. Can you look at the data, analyze it, and put togehter some results in analysis.md?",
+  "setup": {
+    "projectName": "Migrate Data Between Tools Eval",
+    "about": "Self-contained eval project for data-export-migrate. Seeded inputs are under workspace/source or workspace/fixtures; final deliverable is workspace/analysis.md.",
+    "missionObjectives": "Use the Migrate Data Between Tools craftbook/template, read the seeded local fixtures, and write analysis.md without network calls, real credentials, or live services.",
+    "files": [
+      {
+        "path": "source/brief.md",
+        "content": "# Migrate Data Between Tools 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: data-export-migrate - Migrate Data Between Tools.\n"
+      },
+      {
+        "path": "source/records.csv",
+        "content": "customer,region,orders,revenue_usd,churn_risk\nAster,North,12,1440,low\nBoreal,South,8,720,medium\nCedar,West,15,2100,high\nDune,North,5,500,low\n"
+      }
+    ],
+    "worker": {
+      "name": "Jules",
+      "role": "Data Analyst"
+    },
+    "craftbookParams": {
+      "workPath": "tasks/eval"
+    }
+  },
+  "mocks": [],
+  "success": {
+    "summary": "analysis.md is a seeded-data analysis with deterministic computed facts.",
+    "deliverables": [
+      {
+        "path": "analysis.md",
+        "kind": "markdown-report",
+        "minBytes": 900,
+        "checks": [
+          {
+            "kind": "contains",
+            "file": "analysis.md",
+            "pattern": "(?:^|\\n)#{1,3}\\s+\\S",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "analysis.md",
+            "pattern": "40\\b",
+            "flags": "i",
+            "label": "include total orders of 40"
+          },
+          {
+            "kind": "contains",
+            "file": "analysis.md",
+            "pattern": "\\$?4,?760\\b",
+            "flags": "i",
+            "label": "include total revenue of 4760"
+          },
+          {
+            "kind": "contains",
+            "file": "analysis.md",
+            "pattern": "Cedar",
+            "flags": "i",
+            "label": "identify Cedar as top revenue and high risk"
+          },
+          {
+            "kind": "contains",
+            "file": "analysis.md",
+            "pattern": "high",
+            "flags": "i",
+            "label": "include churn-risk finding"
+          }
+        ]
+      }
+    ]
+  },
+  "rubric": {
+    "artifact": {
+      "path": "analysis.md",
+      "kind": "markdown"
+    },
+    "axes": [
+      {
+        "name": "accuracy",
+        "description": "Computed figures are correct against the seeded records."
+      },
+      {
+        "name": "grounding",
+        "description": "Every claim traces to the seeded data — nothing invented."
+      },
+      {
+        "name": "structure",
+        "description": "Tables and sections make the analysis checkable at a glance."
+      },
+      {
+        "name": "actionability",
+        "description": "Recommendations follow from the findings and are concretely doable."
+      }
+    ]
+  },
+  "qualityFocus": [
+    "seeded data reading",
+    "computed facts",
+    "recommendation grounding"
+  ]
+}

package/data/craftbook-templates/da/data-join-merge/versions/1.0.2/craftbook.json

@@ -0,0 +1,113 @@
+{
+  "id": "data-join-merge",
+  "name": "Join / Merge Two Datasets",
+  "description": "Combine two datasets into one reconciled table on a shared key, correctly handling the join type, key mismatches, and duplicate fan-out. Profiles both sources and locks the join key, join type, and conflict rules FIRST (so the merge doesn't silently drop or duplicate rows), then builds the joined output, then verifies the match rate and that no row count exploded. Use this for joining two tables, merging datasets, a VLOOKUP-style match, enriching one file from another, or reconciling records across two sources.\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 join (planner) — lock the join key, join type, and conflict rules → gated on artifact `{{workPath}}/key-scope.md` (markdown-notes)\n2. Build the merge (developer) — normalize keys, join, and emit the reconciled table → gated on `data/merged.csv` (data-file)\n\nThe gates never advance with an unmet criterion, and loop back to the\nowning phase to fix named gaps.\n",
+  "entryStepId": "key-scope",
+  "triggers": [
+    "join two datasets",
+    "merge these tables",
+    "vlookup match",
+    "enrich one file from another",
+    "reconcile two data sources"
+  ],
+  "steps": [
+    {
+      "id": "key-scope",
+      "name": "Scope the join",
+      "description": "lock the join key, join type, and conflict rules",
+      "prompt": "Define the merge contract before joining. Step 1: profile BOTH sources — row counts, the candidate key column(s) in each, and the key's cardinality (is it unique, or one-to-many?). Step 2: assess key compatibility — same type/format? trailing whitespace or case differences? leading-zero or string-vs-number mismatches that must be normalized first? Step 3: choose the join type and justify it (inner = only matches; left = keep all of source A, enrich where matched; full = keep everything). Step 4: define conflict rules for columns present in both (which source wins, or keep both with suffixes) and the expected output column set. Step 5: write an acceptance-criteria checklist ('join key normalized in both', 'join type matches intent', 'output row count is explained by the join type and key cardinality', 'no unintended fan-out duplication', 'unmatched rows handled per the join type', 'expected columns present'). Call write_task_note and write the key analysis + join type + conflict rules + checklist to {{workPath}}/key-scope.md.\n\nThe deliverable `{{workPath}}/key-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}}/key-scope.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/key-scope.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "{{workPath}}/key-scope.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "key-scope",
+        "maxAttempts": 3
+      },
+      "next": "build"
+    },
+    {
+      "id": "build",
+      "name": "Build the merge",
+      "description": "normalize keys, join, and emit the reconciled table",
+      "prompt": "Execute the join exactly to the contract. Step 1: load both sources and normalize the join key in each (trim, case-fold, cast, zero-pad) per the scope. Step 2: perform the scoped join type on the normalized key. Step 3: apply conflict rules for overlapping columns (source-wins or suffixed _a/_b) and select the expected output columns. Step 4: track the numbers — rows in A, rows in B, matched rows, unmatched rows kept/dropped, and final row count — and confirm the final count is explained by the join type and key cardinality (not an accidental fan-out). Step 5: write the merged table to data/merged.csv with a header. On a loop-back, fix only the named gaps. Call write_task_note with the path and the match-rate / row-count reconciliation.",
+      "suggestedRole": "developer",
+      "advanceWhen": {
+        "file": "data/merged.csv",
+        "minBytes": 1,
+        "sniff": "nonempty"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "data/merged.csv",
+            "bytes": 120
+          },
+          {
+            "kind": "sniff",
+            "file": "data/merged.csv",
+            "sniff": "data-table"
+          }
+        ],
+        "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": "Open data/merged.csv and verify the merge is correct and lossless-by-intent against {{workPath}}/key-scope.md. Step 1: confirm it parses and has the expected columns, and that the join key was normalized consistently in both sources. Step 2: reconcile the row count yourself — final must equal matched rows (plus any unmatched-kept for left/full) and must NOT be inflated by duplicate keys creating a cartesian fan-out; compute the match rate and sanity-check it. Step 3: pick 3 keys — one matched, one present only in A, one only in B — and confirm each was handled per the chosen join type. Step 4: confirm overlapping columns followed the conflict rule and no key-normalization error caused false misses. Write PASS/FAIL per criterion; any FAIL loops 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": "data/merged.csv"
+        }
+      ],
+      "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.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"
+}