@bendyline/gilde 0.1.51 → 0.1.53

package/data/craftbook-templates/sp/spec-authoring/versions/2.0.5/test.json

@@ -0,0 +1,162 @@
+{
+  "schemaVersion": 1,
+  "title": "Spec Authoring — asynchronous CSV exports",
+  "objective": "Require the Spec Authoring craftbook to reconcile approved intent with current code and produce a backlog-ready, file-specific implementation spec with measurable acceptance and rollback criteria.",
+  "tags": [
+    "workflow",
+    "spec",
+    "planning",
+    "typescript"
+  ],
+  "prompt": "Use the Spec Authoring craftbook to turn `source/approved-intent.md` into an implementation-ready spec grounded in the current files under `src/` and `tests/`. Resolve ambiguities from the supplied evidence without writing production code. Produce the craftbook audit and decision log, then write `specs/implementation-spec.md` with all required sections, exact file references, API/state transitions, authorization and limit behavior, measurable acceptance criteria, a dependency-free testing plan, rollback, and explicit out-of-scope items. Cite every workspace file used.",
+  "setup": {
+    "projectName": "Async export spec",
+    "about": "A hermetic specification exercise for an existing TypeScript service. The source of truth is limited to seeded workspace files.",
+    "missionObjectives": "Produce a spec another engineer can implement without reopening product scope or guessing security, lifecycle, limit, and rollback behavior.",
+    "files": [
+      {
+        "path": "source/approved-intent.md",
+        "content": "# Approved intent: asynchronous CSV exports\n\nReplace the synchronous customer export with an asynchronous job API.\n\n## Locked product decisions\n- `POST /v1/exports` accepts a saved report id and an `Idempotency-Key` header.\n- Roles `analyst` and `admin` may create exports; `viewer` receives 403.\n- Requests above **50,000 rows** receive 422 before a job is queued.\n- Job states are `queued`, `running`, `succeeded`, and `failed`.\n- Reusing an idempotency key for the same actor within **24 hours** returns the original job.\n- Successful download URLs expire after **15 minutes**.\n- Existing synchronous `/v1/reports/:id.csv` remains available behind a feature flag during rollout.\n\n## Out of scope\nNew report builders, additional export formats, recurring schedules, and email delivery.\n"
+      },
+      {
+        "path": "src/export-controller.ts",
+        "content": "import { mayExport } from './policy.js';\n\nexport type Role = 'viewer' | 'analyst' | 'admin';\n\nexport function downloadReportCsv(role: Role, reportId: string): { status: number; body: string } {\n  if (!mayExport(role)) return { status: 403, body: 'forbidden' };\n  return { status: 200, body: `report_id\\n${reportId}\\n` };\n}\n"
+      },
+      {
+        "path": "src/policy.ts",
+        "content": "export function mayExport(role: 'viewer' | 'analyst' | 'admin'): boolean {\n  return role === 'analyst' || role === 'admin';\n}\n"
+      },
+      {
+        "path": "tests/export-contract.test.ts",
+        "content": "import { strict as assert } from 'node:assert';\nimport { downloadReportCsv } from '../src/export-controller.js';\n\nassert.equal(downloadReportCsv('viewer', 'r-1').status, 403);\nassert.equal(downloadReportCsv('analyst', 'r-1').status, 200);\n"
+      }
+    ]
+  },
+  "mocks": [],
+  "success": {
+    "summary": "The named craftbook produces an evidence-grounded, backlog-ready asynchronous-export spec and records a terminal task handoff.",
+    "deliverables": [
+      {
+        "path": "specs/implementation-spec.md",
+        "kind": "markdown-doc",
+        "minBytes": 1700,
+        "checks": [
+          {
+            "kind": "contains",
+            "file": "specs/implementation-spec.md",
+            "pattern": "^#{1,3}\\s+Context\\b[\\s\\S]*^#{1,3}\\s+Current state\\b[\\s\\S]*^#{1,3}\\s+Proposed change\\b[\\s\\S]*^#{1,3}\\s+Implementation details\\b[\\s\\S]*^#{1,3}\\s+Acceptance criteria\\b[\\s\\S]*^#{1,3}\\s+Testing plan\\b[\\s\\S]*^#{1,3}\\s+Rollback plan\\b[\\s\\S]*^#{1,3}\\s+Out of scope\\b[\\s\\S]*^#{1,3}\\s+File reference\\b",
+            "flags": "im",
+            "label": "complete implementation-spec structure"
+          },
+          {
+            "kind": "valueGrounding",
+            "file": "specs/implementation-spec.md",
+            "facts": [
+              {
+                "id": "create-api",
+                "required": [
+                  "POST\\s+`?/v1/exports`?"
+                ]
+              },
+              {
+                "id": "role-policy",
+                "required": [
+                  "analyst[\\s\\S]{0,80}admin[\\s\\S]{0,120}(viewer[\\s\\S]{0,40}403|403[\\s\\S]{0,40}viewer)"
+                ]
+              },
+              {
+                "id": "row-limit",
+                "required": [
+                  "50,?000\\s+rows"
+                ]
+              },
+              {
+                "id": "row-limit-status",
+                "required": [
+                  "422"
+                ]
+              },
+              {
+                "id": "lifecycle",
+                "required": [
+                  "queued[\\s\\S]{0,100}running[\\s\\S]{0,100}succeeded[\\s\\S]{0,100}failed"
+                ]
+              },
+              {
+                "id": "idempotency-window",
+                "required": [
+                  "24\\s+hours"
+                ]
+              },
+              {
+                "id": "download-expiry",
+                "required": [
+                  "15\\s+minutes"
+                ]
+              }
+            ]
+          },
+          {
+            "kind": "contains",
+            "file": "specs/implementation-spec.md",
+            "pattern": "(Given[\\s\\S]{0,200}When[\\s\\S]{0,200}Then|shall|must)[\\s\\S]*(feature flag|synchronous|reports/:id\\.csv)",
+            "flags": "i",
+            "label": "testable criteria and rollout compatibility"
+          },
+          {
+            "kind": "citationsResolve",
+            "file": "specs/implementation-spec.md",
+            "minCitations": 4
+          }
+        ]
+      }
+    ],
+    "taskNotes": {
+      "minBytes": 170,
+      "checks": [
+        {
+          "kind": "contains",
+          "file": "task-notes.md",
+          "pattern": "\\bDONE\\b[\\s\\S]*specs/implementation-spec\\.md",
+          "label": "terminal craftbook note names the spec"
+        }
+      ],
+      "requireCraftbookTask": true
+    },
+    "taskGraph": {
+      "requireCraftbookTask": true,
+      "requireTerminalStep": true
+    },
+    "unchangedFixtures": [
+      "source/approved-intent.md",
+      "src/export-controller.ts",
+      "src/policy.ts",
+      "tests/export-contract.test.ts"
+    ]
+  },
+  "rubric": {
+    "artifact": {
+      "path": "specs/implementation-spec.md",
+      "kind": "markdown"
+    },
+    "axes": [
+      {
+        "name": "Codebase grounding",
+        "description": "Current-state claims and file changes trace to the seeded implementation, policy, contract test, and approved intent."
+      },
+      {
+        "name": "Implementation precision",
+        "description": "The API, authorization, state machine, idempotency, limits, expiry, persistence boundaries, and file responsibilities are unambiguous."
+      },
+      {
+        "name": "Backlog readiness",
+        "description": "Acceptance criteria are observable, the testing plan covers failure paths, and rollout and rollback can be executed safely."
+      }
+    ]
+  },
+  "qualityFocus": [
+    "Locked product decisions are conserved exactly",
+    "Current and proposed behavior are clearly separated",
+    "File-level implementation and test responsibilities are specific enough to execute"
+  ]
+}

package/data/craftbook-templates/sp/spec-doc/versions/1.0.3/craftbook.json

@@ -0,0 +1,280 @@
+{
+  "id": "spec-doc",
+  "name": "Technical Design Doc",
+  "description": "Write a technical design document (RFC / engineering design doc) that gets a system change reviewed and approved — covering context and problem, goals and non-goals, the proposed design, alternatives considered, trade-offs, risks, and a rollout plan. Scopes the problem, goals, and explicit non-goals FIRST (non-goals prevent reviewer scope-creep), writes the detailed design with diagrams and alternatives, then has a reviewer check it for completeness and unjustified decisions. Use for RFCs, architecture proposals, and pre-implementation design reviews.\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 design (planner) — problem, goals, explicit non-goals, constraints, success metrics → gated on artifact `{{workPath}}/scope.md` (markdown-notes)\n2. Write the design (developer) — detailed proposed design, alternatives, trade-offs, rollout plan → gated on artifact `{{workPath}}/spec.md` (markdown-report)\n3. Review the design (reviewer) — check completeness, justified decisions, and risk coverage → gated on artifact `{{workPath}}/review.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": [
+    "technical design doc",
+    "write an rfc",
+    "engineering design document",
+    "architecture proposal",
+    "system design doc",
+    "design spec"
+  ],
+  "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 design",
+      "description": "problem, goals, explicit non-goals, constraints, success metrics",
+      "prompt": "Frame the problem before proposing a solution. Step 1: write the context and problem statement — what is broken or needed and why now. Step 2: list the GOALS (what the design must achieve) and, explicitly, the NON-GOALS (what it deliberately will not address) — the non-goals keep the review focused. Step 3: capture the constraints (compatibility, performance, deadline, team, existing systems) the design must respect. Step 4: define success metrics — how you will know the change worked. Step 5: note at least one alternative direction worth documenting so the doc shows the decision was considered. Step 6: write an acceptance-criteria checklist ('problem + context stated', 'goals AND non-goals listed', 'constraints captured', 'success metrics defined', 'at least one alternative to document', 'a rollout/migration consideration noted'). Write the framing + checklist via write_task_note AND to {{workPath}}/scope.md. No detailed design 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": "write",
+      "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": "write",
+      "name": "Write the design",
+      "description": "detailed proposed design, alternatives, trade-offs, rollout plan",
+      "prompt": "Write the design document as {{workPath}}/spec.md. Step 1: open with the context/problem, then the goals and non-goals exactly as scoped. Step 2: write the Proposed Design in depth — components and responsibilities, data model/schema changes, APIs/interfaces, and the key flows; include at least one diagram (an ASCII/mermaid block is fine) of the architecture or sequence. Step 3: write an Alternatives Considered section covering each documented alternative with its pros/cons and WHY it was rejected — every significant decision must be justified, not asserted. Step 4: write a Trade-offs and Risks section (what this design gives up, failure modes, mitigations). Step 5: write a Rollout/Migration plan (phasing, flags, backfill, backward compatibility) and a Testing/validation plan tied to the success metrics. Step 6: list open questions. Use numbered headings and keep it concrete with real names. On a loop-back, fix ONLY the named gaps. Write the path + section count via write_task_note.\n\nThe deliverable `{{workPath}}/spec.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}}/spec.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/spec.md",
+            "bytes": 1500,
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/spec.md",
+            "pattern": "(?:^|\\n)#{1,3}\\s+\\S",
+            "flags": "i",
+            "label": "at least one markdown heading",
+            "artifact": true
+          }
+        ],
+        "onReject": "write",
+        "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 design",
+      "description": "check completeness, justified decisions, and risk coverage",
+      "prompt": "Review the design as a staff engineer would in an RFC review. Step 1: confirm the proposed design actually satisfies every stated goal and respects every non-goal and constraint. Step 2: check that each significant decision is justified against the documented alternatives — flag any choice asserted without reasoning. Step 3: verify the risks/trade-offs section is honest (not just 'no risks') and the rollout plan addresses backward compatibility and a way to back out. Step 4: confirm a testing/validation plan ties back to the success metrics. Step 5: list concrete gaps with the section and the fix needed, recorded as PASS/FAIL against the scope checklist. Write the findings via write_task_note AND to {{workPath}}/review.md. Remaining gaps must be fixed in the write phase before this passes.\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": "reviewer",
+      "advanceWhen": {
+        "file": "{{workPath}}/review.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/spec.md",
+            "bytes": 1500,
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/spec.md",
+            "pattern": "(?:^|\\n)#{1,3}\\s+\\S",
+            "flags": "i",
+            "label": "at least one markdown heading",
+            "artifact": true
+          }
+        ],
+        "onReject": "review",
+        "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": "QA the design doc against the locked criteria. Step 1: read {{workPath}}/spec.md end to end. Step 2: check EACH acceptance criterion: problem + context stated, goals AND non-goals present, constraints captured, the proposed design includes a diagram and concrete interfaces/data model, alternatives are documented with reasons for rejection, risks/trade-offs are honest, a rollout/migration plan with a back-out path exists, and a validation plan ties to the success metrics. Step 3: confirm decisions are justified rather than asserted, folding in {{workPath}}/review.md findings. Write PASS/FAIL per criterion with the offending section on any FAIL.\n\nThe deliverable lives in the project's artifacts drawer — open `{{workPath}}/spec.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}}/spec.md",
+          "artifact": true
+        }
+      ],
+      "next": "write",
+      "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.0.3",
+  "releasedAt": "2026-09-01T20:00:00Z",
+  "minGezelVersion": "1.26233"
+}

package/data/craftbook-templates/sp/spec-doc/versions/1.0.3/test.json

@@ -0,0 +1,104 @@
+{
+  "schemaVersion": 1,
+  "title": "Technical Design Doc smoke eval",
+  "objective": "Self-contained smoke eval for the Technical Design Doc 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": "Technical Design Doc Eval",
+    "about": "Self-contained eval project for spec-doc. Seeded inputs are under workspace/source or workspace/fixtures; final deliverable is workspace/analysis.md.",
+    "missionObjectives": "Use the Technical Design Doc 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": "# Technical Design Doc 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: spec-doc - Technical Design Doc.\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"
+    }
+  },
+  "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"
+  ]
+}