@slowcook-ai/cli 0.3.0 → 0.4.0

package/dist/commands/refine/prompts.d.ts

@@ -0,0 +1,23 @@
+/**
+ * System prompts for the refinement agent.
+ *
+ * Two distinct calls:
+ *   1. RELATIONSHIP_ANALYST — classifies a new issue against existing specs.
+ *   2. REFINEMENT_ANALYST   — runs the clarifying-question loop and emits
+ *                              the final spec YAML.
+ *
+ * Both are designed for Claude Opus 4.7 as the default. The relationship
+ * analyst can run on Sonnet to keep costs down; refinement proper benefits
+ * from Opus-level reasoning.
+ */
+export declare const SPEC_CHECKLIST_MD = "\nA complete, testable spec covers ALL of these items. If any are missing or ambiguous, ask about them:\n\n1. **Actors** \u2014 who performs the action? (e.g., authenticated member, admin, anonymous visitor)\n2. **Preconditions** \u2014 what must be true before the action can happen? Auth status, state of prior data, feature flags, etc.\n3. **Invariants** \u2014 what must remain true regardless of input or timing? (e.g., \"ration never exceeds 15\", \"one vote per user per poll\")\n4. **API contract** (if applicable) \u2014 HTTP method, path, request shape, success response shape, error codes and when each fires\n5. **UI behavior** per relevant viewport \u00D7 color scheme \u2014 what the user sees and how they interact, at minimum: desktop_light, mobile_light, and mobile_dark\n6. **Acceptance scenarios** \u2014 concrete Given/When/Then examples that an engineer can turn into tests. Aim for 3-6, covering happy path AND edge cases.\n7. **Non-goals** \u2014 what is explicitly out of scope for this story? (e.g., \"editing reactions is a separate story\")\n";
+export declare const RELATIONSHIP_ANALYST_SYSTEM = "You are a careful spec analyst for the slowcook brewing harness.\n\nGiven a new GitHub issue and a list of existing specs (summaries + selected full bodies), classify the relationship. The goal is to preserve a ratchet: new decisions must not silently duplicate or contradict earlier decisions.\n\nClassify as one of:\n  - \"new_or_independent\": this issue addresses a concern not covered by any active spec\n  - \"overlap\": this issue substantially intersects with one or more active specs (same API, same feature, same user journey, same invariant). Could be resolved by merging, scoping to a delta, or closing as duplicate.\n  - \"contradiction\": this issue proposes something incompatible with an active spec \u2014 reverses a rule, changes a decision, breaks an invariant. The caller will check for a \"change-of-mind\" label: if present, it is authorized revocation; if absent, it is a blocker.\n\nReturn STRICTLY the following JSON, no prose before or after:\n\n{\n  \"kind\": \"new_or_independent\" | \"overlap\" | \"contradiction\",\n  \"conflicting_ids\": [\"042\", \"007\"],\n  \"reasoning\": \"one-paragraph explanation citing specific spec ids and the exact overlap/contradiction\"\n}\n\n- For \"new_or_independent\", set conflicting_ids to [].\n- For \"overlap\" and \"contradiction\", list every spec id you find, not just the strongest match.\n- \"reasoning\" should name the specs by id and cite what specifically overlaps or contradicts. Be concrete \u2014 \"story-042 defines POST /api/reactions with a 15/week ration; this issue changes the ration to 20/week\" is good.\n- If information is insufficient to classify with confidence, pick the most conservative outcome (contradiction > overlap > independent).";
+export declare const REFINEMENT_ANALYST_SYSTEM: (checklist: string) => string;
+/** Trivial, used only as a title for the draft PR. */
+export declare function draftPrTitle(storyId: string, title: string): string;
+export declare function draftPrBody(args: {
+    storyId: string;
+    issueNumber: number;
+    supersedes: string[];
+}): string;
+//# sourceMappingURL=prompts.d.ts.map

package/dist/commands/refine/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/commands/refine/prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,iBAAiB,kjCAU7B,CAAC;AAEF,eAAO,MAAM,2BAA2B,wsDAoBkG,CAAC;AAE3I,eAAO,MAAM,yBAAyB,GAAI,WAAW,MAAM,WAoDwE,CAAC;AAEpI,sDAAsD;AACtD,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,GAAG,MAAM,CAaT"}

package/dist/commands/refine/prompts.js

@@ -0,0 +1,115 @@
+/**
+ * System prompts for the refinement agent.
+ *
+ * Two distinct calls:
+ *   1. RELATIONSHIP_ANALYST — classifies a new issue against existing specs.
+ *   2. REFINEMENT_ANALYST   — runs the clarifying-question loop and emits
+ *                              the final spec YAML.
+ *
+ * Both are designed for Claude Opus 4.7 as the default. The relationship
+ * analyst can run on Sonnet to keep costs down; refinement proper benefits
+ * from Opus-level reasoning.
+ */
+export const SPEC_CHECKLIST_MD = `
+A complete, testable spec covers ALL of these items. If any are missing or ambiguous, ask about them:
+
+1. **Actors** — who performs the action? (e.g., authenticated member, admin, anonymous visitor)
+2. **Preconditions** — what must be true before the action can happen? Auth status, state of prior data, feature flags, etc.
+3. **Invariants** — what must remain true regardless of input or timing? (e.g., "ration never exceeds 15", "one vote per user per poll")
+4. **API contract** (if applicable) — HTTP method, path, request shape, success response shape, error codes and when each fires
+5. **UI behavior** per relevant viewport × color scheme — what the user sees and how they interact, at minimum: desktop_light, mobile_light, and mobile_dark
+6. **Acceptance scenarios** — concrete Given/When/Then examples that an engineer can turn into tests. Aim for 3-6, covering happy path AND edge cases.
+7. **Non-goals** — what is explicitly out of scope for this story? (e.g., "editing reactions is a separate story")
+`;
+export const RELATIONSHIP_ANALYST_SYSTEM = `You are a careful spec analyst for the slowcook brewing harness.
+
+Given a new GitHub issue and a list of existing specs (summaries + selected full bodies), classify the relationship. The goal is to preserve a ratchet: new decisions must not silently duplicate or contradict earlier decisions.
+
+Classify as one of:
+  - "new_or_independent": this issue addresses a concern not covered by any active spec
+  - "overlap": this issue substantially intersects with one or more active specs (same API, same feature, same user journey, same invariant). Could be resolved by merging, scoping to a delta, or closing as duplicate.
+  - "contradiction": this issue proposes something incompatible with an active spec — reverses a rule, changes a decision, breaks an invariant. The caller will check for a "change-of-mind" label: if present, it is authorized revocation; if absent, it is a blocker.
+
+Return STRICTLY the following JSON, no prose before or after:
+
+{
+  "kind": "new_or_independent" | "overlap" | "contradiction",
+  "conflicting_ids": ["042", "007"],
+  "reasoning": "one-paragraph explanation citing specific spec ids and the exact overlap/contradiction"
+}
+
+- For "new_or_independent", set conflicting_ids to [].
+- For "overlap" and "contradiction", list every spec id you find, not just the strongest match.
+- "reasoning" should name the specs by id and cite what specifically overlaps or contradicts. Be concrete — "story-042 defines POST /api/reactions with a 15/week ration; this issue changes the ration to 20/week" is good.
+- If information is insufficient to classify with confidence, pick the most conservative outcome (contradiction > overlap > independent).`;
+export const REFINEMENT_ANALYST_SYSTEM = (checklist) => `You are a rigorous product analyst for the slowcook brewing harness.
+
+Your job is to help the PM turn a GitHub issue into a precise, testable spec. You operate in rounds: each round, you either (a) ask the PM clarifying questions OR (b) emit the final spec as YAML. You do not both ask AND emit in the same round.
+
+## The spec must be complete
+
+${checklist}
+
+## How to decide: ask vs emit
+
+**Ask** if:
+- Any checklist item is missing OR ambiguous
+- A stated requirement has implied questions the spec doesn't answer (e.g., "ration" implies: what period? what counts? what happens when exhausted?)
+- Acceptance scenarios leave happy path + edge cases underspecified
+
+**Emit** if:
+- Every checklist item is present with concrete, testable language
+- Acceptance scenarios cover happy path + at least 2 edge cases and map cleanly to test cases
+- Non-goals explicitly close off likely scope creep
+
+## Output formats
+
+When asking: output a SINGLE Markdown comment, numbered list, ≤5 questions per round. Prefer fewer, sharper questions over a long list. Ask the MOST important first. Group related questions if they share context. Address the PM directly ("you"). Begin with a one-line acknowledgment of what you have so far. End with:
+
+"Please answer inline by replying to this comment. I'll continue when you do."
+
+When emitting the spec: output ONLY the YAML, nothing before or after, starting with \`---\` and ending with the last field. The YAML MUST validate against this schema (\`?\` marks optional):
+
+- story_id: string (provided to you — don't invent)
+- title: string (one-line description)
+- status: "active"
+- created_at: ISO-8601 UTC timestamp (provided to you)
+- supersedes: string[] (provided to you)
+- superseded_by: null
+- token_budget_usd?: number
+- estimate?: "small" | "medium" | "large"  (small ≤4h, medium ≤12h, large = split it)
+- source_issue: "#N" (the issue number, provided)
+- refined_by: "slowcook-refine@<version>" (provided)
+- actors: [{ name, notes? }]
+- preconditions: string[]
+- invariants: string[]
+- api_contract?: [{ method, path, request_schema?, responses? }]
+- ui_behavior?: { desktop_light: string, mobile_light: string, mobile_dark: string, ... }
+- acceptance_scenarios: string[] (Given/When/Then form)
+- non_goals: string[]
+- related_specs?: [{ id, relationship: "overlap"|"related"|"superseded", note? }]
+
+## Constraints
+
+- Do NOT hallucinate facts not in the issue or prior conversation. If you infer something, flag it as an assumption in the question round.
+- Keep scope tight: a medium-sized story, not an epic. If the issue feels larger, propose splitting in the question round.
+- Treat PM silence as "please ask again" — summarize where we are and re-ask open questions.
+- The spec is the contract for code-generation agents down the pipeline. Every invariant and acceptance scenario must be testable.`;
+/** Trivial, used only as a title for the draft PR. */
+export function draftPrTitle(storyId, title) {
+    return `spec: story-${storyId} — ${title}`;
+}
+export function draftPrBody(args) {
+    const supersedesSection = args.supersedes.length > 0
+        ? `\n## Supersedes\n\nThis spec explicitly supersedes: ${args.supersedes
+            .map((id) => `story-${id}`)
+            .join(", ")}. The index has been updated to mark those stories as superseded.\n`
+        : "";
+    return `Spec refined from #${args.issueNumber} by the slowcook refinement agent.
+
+Review the YAML, edit anything that needs tightening, then mark this PR ready-for-review and merge to freeze the spec.
+${supersedesSection}
+---
+*Generated by \`slowcook refine\`.*`;
+}
+//# sourceMappingURL=prompts.js.map

package/dist/commands/refine/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../../../src/commands/refine/prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAAG;;;;;;;;;;CAUhC,CAAC;AAEF,MAAM,CAAC,MAAM,2BAA2B,GAAG;;;;;;;;;;;;;;;;;;;;0IAoB+F,CAAC;AAE3I,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,SAAiB,EAAE,EAAE,CAAC;;;;;;EAM9D,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mIA8CwH,CAAC;AAEpI,sDAAsD;AACtD,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,KAAa;IACzD,OAAO,eAAe,OAAO,MAAM,KAAK,EAAE,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAI3B;IACC,MAAM,iBAAiB,GACrB,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC;QACxB,CAAC,CAAC,uDAAuD,IAAI,CAAC,UAAU;aACnE,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC;aAC1B,IAAI,CAAC,IAAI,CAAC,qEAAqE;QACpF,CAAC,CAAC,EAAE,CAAC;IACT,OAAO,sBAAsB,IAAI,CAAC,WAAW;;;EAG7C,iBAAiB;;oCAEiB,CAAC;AACrC,CAAC"}

package/dist/commands/refine/relationship.d.ts

@@ -0,0 +1,21 @@
+import type { LlmClient } from "./llm.js";
+import type { Spec, RelationshipVerdict } from "@slowcook-ai/core";
+export interface RelationshipInput {
+    issueTitle: string;
+    issueBody: string;
+    activeSpecs: Spec[];
+}
+export interface RelationshipOptions {
+    llm: LlmClient;
+    model: string;
+}
+export declare function analyzeRelationship(input: RelationshipInput, options: RelationshipOptions): Promise<RelationshipVerdict>;
+export declare function parseVerdict(raw: string): RelationshipVerdict;
+/** Comment body posted to the issue when relationship analysis surfaces a conflict. */
+export declare function overlapCommentBody(verdict: Extract<RelationshipVerdict, {
+    kind: "overlap";
+}>): string;
+export declare function contradictionCommentBody(verdict: Extract<RelationshipVerdict, {
+    kind: "contradiction";
+}>, hasChangeOfMind: boolean): string;
+//# sourceMappingURL=relationship.d.ts.map

package/dist/commands/refine/relationship.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship.d.ts","sourceRoot":"","sources":["../../../src/commands/refine/relationship.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,KAAK,EAAE,IAAI,EAAE,mBAAmB,EAAgB,MAAM,mBAAmB,CAAC;AASjF,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,IAAI,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,SAAS,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,mBAAmB,CAAC,CAa9B;AAiDD,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,CA0B7D;AAmBD,uFAAuF;AACvF,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC,mBAAmB,EAAE;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC,GAAG,MAAM,CAerG;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,OAAO,CAAC,mBAAmB,EAAE;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,CAAC,EAChE,eAAe,EAAE,OAAO,GACvB,MAAM,CAwBR"}

package/dist/commands/refine/relationship.js

@@ -0,0 +1,148 @@
+import { z } from "zod";
+import { RELATIONSHIP_ANALYST_SYSTEM } from "./prompts.js";
+const VerdictSchema = z.object({
+    kind: z.enum(["new_or_independent", "overlap", "contradiction"]),
+    conflicting_ids: z.array(z.string()),
+    reasoning: z.string(),
+});
+export async function analyzeRelationship(input, options) {
+    const userMessage = buildUserMessage(input);
+    const raw = await options.llm.complete({
+        system: RELATIONSHIP_ANALYST_SYSTEM,
+        cacheSystem: true,
+        model: options.model,
+        messages: [{ role: "user", content: userMessage }],
+        maxTokens: 1024,
+        temperature: 0,
+    });
+    const parsed = parseVerdict(raw);
+    return parsed;
+}
+function buildUserMessage(input) {
+    const specSection = input.activeSpecs.length === 0
+        ? "There are no active specs yet."
+        : input.activeSpecs
+            .map((s) => `### story-${s.story_id} — ${s.title} (status: ${s.status})\n` + specSummary(s))
+            .join("\n\n");
+    return `## New issue
+
+Title: ${input.issueTitle}
+
+Body:
+${input.issueBody}
+
+## Existing active specs
+
+${specSection}
+
+## Task
+
+Classify the relationship of the new issue to the existing specs. Respond with ONLY JSON per the schema in your system prompt.`;
+}
+function specSummary(spec) {
+    const lines = [];
+    if (spec.invariants.length) {
+        lines.push(`Invariants: ${spec.invariants.join("; ")}`);
+    }
+    if (spec.api_contract && spec.api_contract.length) {
+        const endpoints = spec.api_contract
+            .map((e) => {
+            const obj = e;
+            return `${obj.method ?? "?"} ${obj.path ?? "?"}`;
+        })
+            .join(", ");
+        lines.push(`API: ${endpoints}`);
+    }
+    if (spec.acceptance_scenarios.length) {
+        lines.push(`Acceptance: ${spec.acceptance_scenarios.slice(0, 3).join(" / ")}`);
+    }
+    if (spec.non_goals.length) {
+        lines.push(`Non-goals: ${spec.non_goals.join("; ")}`);
+    }
+    return lines.join("\n");
+}
+export function parseVerdict(raw) {
+    const cleaned = extractJsonObject(raw);
+    let json;
+    try {
+        json = JSON.parse(cleaned);
+    }
+    catch (e) {
+        throw new Error(`Relationship analyst returned non-JSON. First 300 chars: ${cleaned.slice(0, 300)}`);
+    }
+    const parsed = VerdictSchema.safeParse(json);
+    if (!parsed.success) {
+        throw new Error(`Relationship analyst output failed schema validation: ${parsed.error.issues
+            .map((i) => `${i.path.join(".")}: ${i.message}`)
+            .join("; ")}`);
+    }
+    const v = parsed.data;
+    if (v.kind === "new_or_independent") {
+        return { kind: "new_or_independent", reasoning: v.reasoning };
+    }
+    if (v.kind === "overlap") {
+        return { kind: "overlap", conflicting_ids: v.conflicting_ids, reasoning: v.reasoning };
+    }
+    return { kind: "contradiction", conflicting_ids: v.conflicting_ids, reasoning: v.reasoning };
+}
+/** Best-effort extraction of a JSON object from LLM output that may contain prose. */
+function extractJsonObject(raw) {
+    const trimmed = raw.trim();
+    // Direct JSON?
+    if (trimmed.startsWith("{"))
+        return trimmed;
+    // Fenced code block?
+    const fence = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (fence && fence[1])
+        return fence[1].trim();
+    // First brace through matching brace?
+    const firstBrace = trimmed.indexOf("{");
+    const lastBrace = trimmed.lastIndexOf("}");
+    if (firstBrace !== -1 && lastBrace > firstBrace) {
+        return trimmed.slice(firstBrace, lastBrace + 1);
+    }
+    return trimmed;
+}
+/** Comment body posted to the issue when relationship analysis surfaces a conflict. */
+export function overlapCommentBody(verdict) {
+    const specs = verdict.conflicting_ids.map((id) => `\`story-${id}\``).join(", ");
+    return `### slowcook · overlap detected
+
+This issue overlaps with existing active specs: ${specs}.
+
+**Reasoning:** ${verdict.reasoning}
+
+Please choose how to proceed:
+
+- **Merge**: close this issue and extend the overlapping spec. Comment \`/slowcook merge-into story-<id>\` and I'll relabel.
+- **Delta**: reframe this issue to cover only what the overlapping spec doesn't (and say so in the body). I'll re-analyze on the next comment.
+- **Duplicate**: close this issue if it's entirely covered.
+
+I'll pause refinement until the issue body or labels are updated.`;
+}
+export function contradictionCommentBody(verdict, hasChangeOfMind) {
+    const specs = verdict.conflicting_ids.map((id) => `\`story-${id}\``).join(", ");
+    if (hasChangeOfMind) {
+        return `### slowcook · change-of-mind authorized
+
+This issue contradicts existing active specs: ${specs}. The \`change-of-mind\` label is present, so I'll proceed with refinement; the resulting spec will explicitly supersede those stories.
+
+**Reasoning:** ${verdict.reasoning}
+
+Proceeding with clarifying questions...`;
+    }
+    return `### slowcook · contradiction — refinement blocked
+
+This issue contradicts existing active specs: ${specs}.
+
+**Reasoning:** ${verdict.reasoning}
+
+The ratchet means previously-accepted decisions stay in force unless explicitly revoked. To proceed:
+
+- If this is a **genuine change of mind**, add the \`change-of-mind\` label and re-comment. I will then refine the spec with explicit \`supersedes\` tracking.
+- If this is an **accidental conflict**, revise the issue body to align with the existing specs and remove the contradiction. I'll re-analyze on the next comment.
+- If you intend the overlapping specs to **coexist** and think this isn't a real contradiction, add a comment explaining the independence and I'll re-classify.
+
+I've added the \`blocked-contradiction\` label for visibility.`;
+}
+//# sourceMappingURL=relationship.js.map

package/dist/commands/refine/relationship.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship.js","sourceRoot":"","sources":["../../../src/commands/refine/relationship.ts"],"names":[],"mappings":"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"}

package/dist/commands/refine/spec-yaml.d.ts

@@ -0,0 +1,192 @@
+import { z } from "zod";
+import { type Spec, type SpecIndex, type SpecIndexEntry } from "@slowcook-ai/core";
+/** Where specs live, relative to repo root. */
+export declare const SPECS_DIR = "specs";
+export declare const INDEX_FILE: string;
+export declare function readIndex(repoRoot: string): SpecIndex;
+export declare function writeIndex(repoRoot: string, index: SpecIndex): void;
+export declare function readSpec(repoRoot: string, storyId: string): Spec;
+export declare function writeSpec(repoRoot: string, spec: Spec): string;
+export declare function listActiveSpecs(repoRoot: string): Spec[];
+/** Allocate the next unused story ID (zero-padded 3 digits). */
+export declare function nextStoryId(repoRoot: string): string;
+/** Public accessors for tests. */
+export declare const schemas: {
+    SpecIndex: z.ZodObject<{
+        $schema: z.ZodOptional<z.ZodString>;
+        schema_version: z.ZodLiteral<1>;
+        stories: z.ZodRecord<z.ZodString, z.ZodObject<{
+            title: z.ZodString;
+            status: z.ZodEnum<["draft", "active", "superseded"]>;
+            source_issue: z.ZodOptional<z.ZodString>;
+            tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            summary: z.ZodOptional<z.ZodString>;
+            supersedes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            superseded_by: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNull]>>;
+        }, "strip", z.ZodTypeAny, {
+            status: "draft" | "active" | "superseded";
+            title: string;
+            source_issue?: string | undefined;
+            tags?: string[] | undefined;
+            summary?: string | undefined;
+            supersedes?: string[] | undefined;
+            superseded_by?: string | null | undefined;
+        }, {
+            status: "draft" | "active" | "superseded";
+            title: string;
+            source_issue?: string | undefined;
+            tags?: string[] | undefined;
+            summary?: string | undefined;
+            supersedes?: string[] | undefined;
+            superseded_by?: string | null | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        schema_version: 1;
+        stories: Record<string, {
+            status: "draft" | "active" | "superseded";
+            title: string;
+            source_issue?: string | undefined;
+            tags?: string[] | undefined;
+            summary?: string | undefined;
+            supersedes?: string[] | undefined;
+            superseded_by?: string | null | undefined;
+        }>;
+        $schema?: string | undefined;
+    }, {
+        schema_version: 1;
+        stories: Record<string, {
+            status: "draft" | "active" | "superseded";
+            title: string;
+            source_issue?: string | undefined;
+            tags?: string[] | undefined;
+            summary?: string | undefined;
+            supersedes?: string[] | undefined;
+            superseded_by?: string | null | undefined;
+        }>;
+        $schema?: string | undefined;
+    }>;
+    Spec: z.ZodObject<{
+        $schema: z.ZodOptional<z.ZodString>;
+        story_id: z.ZodString;
+        title: z.ZodString;
+        status: z.ZodEnum<["draft", "active", "superseded"]>;
+        created_at: z.ZodString;
+        supersedes: z.ZodArray<z.ZodString, "many">;
+        superseded_by: z.ZodUnion<[z.ZodString, z.ZodNull]>;
+        token_budget_usd: z.ZodOptional<z.ZodNumber>;
+        estimate: z.ZodOptional<z.ZodEnum<["small", "medium", "large"]>>;
+        source_issue: z.ZodOptional<z.ZodString>;
+        refined_by: z.ZodOptional<z.ZodString>;
+        actors: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            notes: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            notes?: string | undefined;
+        }, {
+            name: string;
+            notes?: string | undefined;
+        }>, "many">;
+        preconditions: z.ZodArray<z.ZodString, "many">;
+        invariants: z.ZodArray<z.ZodString, "many">;
+        api_contract: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
+        ui_behavior: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        acceptance_scenarios: z.ZodArray<z.ZodString, "many">;
+        non_goals: z.ZodArray<z.ZodString, "many">;
+        related_specs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            relationship: z.ZodEnum<["overlap", "related", "superseded"]>;
+            note: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            relationship: "superseded" | "overlap" | "related";
+            note?: string | undefined;
+        }, {
+            id: string;
+            relationship: "superseded" | "overlap" | "related";
+            note?: string | undefined;
+        }>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        status: "draft" | "active" | "superseded";
+        title: string;
+        supersedes: string[];
+        superseded_by: string | null;
+        story_id: string;
+        created_at: string;
+        actors: {
+            name: string;
+            notes?: string | undefined;
+        }[];
+        preconditions: string[];
+        invariants: string[];
+        acceptance_scenarios: string[];
+        non_goals: string[];
+        $schema?: string | undefined;
+        source_issue?: string | undefined;
+        token_budget_usd?: number | undefined;
+        estimate?: "small" | "medium" | "large" | undefined;
+        refined_by?: string | undefined;
+        api_contract?: unknown[] | undefined;
+        ui_behavior?: Record<string, string> | undefined;
+        related_specs?: {
+            id: string;
+            relationship: "superseded" | "overlap" | "related";
+            note?: string | undefined;
+        }[] | undefined;
+    }, {
+        status: "draft" | "active" | "superseded";
+        title: string;
+        supersedes: string[];
+        superseded_by: string | null;
+        story_id: string;
+        created_at: string;
+        actors: {
+            name: string;
+            notes?: string | undefined;
+        }[];
+        preconditions: string[];
+        invariants: string[];
+        acceptance_scenarios: string[];
+        non_goals: string[];
+        $schema?: string | undefined;
+        source_issue?: string | undefined;
+        token_budget_usd?: number | undefined;
+        estimate?: "small" | "medium" | "large" | undefined;
+        refined_by?: string | undefined;
+        api_contract?: unknown[] | undefined;
+        ui_behavior?: Record<string, string> | undefined;
+        related_specs?: {
+            id: string;
+            relationship: "superseded" | "overlap" | "related";
+            note?: string | undefined;
+        }[] | undefined;
+    }>;
+    SpecIndexEntry: z.ZodObject<{
+        title: z.ZodString;
+        status: z.ZodEnum<["draft", "active", "superseded"]>;
+        source_issue: z.ZodOptional<z.ZodString>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        summary: z.ZodOptional<z.ZodString>;
+        supersedes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        superseded_by: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNull]>>;
+    }, "strip", z.ZodTypeAny, {
+        status: "draft" | "active" | "superseded";
+        title: string;
+        source_issue?: string | undefined;
+        tags?: string[] | undefined;
+        summary?: string | undefined;
+        supersedes?: string[] | undefined;
+        superseded_by?: string | null | undefined;
+    }, {
+        status: "draft" | "active" | "superseded";
+        title: string;
+        source_issue?: string | undefined;
+        tags?: string[] | undefined;
+        summary?: string | undefined;
+        supersedes?: string[] | undefined;
+        superseded_by?: string | null | undefined;
+    }>;
+};
+/** Minimal helper for the agent to build a SpecIndexEntry from a Spec. */
+export declare function entryFromSpec(spec: Spec): SpecIndexEntry;
+//# sourceMappingURL=spec-yaml.d.ts.map

package/dist/commands/refine/spec-yaml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-yaml.d.ts","sourceRoot":"","sources":["../../../src/commands/refine/spec-yaml.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAEL,KAAK,IAAI,EACT,KAAK,SAAS,EACd,KAAK,cAAc,EACpB,MAAM,mBAAmB,CAAC;AAE3B,+CAA+C;AAC/C,eAAO,MAAM,SAAS,UAAU,CAAC;AACjC,eAAO,MAAM,UAAU,QAAiC,CAAC;AAkDzD,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAWrD;AAED,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI,CAQnE;AAED,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAUhE;AAED,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,MAAM,CAK9D;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,CAiBxD;AAED,gEAAgE;AAChE,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKpD;AAED,kCAAkC;AAClC,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAInB,CAAC;AAEF,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,cAAc,CASxD"}

package/dist/commands/refine/spec-yaml.js

@@ -0,0 +1,125 @@
+import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync, } from "node:fs";
+import { join, dirname } from "node:path";
+import YAML from "yaml";
+import { z } from "zod";
+import { makeEmptyIndex, } from "@slowcook-ai/core";
+/** Where specs live, relative to repo root. */
+export const SPECS_DIR = "specs";
+export const INDEX_FILE = join(SPECS_DIR, "_index.yaml");
+const SpecStatusSchema = z.enum(["draft", "active", "superseded"]);
+const SpecIndexEntrySchema = z.object({
+    title: z.string(),
+    status: SpecStatusSchema,
+    source_issue: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    summary: z.string().optional(),
+    supersedes: z.array(z.string()).optional(),
+    superseded_by: z.union([z.string(), z.null()]).optional(),
+});
+const SpecIndexSchema = z.object({
+    $schema: z.string().optional(),
+    schema_version: z.literal(1),
+    stories: z.record(z.string(), SpecIndexEntrySchema),
+});
+const SpecSchema = z.object({
+    $schema: z.string().optional(),
+    story_id: z.string(),
+    title: z.string(),
+    status: SpecStatusSchema,
+    created_at: z.string(),
+    supersedes: z.array(z.string()),
+    superseded_by: z.union([z.string(), z.null()]),
+    token_budget_usd: z.number().optional(),
+    estimate: z.enum(["small", "medium", "large"]).optional(),
+    source_issue: z.string().optional(),
+    refined_by: z.string().optional(),
+    actors: z.array(z.object({ name: z.string(), notes: z.string().optional() })),
+    preconditions: z.array(z.string()),
+    invariants: z.array(z.string()),
+    api_contract: z.array(z.unknown()).optional(),
+    ui_behavior: z.record(z.string(), z.string()).optional(),
+    acceptance_scenarios: z.array(z.string()),
+    non_goals: z.array(z.string()),
+    related_specs: z
+        .array(z.object({
+        id: z.string(),
+        relationship: z.enum(["overlap", "related", "superseded"]),
+        note: z.string().optional(),
+    }))
+        .optional(),
+});
+export function readIndex(repoRoot) {
+    const path = join(repoRoot, INDEX_FILE);
+    if (!existsSync(path))
+        return makeEmptyIndex();
+    const raw = YAML.parse(readFileSync(path, "utf8"));
+    const parsed = SpecIndexSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new Error(`Invalid ${INDEX_FILE}: ${parsed.error.issues.map((i) => i.message).join("; ")}`);
+    }
+    return parsed.data;
+}
+export function writeIndex(repoRoot, index) {
+    const path = join(repoRoot, INDEX_FILE);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, YAML.stringify(index, { lineWidth: 0 }), "utf8");
+}
+export function readSpec(repoRoot, storyId) {
+    const path = join(repoRoot, SPECS_DIR, `story-${storyId}.yaml`);
+    const raw = YAML.parse(readFileSync(path, "utf8"));
+    const parsed = SpecSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new Error(`Invalid spec at ${path}: ${parsed.error.issues.map((i) => i.message).join("; ")}`);
+    }
+    return parsed.data;
+}
+export function writeSpec(repoRoot, spec) {
+    const path = join(repoRoot, SPECS_DIR, `story-${spec.story_id}.yaml`);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, YAML.stringify(spec, { lineWidth: 0 }), "utf8");
+    return path;
+}
+export function listActiveSpecs(repoRoot) {
+    const dir = join(repoRoot, SPECS_DIR);
+    if (!existsSync(dir))
+        return [];
+    const files = readdirSync(dir).filter((f) => f.startsWith("story-") && f.endsWith(".yaml"));
+    const specs = [];
+    for (const f of files) {
+        const id = f.replace(/^story-/, "").replace(/\.yaml$/, "");
+        try {
+            const s = readSpec(repoRoot, id);
+            if (s.status === "active")
+                specs.push(s);
+        }
+        catch {
+            // ignore invalid specs; surface them elsewhere
+        }
+    }
+    return specs;
+}
+/** Allocate the next unused story ID (zero-padded 3 digits). */
+export function nextStoryId(repoRoot) {
+    const index = readIndex(repoRoot);
+    const existing = Object.keys(index.stories).map((id) => parseInt(id, 10)).filter((n) => !isNaN(n));
+    const max = existing.length > 0 ? Math.max(...existing) : 0;
+    return String(max + 1).padStart(3, "0");
+}
+/** Public accessors for tests. */
+export const schemas = {
+    SpecIndex: SpecIndexSchema,
+    Spec: SpecSchema,
+    SpecIndexEntry: SpecIndexEntrySchema,
+};
+/** Minimal helper for the agent to build a SpecIndexEntry from a Spec. */
+export function entryFromSpec(spec) {
+    return {
+        title: spec.title,
+        status: spec.status,
+        source_issue: spec.source_issue,
+        summary: spec.acceptance_scenarios[0]?.slice(0, 160),
+        supersedes: spec.supersedes,
+        superseded_by: spec.superseded_by,
+    };
+}
+//# sourceMappingURL=spec-yaml.js.map