@slowcook-ai/cli 0.3.0 → 0.4.0

package/README.md

@@ -8,7 +8,45 @@ CLI for the slowcook brewing harness. Installs the `slowcook` binary.
 npm i -D @slowcook-ai/cli
 ```
 
-## Commands (v0.3)
+## Commands (v0.4)
+
+### `slowcook refine` (first agent)
+
+Drives a GitHub issue through a clarifying-question loop until a frozen spec is emitted as a draft PR. Enforces the issue-level ratchet: new issues must not silently duplicate or contradict earlier decisions.
+
+```bash
+npx slowcook refine --issue <number> [options]
+```
+
+**Required environment:**
+
+- `ANTHROPIC_API_KEY` — for the refinement and relationship-analysis LLM calls
+- `GITHUB_TOKEN` — with `contents: write`, `issues: write`, `pull-requests: write`
+
+**Options:**
+
+| Flag | Default | Description |
+|---|---|---|
+| `--issue <number>` | required | GitHub issue number |
+| `--cwd <path>` | `.` | Repo working directory |
+| `--owner <login>` | parsed from git remote | Repo owner |
+| `--repo <name>` | parsed from git remote | Repo name |
+| `--base <branch>` | `main` | Base branch for the draft spec PR |
+| `--refine-model <id>` | `claude-opus-4-7` | Model for the refinement loop |
+| `--relationship-model <id>` | `claude-sonnet-4-5` | Model for relationship analysis |
+
+**Behaviour per invocation:**
+
+1. Reads the issue (body + labels + comments) and all currently-active specs.
+2. Runs a relationship analysis: `new_or_independent | overlap | contradiction`.
+3. Acts on the verdict:
+   - **overlap** — posts a comment naming the overlapping spec ids, applies `blocked-overlap` label, exits.
+   - **contradiction** without `change-of-mind` label — posts a blocker comment, applies `blocked-contradiction` label, exits.
+   - **contradiction** with `change-of-mind` label — proceeds; the spec's `supersedes` field is populated.
+   - **new / independent** — proceeds to the refinement loop.
+4. Runs one round of refinement: either posts clarifying questions (and exits; next invocation picks up on the next PM comment) OR emits the spec YAML, writes `specs/story-N.yaml` and updates `specs/_index.yaml`, commits + pushes a branch, opens a draft PR, applies `spec-ready` label.
+
+Re-run on every new PM comment in the issue (via a GitHub Actions workflow triggered by `issue_comment` + `issues` events).
 
 ### `slowcook init`
 

package/dist/cli.js

@@ -2,7 +2,8 @@
 import { guard } from "./commands/guard.js";
 import { manifest } from "./commands/manifest.js";
 import { init } from "./commands/init/index.js";
-const VERSION = "0.3.0";
+import { refine } from "./commands/refine/index.js";
+const VERSION = "0.4.0";
 const USAGE = `
 slowcook — TDD-first agentic development harness
 
@@ -11,6 +12,7 @@ Usage:
   slowcook guard --base <ref> --head <ref> [--override] [--config <path>]
   slowcook manifest record [--stack-config <path>] [--manifest <path>] [--story <id>]
   slowcook manifest verify [--stack-config <path>] [--manifest <path>] [--story <id>]
+  slowcook refine --issue <number> [--cwd <path>] [--owner <login>] [--repo <name>]
   slowcook version
   slowcook help
 
@@ -18,9 +20,10 @@ Commands available in ${VERSION}:
   init        Scaffold slowcook configuration in a consumer project.
   guard       Check for frozen-path violations between two git refs.
   manifest    Record or verify the set of discoverable tests.
+  refine      Drive a GitHub issue toward a frozen spec (refinement agent).
 
 Coming in later versions:
-  refine, testgen, brew, review, dashboard
+  testgen, brew, review, dashboard
 
 Docs: https://github.com/aminazar/slowcook
 `;
@@ -37,6 +40,9 @@ async function main() {
         case "manifest":
             await manifest(args.slice(1));
             return;
+        case "refine":
+            await refine(args.slice(1), VERSION);
+            return;
         case "version":
         case "--version":
         case "-v":

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC;AAEhD,MAAM,OAAO,GAAG,OAAO,CAAC;AAExB,MAAM,KAAK,GAAG;;;;;;;;;;;wBAWU,OAAO;;;;;;;;;CAS9B,CAAC;AAEF,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAExB,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,MAAM;YACT,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;YACnC,OAAO;QACT,KAAK,OAAO;YACV,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YAC3B,OAAO;QACT,KAAK,UAAU;YACb,MAAM,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YAC9B,OAAO;QACT,KAAK,SAAS,CAAC;QACf,KAAK,WAAW,CAAC;QACjB,KAAK,IAAI;YACP,OAAO,CAAC,GAAG,CAAC,YAAY,OAAO,EAAE,CAAC,CAAC;YACnC,OAAO;QACT,KAAK,SAAS,CAAC;QACf,KAAK,MAAM,CAAC;QACZ,KAAK,QAAQ,CAAC;QACd,KAAK,IAAI;YACP,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACnB,OAAO;QACT;YACE,OAAO,CAAC,KAAK,CAAC,oBAAoB,OAAO,KAAK,KAAK,EAAE,CAAC,CAAC;YACvD,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW;IACjC,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,OAAO,CAAC,KAAK,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7E,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAEpD,MAAM,OAAO,GAAG,OAAO,CAAC;AAExB,MAAM,KAAK,GAAG;;;;;;;;;;;;wBAYU,OAAO;;;;;;;;;;CAU9B,CAAC;AAEF,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAExB,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,MAAM;YACT,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;YACnC,OAAO;QACT,KAAK,OAAO;YACV,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YAC3B,OAAO;QACT,KAAK,UAAU;YACb,MAAM,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YAC9B,OAAO;QACT,KAAK,QAAQ;YACX,MAAM,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;YACrC,OAAO;QACT,KAAK,SAAS,CAAC;QACf,KAAK,WAAW,CAAC;QACjB,KAAK,IAAI;YACP,OAAO,CAAC,GAAG,CAAC,YAAY,OAAO,EAAE,CAAC,CAAC;YACnC,OAAO;QACT,KAAK,SAAS,CAAC;QACf,KAAK,MAAM,CAAC;QACZ,KAAK,QAAQ,CAAC;QACd,KAAK,IAAI;YACP,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACnB,OAAO;QACT;YACE,OAAO,CAAC,KAAK,CAAC,oBAAoB,OAAO,KAAK,KAAK,EAAE,CAAC,CAAC;YACvD,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW;IACjC,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,OAAO,CAAC,KAAK,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7E,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

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

@@ -0,0 +1,62 @@
+import type { LlmClient } from "./llm.js";
+import type { ForgeAdapter, Spec } from "@slowcook-ai/core";
+export declare const LABEL_CHANGE_OF_MIND = "change-of-mind";
+export declare const LABEL_BLOCKED_CONTRADICTION = "blocked-contradiction";
+export declare const LABEL_BLOCKED_OVERLAP = "blocked-overlap";
+export declare const LABEL_SPEC_READY = "spec-ready";
+export declare const LABEL_NEEDS_REFINEMENT = "needs-refinement";
+export interface RefineContext {
+    issueNumber: number;
+    repoRoot: string;
+    forge: ForgeAdapter;
+    llm: LlmClient;
+    /** Model id for refinement (heavy reasoning). */
+    refineModel: string;
+    /** Model id for relationship analysis (cheaper). */
+    relationshipModel: string;
+    /** slowcook CLI version string for the spec's refined_by field. */
+    cliVersion: string;
+    /** Base branch for PRs (default: "main"). */
+    baseBranch: string;
+    /** Current UTC time (injectable for tests). */
+    now: Date;
+}
+export type RefineOutcome = {
+    kind: "questions-posted";
+    commentId: number;
+} | {
+    kind: "spec-emitted";
+    specPath: string;
+    prUrl: string;
+    prNumber: number;
+} | {
+    kind: "overlap-flagged";
+    conflicting_ids: string[];
+} | {
+    kind: "contradiction-blocked";
+    conflicting_ids: string[];
+} | {
+    kind: "change-of-mind-accepted";
+    supersedes: string[];
+} | {
+    kind: "noop";
+    reason: string;
+};
+export declare function runRefinement(ctx: RefineContext): Promise<RefineOutcome>;
+interface ParseContext {
+    storyId: string;
+    issueNumber: number;
+    createdAt: string;
+    cliVersion: string;
+    supersedes: string[];
+}
+export type AgentOutput = {
+    kind: "questions";
+    markdown: string;
+} | {
+    kind: "spec";
+    spec: Spec;
+};
+export declare function parseAgentOutput(raw: string, ctx: ParseContext): AgentOutput;
+export {};
+//# sourceMappingURL=agent.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/commands/refine/agent.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,UAAU,CAAC;AACtD,OAAO,KAAK,EACV,YAAY,EAGZ,IAAI,EAEL,MAAM,mBAAmB,CAAC;AAsB3B,eAAO,MAAM,oBAAoB,mBAAmB,CAAC;AACrD,eAAO,MAAM,2BAA2B,0BAA0B,CAAC;AACnE,eAAO,MAAM,qBAAqB,oBAAoB,CAAC;AACvD,eAAO,MAAM,gBAAgB,eAAe,CAAC;AAC7C,eAAO,MAAM,sBAAsB,qBAAqB,CAAC;AAEzD,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,YAAY,CAAC;IACpB,GAAG,EAAE,SAAS,CAAC;IACf,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,GAAG,EAAE,IAAI,CAAC;CACX;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC3E;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,eAAe,EAAE,MAAM,EAAE,CAAA;CAAE,GACtD;IAAE,IAAI,EAAE,uBAAuB,CAAC;IAAC,eAAe,EAAE,MAAM,EAAE,CAAA;CAAE,GAC5D;IAAE,IAAI,EAAE,yBAAyB,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAKrC,wBAAsB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAgH9E;AA2CD,UAAU,YAAY;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC;AA+BjC,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,YAAY,GAChB,WAAW,CA6Cb"}

package/dist/commands/refine/agent.js

@@ -0,0 +1,209 @@
+import YAML from "yaml";
+import { z } from "zod";
+import { REFINEMENT_ANALYST_SYSTEM, SPEC_CHECKLIST_MD, draftPrTitle, draftPrBody, } from "./prompts.js";
+import { readIndex, writeIndex, writeSpec, listActiveSpecs, nextStoryId, entryFromSpec, } from "./spec-yaml.js";
+import { analyzeRelationship, contradictionCommentBody, overlapCommentBody, } from "./relationship.js";
+import { applySupersede } from "@slowcook-ai/core";
+export const LABEL_CHANGE_OF_MIND = "change-of-mind";
+export const LABEL_BLOCKED_CONTRADICTION = "blocked-contradiction";
+export const LABEL_BLOCKED_OVERLAP = "blocked-overlap";
+export const LABEL_SPEC_READY = "spec-ready";
+export const LABEL_NEEDS_REFINEMENT = "needs-refinement";
+/** Schema for the <sentinel> block the agent uses when it emits a spec. */
+const SpecEmissionFenceStart = "---";
+export async function runRefinement(ctx) {
+    const issue = await ctx.forge.getIssue(ctx.issueNumber);
+    if (issue.state === "closed") {
+        return { kind: "noop", reason: "issue is closed" };
+    }
+    if (!issue.labels.includes(LABEL_NEEDS_REFINEMENT)) {
+        return { kind: "noop", reason: `issue is not labeled ${LABEL_NEEDS_REFINEMENT}` };
+    }
+    // Step 1: relationship analysis
+    const existingSpecs = listActiveSpecs(ctx.repoRoot);
+    const verdict = await analyzeRelationship({ issueTitle: issue.title, issueBody: issue.body, activeSpecs: existingSpecs }, { llm: ctx.llm, model: ctx.relationshipModel });
+    const hasChangeOfMind = issue.labels.includes(LABEL_CHANGE_OF_MIND);
+    if (verdict.kind === "overlap") {
+        const comment = await ctx.forge.createIssueComment(ctx.issueNumber, overlapCommentBody(verdict));
+        await ctx.forge.addIssueLabels(ctx.issueNumber, [LABEL_BLOCKED_OVERLAP]);
+        return { kind: "overlap-flagged", conflicting_ids: verdict.conflicting_ids };
+    }
+    if (verdict.kind === "contradiction") {
+        if (!hasChangeOfMind) {
+            await ctx.forge.createIssueComment(ctx.issueNumber, contradictionCommentBody(verdict, false));
+            await ctx.forge.addIssueLabels(ctx.issueNumber, [LABEL_BLOCKED_CONTRADICTION]);
+            return { kind: "contradiction-blocked", conflicting_ids: verdict.conflicting_ids };
+        }
+        // Authorized change-of-mind: post an acknowledgment and proceed
+        await ctx.forge.createIssueComment(ctx.issueNumber, contradictionCommentBody(verdict, true));
+    }
+    const supersedes = verdict.kind === "contradiction" && hasChangeOfMind ? verdict.conflicting_ids : [];
+    // Step 2: refinement loop (single round — ask or emit based on full history)
+    const comments = await ctx.forge.listIssueComments(ctx.issueNumber);
+    const chat = buildChatHistory(issue, comments, supersedes);
+    const storyId = nextStoryId(ctx.repoRoot);
+    const agentResponse = await ctx.llm.complete({
+        system: REFINEMENT_ANALYST_SYSTEM(SPEC_CHECKLIST_MD),
+        cacheSystem: true,
+        model: ctx.refineModel,
+        messages: chat,
+        maxTokens: 4096,
+        temperature: 0.2,
+    });
+    const parsed = parseAgentOutput(agentResponse, {
+        storyId,
+        issueNumber: ctx.issueNumber,
+        createdAt: ctx.now.toISOString(),
+        cliVersion: ctx.cliVersion,
+        supersedes,
+    });
+    if (parsed.kind === "questions") {
+        const comment = await ctx.forge.createIssueComment(ctx.issueNumber, parsed.markdown);
+        return { kind: "questions-posted", commentId: comment.id };
+    }
+    // Spec emitted → write, update index, open draft PR
+    const spec = parsed.spec;
+    const specPath = writeSpec(ctx.repoRoot, spec);
+    const index = readIndex(ctx.repoRoot);
+    const updatedIndex = applySupersede(index, { id: spec.story_id, entry: entryFromSpec(spec) }, supersedes);
+    writeIndex(ctx.repoRoot, updatedIndex);
+    const branch = `slowcook/spec/story-${spec.story_id}`;
+    await ctx.forge.git.createBranch(branch);
+    await ctx.forge.git.stage(specPath);
+    await ctx.forge.git.stage(`specs/_index.yaml`);
+    await ctx.forge.git.commit(`slowcook: spec story-${spec.story_id} — ${spec.title}\n\nRefined from #${ctx.issueNumber}.`);
+    await ctx.forge.git.push(branch);
+    const pr = await ctx.forge.createPullRequest({
+        title: draftPrTitle(spec.story_id, spec.title),
+        body: draftPrBody({
+            storyId: spec.story_id,
+            issueNumber: ctx.issueNumber,
+            supersedes,
+        }),
+        head: branch,
+        base: ctx.baseBranch,
+        draft: true,
+        labels: ["slowcook-spec"],
+    });
+    await ctx.forge.addIssueLabels(ctx.issueNumber, [LABEL_SPEC_READY]);
+    await ctx.forge.removeIssueLabel(ctx.issueNumber, LABEL_NEEDS_REFINEMENT);
+    return { kind: "spec-emitted", specPath, prUrl: pr.url, prNumber: pr.number };
+}
+// ----- helpers -----
+function buildChatHistory(issue, comments, supersedes) {
+    // First message: the issue body + metadata.
+    const issueBlock = `# Issue #${issue.number}: ${issue.title}
+
+${issue.body}`;
+    const messages = [{ role: "user", content: issueBlock }];
+    // Interleave prior comments: bot comments become assistant turns, PM comments become user turns.
+    // Skip the issue-level "overlap/contradiction" analysis acknowledgments by matching their headers.
+    for (const c of comments) {
+        const skip = c.body.startsWith("### slowcook · overlap detected") ||
+            c.body.startsWith("### slowcook · contradiction") ||
+            c.body.startsWith("### slowcook · change-of-mind authorized");
+        if (skip)
+            continue;
+        messages.push({
+            role: c.is_bot ? "assistant" : "user",
+            content: c.body,
+        });
+    }
+    if (supersedes.length > 0) {
+        messages.push({
+            role: "user",
+            content: `(slowcook system note: this spec is authorized to supersede ${supersedes
+                .map((id) => `story-${id}`)
+                .join(", ")}. Set the \`supersedes\` field accordingly.)`,
+        });
+    }
+    return messages;
+}
+const EmittedSpecSchema = z.object({
+    story_id: z.string().optional(),
+    title: z.string(),
+    status: z.string().optional(),
+    created_at: z.string().optional(),
+    supersedes: z.array(z.string()).optional(),
+    superseded_by: z.unknown().optional(),
+    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 parseAgentOutput(raw, ctx) {
+    const trimmed = raw.trim();
+    // Heuristic: spec starts with `---` or is wrapped in a ```yaml block.
+    const yamlBlock = extractYamlBlock(trimmed);
+    if (yamlBlock) {
+        const doc = YAML.parse(yamlBlock);
+        const parsed = EmittedSpecSchema.safeParse(doc);
+        if (!parsed.success) {
+            throw new Error(`Agent emitted a YAML-shaped response but it failed validation:\n${parsed.error.issues
+                .map((i) => `  ${i.path.join(".") || "(root)"}: ${i.message}`)
+                .join("\n")}\n\nRaw YAML:\n${yamlBlock.slice(0, 500)}`);
+        }
+        const d = parsed.data;
+        const spec = {
+            $schema: "./spec.schema.json",
+            story_id: ctx.storyId,
+            title: d.title,
+            status: "active",
+            created_at: ctx.createdAt,
+            supersedes: ctx.supersedes,
+            superseded_by: null,
+            token_budget_usd: d.token_budget_usd,
+            estimate: d.estimate,
+            source_issue: `#${ctx.issueNumber}`,
+            refined_by: `slowcook-refine@${ctx.cliVersion}`,
+            actors: d.actors,
+            preconditions: d.preconditions,
+            invariants: d.invariants,
+            api_contract: d.api_contract,
+            ui_behavior: d.ui_behavior,
+            acceptance_scenarios: d.acceptance_scenarios,
+            non_goals: d.non_goals,
+            related_specs: d.related_specs,
+        };
+        return { kind: "spec", spec };
+    }
+    // Otherwise: treat as a question round (markdown).
+    if (trimmed.length === 0) {
+        throw new Error("Agent returned an empty response; expected questions or a spec.");
+    }
+    return { kind: "questions", markdown: trimmed };
+}
+function extractYamlBlock(s) {
+    // ```yaml ... ``` fenced
+    const fence = s.match(/```yaml\s*([\s\S]*?)```/);
+    if (fence && fence[1])
+        return fence[1].trim();
+    // Bare YAML starting with --- (document separator)
+    if (s.startsWith("---")) {
+        return s;
+    }
+    // Content that's just YAML without front-matter fence — detect heuristically.
+    // If it contains typical spec keys AND doesn't look like markdown, treat as YAML.
+    const looksLikeYaml = /(^|\n)title:\s/i.test(s) &&
+        /(^|\n)actors:\s*/i.test(s) &&
+        /(^|\n)acceptance_scenarios:\s*/i.test(s);
+    if (looksLikeYaml && !s.includes("```") && !s.includes("### ")) {
+        return s;
+    }
+    return null;
+}
+//# sourceMappingURL=agent.js.map

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

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

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

@@ -0,0 +1,2 @@
+export declare function refine(argv: string[], cliVersion: string): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/refine/index.ts"],"names":[],"mappings":"AAgHA,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmF9E"}

package/dist/commands/refine/index.js

@@ -0,0 +1,177 @@
+import { execSync } from "node:child_process";
+import { GitHubAdapter } from "@slowcook-ai/forge-github";
+import { AnthropicClient } from "./llm.js";
+import { runRefinement } from "./agent.js";
+function parseArgs(argv) {
+    const args = {
+        issueNumber: 0,
+        repoRoot: process.cwd(),
+        baseBranch: "main",
+        refineModel: "claude-opus-4-7",
+        relationshipModel: "claude-sonnet-4-5",
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        const next = argv[i + 1];
+        if (arg === "--issue" && next) {
+            args.issueNumber = parseInt(next, 10);
+            i++;
+        }
+        else if (arg === "--cwd" && next) {
+            args.repoRoot = next;
+            i++;
+        }
+        else if (arg === "--owner" && next) {
+            args.owner = next;
+            i++;
+        }
+        else if (arg === "--repo" && next) {
+            args.repo = next;
+            i++;
+        }
+        else if (arg === "--base" && next) {
+            args.baseBranch = next;
+            i++;
+        }
+        else if (arg === "--refine-model" && next) {
+            args.refineModel = next;
+            i++;
+        }
+        else if (arg === "--relationship-model" && next) {
+            args.relationshipModel = next;
+            i++;
+        }
+        else if (arg === "--help" || arg === "-h") {
+            printHelp();
+            process.exit(0);
+        }
+    }
+    if (!args.issueNumber || isNaN(args.issueNumber)) {
+        console.error("Missing required --issue <number>");
+        printHelp();
+        process.exit(64);
+    }
+    return args;
+}
+function printHelp() {
+    console.log(`
+slowcook refine — drive a GitHub issue toward a frozen spec
+
+Each invocation is one round:
+  - Analyzes the issue's relationship to existing active specs.
+  - If overlap or contradiction (without 'change-of-mind' label): posts a
+    comment explaining how to proceed and exits.
+  - If no blocker: either asks clarifying questions (as a comment) or emits
+    the final spec + opens a draft PR.
+
+Re-run on every new PM comment (typically via a GitHub Actions workflow
+triggered by issue_comment events).
+
+Usage:
+  slowcook refine --issue <number> [options]
+
+Options:
+  --issue <number>             Issue to refine (required)
+  --cwd <path>                 Repo working directory (default: current dir)
+  --owner <login>              Repo owner (default: parsed from 'git remote get-url origin')
+  --repo <name>                Repo name (default: parsed from 'git remote get-url origin')
+  --base <branch>              Base branch for the spec PR (default: main)
+  --refine-model <id>          Model for the refinement loop (default: claude-opus-4-7)
+  --relationship-model <id>    Model for relationship analysis (default: claude-sonnet-4-5)
+  --help, -h                   Show this help
+
+Environment:
+  ANTHROPIC_API_KEY  (required)  Anthropic API key
+  GITHUB_TOKEN       (required)  GitHub token with issues:write, contents:write, pull-requests:write
+
+Exit codes:
+  0  outcome was reached (questions posted, spec emitted, or noop)
+  2  script error (bad args, missing env, network failure)
+`);
+}
+function detectOwnerRepo(cwd) {
+    try {
+        const url = execSync("git remote get-url origin", {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        const m = url.match(/github\.com[:/]([^/]+)\/([^/.]+)(?:\.git)?$/);
+        if (m && m[1] && m[2])
+            return { owner: m[1], repo: m[2] };
+    }
+    catch {
+        // not a git repo / no origin — fine
+    }
+    return null;
+}
+export async function refine(argv, cliVersion) {
+    const args = parseArgs(argv);
+    const anthropicKey = process.env["ANTHROPIC_API_KEY"];
+    if (!anthropicKey) {
+        console.error("ANTHROPIC_API_KEY environment variable is not set.");
+        process.exit(2);
+    }
+    const githubToken = process.env["GITHUB_TOKEN"];
+    if (!githubToken) {
+        console.error("GITHUB_TOKEN environment variable is not set.");
+        process.exit(2);
+    }
+    let owner = args.owner;
+    let repo = args.repo;
+    if (!owner || !repo) {
+        const detected = detectOwnerRepo(args.repoRoot);
+        if (!detected) {
+            console.error("Could not detect owner/repo from git remote. Pass --owner and --repo explicitly.");
+            process.exit(2);
+        }
+        owner = owner ?? detected.owner;
+        repo = repo ?? detected.repo;
+    }
+    const forge = new GitHubAdapter({ owner, repo, token: githubToken });
+    const llm = new AnthropicClient(anthropicKey);
+    const ctx = {
+        issueNumber: args.issueNumber,
+        repoRoot: args.repoRoot,
+        forge,
+        llm,
+        refineModel: args.refineModel,
+        relationshipModel: args.relationshipModel,
+        cliVersion,
+        baseBranch: args.baseBranch,
+        now: new Date(),
+    };
+    console.log(`slowcook refine · issue #${args.issueNumber} on ${owner}/${repo} (refine model: ${args.refineModel})`);
+    try {
+        const outcome = await runRefinement(ctx);
+        switch (outcome.kind) {
+            case "questions-posted":
+                console.log(`Posted clarifying questions (comment ${outcome.commentId}). Awaiting PM reply.`);
+                break;
+            case "spec-emitted":
+                console.log(`Spec written: ${outcome.specPath}`);
+                console.log(`Draft PR: ${outcome.prUrl}`);
+                break;
+            case "overlap-flagged":
+                console.log(`Overlap with ${outcome.conflicting_ids.join(", ")}. Awaiting PM resolution.`);
+                break;
+            case "contradiction-blocked":
+                console.log(`Contradiction with ${outcome.conflicting_ids.join(", ")}. Blocked until 'change-of-mind' label applied.`);
+                break;
+            case "change-of-mind-accepted":
+                console.log(`Change-of-mind accepted; will supersede ${outcome.supersedes.join(", ")}.`);
+                break;
+            case "noop":
+                console.log(`Noop: ${outcome.reason}.`);
+                break;
+        }
+    }
+    catch (e) {
+        console.error(`Refinement failed: ${e.message}`);
+        if (process.env["SLOWCOOK_DEBUG"]) {
+            console.error(e);
+        }
+        process.exit(2);
+    }
+}
+//# sourceMappingURL=index.js.map

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

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

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

@@ -0,0 +1,27 @@
+/**
+ * Minimal LLM interface the refinement agent uses. Isolated so we can inject
+ * a fake in tests without touching the network.
+ */
+export interface LlmClient {
+    complete(args: LlmRequest): Promise<string>;
+}
+export interface LlmMessage {
+    role: "user" | "assistant";
+    content: string;
+}
+export interface LlmRequest {
+    system: string;
+    /** System content will be cached if `cacheSystem` is true. */
+    cacheSystem?: boolean;
+    messages: LlmMessage[];
+    /** Model id to use (e.g., "claude-opus-4-7"). */
+    model: string;
+    maxTokens?: number;
+    temperature?: number;
+}
+export declare class AnthropicClient implements LlmClient {
+    private readonly client;
+    constructor(apiKey: string);
+    complete(args: LlmRequest): Promise<string>;
+}
+//# sourceMappingURL=llm.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../../../src/commands/refine/llm.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,eAAgB,YAAW,SAAS;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;gBAEvB,MAAM,EAAE,MAAM;IAIpB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;CA4BlD"}

package/dist/commands/refine/llm.js

@@ -0,0 +1,33 @@
+import Anthropic from "@anthropic-ai/sdk";
+export class AnthropicClient {
+    client;
+    constructor(apiKey) {
+        this.client = new Anthropic({ apiKey });
+    }
+    async complete(args) {
+        const systemContent = args.cacheSystem
+            ? [
+                {
+                    type: "text",
+                    text: args.system,
+                    cache_control: { type: "ephemeral" },
+                },
+            ]
+            : args.system;
+        const response = await this.client.messages.create({
+            model: args.model,
+            max_tokens: args.maxTokens ?? 4096,
+            temperature: args.temperature ?? 0.2,
+            system: systemContent,
+            messages: args.messages.map((m) => ({
+                role: m.role,
+                content: m.content,
+            })),
+        });
+        const first = response.content[0];
+        if (first && first.type === "text")
+            return first.text;
+        throw new Error(`Expected a text response from Claude, got: ${JSON.stringify(response.content).slice(0, 200)}`);
+    }
+}
+//# sourceMappingURL=llm.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"llm.js","sourceRoot":"","sources":["../../../src/commands/refine/llm.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,mBAAmB,CAAC;AA0B1C,MAAM,OAAO,eAAe;IACT,MAAM,CAAY;IAEnC,YAAY,MAAc;QACxB,IAAI,CAAC,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;IAC1C,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,IAAgB;QAC7B,MAAM,aAAa,GAAG,IAAI,CAAC,WAAW;YACpC,CAAC,CAAC;gBACE;oBACE,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,IAAI,CAAC,MAAM;oBACjB,aAAa,EAAE,EAAE,IAAI,EAAE,WAAoB,EAAE;iBAC9C;aACF;YACH,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;QAEhB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;YACjD,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,UAAU,EAAE,IAAI,CAAC,SAAS,IAAI,IAAI;YAClC,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,GAAG;YACpC,MAAM,EAAE,aAAsB;YAC9B,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAClC,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,OAAO,EAAE,CAAC,CAAC,OAAO;aACnB,CAAC,CAAC;SACJ,CAAC,CAAC;QAEH,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QAClC,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM;YAAE,OAAO,KAAK,CAAC,IAAI,CAAC;QACtD,MAAM,IAAI,KAAK,CACb,8CAA8C,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAC/F,CAAC;IACJ,CAAC;CACF"}