@bendyline/gilde 0.1.24 → 0.1.26

package/data/craftbook-templates/sp/spec-authoring/versions/2.0.1/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/te/technical-documentation/versions/2.0.1/craftbook.json

@@ -0,0 +1,343 @@
+{
+  "id": "technical-documentation",
+  "name": "Technical Documentation",
+  "description": "Generate a coherent documentation set from a codebase, organized by the Diataxis model (tutorials, how-to guides, reference, explanation), with cross-links and a coverage pass.",
+  "basedOn": {
+    "name": "gstack",
+    "url": "https://github.com/garrytan/gstack"
+  },
+  "plan": "Treat documentation as a tested product surface. Research implementation, tests, configuration, and existing prose before writing. Separate learning-oriented tutorials, task-oriented how-to guides, factual reference, and explanatory rationale. Every public claim must trace to a workspace source, every example must be verified when the environment permits, and every produced page must be reachable from the documentation index.",
+  "entryStepId": "inventory",
+  "triggers": [
+    "write docs for this",
+    "generate documentation",
+    "document this feature",
+    "create a tutorial",
+    "write a how-to",
+    "explain this module",
+    "docs for this project"
+  ],
+  "command": "technical-documentation",
+  "steps": [
+    {
+      "id": "inventory",
+      "name": "Inventory the documentation surface",
+      "description": "Map readers, public interfaces, source evidence, existing coverage, and gaps.",
+      "prompt": "Confirm the requested scope from the task and project context. Inspect the project guide, package or build metadata, entry points, public interfaces, configuration, examples, tests, and current docs with workspace tools. Build an exact inventory of the entities in scope, their source paths, intended readers, existing documentation, missing coverage, and risky claims that need verification. Do not start polished prose yet.\n\nObservable handoff: write the completed result to `notes/documentation-inventory.md` in the workspace. Do not merely describe what the file would contain. Re-read it before finishing this phase and repair any incomplete sections.",
+      "suggestedRole": "technical researcher",
+      "advanceWhen": {
+        "file": "notes/documentation-inventory.md",
+        "minBytes": 900,
+        "sniff": "nonempty",
+        "requireChange": true,
+        "goto": "plan-docs"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "notes/documentation-inventory.md",
+            "bytes": 900
+          },
+          {
+            "kind": "sniff",
+            "file": "notes/documentation-inventory.md",
+            "sniff": "nonempty"
+          },
+          {
+            "kind": "contains",
+            "file": "notes/documentation-inventory.md",
+            "pattern": "^##\\s+Scope",
+            "flags": "im",
+            "label": "Scope section"
+          },
+          {
+            "kind": "contains",
+            "file": "notes/documentation-inventory.md",
+            "pattern": "^##\\s+Readers",
+            "flags": "im",
+            "label": "Readers section"
+          },
+          {
+            "kind": "contains",
+            "file": "notes/documentation-inventory.md",
+            "pattern": "^##\\s+Public surface",
+            "flags": "im",
+            "label": "Public surface section"
+          },
+          {
+            "kind": "contains",
+            "file": "notes/documentation-inventory.md",
+            "pattern": "^##\\s+Source map",
+            "flags": "im",
+            "label": "Source map section"
+          },
+          {
+            "kind": "contains",
+            "file": "notes/documentation-inventory.md",
+            "pattern": "^##\\s+Coverage gaps",
+            "flags": "im",
+            "label": "Coverage gaps section"
+          }
+        ],
+        "onReject": "inventory",
+        "maxAttempts": 3
+      },
+      "next": "plan-docs"
+    },
+    {
+      "id": "plan-docs",
+      "name": "Design the documentation set",
+      "description": "Choose the right document type for each reader need and lock verification criteria.",
+      "prompt": "Turn `notes/documentation-inventory.md` into a document plan. For each proposed page, state its reader, job, quadrant, destination path, evidence sources, prerequisites, cross-links, and pass/fail checks. Reuse existing conventions and update existing pages when that is clearer than duplication. Keep the set proportional to the scope, but cover every public item in the inventory or explicitly defer it with a reason.\n\nObservable handoff: write the completed result to `notes/documentation-plan.md` in the workspace. Do not merely describe what the file would contain. Re-read it before finishing this phase and repair any incomplete sections.",
+      "suggestedRole": "documentation architect",
+      "advanceWhen": {
+        "file": "notes/documentation-plan.md",
+        "minBytes": 900,
+        "sniff": "nonempty",
+        "requireChange": true,
+        "goto": "author-and-verify"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "notes/documentation-plan.md",
+            "bytes": 900
+          },
+          {
+            "kind": "sniff",
+            "file": "notes/documentation-plan.md",
+            "sniff": "nonempty"
+          },
+          {
+            "kind": "contains",
+            "file": "notes/documentation-plan.md",
+            "pattern": "^##\\s+Document matrix",
+            "flags": "im",
+            "label": "Document matrix section"
+          },
+          {
+            "kind": "contains",
+            "file": "notes/documentation-plan.md",
+            "pattern": "^##\\s+Information architecture",
+            "flags": "im",
+            "label": "Information architecture section"
+          },
+          {
+            "kind": "contains",
+            "file": "notes/documentation-plan.md",
+            "pattern": "^##\\s+Verification plan",
+            "flags": "im",
+            "label": "Verification plan section"
+          },
+          {
+            "kind": "contains",
+            "file": "notes/documentation-plan.md",
+            "pattern": "^##\\s+Deferred coverage",
+            "flags": "im",
+            "label": "Deferred coverage section"
+          }
+        ],
+        "onReject": "plan-docs",
+        "maxAttempts": 3
+      },
+      "next": "author-and-verify"
+    },
+    {
+      "id": "author-and-verify",
+      "name": "Author, link, and verify the docs",
+      "description": "Write the planned pages, validate examples and links, and expose the complete set through one index.",
+      "prompt": "Implement the approved document plan in the workspace. Keep reference factual, how-to steps actionable, tutorials quick to first result, and explanations explicit about trade-offs. Verify commands, code examples, option names, defaults, and constraints against implementation and tests; run safe examples where possible and label anything not executed. Add troubleshooting based on real failure paths. Cross-link related pages and write an index that lists every created or updated document, its reader job, quadrant, source evidence, and verification status.\n\nObservable handoff: write the completed result to `docs/documentation-index.md` in the workspace. Do not merely describe what the file would contain. Re-read it before finishing this phase and repair any incomplete sections.",
+      "suggestedRole": "technical writer",
+      "advanceWhen": {
+        "file": "docs/documentation-index.md",
+        "minBytes": 1200,
+        "sniff": "nonempty",
+        "requireChange": true,
+        "goto": "evaluate"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "docs/documentation-index.md",
+            "bytes": 1200
+          },
+          {
+            "kind": "sniff",
+            "file": "docs/documentation-index.md",
+            "sniff": "nonempty"
+          },
+          {
+            "kind": "contains",
+            "file": "docs/documentation-index.md",
+            "pattern": "^##\\s+Documentation map",
+            "flags": "im",
+            "label": "Documentation map section"
+          },
+          {
+            "kind": "contains",
+            "file": "docs/documentation-index.md",
+            "pattern": "^##\\s+Tutorials",
+            "flags": "im",
+            "label": "Tutorials section"
+          },
+          {
+            "kind": "contains",
+            "file": "docs/documentation-index.md",
+            "pattern": "^##\\s+How-to guides",
+            "flags": "im",
+            "label": "How-to guides section"
+          },
+          {
+            "kind": "contains",
+            "file": "docs/documentation-index.md",
+            "pattern": "^##\\s+Reference",
+            "flags": "im",
+            "label": "Reference section"
+          },
+          {
+            "kind": "contains",
+            "file": "docs/documentation-index.md",
+            "pattern": "^##\\s+Explanation",
+            "flags": "im",
+            "label": "Explanation section"
+          },
+          {
+            "kind": "contains",
+            "file": "docs/documentation-index.md",
+            "pattern": "^##\\s+Verification",
+            "flags": "im",
+            "label": "Verification section"
+          }
+        ],
+        "onReject": "author-and-verify",
+        "maxAttempts": 3
+      },
+      "next": "evaluate"
+    },
+    {
+      "id": "evaluate",
+      "name": "Evaluate the deliverable",
+      "description": "Independently grade the observable deliverable and route it to finish, repair, or user escalation.",
+      "prompt": "Review `docs/documentation-index.md`, `notes/documentation-inventory.md`, `notes/documentation-plan.md` against every criterion below. Inspect the underlying evidence files named by the workflow; do not grade from the author's summary alone.\n\n1. Every in-scope public item is documented or explicitly deferred with a reason.\n2. Claims, types, defaults, constraints, and examples agree with the cited implementation or tests.\n3. Tutorial, how-to, reference, and explanation content serve distinct reader jobs without needless duplication.\n4. Commands and examples have credible verification results or are clearly marked unexecuted.\n5. Every produced page is linked from the index and all internal links resolve.\n6. The prose is concrete, readable, and includes real troubleshooting and trade-offs where relevant.\n\nWrite an evidence-backed review to `reviews/technical-documentation-review.md`. Give each criterion a PASS or FAIL with a concrete path, excerpt, measurement, or observed behavior. End with exactly `Verdict: PASS` or `Verdict: REVISE`. Then use `advance_task_step` for the active task: PASS routes to `finish`; REVISE routes to `repair` for review rounds 1 through 2, and the 3th REVISE routes to `needs-user`. Never route to finish while a criterion is unmet.",
+      "suggestedRole": "technical editor",
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "reviews/technical-documentation-review.md",
+            "bytes": 400
+          },
+          {
+            "kind": "contains",
+            "file": "reviews/technical-documentation-review.md",
+            "pattern": "Verdict:\\s*(?:PASS|REVISE)",
+            "flags": "i",
+            "label": "explicit PASS or REVISE verdict"
+          }
+        ],
+        "onReject": "evaluate",
+        "maxAttempts": 3
+      },
+      "next": "repair"
+    },
+    {
+      "id": "repair",
+      "name": "Repair the deliverable",
+      "description": "Fix only the concrete gaps from the latest independent review.",
+      "prompt": "Read `reviews/technical-documentation-review.md` and repair every failed criterion in `docs/documentation-index.md`, `notes/documentation-inventory.md`, `notes/documentation-plan.md`. Make the changes in the actual workspace files, not just in task notes or a reply. Preserve evidence that already passed. Re-run or re-check anything the reviewer found unproven. Ensure `docs/documentation-index.md` is genuinely updated this turn so the repair is observable, then hand it back for independent evaluation.",
+      "suggestedRole": "technical writer",
+      "advanceWhen": {
+        "file": "docs/documentation-index.md",
+        "minBytes": 1200,
+        "sniff": "nonempty",
+        "requireChange": true,
+        "goto": "evaluate"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "docs/documentation-index.md",
+            "bytes": 1200
+          },
+          {
+            "kind": "sniff",
+            "file": "docs/documentation-index.md",
+            "sniff": "nonempty"
+          },
+          {
+            "kind": "contains",
+            "file": "docs/documentation-index.md",
+            "pattern": "^##\\s+Documentation map",
+            "flags": "im",
+            "label": "Documentation map section"
+          },
+          {
+            "kind": "contains",
+            "file": "docs/documentation-index.md",
+            "pattern": "^##\\s+Tutorials",
+            "flags": "im",
+            "label": "Tutorials section"
+          },
+          {
+            "kind": "contains",
+            "file": "docs/documentation-index.md",
+            "pattern": "^##\\s+How-to guides",
+            "flags": "im",
+            "label": "How-to guides section"
+          },
+          {
+            "kind": "contains",
+            "file": "docs/documentation-index.md",
+            "pattern": "^##\\s+Reference",
+            "flags": "im",
+            "label": "Reference section"
+          },
+          {
+            "kind": "contains",
+            "file": "docs/documentation-index.md",
+            "pattern": "^##\\s+Explanation",
+            "flags": "im",
+            "label": "Explanation section"
+          },
+          {
+            "kind": "contains",
+            "file": "docs/documentation-index.md",
+            "pattern": "^##\\s+Verification",
+            "flags": "im",
+            "label": "Verification section"
+          }
+        ],
+        "onReject": "repair",
+        "maxAttempts": 3
+      },
+      "next": "evaluate"
+    },
+    {
+      "id": "finish",
+      "name": "Finish",
+      "description": "All deterministic and reviewer criteria passed.",
+      "prompt": "The independent review passed. Read `reviews/technical-documentation-review.md`, then use `write_task_note` to record a concise DONE summary with the final deliverable paths (`docs/documentation-index.md`, `notes/documentation-inventory.md`, `notes/documentation-plan.md`) and the evidence that each acceptance criterion passed. Report DONE without starting new work.",
+      "suggestedRole": "project lead",
+      "terminal": true
+    },
+    {
+      "id": "needs-user",
+      "name": "Escalate unresolved concerns",
+      "description": "The bounded repair loop ended without a defensible pass.",
+      "prompt": "The deliverable did not pass after 3 review rounds. Do not claim success. Read `reviews/technical-documentation-review.md`, then use `write_task_note` to record DONE_WITH_CONCERNS: the unmet criteria, what was attempted, the affected paths, and the smallest user decision or missing input needed to continue.",
+      "suggestedRole": "project lead",
+      "terminal": true
+    }
+  ],
+  "version": "2.0.1",
+  "releasedAt": "2026-08-13T00:00:00Z"
+}