@bendyline/gilde 0.1.37 → 0.1.39

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

@@ -0,0 +1,448 @@
+{
+  "id": "spec-authoring",
+  "name": "Spec Authoring",
+  "description": "Turn a rough intent into a backlog-ready spec: interrogate scope and requirements against the real code, then file a well-formed, unambiguous issue.",
+  "basedOn": {
+    "name": "gstack",
+    "url": "https://github.com/garrytan/gstack"
+  },
+  "plan": "Turn an already-approved intent into an implementation-ready workspace specification. Inspect the real project before asking questions, resolve one consequential decision at a time, and leave no hidden architecture choice to the implementer. Acceptance criteria must be pass/fail, references must use real paths, and risky changes need verification and rollback. The canonical deliverable stays in the workspace; publishing it elsewhere is a separate user-authorized action.",
+  "entryStepId": "inspect",
+  "triggers": [
+    "spec this out",
+    "file an issue",
+    "write up a ticket",
+    "turn this into an issue",
+    "make this a github issue",
+    "turn this into a backlog item"
+  ],
+  "command": "spec-authoring",
+  "steps": [
+    {
+      "id": "inspect",
+      "name": "Inspect the current system",
+      "description": "Map present behavior, relevant code, conventions, dependencies, tests, and constraints.",
+      "prompt": "Read the approved intent and inspect the relevant workspace before asking the user anything. Trace current behavior through entry points, interfaces, data models, dependencies, tests, and adjacent patterns. Record exact paths and what each proves. Identify root cause for bugs, compatibility boundaries, security or migration risks, and unknowns that cannot be answered from the project. Do not design the change yet.\n\nObservable handoff: write the completed result to `specs/source-audit.md` in the workspace with `write_file`. Do not merely describe what the file would contain. Re-read it with `read_file` before finishing this phase and repair any incomplete sections.",
+      "suggestedRole": "principal engineer",
+      "advanceWhen": {
+        "file": "specs/source-audit.md",
+        "minBytes": 1000,
+        "sniff": "nonempty",
+        "requireChange": true,
+        "goto": "resolve-decisions"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "specs/source-audit.md",
+            "bytes": 1000
+          },
+          {
+            "kind": "sniff",
+            "file": "specs/source-audit.md",
+            "sniff": "nonempty"
+          },
+          {
+            "kind": "contains",
+            "file": "specs/source-audit.md",
+            "pattern": "^##\\s+Current behavior",
+            "flags": "im",
+            "label": "Current behavior section"
+          },
+          {
+            "kind": "contains",
+            "file": "specs/source-audit.md",
+            "pattern": "^##\\s+Source map",
+            "flags": "im",
+            "label": "Source map section"
+          },
+          {
+            "kind": "contains",
+            "file": "specs/source-audit.md",
+            "pattern": "^##\\s+Conventions",
+            "flags": "im",
+            "label": "Conventions section"
+          },
+          {
+            "kind": "contains",
+            "file": "specs/source-audit.md",
+            "pattern": "^##\\s+Constraints",
+            "flags": "im",
+            "label": "Constraints section"
+          },
+          {
+            "kind": "contains",
+            "file": "specs/source-audit.md",
+            "pattern": "^##\\s+Unknowns",
+            "flags": "im",
+            "label": "Unknowns section"
+          }
+        ],
+        "onReject": "inspect",
+        "maxAttempts": 3
+      },
+      "next": "resolve-decisions"
+    },
+    {
+      "id": "resolve-decisions",
+      "name": "Resolve scope and design decisions",
+      "description": "Close consequential ambiguities and record alternatives, rationale, and boundaries.",
+      "prompt": "Use `specs/source-audit.md` to enumerate only decisions the workspace cannot settle. Ask the user one consequential question at a time with `ask_user_question`, supplying a recommendation and trade-offs. In unattended mode, make only reversible assumptions and label them. Record the selected architecture, data and interface shapes, compatibility choices, dependency order, out-of-scope items, alternatives rejected, and decisions still blocked.\n\nObservable handoff: write the completed result to `specs/decision-log.md` in the workspace with `write_file`. Do not merely describe what the file would contain. Re-read it with `read_file` before finishing this phase and repair any incomplete sections.",
+      "suggestedRole": "solution architect",
+      "consumes": [
+        {
+          "file": "specs/source-audit.md"
+        }
+      ],
+      "advanceWhen": {
+        "file": "specs/decision-log.md",
+        "minBytes": 900,
+        "sniff": "nonempty",
+        "requireChange": true,
+        "goto": "write-spec"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "specs/decision-log.md",
+            "bytes": 900
+          },
+          {
+            "kind": "sniff",
+            "file": "specs/decision-log.md",
+            "sniff": "nonempty"
+          },
+          {
+            "kind": "contains",
+            "file": "specs/decision-log.md",
+            "pattern": "^##\\s+Scope",
+            "flags": "im",
+            "label": "Scope section"
+          },
+          {
+            "kind": "contains",
+            "file": "specs/decision-log.md",
+            "pattern": "^##\\s+Decisions",
+            "flags": "im",
+            "label": "Decisions section"
+          },
+          {
+            "kind": "contains",
+            "file": "specs/decision-log.md",
+            "pattern": "^##\\s+Alternatives",
+            "flags": "im",
+            "label": "Alternatives section"
+          },
+          {
+            "kind": "contains",
+            "file": "specs/decision-log.md",
+            "pattern": "^##\\s+Out of scope",
+            "flags": "im",
+            "label": "Out of scope section"
+          },
+          {
+            "kind": "contains",
+            "file": "specs/decision-log.md",
+            "pattern": "^##\\s+Open blockers",
+            "flags": "im",
+            "label": "Open blockers section"
+          }
+        ],
+        "onReject": "resolve-decisions",
+        "maxAttempts": 3
+      },
+      "next": "write-spec"
+    },
+    {
+      "id": "write-spec",
+      "name": "Write the implementation specification",
+      "description": "Produce a backlog-ready spec with concrete interfaces, sequencing, tests, and rollback.",
+      "prompt": "Synthesize the source audit and decision log into a self-contained implementation specification. Include current versus proposed behavior, precise file changes, actual schema or API shapes where relevant, dependency-ordered work, measurable acceptance criteria, a testing pyramid, observability, rollout and rollback, effort by component, and explicit exclusions. Split work that cannot be completed safely as one bounded change. Use real workspace paths; never manufacture line numbers or execution results.\n\nObservable handoff: write the completed result to `specs/implementation-spec.md` in the workspace with `write_file`. Do not merely describe what the file would contain. Re-read it with `read_file` before finishing this phase and repair any incomplete sections.",
+      "suggestedRole": "specification writer",
+      "advanceWhen": {
+        "file": "specs/implementation-spec.md",
+        "minBytes": 1800,
+        "sniff": "nonempty",
+        "requireChange": true,
+        "goto": "evaluate"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "specs/implementation-spec.md",
+            "bytes": 1800
+          },
+          {
+            "kind": "sniff",
+            "file": "specs/implementation-spec.md",
+            "sniff": "nonempty"
+          },
+          {
+            "kind": "contains",
+            "file": "specs/implementation-spec.md",
+            "pattern": "^##\\s+Context",
+            "flags": "im",
+            "label": "Context section"
+          },
+          {
+            "kind": "contains",
+            "file": "specs/implementation-spec.md",
+            "pattern": "^##\\s+Current state",
+            "flags": "im",
+            "label": "Current state section"
+          },
+          {
+            "kind": "contains",
+            "file": "specs/implementation-spec.md",
+            "pattern": "^##\\s+Proposed change",
+            "flags": "im",
+            "label": "Proposed change section"
+          },
+          {
+            "kind": "contains",
+            "file": "specs/implementation-spec.md",
+            "pattern": "^##\\s+Implementation details",
+            "flags": "im",
+            "label": "Implementation details section"
+          },
+          {
+            "kind": "contains",
+            "file": "specs/implementation-spec.md",
+            "pattern": "^##\\s+Acceptance criteria",
+            "flags": "im",
+            "label": "Acceptance criteria section"
+          },
+          {
+            "kind": "contains",
+            "file": "specs/implementation-spec.md",
+            "pattern": "^##\\s+Testing plan",
+            "flags": "im",
+            "label": "Testing plan section"
+          },
+          {
+            "kind": "contains",
+            "file": "specs/implementation-spec.md",
+            "pattern": "^##\\s+Rollback plan",
+            "flags": "im",
+            "label": "Rollback plan section"
+          },
+          {
+            "kind": "contains",
+            "file": "specs/implementation-spec.md",
+            "pattern": "^##\\s+Out of scope",
+            "flags": "im",
+            "label": "Out of scope section"
+          },
+          {
+            "kind": "contains",
+            "file": "specs/implementation-spec.md",
+            "pattern": "^##\\s+File reference",
+            "flags": "im",
+            "label": "File reference section"
+          }
+        ],
+        "onReject": "write-spec",
+        "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 `specs/implementation-spec.md`, `specs/source-audit.md`, `specs/decision-log.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 material current-state claim and file reference traces to inspected workspace evidence.\n2. The proposed architecture, interfaces, data shapes, and sequencing leave no hidden design decision to the implementer.\n3. Acceptance criteria are individually observable and pass/fail rather than subjective.\n4. The testing plan covers unit, integration, and end-to-end layers in proportion to risk.\n5. Migration, compatibility, observability, rollout, and rollback are addressed when relevant.\n6. Scope is bounded, exclusions are explicit, and unresolved blockers are not disguised as assumptions.\n\nOpen `specs/implementation-spec.md`, `specs/source-audit.md`, `specs/decision-log.md` with `read_file`. Write the evidence-backed review to `{{workPath}}/reviews/spec-authoring-review.md` in the artifacts drawer with `write_artifact`. 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": "engineering reviewer",
+      "consumes": [
+        {
+          "file": "specs/implementation-spec.md"
+        },
+        {
+          "file": "specs/source-audit.md"
+        },
+        {
+          "file": "specs/decision-log.md"
+        }
+      ],
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/reviews/spec-authoring-review.md",
+            "bytes": 400,
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/reviews/spec-authoring-review.md",
+            "pattern": "Verdict:\\s*(?:PASS|REVISE)",
+            "flags": "i",
+            "label": "explicit PASS or REVISE verdict",
+            "artifact": true
+          }
+        ],
+        "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 `{{workPath}}/reviews/spec-authoring-review.md` with `read_artifact` and repair every failed criterion in `specs/implementation-spec.md`, `specs/source-audit.md`, `specs/decision-log.md`. Make changes on each file's declared surface (`write_artifact` for artifact inputs, `write_file` for workspace inputs), not in task notes or a reply. Preserve evidence that already passed. Re-run or re-check anything the reviewer found unproven. Ensure `specs/implementation-spec.md` is genuinely updated this turn so the repair is observable, then hand it back for independent evaluation.",
+      "suggestedRole": "specification writer",
+      "consumes": [
+        {
+          "file": "{{workPath}}/reviews/spec-authoring-review.md",
+          "artifact": true
+        },
+        {
+          "file": "specs/implementation-spec.md"
+        },
+        {
+          "file": "specs/source-audit.md"
+        },
+        {
+          "file": "specs/decision-log.md"
+        }
+      ],
+      "advanceWhen": {
+        "file": "specs/implementation-spec.md",
+        "minBytes": 1800,
+        "sniff": "nonempty",
+        "requireChange": true,
+        "goto": "evaluate"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "specs/implementation-spec.md",
+            "bytes": 1800
+          },
+          {
+            "kind": "sniff",
+            "file": "specs/implementation-spec.md",
+            "sniff": "nonempty"
+          },
+          {
+            "kind": "contains",
+            "file": "specs/implementation-spec.md",
+            "pattern": "^##\\s+Context",
+            "flags": "im",
+            "label": "Context section"
+          },
+          {
+            "kind": "contains",
+            "file": "specs/implementation-spec.md",
+            "pattern": "^##\\s+Current state",
+            "flags": "im",
+            "label": "Current state section"
+          },
+          {
+            "kind": "contains",
+            "file": "specs/implementation-spec.md",
+            "pattern": "^##\\s+Proposed change",
+            "flags": "im",
+            "label": "Proposed change section"
+          },
+          {
+            "kind": "contains",
+            "file": "specs/implementation-spec.md",
+            "pattern": "^##\\s+Implementation details",
+            "flags": "im",
+            "label": "Implementation details section"
+          },
+          {
+            "kind": "contains",
+            "file": "specs/implementation-spec.md",
+            "pattern": "^##\\s+Acceptance criteria",
+            "flags": "im",
+            "label": "Acceptance criteria section"
+          },
+          {
+            "kind": "contains",
+            "file": "specs/implementation-spec.md",
+            "pattern": "^##\\s+Testing plan",
+            "flags": "im",
+            "label": "Testing plan section"
+          },
+          {
+            "kind": "contains",
+            "file": "specs/implementation-spec.md",
+            "pattern": "^##\\s+Rollback plan",
+            "flags": "im",
+            "label": "Rollback plan section"
+          },
+          {
+            "kind": "contains",
+            "file": "specs/implementation-spec.md",
+            "pattern": "^##\\s+Out of scope",
+            "flags": "im",
+            "label": "Out of scope section"
+          },
+          {
+            "kind": "contains",
+            "file": "specs/implementation-spec.md",
+            "pattern": "^##\\s+File reference",
+            "flags": "im",
+            "label": "File reference section"
+          }
+        ],
+        "onReject": "repair",
+        "maxAttempts": 3
+      },
+      "next": "evaluate"
+    },
+    {
+      "id": "finish",
+      "name": "Finish",
+      "description": "All deterministic and reviewer criteria passed.",
+      "prompt": "The independent review passed. Read `{{workPath}}/reviews/spec-authoring-review.md` with `read_artifact`, then use `write_task_note` to record a concise DONE summary with the final deliverable paths (`specs/implementation-spec.md`, `specs/source-audit.md`, `specs/decision-log.md`) and the evidence that each acceptance criterion passed. Report DONE without starting new work.",
+      "suggestedRole": "project lead",
+      "consumes": [
+        {
+          "file": "{{workPath}}/reviews/spec-authoring-review.md",
+          "artifact": true
+        }
+      ],
+      "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 `{{workPath}}/reviews/spec-authoring-review.md` with `read_artifact`, 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",
+      "consumes": [
+        {
+          "file": "{{workPath}}/reviews/spec-authoring-review.md",
+          "artifact": true
+        }
+      ],
+      "terminal": true
+    }
+  ],
+  "version": "2.0.4",
+  "releasedAt": "2026-08-21T00:00:00Z",
+  "paramSchema": {
+    "type": "object",
+    "properties": {
+      "workPath": {
+        "type": "string",
+        "title": "Working folder",
+        "description": "Per-task working folder in the artifacts drawer. Defaults to this task's own folder so runs never collide; override with a stable name when you deliberately want runs to share files.",
+        "default": "{{task.dir}}"
+      }
+    }
+  },
+  "minGezelVersion": "1.26233"
+}

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

@@ -0,0 +1,165 @@
+{
+  "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"
+      }
+    ],
+    "craftbookParams": {
+      "workPath": "tasks/eval"
+    }
+  },
+  "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"
+  ]
+}