@bendyline/gilde 0.1.17 → 0.1.18

package/authoring/gstack/evals/spec.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": {
+    "taskGraph": {
+      "requireCraftbookTask": true,
+      "requireTerminalStep": true
+    },
+    "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,
+      "requireCraftbookTask": true,
+      "checks": [
+        {
+          "kind": "contains",
+          "file": "task-notes.md",
+          "pattern": "\\bDONE\\b[\\s\\S]*specs/implementation-spec\\.md",
+          "label": "terminal craftbook note names the spec"
+        }
+      ]
+    },
+    "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/authoring/gstack/overlays/cso.json

@@ -0,0 +1,132 @@
+{
+  "workflow": {
+    "plan": "Run an evidence-first architecture review without changing product code. Trace trust boundaries, data flows, identity, authorization, secrets, dependencies, and operational controls from actual workspace material. Never copy secret values into notes or reports. Separate confirmed findings from hypotheses and research gaps. Rank actionable findings by severity, exploitability, confidence, and blast radius, then give the owner a practical remediation and verification path.",
+    "phases": [
+      {
+        "id": "model-system",
+        "name": "Map assets and trust boundaries",
+        "description": "Establish the system, sensitive assets, actors, data flows, controls, and review limits.",
+        "suggestedRole": "security architect",
+        "prompt": "Inspect architecture notes, entry points, deployment and dependency metadata, configuration schemas, authentication and authorization code, persistence, network surfaces, and security tests. Map sensitive assets, actors, privilege levels, trust boundaries, inbound and outbound data flows, third parties, and existing controls. Record only secret names or locations, never values. State scope exclusions and missing evidence explicitly.",
+        "output": {
+          "path": "security/review-scope.md",
+          "minBytes": 1000,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+System scope",
+              "label": "System scope section"
+            },
+            {
+              "pattern": "^##\\s+Assets",
+              "label": "Assets section"
+            },
+            {
+              "pattern": "^##\\s+Actors and privileges",
+              "label": "Actors and privileges section"
+            },
+            {
+              "pattern": "^##\\s+Trust boundaries",
+              "label": "Trust boundaries section"
+            },
+            {
+              "pattern": "^##\\s+Data flows",
+              "label": "Data flows section"
+            },
+            {
+              "pattern": "^##\\s+Review limits",
+              "label": "Review limits section"
+            }
+          ]
+        }
+      },
+      {
+        "id": "audit",
+        "name": "Audit controls and prove findings",
+        "description": "Walk the attack surface systematically and maintain an evidence-backed findings register.",
+        "suggestedRole": "application security engineer",
+        "prompt": "Use `security/review-scope.md` to inspect secrets handling, dependency and supply-chain controls, authentication, session management, authorization at every mutation sink, input handling, output encoding, injection boundaries, file and path access, cryptography, logging, privacy, network exposure, update paths, and failure behavior. For every candidate, capture the exact evidence path, attack preconditions, affected asset, impact, confidence, and a safe validation method. Do not claim a vulnerability from a pattern match alone. If external advisory research is unavailable, label dependency status unverified rather than guessing.",
+        "output": {
+          "path": "security/findings-register.md",
+          "minBytes": 1300,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Coverage",
+              "label": "Coverage section"
+            },
+            {
+              "pattern": "^##\\s+Confirmed findings",
+              "label": "Confirmed findings section"
+            },
+            {
+              "pattern": "^##\\s+Rejected hypotheses",
+              "label": "Rejected hypotheses section"
+            },
+            {
+              "pattern": "^##\\s+Research gaps",
+              "label": "Research gaps section"
+            },
+            {
+              "pattern": "Severity.*Confidence.*Evidence",
+              "label": "finding table with severity, confidence, and evidence"
+            }
+          ]
+        }
+      },
+      {
+        "id": "report",
+        "name": "Write the security architecture review",
+        "description": "Deliver prioritized findings, strengths, remediation, and retest instructions for owners.",
+        "suggestedRole": "security reviewer",
+        "prompt": "Synthesize the scope and findings register into a decision-ready report. Start with an executive risk posture and the strongest controls already working. For each confirmed finding, include severity, confidence, evidence path, causal control gap, realistic attack path, impact, prioritized remediation, owner, verification, and residual risk. Group systemic themes, distinguish quick containment from durable fixes, and state areas not verified. Do not include exploit payloads or sensitive values unless the user explicitly needs a safe proof and policy permits it.",
+        "output": {
+          "path": "security/security-architecture-review.md",
+          "minBytes": 1600,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Executive risk posture",
+              "label": "Executive risk posture section"
+            },
+            {
+              "pattern": "^##\\s+What is working",
+              "label": "What is working section"
+            },
+            {
+              "pattern": "^##\\s+Prioritized findings",
+              "label": "Prioritized findings section"
+            },
+            {
+              "pattern": "^##\\s+Remediation plan",
+              "label": "Remediation plan section"
+            },
+            {
+              "pattern": "^##\\s+Verification",
+              "label": "Verification section"
+            },
+            {
+              "pattern": "^##\\s+Unverified areas",
+              "label": "Unverified areas section"
+            }
+          ]
+        }
+      }
+    ],
+    "review": {
+      "artifactPath": "security/security-architecture-review.md",
+      "relatedPaths": [
+        "security/review-scope.md",
+        "security/findings-register.md"
+      ],
+      "reviewPath": "reviews/security-architecture-review-evaluation.md",
+      "reviewerRole": "independent security reviewer",
+      "repairRole": "application security engineer",
+      "criteria": [
+        "Scope, assets, trust boundaries, actors, data flows, and review limits are explicit.",
+        "Coverage includes identity, authorization, secrets, dependencies, inputs, storage, network, logging, updates, and operational failure paths where applicable.",
+        "Every confirmed finding has inspectable evidence, realistic preconditions, impact, severity, and confidence; pattern-only suspicions are not promoted.",
+        "No secret value or unsafe exploit detail is exposed in the deliverables.",
+        "Remediation is prioritized, owned, verifiable, and distinguishes containment from durable control repair.",
+        "Positive controls, rejected hypotheses, residual risk, and unverified areas are reported honestly."
+      ]
+    }
+  }
+}

package/authoring/gstack/overlays/design-consultation.json

@@ -0,0 +1,153 @@
+{
+  "set": {
+    "toolsets": [
+      {
+        "toolsetId": "@playwright/mcp",
+        "optional": true,
+        "reason": "render and inspect the generated design-system preview when browser tools are available"
+      }
+    ]
+  },
+  "workflow": {
+    "plan": "Build one coherent visual system from product purpose, user needs, existing interface evidence, and a memorable design intent. Make opinionated recommendations with reasons instead of presenting an arbitrary menu. Preserve useful existing conventions, state accessibility constraints, and distinguish observed patterns from outside inspiration. Deliver both a durable DESIGN.md and a self-contained HTML preview that makes the system inspectable before implementation.",
+    "phases": [
+      {
+        "id": "audit-interface",
+        "name": "Audit the current interface",
+        "description": "Map the product, users, existing visual language, implementation constraints, and inconsistencies.",
+        "suggestedRole": "product designer",
+        "prompt": "Inspect the project description, interface entry points, components, styles, assets, screenshots, and accessibility conventions with workspace tools. Identify the product type, primary users and jobs, current design tokens and patterns worth preserving, inconsistencies, technical constraints, and missing states. If no interface exists, document that and work from the product brief rather than inventing current-state claims.",
+        "output": {
+          "path": "design/current-state-audit.md",
+          "minBytes": 900,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Product and users",
+              "label": "Product and users section"
+            },
+            {
+              "pattern": "^##\\s+Existing language",
+              "label": "Existing language section"
+            },
+            {
+              "pattern": "^##\\s+Inconsistencies",
+              "label": "Inconsistencies section"
+            },
+            {
+              "pattern": "^##\\s+Constraints",
+              "label": "Constraints section"
+            },
+            {
+              "pattern": "^##\\s+Accessibility",
+              "label": "Accessibility section"
+            }
+          ]
+        }
+      },
+      {
+        "id": "design-brief",
+        "name": "Lock the design brief",
+        "description": "Define the memorable intent, principles, references, exclusions, and success tests.",
+        "suggestedRole": "design strategist",
+        "prompt": "Use the audit to pre-fill a concise design brief. Ask the user one high-leverage question at a time with `ask_user_question`: confirm audience and product posture, the one thing the experience should be remembered for, useful references, strong dislikes, brand or accessibility constraints, and the most important workflows. When research tools are available and the user wants it, collect relevant outside patterns with sources; otherwise label proposals as design judgment. Recommend a direction and explain why it fits.",
+        "output": {
+          "path": "design/design-brief.md",
+          "minBytes": 800,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Memorable intent",
+              "label": "Memorable intent section"
+            },
+            {
+              "pattern": "^##\\s+Design principles",
+              "label": "Design principles section"
+            },
+            {
+              "pattern": "^##\\s+References",
+              "label": "References section"
+            },
+            {
+              "pattern": "^##\\s+Avoid",
+              "label": "Avoid section"
+            },
+            {
+              "pattern": "^##\\s+Success tests",
+              "label": "Success tests section"
+            }
+          ]
+        }
+      },
+      {
+        "id": "propose-system",
+        "name": "Propose and render the design system",
+        "description": "Specify the system and render a realistic, accessible preview of its important states.",
+        "suggestedRole": "design systems lead",
+        "prompt": "Create `DESIGN.md` from the audit and brief, covering foundations, type scale, color roles and contrast, spacing, grid, shape, elevation, iconography, motion, components, states, responsive behavior, content voice, accessibility, and adoption sequence. Use exact reusable tokens and explain how every choice serves the memorable intent. Also create `previews/design-system.html`: a self-contained, responsive page that applies the proposed tokens to representative navigation, type, controls, cards, data or content, empty, loading, error, focus, hover, and disabled states. Inspect it with browser tools when available and record what was actually checked.",
+        "output": {
+          "path": "DESIGN.md",
+          "minBytes": 1800,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Design intent",
+              "label": "Design intent section"
+            },
+            {
+              "pattern": "^##\\s+Tokens",
+              "label": "Tokens section"
+            },
+            {
+              "pattern": "^##\\s+Typography",
+              "label": "Typography section"
+            },
+            {
+              "pattern": "^##\\s+Color",
+              "label": "Color section"
+            },
+            {
+              "pattern": "^##\\s+Components and states",
+              "label": "Components and states section"
+            },
+            {
+              "pattern": "^##\\s+Accessibility",
+              "label": "Accessibility section"
+            },
+            {
+              "pattern": "^##\\s+Adoption",
+              "label": "Adoption section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "minBytes",
+              "file": "previews/design-system.html",
+              "bytes": 1800
+            },
+            {
+              "kind": "htmlLint",
+              "file": "previews/design-system.html"
+            }
+          ]
+        }
+      }
+    ],
+    "review": {
+      "artifactPath": "DESIGN.md",
+      "relatedPaths": [
+        "previews/design-system.html",
+        "design/current-state-audit.md",
+        "design/design-brief.md"
+      ],
+      "reviewPath": "reviews/design-system-consultation-review.md",
+      "reviewerRole": "product design reviewer",
+      "repairRole": "design systems lead",
+      "criteria": [
+        "The system visibly serves the product, users, memorable intent, and real implementation constraints.",
+        "Typography, color, spacing, layout, shape, motion, content, and components form a coherent system rather than independent preferences.",
+        "Tokens are specific and reusable, with responsive rules and all important interaction states.",
+        "Contrast, focus, reduced motion, keyboard use, readability, and error communication have explicit treatment.",
+        "The HTML preview is complete, renders without structural errors, and demonstrates representative states rather than a static swatch sheet.",
+        "Existing strengths, outside sources, design judgment, and unresolved assumptions are labeled honestly."
+      ]
+    }
+  }
+}

package/authoring/gstack/overlays/document-generate.json

@@ -0,0 +1,124 @@
+{
+  "workflow": {
+    "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.",
+    "phases": [
+      {
+        "id": "inventory",
+        "name": "Inventory the documentation surface",
+        "description": "Map readers, public interfaces, source evidence, existing coverage, and gaps.",
+        "suggestedRole": "technical researcher",
+        "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.",
+        "output": {
+          "path": "notes/documentation-inventory.md",
+          "minBytes": 900,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Scope",
+              "label": "Scope section"
+            },
+            {
+              "pattern": "^##\\s+Readers",
+              "label": "Readers section"
+            },
+            {
+              "pattern": "^##\\s+Public surface",
+              "label": "Public surface section"
+            },
+            {
+              "pattern": "^##\\s+Source map",
+              "label": "Source map section"
+            },
+            {
+              "pattern": "^##\\s+Coverage gaps",
+              "label": "Coverage gaps section"
+            }
+          ]
+        }
+      },
+      {
+        "id": "plan-docs",
+        "name": "Design the documentation set",
+        "description": "Choose the right document type for each reader need and lock verification criteria.",
+        "suggestedRole": "documentation architect",
+        "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.",
+        "output": {
+          "path": "notes/documentation-plan.md",
+          "minBytes": 900,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Document matrix",
+              "label": "Document matrix section"
+            },
+            {
+              "pattern": "^##\\s+Information architecture",
+              "label": "Information architecture section"
+            },
+            {
+              "pattern": "^##\\s+Verification plan",
+              "label": "Verification plan section"
+            },
+            {
+              "pattern": "^##\\s+Deferred coverage",
+              "label": "Deferred coverage section"
+            }
+          ]
+        }
+      },
+      {
+        "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.",
+        "suggestedRole": "technical writer",
+        "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.",
+        "output": {
+          "path": "docs/documentation-index.md",
+          "minBytes": 1200,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Documentation map",
+              "label": "Documentation map section"
+            },
+            {
+              "pattern": "^##\\s+Tutorials",
+              "label": "Tutorials section"
+            },
+            {
+              "pattern": "^##\\s+How-to guides",
+              "label": "How-to guides section"
+            },
+            {
+              "pattern": "^##\\s+Reference",
+              "label": "Reference section"
+            },
+            {
+              "pattern": "^##\\s+Explanation",
+              "label": "Explanation section"
+            },
+            {
+              "pattern": "^##\\s+Verification",
+              "label": "Verification section"
+            }
+          ]
+        }
+      }
+    ],
+    "review": {
+      "artifactPath": "docs/documentation-index.md",
+      "relatedPaths": [
+        "notes/documentation-inventory.md",
+        "notes/documentation-plan.md"
+      ],
+      "reviewPath": "reviews/technical-documentation-review.md",
+      "reviewerRole": "technical editor",
+      "repairRole": "technical writer",
+      "criteria": [
+        "Every in-scope public item is documented or explicitly deferred with a reason.",
+        "Claims, types, defaults, constraints, and examples agree with the cited implementation or tests.",
+        "Tutorial, how-to, reference, and explanation content serve distinct reader jobs without needless duplication.",
+        "Commands and examples have credible verification results or are clearly marked unexecuted.",
+        "Every produced page is linked from the index and all internal links resolve.",
+        "The prose is concrete, readable, and includes real troubleshooting and trade-offs where relevant."
+      ]
+    }
+  }
+}