@bendyline/gilde 0.1.50 → 0.1.52

package/data/craftbook-templates/an/anomaly-scan/versions/1.0.3/test.json

@@ -0,0 +1,123 @@
+{
+  "schemaVersion": 1,
+  "title": "Anomaly scan over seeded orders data",
+  "objective": "Measure whether the anomaly-scan craftbook defines reproducible criteria, emits machine-readable flags, and writes a triage-ready report.",
+  "tags": [
+    "data"
+  ],
+  "prompt": "In the `Anomaly Scan Eval` project, read `data/orders.csv`, define concrete anomaly thresholds, write `data/anomalies.json`, and then write `tasks/eval/report.md` ranking the findings. The report must separate likely real problems from probable noise.",
+  "setup": {
+    "projectName": "Anomaly Scan Eval",
+    "about": "Self-contained eval project for anomaly-scan. The source dataset is workspace/data/orders.csv.",
+    "missionObjectives": "Find and explain anomalous order rows with explicit rules, JSON flags, severities, and a triage report.",
+    "files": [
+      {
+        "path": "data/orders.csv",
+        "content": "order_id,order_date,sku,quantity,revenue,region\nO-1001,2026-05-01,CHAIR-1,2,240,West\nO-1002,2026-05-01,LAMP-2,1,80,East\nO-1003,2026-05-02,DESK-5,1,620,West\nO-1004,2026-05-02,CHAIR-1,3,360,South\nO-1005,2026-05-03,LAMP-2,2,160,East\nO-1006,2026-05-03,DESK-5,1,610,West\nO-1007,2026-05-04,CHAIR-1,4,-480,West\nO-1008,2026-05-04,LAMP-2,1,82,North\nO-1009,2026-05-05,DESK-5,50,30500,West\nO-1010,2028-01-01,LAMP-2,1,80,East\nO-1011,2026-05-06,CHAIR-1,2,242,South\nO-1012,2026-05-06,DESK-5,1,615,West\nO-1013,2026-05-07,LAMP-2,0,0,East\n"
+      }
+    ],
+    "worker": {
+      "name": "Cato",
+      "role": "Data Analyst"
+    },
+    "craftbookParams": {
+      "workPath": "tasks/eval"
+    }
+  },
+  "mocks": [],
+  "success": {
+    "summary": "workspace/report.md and data/anomalies.json identify the seeded anomalous rows with rules, thresholds, severity, and triage guidance.",
+    "deliverables": [
+      {
+        "path": "tasks/eval/report.md",
+        "kind": "markdown-report",
+        "minBytes": 1800,
+        "checks": [
+          {
+            "kind": "contains",
+            "file": "tasks/eval/report.md",
+            "pattern": "(?:^|\\n)#{1,3}\\s+\\S",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/report.md",
+            "pattern": "O-1007|O-1009|O-1010|O-1013",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/report.md",
+            "pattern": "negative|future|quantity|outlier|threshold|severity",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/report.md",
+            "pattern": "likely real|probable noise|false positive",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/report.md",
+            "pattern": "recommended next steps|triage|action",
+            "flags": "i"
+          }
+        ]
+      },
+      {
+        "path": "data/anomalies.json",
+        "kind": "json",
+        "minBytes": 300,
+        "checks": [
+          {
+            "kind": "sniff",
+            "file": "data/anomalies.json",
+            "sniff": "json-valid"
+          },
+          {
+            "kind": "contains",
+            "file": "data/anomalies.json",
+            "pattern": "O-1007|O-1009|O-1010|O-1013",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "data/anomalies.json",
+            "pattern": "severity|rule|threshold|summary",
+            "flags": "i"
+          }
+        ]
+      }
+    ]
+  },
+  "rubric": {
+    "artifact": {
+      "path": "tasks/eval/report.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": [
+    "criteria first",
+    "JSON flags",
+    "ranked triage report"
+  ]
+}

package/data/craftbook-templates/ap/api-contract-review/versions/1.1.3/craftbook.json

@@ -0,0 +1,278 @@
+{
+  "id": "api-contract-review",
+  "name": "API Contract Review",
+  "description": "Review an API contract or specification (OpenAPI/REST/GraphQL) for correctness, consistency, and developer ergonomics, then produce a findings report. First scopes the surface and locks an API design checklist (resource naming and HTTP semantics, status codes, pagination and filtering, error schema consistency, auth, versioning and backward compatibility, idempotency, and schema/type rigor), then reviews each endpoint and type against those rules and REST/GraphQL best practices, then writes a findings report rating each issue and giving the corrected contract snippet. Use this for an API design review, reviewing an OpenAPI/Swagger spec, a REST or GraphQL contract review, endpoint/schema critique, or checking an API for consistency and backward compatibility before it ships — it returns specific, spec-anchored fixes rather than 'make the API cleaner'.\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 contract review (reviewer) — map the surface, lock an API design checklist → gated on artifact `{{workPath}}/scope.md` (markdown-notes)\n2. Review the endpoints (developer) — check each operation + type against the rules → gated on artifact `{{workPath}}/review.md` (markdown-notes)\n3. Write the contract report (reviewer) — findings with corrected snippets + compat verdict → gated on artifact `{{workPath}}/api-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": [
+    "api contract review",
+    "review my openapi spec",
+    "review this REST API",
+    "graphql schema review",
+    "is this api backward compatible",
+    "api design review"
+  ],
+  "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}}"
+      }
+    }
+  },
+  "steps": [
+    {
+      "id": "scope",
+      "name": "Scope the contract review",
+      "description": "map the surface, lock an API design checklist",
+      "prompt": "Step 1: Read the contract (OpenAPI/Swagger YAML/JSON, a GraphQL SDL, or the route/handler definitions) and inventory every endpoint/operation/type with its method, path, params, request/response schema, and auth. Step 2: Note whether this is a NEW API or a CHANGE to an existing one (if a change, backward compatibility is a first-class criterion). Step 3: Write an API acceptance-criteria checklist covering: resource naming (nouns, plural collections, consistent casing) and correct HTTP-method semantics; correct and consistent status codes (201 on create, 204 on empty, 4xx vs 5xx); a single consistent error schema across all endpoints; pagination/filtering/sorting conventions applied uniformly; auth declared per operation; explicit versioning and no breaking changes (no removed/renamed fields, no narrowed types, no new required inputs) for changes; idempotency for unsafe-but-retried operations; and schema rigor (required vs optional correct, enums constrained, types precise, examples present). Step 4: State the pass condition for each. Write the surface inventory + checklist to `write_task_note` AND `{{workPath}}/scope.md`. No findings 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": "review",
+      "toolPolicy": {
+        "disallowBuiltinToolsets": [
+          "ai-apps",
+          "archives",
+          "audio",
+          "browser-automation",
+          "code-execution",
+          "craftbooks",
+          "data-tables",
+          "entity-intel",
+          "git",
+          "image-intel",
+          "images",
+          "role-delegation",
+          "role-delegation-escalation",
+          "security-intel",
+          "team-management",
+          "videos",
+          "web",
+          "workspace-fs-write"
+        ],
+        "outputMedium": "artifact",
+        "additionalOutputMedia": [
+          "task-note"
+        ]
+      }
+    },
+    {
+      "id": "review",
+      "name": "Review the endpoints",
+      "description": "check each operation + type against the rules",
+      "prompt": "Step 1: Walk EACH endpoint/operation against the checklist: verify the method matches the action, the path is a sensible resource, the status codes are correct and complete (including error codes), the request/response schemas are precise, and auth is declared. Step 2: Walk EACH type/schema: required vs optional fields are right, enums and formats constrain values, nullability is intentional, and naming is consistent. Step 3: Cross-cut the whole surface for consistency: do all errors share one schema, is pagination uniform, is casing consistent, are similar resources modeled the same way. Step 4: For a CHANGE, diff against the prior contract and flag every breaking change. Step 5: For each finding capture: the operation/type, the rule violated, the impact on a client developer, severity, and the CORRECTED snippet (the fixed YAML/SDL/schema fragment). Good looks like: a finding with a before/after contract snippet, not 'improve error handling'. Stage findings to `write_task_note`. Do not write the report yet.\n\nThe deliverable `{{workPath}}/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": "developer",
+      "advanceWhen": {
+        "file": "{{workPath}}/review.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/review.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "{{workPath}}/review.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "review",
+        "maxAttempts": 3
+      },
+      "next": "report",
+      "toolPolicy": {
+        "disallowBuiltinToolsets": [
+          "ai-apps",
+          "archives",
+          "audio",
+          "browser-automation",
+          "code-execution",
+          "craftbooks",
+          "data-tables",
+          "entity-intel",
+          "git",
+          "image-intel",
+          "images",
+          "role-delegation",
+          "role-delegation-escalation",
+          "security-intel",
+          "team-management",
+          "videos",
+          "web",
+          "workspace-fs-write"
+        ],
+        "outputMedium": "artifact",
+        "additionalOutputMedia": [
+          "task-note"
+        ]
+      }
+    },
+    {
+      "id": "report",
+      "name": "Write the contract report",
+      "description": "findings with corrected snippets + compat verdict",
+      "prompt": "Step 1: Open `{{workPath}}/api-review.md` and write a verdict: Approve / Approve-with-changes / Request-changes, and for a change an explicit Backward-compatible: yes/no. Step 2: Add a '## Breaking changes' section first if any (each with the operation and the corrected approach), then '## Blocking' and '## Non-blocking' findings, each as `operation/type — rule — impact — corrected snippet`. Step 3: Add a '## Consistency' section for cross-cutting issues (error schema, pagination, casing). Step 4: Add a '## Strengths' note on what the contract gets right. Every finding must cite the operation/type and include a concrete corrected snippet — no generic advice. On a loop-back, fix only the named gaps. `write_task_note` the report path, the compatibility verdict, and the count of blocking findings.\n\nThe deliverable `{{workPath}}/api-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}}/api-review.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/api-review.md",
+            "bytes": 1500,
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/api-review.md",
+            "pattern": "(?:^|\\n)#{1,3}\\s+\\S",
+            "flags": "i",
+            "label": "at least one markdown heading",
+            "artifact": true
+          }
+        ],
+        "onReject": "report",
+        "maxAttempts": 4
+      },
+      "next": "evaluate",
+      "toolPolicy": {
+        "disallowBuiltinToolsets": [
+          "ai-apps",
+          "archives",
+          "audio",
+          "browser-automation",
+          "code-execution",
+          "craftbooks",
+          "data-tables",
+          "entity-intel",
+          "git",
+          "image-intel",
+          "images",
+          "role-delegation",
+          "role-delegation-escalation",
+          "security-intel",
+          "team-management",
+          "videos",
+          "web",
+          "workspace-fs-write"
+        ],
+        "outputMedium": "artifact",
+        "additionalOutputMedia": [
+          "task-note"
+        ]
+      }
+    },
+    {
+      "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}}/api-review.md` and grade it against the scope checklist. Check EACH criterion and write PASS/FAIL with a one-line reason: (1) every endpoint/operation and type was reviewed; (2) HTTP-method/status-code semantics were checked; (3) error schema, pagination, and naming consistency were assessed across the surface; (4) for a change, backward compatibility is explicitly stated and any breaking change is flagged; (5) each finding includes a concrete corrected contract snippet; (6) findings are prioritized (breaking/blocking/non-blocking); (7) the verdict matches the findings. If any criterion fails, name the exact gap and loop back.\n\nThe deliverable lives in the project's artifacts drawer — open `{{workPath}}/api-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}}/api-review.md",
+          "artifact": true
+        }
+      ],
+      "next": "report",
+      "toolPolicy": {
+        "disallowBuiltinToolsets": [
+          "ai-apps",
+          "archives",
+          "audio",
+          "browser-automation",
+          "code-execution",
+          "craftbooks",
+          "data-tables",
+          "entity-intel",
+          "git",
+          "image-intel",
+          "images",
+          "role-delegation",
+          "role-delegation-escalation",
+          "security-intel",
+          "team-management",
+          "videos",
+          "web",
+          "workspace-fs-write"
+        ],
+        "outputMedium": "task-note"
+      }
+    },
+    {
+      "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,
+      "toolPolicy": {
+        "disallowBuiltinToolsets": [
+          "ai-apps",
+          "archives",
+          "artifacts",
+          "audio",
+          "browser-automation",
+          "code-execution",
+          "craftbooks",
+          "data-tables",
+          "entity-intel",
+          "git",
+          "image-intel",
+          "images",
+          "role-delegation",
+          "role-delegation-escalation",
+          "security-intel",
+          "team-management",
+          "videos",
+          "web",
+          "workspace-fs-write"
+        ],
+        "outputMedium": "task-note"
+      }
+    }
+  ],
+  "version": "1.1.3",
+  "releasedAt": "2026-09-01T20:00:00Z",
+  "minGezelVersion": "1.26233"
+}

package/data/craftbook-templates/ap/api-contract-review/versions/1.1.3/test.json

@@ -0,0 +1,192 @@
+{
+  "schemaVersion": 1,
+  "title": "API Contract Review codebase eval",
+  "objective": "Measure whether the review reconciles an OpenAPI contract with the implemented route inventory and catches consistency, semantics, auth, pagination, and drift defects without inventing drift.",
+  "tags": [
+    "corpus"
+  ],
+  "prompt": "Use the API Contract Review craftbook for a codebase-wide API design pass. Reconcile openapi.yaml against the implemented routes and write tasks/eval/api-review.md with corrected snippets, plus a machine-readable list of the contract/implementation drifts you found at tasks/eval/drift.json (one record per drift, each with its path, method, issue, and fix). Do not edit the contract or the handlers.",
+  "setup": {
+    "projectName": "API Design Maintenance Eval",
+    "about": "A small REST API whose OpenAPI contract and route files contain deliberate design defects and contract/implementation drift.",
+    "missionObjectives": "Produce an evidence-backed API design report covering every documented operation and every implemented route, plus a structured drift list.",
+    "files": [
+      {
+        "path": "openapi.yaml",
+        "content": "openapi: 3.0.3\ninfo: { title: Widget API, version: 1.0.0 }\npaths:\n  /getWidgets:\n    get:\n      summary: List widgets\n      responses:\n        '200':\n          description: widgets\n          content:\n            application/json:\n              schema: { type: array, items: { $ref: '#/components/schemas/Widget' } }\n  /widgets:\n    post:\n      requestBody:\n        required: true\n        content:\n          application/json:\n            schema: { $ref: '#/components/schemas/Widget' }\n      responses:\n        '200': { description: created }\n  /widgets/{widgetId}/history:\n    get:\n      summary: Revision history for one widget\n      parameters:\n        - { name: widgetId, in: path, required: true, schema: { type: string } }\n      responses:\n        '200':\n          description: revisions\n          content:\n            application/json:\n              schema: { type: array, items: { $ref: '#/components/schemas/Revision' } }\n  /widgets/{widgetId}/status:\n    get:\n      summary: Processing status for one widget\n      parameters:\n        - { name: widgetId, in: path, required: true, schema: { type: string } }\n      responses:\n        '200':\n          description: status\n          content:\n            application/json:\n              schema:\n                type: object\n                required: [state, retryCount]\n                properties:\n                  state: { type: string, enum: [queued, running, done] }\n                  retryCount: { type: string }\n  /widgets/{widgetId}/owner:\n    get:\n      summary: Owner of one widget\n      parameters:\n        - { name: widgetId, in: path, required: true, schema: { type: string } }\n      responses:\n        '200':\n          description: owner\n          content:\n            application/json:\n              schema:\n                type: object\n                required: [id]\n                properties:\n                  id: { type: string }\n                  email: { type: string, nullable: true }\n  /users/{userId}:\n    get:\n      summary: One user\n      parameters:\n        - { name: userId, in: path, required: true, schema: { type: string } }\n      responses:\n        '200':\n          description: user\n          content:\n            application/json:\n              schema: { $ref: '#/components/schemas/User' }\n  /users/{userId}/sessions:\n    get:\n      summary: Sessions for one user\n      parameters:\n        - { name: userId, in: path, required: true, schema: { type: string } }\n      responses:\n        '200':\n          description: sessions\n          content:\n            application/json:\n              schema: { type: array, items: { $ref: '#/components/schemas/Session' } }\ncomponents:\n  schemas:\n    Widget:\n      type: object\n      properties:\n        id: { type: string }\n        display_name: { type: string }\n    Revision:\n      type: object\n      properties:\n        id: { type: string }\n        changedAt: { type: string, format: date-time }\n    User:\n      type: object\n      properties:\n        id: { type: string }\n        email: { type: string }\n    Session:\n      type: object\n      properties:\n        id: { type: string }\n        startedAt: { type: string, format: date-time }\n"
+      },
+      {
+        "path": "src/routes.ts",
+        "content": "import { registerSessionRoutes } from './session-routes';\n\nexport function registerRoutes(app, db) {\n  app.get('/getWidgets', async (_req, res) => {\n    res.json(await db.widgets.all());\n  });\n\n  app.post('/widgets', async (req, res) => {\n    const widget = await db.widgets.create(req.body);\n    res.status(200).json(widget);\n  });\n\n  app.get('/widgets/:id', async (req, res) => {\n    const item = await db.widgets.get(req.params.id);\n    if (!item) return res.status(404).json({ message: 'missing' });\n    res.json(item);\n  });\n\n  app.get('/widgets/:widgetId/status', async (req, res) => {\n    const row = await db.widgets.status(req.params.widgetId);\n    res.json({ state: row.state, retryCount: row.attempts.length });\n  });\n\n  app.get('/widgets/:widgetId/owner', async (req, res) => {\n    const owner = await db.widgets.owner(req.params.widgetId);\n    const body = { id: owner.id };\n    if (owner.email !== null && owner.email !== undefined) body.email = owner.email;\n    res.json(body);\n  });\n\n  app.get('/users/:userId', async (req, res) => {\n    res.json(await db.users.get(req.params.userId));\n  });\n\n  registerSessionRoutes(app, db);\n}\n"
+      },
+      {
+        "path": "src/session-routes.ts",
+        "content": "export function registerSessionRoutes(app, db) {\n  app.get('/users/:userId/sessions', async (req, res) => {\n    res.json(await db.sessions.forUser(req.params.userId));\n  });\n}\n"
+      },
+      {
+        "path": "docs/api-contract.md",
+        "content": "# Contract conventions\n\n`openapi.yaml` is the contract. The route inventory is `src/routes.ts` **and**\n`src/session-routes.ts` together: `registerRoutes` imports and calls\n`registerSessionRoutes`, so an operation is implemented when a handler for it exists in\neither file.\n\n## Path parameters\n\nPath templating differs by convention and is never drift on its own. The contract writes a\npath parameter as `{name}`; the router writes the same parameter as `:name`. `GET\n/users/{userId}` and `app.get('/users/:userId', ...)` are the same operation.\n\n## Response bodies\n\nA response property listed under `required` must always be present with its declared type.\nA property that is NOT listed under `required` and is marked `nullable: true` may be\nomitted or sent as null: a handler that leaves it out when it has no value is correct as\nwritten, not a contract violation.\n"
+      },
+      {
+        "path": "tests/api-contract-oracle.mjs",
+        "content": "// Precision/recall oracle for the API contract review.\n//\n// Run by the harness with the reviewed workspace as cwd. It grades the two\n// halves of a real reconciliation separately, because recall alone is passed\n// by a report that flags every operation it could not instantly match:\n//\n//   RECALL    - each of the three REAL drifts between openapi.yaml and the\n//               route inventory is reported, matched by path AND class.\n//   PRECISION - none of the three SAFE operations is CLAIMED to drift. Each\n//               is a deliberate look-alike of a real drift, and each is\n//               documented as correct in docs/api-contract.md.\n//\n// Classes are matched by their ordinary names - documented but not\n// implemented, implemented but not documented, response schema mismatch - and\n// never by wording this fixture invented, so the bar is \"a real contract\n// reconciliation\" rather than this scenario's vocabulary.\n//\n// Three rules keep the precision half off correct work, because a gate that\n// punishes a good review is worse than no gate at all:\n//\n//   1. A record is judged by what it is ABOUT - its path/endpoint field - not\n//      by every string it contains. Citing a neighbouring operation as the\n//      model for a fix (\"add a path item like /widgets/{widgetId}/owner\") is\n//      normal review prose, not a claim against that neighbour.\n//   2. Precision fires only on a reconciliation CLAIM: missing handler,\n//      undocumented operation, schema or parameter disagreement. Saying a\n//      safe operation has no pagination, no security scheme or no documented\n//      404 is TRUE of this fixture and is fair review - those design smells\n//      are graded by the api-review.md checks, never punished here. HARD\n//      claims name the operation itself and always count; SOFT claims leave\n//      the subject implicit (\"missing from the spec\") and are read as design\n//      remarks when they sit in a clause about a design feature.\n//   3. A \"this one is fine\" verdict is a non-claim only when it asserts no\n//      drift class. That keeps ordinary remediation wording - \"change the\n//      type so the schema matches the handler\" - from erasing a real finding,\n//      and stops a false positive from being excused by appending \"no drift\".\n//\n// The recall classes are built from the same families as the precision\n// claims, so a record that satisfies recall can never be discarded as a\n// verdict, and the two halves cannot drift apart as the vocabulary grows.\nimport { readFileSync } from 'node:fs';\n\n/**\n * Fail with the message ALONE on stderr.\n *\n * A thrown Error would work, but the harness feeds this script's stderr\n * into the model's repair nudge verbatim, and an uncaught throw pads that\n * nudge with a Node stack trace and a version banner. The actionable\n * sentence is what the next attempt needs; the stack is noise that pushes\n * it out of view on a small model.\n */\nfunction fail(message) {\n  console.error(message);\n  process.exit(1);\n}\n\n\nconst DRIFT = 'tasks/eval/drift.json';\n\nlet raw;\ntry {\n  raw = readFileSync(DRIFT, 'utf8');\n} catch {\n  fail(DRIFT + ' does not exist - the machine-readable drift list is required');\n}\n\nlet records;\ntry {\n  records = JSON.parse(raw.replace(/^\\uFEFF/, ''));\n} catch (err) {\n  fail(DRIFT + ' is not valid JSON: ' + err.message);\n}\nif (!Array.isArray(records)) {\n  const arrays =\n    records && typeof records === 'object' ? Object.values(records).filter(Array.isArray) : [];\n  if (arrays.length === 0) fail(DRIFT + ' must be an array of drift records');\n  records = arrays.flat();\n}\n\nfunction strings(value, out) {\n  if (typeof value === 'string') out.push(value);\n  else if (Array.isArray(value)) for (const entry of value) strings(entry, out);\n  else if (value && typeof value === 'object')\n    for (const entry of Object.values(value)) strings(entry, out);\n  return out;\n}\n\nconst union = (...parts) => new RegExp(parts.map((part) => part.source).join('|'));\n\n// `{widgetId}` and `:widgetId` are the same parameter; the contract and the\n// router spell it differently and a review may quote either form.\nconst normalize = (text) =>\n  text\n    .toLowerCase()\n    .replace(/\\{\\s*([a-z0-9_]+)\\s*\\}/g, ':$1')\n    // Mark sentence ends with `;` so the clause-scoped spans below cannot\n    // borrow words from the next sentence - but leave the dot inside\n    // `src/routes.ts` and `row.attempts.length` alone, or every clause would\n    // stop at the first filename a review cites as evidence.\n    .replace(/\\.(?=\\s|$)/g, ' ; ');\n\nconst textOf = (record) => normalize(strings(record, []).join(' | '));\n\n// What a record is ABOUT. The drift list is one record per operation and the\n// record schema requires a `path`, so the identifying fields are the honest\n// subject; `issue` and `fix` prose routinely names other operations.\nconst SUBJECT_KEY = /^(api)?(path|endpoint|operation|operationid|route|url|uri|resource)s?$/;\nfunction subjectOf(record) {\n  const parts = [];\n  for (const [key, value] of Object.entries(record)) {\n    if (SUBJECT_KEY.test(key.toLowerCase().replace(/[^a-z]/g, ''))) strings(value, parts);\n  }\n  return parts.length > 0 ? normalize(parts.join(' | ')) : null;\n}\n\n// ---------------------------------------------------------------------------\n// The ordinary vocabulary for \"the contract and the code disagree\". Prose is\n// joined with ` | ` and clause spans never cross `;` or `|`, so one sentence\n// cannot borrow words from the next.\n// ---------------------------------------------------------------------------\n\n// HARD: the operation itself is named as the thing that is wrong.\nconst NO_HANDLER = union(\n  /no (matching |registered |corresponding )?(route|handler|endpoint)\\b/,\n  /missing (route|handler|endpoint)\\b/,\n  /(handler|route|endpoint)[^;|]{0,40}(is |are )?(missing|absent|not found|not registered|does not exist|doesn'?t exist)/,\n  /(missing|absent) from (the )?(route|router|code|src|handler)/,\n  /not (present|found|registered|defined) in (the )?(route|router|code|src)/,\n  /not (registered|implemented|defined|handled) (by|in) (either|any|both)/,\n  /neither[^;|]{0,80}(register|implement|defin|handl)/,\n  /(none of|not one of)[^;|]{0,60}(route|file|handler)[^;|]{0,40}(register|implement|defin|handl)/,\n  /does not appear in (either|any|both|the) ?(of the )?(route|router|code|file)/,\n  /(nothing|no code|no file|nowhere)[^;|]{0,30}implement/,\n  /(code|implementation|router?|server|service|app)[^;|]{0,30}(does not|doesn'?t) implement/,\n  /(could not|couldn'?t|cannot|can'?t|unable to) (find|locate|see)[^;|]{0,40}(handler|route|endpoint|implementation)/,\n  /lacks (a |an )?(handler|route|implementation)\\b/,\n  /ghost (route|endpoint|operation|path)/,\n  /orphan(ed)? (spec|contract|path|operation|entry)/,\n  /spec[- ]only/,\n  /dead (spec|contract) entry/,\n);\n\nconst NO_PATH_ITEM = union(\n  /undocumented (operation|endpoint|route|path|handler)/,\n  /(operation|endpoint|route|path|handler)[^;|]{0,40}(is |are )?(not documented|undocumented)/,\n  /no path item/,\n  /no (matching |corresponding )?(spec|contract|openapi(\\.yaml)?) (entry|path item)/,\n  /shadow (route|endpoint)/,\n  /(spec|contract|openapi(\\.yaml)?)[^;|]{0,50}(does not|doesn'?t|fails to) (document|include|list|cover|mention)[^;|]{0,15}\\b(it|this|that|the (operation|endpoint|route|path))\\b/,\n  /(spec|contract|openapi(\\.yaml)?)[^;|]{0,40}(omits|lacks|has no|says nothing about)[^;|]{0,15}\\b(it|this|that|entry|path item|the (operation|endpoint|route|path))\\b/,\n);\n\nconst SCHEMA_DISAGREEMENT = union(\n  /schema mismatch|response mismatch|type mismatch/,\n  /type (conflict|disagreement|drift)/,\n  /wrong type|incorrect type/,\n  /(does not|doesn'?t) match the (schema|contract|spec|declared)/,\n  /(violates|contradicts) the (schema|contract|spec)/,\n  /(declar\\w+|documented)[^;|]{0,40}\\b(string|number|integer|boolean|array|object)\\b[^;|]{0,80}(returns|sends|responds|actually|but)/,\n  /required (field|property|member)[^;|]{0,40}(missing|omitted|absent|not returned)/,\n  /(omits|drops|does not return|doesn'?t return|never returns)[^;|]{0,40}(email|required)/,\n);\n\nconst PARAM_DISAGREEMENT = union(\n  /param\\w*[^;|]{0,60}(mismatch|mismatched|differ|do(es)? not match|doesn'?t match|inconsistent|drift)/,\n  /(templat|naming)\\w*[^;|]{0,60}(mismatch|differ|drift|inconsistent)/,\n);\n\n// SOFT: the subject is implicit, so these are also how a reviewer says a\n// design feature is absent. They count against precision only outside a\n// clause about such a feature.\nconst NOT_IMPLEMENTED_LOOSE = union(\n  /not implemented|no implementation|missing implementation|unimplemented|never implemented/,\n  /implemented nowhere/,\n  /(missing|absent) from (the )?implementation/,\n);\n\nconst NOT_DOCUMENTED_LOOSE = union(\n  /not documented|undocumented|documented nowhere/,\n  /(missing|absent) from (the )?(spec|contract|openapi)/,\n  /not in (the )?(spec|contract|openapi)/,\n);\n\nconst HARD_CLAIM = union(NO_HANDLER, NO_PATH_ITEM, SCHEMA_DISAGREEMENT, PARAM_DISAGREEMENT);\nconst SOFT_CLAIM = union(NOT_IMPLEMENTED_LOOSE, NOT_DOCUMENTED_LOOSE);\n\n// A clause whose subject is a design feature rather than the operation. Every\n// one of these is genuinely absent from this fixture, so a reviewer naming it\n// is right and must not be charged with inventing drift.\nconst DESIGN_CLAUSE =\n  /[^;|]*\\b(pagination|paginat\\w+|cursor|offset|page size|security|securityschemes?|scopes?|auth\\w*|oauth|401|403|404|4xx|5xx|error responses?|status codes?|examples?|descriptions?|summar\\w+|naming|verb in (the )?path|rate[- ]limit\\w*|versioning|idempoten\\w+|cach\\w+|etag|headers?|content[- ]type)\\b[^;|]*/g;\n\nconst claimsDrift = (text) =>\n  HARD_CLAIM.test(text) || SOFT_CLAIM.test(text.replace(DESIGN_CLAUSE, ' '));\n\n// Recall is deliberately more generous than precision: extra tolerance here\n// only risks passing a sloppy review, while a miss fails a correct one.\nconst TYPE_EVIDENCE =\n  /(?<!\\bno )mismatch|(?<!\\bno )not match|doesn'?t match|typed as|should be (a |an )?(number|integer)|declar\\w*[\\s\\S]{0,60}\\b(string|number|integer)\\b|\\bstring\\b[\\s\\S]{0,120}\\b(number|integer)\\b|\\b(number|integer)\\b[\\s\\S]{0,120}\\bstring\\b/;\n\nconst REAL = [\n  {\n    label:\n      'GET /widgets/{widgetId}/history is documented in openapi.yaml but no handler implements it',\n    path: /\\/widgets\\/:[a-z0-9_]+\\/history/,\n    klass: union(\n      NO_HANDLER,\n      NOT_IMPLEMENTED_LOOSE,\n      /documented but/,\n      /only (exists )?in the (spec|contract|openapi)/,\n    ),\n  },\n  {\n    label:\n      'GET /widgets/{widgetId}/status returns retryCount as a number while the contract declares it a string',\n    path: /\\/widgets\\/:[a-z0-9_]+\\/status/,\n    klass: union(SCHEMA_DISAGREEMENT, TYPE_EVIDENCE),\n  },\n  {\n    label: 'GET /widgets/:id is implemented in src/routes.ts but absent from openapi.yaml',\n    path: /\\/widgets\\/:[a-z0-9_]+(?![a-z0-9_/])/,\n    klass: union(\n      NO_PATH_ITEM,\n      NOT_DOCUMENTED_LOOSE,\n      /add[^;|]{0,50}\\b(path item|operation|entry|endpoint|route|definition|it)\\b[^;|]{0,20}\\bto\\b[^;|]{0,15}(spec|contract|openapi)/,\n      /document it/,\n    ),\n  },\n];\n\n// A record that states the operation conforms is a verdict, not a drift\n// claim - but only when it asserts no drift class of its own.\nconst NO_DRIFT_VERDICT =\n  /no drift|not a drift|not drift|matches the (spec|contract|implementation|handler|schema)|conforms to the (spec|contract)|correct as written|as designed|verified (safe|correct|ok)|no mismatch|no issue|no violation|not a (real )?(issue|violation|finding)|false positive|(permitted|allowed) by the (spec|contract)/;\n\nconst assertsDrift = (text) => claimsDrift(text) || REAL.some((real) => real.klass.test(text));\n\nconst entries = records\n  .filter((record) => record && typeof record === 'object')\n  .map((record) => ({ record, text: textOf(record), subject: subjectOf(record) }));\n\nconst claims = entries.filter(\n  (entry) => assertsDrift(entry.text) || !NO_DRIFT_VERDICT.test(entry.text),\n);\n\nconst missing = REAL.filter(\n  (real) => !claims.some((entry) => real.path.test(entry.text) && real.klass.test(entry.text)),\n);\nif (missing.length > 0) {\n  fail(\n    'RECALL FAILURE - openapi.yaml and the route inventory disagree in three places and these ' +\n      'were not reported: ' +\n      missing.map((real) => real.label).join('; ') +\n      '. Reported paths: ' +\n      (entries\n        .map((entry) => String(entry.record.path ?? entry.record.operation ?? '?'))\n        .join(', ') || '(nothing)'),\n  );\n}\n\nconst SAFE = [\n  {\n    label: 'GET /users/{userId}',\n    path: /\\/users\\/:[a-z0-9_]+(?![a-z0-9_/])/,\n    why: 'it is documented AND implemented in src/routes.ts - `{userId}` in the contract and `:userId` in the router are the same path parameter',\n  },\n  {\n    label: 'GET /users/{userId}/sessions',\n    path: /\\/users\\/:[a-z0-9_]+\\/sessions/,\n    why: 'its handler is registered in src/session-routes.ts, which src/routes.ts imports and calls - reading only one route file is what makes it look missing',\n  },\n  {\n    label: 'GET /widgets/{widgetId}/owner',\n    path: /\\/widgets\\/:[a-z0-9_]+\\/owner/,\n    why: 'the contract marks `email` nullable and leaves it out of `required`, so a handler that omits it when the owner has no address is permitted',\n  },\n];\n\nconst falsePositives = [];\nfor (const safe of SAFE) {\n  for (const entry of claims) {\n    // Judge the record by its subject, so a fix that cites this operation as\n    // the model for another one is not counted against the review.\n    if (!safe.path.test(entry.subject ?? entry.text)) continue;\n    // And only when it actually claims a contract/implementation\n    // disagreement - a design remark about a safe operation is fair review.\n    if (!claimsDrift(entry.text)) continue;\n    falsePositives.push(\n      safe.label +\n        ' reported as \"' +\n        String(entry.record.issue ?? entry.record.kind ?? entry.record.type ?? 'drift') +\n        '\" - ' +\n        safe.why,\n    );\n  }\n}\nif (falsePositives.length > 0) {\n  fail(\n    'PRECISION FAILURE - these operations agree with the contract and must not be listed as ' +\n      'drift: ' +\n      falsePositives.join('; ') +\n      '. A reconciliation that invents drift is not usable; re-read docs/api-contract.md and ' +\n      'both route files before deciding an operation is missing.',\n  );\n}\n\nconsole.log(\n  'API contract precision/recall oracle passed: all 3 real drifts reported, 0 false drifts on ' +\n    'the 3 safe operations.',\n);\n",
+        "surface": "workspace",
+        "modelInput": false
+      }
+    ],
+    "worker": {
+      "name": "Rae",
+      "role": "Reviewer"
+    },
+    "craftbookParams": {
+      "workPath": "tasks/eval"
+    }
+  },
+  "mocks": [],
+  "success": {
+    "summary": "tasks/eval/api-review.md covers every seeded operation with corrected contract snippets, and tasks/eval/drift.json lists every real contract/implementation drift and nothing else.",
+    "deliverables": [
+      {
+        "path": "tasks/eval/api-review.md",
+        "kind": "markdown-report",
+        "minBytes": 1400,
+        "checks": [
+          {
+            "kind": "contains",
+            "file": "tasks/eval/api-review.md",
+            "pattern": "openapi\\.yaml|src/routes\\.ts",
+            "flags": "i",
+            "label": "real evidence"
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/api-review.md",
+            "pattern": "/getWidgets|resource naming|noun",
+            "flags": "i",
+            "label": "resource naming"
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/api-review.md",
+            "pattern": "201|created",
+            "flags": "i",
+            "label": "create response semantics"
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/api-review.md",
+            "pattern": "pagination|cursor|limit",
+            "flags": "i",
+            "label": "collection pagination"
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/api-review.md",
+            "pattern": "auth|security",
+            "flags": "i",
+            "label": "auth coverage"
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/api-review.md",
+            "pattern": "/widgets/:id|not documented|drift",
+            "flags": "i",
+            "label": "implementation drift"
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/api-review.md",
+            "pattern": "retryCount|schema mismatch|type mismatch|response schema",
+            "flags": "i",
+            "label": "response schema drift"
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/api-review.md",
+            "pattern": "```(?:ya?ml|json)?[\\s\\S]{20,}```",
+            "flags": "i",
+            "label": "corrected snippet"
+          }
+        ]
+      },
+      {
+        "path": "tasks/eval/drift.json",
+        "kind": "json",
+        "minBytes": 200,
+        "checks": [
+          {
+            "kind": "sniff",
+            "file": "tasks/eval/drift.json",
+            "sniff": "json-valid"
+          },
+          {
+            "kind": "recordSchema",
+            "file": "tasks/eval/drift.json",
+            "format": "json",
+            "minRows": 3,
+            "fields": [
+              {
+                "name": "path",
+                "type": "nonempty",
+                "required": true
+              },
+              {
+                "name": "method",
+                "type": "nonempty",
+                "required": true
+              },
+              {
+                "name": "issue",
+                "type": "nonempty",
+                "required": true
+              },
+              {
+                "name": "fix",
+                "type": "nonempty",
+                "required": true
+              }
+            ],
+            "allowExtraFields": true
+          },
+          {
+            "kind": "nodeScriptPasses",
+            "script": "tests/api-contract-oracle.mjs",
+            "timeoutMs": 30000,
+            "requiredOutput": [
+              {
+                "pattern": "API contract precision/recall oracle passed",
+                "label": "every real drift reported, and no safe operation reported"
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  },
+  "rubric": {
+    "artifact": {
+      "path": "tasks/eval/api-review.md",
+      "kind": "markdown"
+    },
+    "axes": [
+      {
+        "name": "surface coverage",
+        "description": "The contract and all implemented operations are reconciled."
+      },
+      {
+        "name": "design rigor",
+        "description": "Semantics, consistency, auth, pagination, and schema quality are reviewed."
+      },
+      {
+        "name": "actionability",
+        "description": "Findings include concrete corrected snippets and compatibility impact."
+      }
+    ]
+  },
+  "qualityFocus": [
+    "contract-implementation reconciliation",
+    "API semantics",
+    "corrected snippets",
+    "drift precision"
+  ]
+}