@slowcook-ai/cli 0.6.14 → 0.7.1

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

@@ -11,11 +11,29 @@ export interface RelationshipOptions {
 }
 export declare function analyzeRelationship(input: RelationshipInput, options: RelationshipOptions): Promise<RelationshipVerdict>;
 export declare function parseVerdict(raw: string): RelationshipVerdict;
+/**
+ * Format a spec reference for user-facing prose (issue comments, PR bodies).
+ * Prefers GitHub's native issue-number reference (\`#N\`) which auto-renders
+ * as a hyperlink. Falls back to the internal \`story-N\` id if the spec has
+ * no \`source_issue\` recorded.
+ *
+ * Inside YAML specs and internal slowcook state, keep using \`story-N\` —
+ * it's the stable canonical identifier. This function is only for prose.
+ */
+export declare function specRefForProse(spec: Spec): string;
 /** Comment body posted to the issue when relationship analysis surfaces a conflict. */
 export declare function overlapCommentBody(verdict: Extract<RelationshipVerdict, {
     kind: "overlap";
-}>): string;
+}>, activeSpecs?: Spec[]): string;
+/**
+ * Comment body for the follow_up verdict — posted informationally, does NOT
+ * halt refinement. Tells the PM "I noticed this builds on X, will cite it in
+ * the resulting spec, proceeding with refinement now."
+ */
+export declare function followUpCommentBody(verdict: Extract<RelationshipVerdict, {
+    kind: "follow_up";
+}>, activeSpecs?: Spec[]): string;
 export declare function contradictionCommentBody(verdict: Extract<RelationshipVerdict, {
     kind: "contradiction";
-}>, hasChangeOfMind: boolean): string;
+}>, hasChangeOfMind: boolean, activeSpecs?: Spec[]): string;
 //# sourceMappingURL=relationship.d.ts.map

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

@@ -1 +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"}
+{"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,CA6B7D;AAmBD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAIlD;AAYD,uFAAuF;AACvF,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,OAAO,CAAC,mBAAmB,EAAE;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC,EAC1D,WAAW,GAAE,IAAI,EAAO,GACvB,MAAM,CAeR;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,OAAO,CAAC,mBAAmB,EAAE;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,CAAC,EAC5D,WAAW,GAAE,IAAI,EAAO,GACvB,MAAM,CASR;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,OAAO,CAAC,mBAAmB,EAAE;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,CAAC,EAChE,eAAe,EAAE,OAAO,EACxB,WAAW,GAAE,IAAI,EAAO,GACvB,MAAM,CAwBR"}

package/dist/commands/refine/relationship.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { RELATIONSHIP_ANALYST_SYSTEM } from "./prompts.js";
 const VerdictSchema = z.object({
-    kind: z.enum(["new_or_independent", "overlap", "contradiction"]),
+    kind: z.enum(["new_or_independent", "follow_up", "overlap", "contradiction"]),
     conflicting_ids: z.array(z.string()),
     reasoning: z.string(),
 });
@@ -80,6 +80,9 @@ export function parseVerdict(raw) {
     if (v.kind === "new_or_independent") {
         return { kind: "new_or_independent", reasoning: v.reasoning };
     }
+    if (v.kind === "follow_up") {
+        return { kind: "follow_up", related_ids: v.conflicting_ids, reasoning: v.reasoning };
+    }
     if (v.kind === "overlap") {
         return { kind: "overlap", conflicting_ids: v.conflicting_ids, reasoning: v.reasoning };
     }
@@ -103,9 +106,34 @@ function extractJsonObject(raw) {
     }
     return trimmed;
 }
+/**
+ * Format a spec reference for user-facing prose (issue comments, PR bodies).
+ * Prefers GitHub's native issue-number reference (\`#N\`) which auto-renders
+ * as a hyperlink. Falls back to the internal \`story-N\` id if the spec has
+ * no \`source_issue\` recorded.
+ *
+ * Inside YAML specs and internal slowcook state, keep using \`story-N\` —
+ * it's the stable canonical identifier. This function is only for prose.
+ */
+export function specRefForProse(spec) {
+    const issueNum = spec.source_issue?.match(/#?(\d+)/)?.[1];
+    if (issueNum)
+        return `#${issueNum} (story-${spec.story_id})`;
+    return `story-${spec.story_id}`;
+}
+function specsRef(ids, activeSpecs) {
+    return ids
+        .map((id) => {
+        const found = activeSpecs.find((s) => s.story_id === id);
+        if (found)
+            return specRefForProse(found);
+        return `\`story-${id}\``;
+    })
+        .join(", ");
+}
 /** 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(", ");
+export function overlapCommentBody(verdict, activeSpecs = []) {
+    const specs = specsRef(verdict.conflicting_ids, activeSpecs);
     return `### slowcook · overlap detected
 
 This issue overlaps with existing active specs: ${specs}.
@@ -120,8 +148,23 @@ Please choose how to proceed:
 
 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(", ");
+/**
+ * Comment body for the follow_up verdict — posted informationally, does NOT
+ * halt refinement. Tells the PM "I noticed this builds on X, will cite it in
+ * the resulting spec, proceeding with refinement now."
+ */
+export function followUpCommentBody(verdict, activeSpecs = []) {
+    const specs = specsRef(verdict.related_ids, activeSpecs);
+    return `### slowcook · follow-up detected
+
+This issue builds on top of ${specs} — it fulfills scope the prior spec(s) explicitly deferred via \`non_goals\` or "future story" phrasing. That's a legitimate scope-growth pattern, not a duplication. **Continuing with refinement.**
+
+**Reasoning:** ${verdict.reasoning}
+
+The resulting spec will list the predecessor(s) in its \`related_specs\` field so the chain is auditable.`;
+}
+export function contradictionCommentBody(verdict, hasChangeOfMind, activeSpecs = []) {
+    const specs = specsRef(verdict.conflicting_ids, activeSpecs);
     if (hasChangeOfMind) {
         return `### slowcook · change-of-mind authorized
 

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

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

@@ -34,44 +34,44 @@ export declare const schemas: {
             supersedes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
             superseded_by: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNull]>>;
         }, "strip", z.ZodTypeAny, {
-            title: string;
             status: "draft" | "active" | "superseded";
+            title: string;
+            supersedes?: string[] | undefined;
+            superseded_by?: string | null | undefined;
             source_issue?: string | undefined;
             tags?: string[] | undefined;
             summary?: string | undefined;
-            supersedes?: string[] | undefined;
-            superseded_by?: string | null | undefined;
         }, {
-            title: string;
             status: "draft" | "active" | "superseded";
+            title: string;
+            supersedes?: string[] | undefined;
+            superseded_by?: string | null | undefined;
             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, {
-            title: string;
             status: "draft" | "active" | "superseded";
+            title: string;
+            supersedes?: string[] | undefined;
+            superseded_by?: string | null | undefined;
             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, {
-            title: string;
             status: "draft" | "active" | "superseded";
+            title: string;
+            supersedes?: string[] | undefined;
+            superseded_by?: string | null | undefined;
             source_issue?: string | undefined;
             tags?: string[] | undefined;
             summary?: string | undefined;
-            supersedes?: string[] | undefined;
-            superseded_by?: string | null | undefined;
         }>;
         $schema?: string | undefined;
     }>;
@@ -109,20 +109,20 @@ export declare const schemas: {
             note: z.ZodOptional<z.ZodString>;
         }, "strip", z.ZodTypeAny, {
             id: string;
-            relationship: "superseded" | "overlap" | "related";
+            relationship: "overlap" | "superseded" | "related";
             note?: string | undefined;
         }, {
             id: string;
-            relationship: "superseded" | "overlap" | "related";
+            relationship: "overlap" | "superseded" | "related";
             note?: string | undefined;
         }>, "many">>;
     }, "strip", z.ZodTypeAny, {
-        title: string;
         status: "draft" | "active" | "superseded";
-        supersedes: string[];
-        superseded_by: string | null;
         story_id: string;
+        title: string;
         created_at: string;
+        supersedes: string[];
+        superseded_by: string | null;
         actors: {
             name: string;
             notes?: string | undefined;
@@ -131,25 +131,25 @@ export declare const schemas: {
         invariants: string[];
         acceptance_scenarios: string[];
         non_goals: string[];
-        source_issue?: string | undefined;
-        $schema?: string | undefined;
         token_budget_usd?: number | undefined;
         estimate?: "small" | "medium" | "large" | undefined;
+        source_issue?: string | undefined;
         refined_by?: string | undefined;
         api_contract?: unknown[] | undefined;
         ui_behavior?: Record<string, string> | undefined;
         related_specs?: {
             id: string;
-            relationship: "superseded" | "overlap" | "related";
+            relationship: "overlap" | "superseded" | "related";
             note?: string | undefined;
         }[] | undefined;
+        $schema?: string | undefined;
     }, {
-        title: string;
         status: "draft" | "active" | "superseded";
-        supersedes: string[];
-        superseded_by: string | null;
         story_id: string;
+        title: string;
         created_at: string;
+        supersedes: string[];
+        superseded_by: string | null;
         actors: {
             name: string;
             notes?: string | undefined;
@@ -158,18 +158,18 @@ export declare const schemas: {
         invariants: string[];
         acceptance_scenarios: string[];
         non_goals: string[];
-        source_issue?: string | undefined;
-        $schema?: string | undefined;
         token_budget_usd?: number | undefined;
         estimate?: "small" | "medium" | "large" | undefined;
+        source_issue?: string | undefined;
         refined_by?: string | undefined;
         api_contract?: unknown[] | undefined;
         ui_behavior?: Record<string, string> | undefined;
         related_specs?: {
             id: string;
-            relationship: "superseded" | "overlap" | "related";
+            relationship: "overlap" | "superseded" | "related";
             note?: string | undefined;
         }[] | undefined;
+        $schema?: string | undefined;
     }>;
     SpecIndexEntry: z.ZodObject<{
         title: z.ZodString;
@@ -180,21 +180,21 @@ export declare const schemas: {
         supersedes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         superseded_by: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNull]>>;
     }, "strip", z.ZodTypeAny, {
-        title: string;
         status: "draft" | "active" | "superseded";
+        title: string;
+        supersedes?: string[] | undefined;
+        superseded_by?: string | null | undefined;
         source_issue?: string | undefined;
         tags?: string[] | undefined;
         summary?: string | undefined;
-        supersedes?: string[] | undefined;
-        superseded_by?: string | null | undefined;
     }, {
-        title: string;
         status: "draft" | "active" | "superseded";
+        title: string;
+        supersedes?: string[] | undefined;
+        superseded_by?: string | null | undefined;
         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. */

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

@@ -43,6 +43,39 @@ export type TestgenOutcome = {
  */
 export declare function runTestgen(ctx: TestgenContext): Promise<TestgenOutcome>;
 export declare function buildProjectContext(repoRoot: string): string;
+/**
+ * Phase B2 (0.7.0) testgen output: one test file, zero-or-more route stubs,
+ * zero-or-more mock helpers. The LLM emits these as XML-tagged blocks
+ * (see TESTGEN_SYSTEM for the exact format); slowcook parses, de-duplicates
+ * against existing files, and writes only what's new.
+ */
+export interface TestgenBundle {
+    testContent: string;
+    stubs: Array<{
+        path: string;
+        contents: string;
+    }>;
+    helpers: Array<{
+        path: string;
+        contents: string;
+    }>;
+}
+/**
+ * Parse XML-tagged multi-artifact output into a TestgenBundle.
+ *
+ * Accepted shape (from the prompt):
+ *   <test_file>...</test_file>
+ *   <stub path="src/app/api/foo/route.ts">...</stub>   (zero or more)
+ *   <helper path="tests/helpers/mocks/bar.ts">...</helper>  (zero or more)
+ *
+ * Tolerant of code-fenced output: if the LLM wraps the whole thing in
+ * ```, we strip it. If a block's contents are themselves code-fenced,
+ * we strip those too — tier-1 test / helper / stub files are raw TS.
+ *
+ * Throws if `<test_file>` is missing or empty — that's the one mandatory
+ * artifact.
+ */
+export declare function parseTestgenBundle(raw: string, storyId: string): TestgenBundle;
 /**
  * Tier-1 conformance lint. Run on every generated test file before commit.
  * Catches patterns the prompt forbids — inline `vi.mock`, `fetch(...)`,

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

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/commands/testgen/agent.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,YAAY,EAAQ,MAAM,mBAAmB,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AASlD,eAAO,MAAM,iBAAiB,gBAAgB,CAAC;AAC/C,eAAO,MAAM,qBAAqB,oBAAoB,CAAC;AAEvD,eAAO,MAAM,qBAAqB,sBAAsB,CAAC;AACzD,eAAO,MAAM,aAAa,uBAAuB,CAAC;AAClD,eAAO,MAAM,gBAAgB,wBAAwB,CAAC;AAEtD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,YAAY,CAAC;IACpB,GAAG,EAAE,SAAS,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,GAAG,EAAE,OAAO,CAAC;IACb,2EAA2E;IAC3E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,mCAAmC;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,GAAG,EAAE,IAAI,CAAC;CACX;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,EAAE,CAAA;CAAE,GACzG;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5E;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAqH7E;AAgCD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CA6E5D;AA4BD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AA6DD,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAepF;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CA4BjF"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/commands/testgen/agent.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,YAAY,EAAQ,MAAM,mBAAmB,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AASlD,eAAO,MAAM,iBAAiB,gBAAgB,CAAC;AAC/C,eAAO,MAAM,qBAAqB,oBAAoB,CAAC;AAEvD,eAAO,MAAM,qBAAqB,sBAAsB,CAAC;AACzD,eAAO,MAAM,aAAa,uBAAuB,CAAC;AAClD,eAAO,MAAM,gBAAgB,wBAAwB,CAAC;AAEtD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,YAAY,CAAC;IACpB,GAAG,EAAE,SAAS,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,GAAG,EAAE,OAAO,CAAC;IACb,2EAA2E;IAC3E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,mCAAmC;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,GAAG,EAAE,IAAI,CAAC;CACX;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,EAAE,CAAA;CAAE,GACzG;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5E;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CA8I7E;AAkED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CA8F5D;AAsCD;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjD,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACpD;AAqBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,aAAa,CAiC9E;AASD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AA6DD,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAepF;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CA4BjF"}

package/dist/commands/testgen/agent.js

@@ -1,4 +1,4 @@
-import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, readdirSync, } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, readdirSync, statSync, } from "node:fs";
 import { join, dirname } from "node:path";
 import YAML from "yaml";
 import { buildManifest, } from "@slowcook-ai/core";
@@ -26,14 +26,14 @@ export async function runTestgen(ctx) {
     const toRemove = [];
     for (const spec of specs) {
         const projectContext = buildProjectContext(ctx.repoRoot);
-        const fileContents = await generateTestFile(spec, ctx, projectContext);
+        const bundle = await generateTestBundle(spec, ctx, projectContext);
         const testPath = join(TESTS_INTEGRATION_DIR, `story-${spec.story_id}.test.ts`);
         // Tier-1 conformance gate: if the LLM slipped back to tier-0 habits
         // (inline vi.mock, fetch(), etc.), we refuse to ship the file. Halts
         // loudly here rather than quietly producing HTTP-loopback tests the
         // brewing loop can't ratchet against. The caller can re-run with a
         // different seed or hand-edit and re-run testgen.
-        const violations = lintTierOneTest(testPath, fileContents);
+        const violations = lintTierOneTest(testPath, bundle.testContent);
         if (violations.length > 0) {
             const details = violations
                 .slice(0, 10)
@@ -44,7 +44,12 @@ export async function runTestgen(ctx) {
                 `The LLM emitted patterns banned by docs/plans/0.7-testgen-two-tier.md §4.1-§7.3. ` +
                 `Re-run testgen with a different model/seed, or hand-edit the generated file to use project mock helpers.`);
         }
-        const manifestIds = extractTestIdsFromFile(testPath, fileContents);
+        // De-dupe stubs + helpers: skip anything whose target file exists and
+        // isn't a @slowcook-stub (for stubs) or isn't empty (for helpers). This
+        // lets testgen re-run safely without clobbering in-progress impls.
+        const stubsToWrite = bundle.stubs.filter((s) => shouldWriteStub(ctx.repoRoot, s.path));
+        const helpersToWrite = bundle.helpers.filter((h) => shouldWriteHelper(ctx.repoRoot, h.path));
+        const manifestIds = extractTestIdsFromFile(testPath, bundle.testContent);
         const manifest = buildManifest({
             slowcookVersion: ctx.cliVersion,
             storyId: spec.story_id,
@@ -52,7 +57,14 @@ export async function runTestgen(ctx) {
             suites: [{ suite: "backend", command: "npx vitest list", test_count: manifestIds.length }],
             now: ctx.now,
         });
-        generated.push({ spec, testPath, fileContents, manifest });
+        generated.push({
+            spec,
+            testPath,
+            fileContents: bundle.testContent,
+            manifest,
+            stubs: stubsToWrite,
+            helpers: helpersToWrite,
+        });
         for (const superseded of spec.supersedes) {
             toRemove.push(superseded);
         }
@@ -62,6 +74,12 @@ export async function runTestgen(ctx) {
         writeFileAt(ctx.repoRoot, g.testPath, g.fileContents);
         const manifestPath = join(MANIFESTS_DIR, `story-${g.spec.story_id}.json`);
         writeFileAt(ctx.repoRoot, manifestPath, JSON.stringify(g.manifest, null, 2) + "\n");
+        for (const stub of g.stubs) {
+            writeFileAt(ctx.repoRoot, stub.path, stub.contents);
+        }
+        for (const helper of g.helpers) {
+            writeFileAt(ctx.repoRoot, helper.path, helper.contents);
+        }
     }
     const actuallyRemoved = [];
     for (const id of toRemove) {
@@ -77,6 +95,10 @@ export async function runTestgen(ctx) {
     for (const g of generated) {
         await ctx.forge.git.stage(g.testPath);
         await ctx.forge.git.stage(join(MANIFESTS_DIR, `story-${g.spec.story_id}.json`));
+        for (const stub of g.stubs)
+            await ctx.forge.git.stage(stub.path);
+        for (const helper of g.helpers)
+            await ctx.forge.git.stage(helper.path);
     }
     for (const id of actuallyRemoved) {
         await ctx.forge.git.stage(join(TESTS_INTEGRATION_DIR, `story-${id}.test.ts`));
@@ -123,6 +145,38 @@ export async function runTestgen(ctx) {
         throw e;
     }
 }
+/**
+ * Decide whether to write a stub file. Write when:
+ *  - The target doesn't exist — most common case, new story.
+ *  - The target exists but is itself a @slowcook-stub (marker on line 1).
+ *    Lets testgen re-runs refresh stubs as spec evolves.
+ * Skip when:
+ *  - The target exists and has real implementation (no stub marker).
+ *    Could be a brownfield consumer where the route already exists, or
+ *    brewing has already replaced the stub body. Either way, don't clobber.
+ */
+function shouldWriteStub(repoRoot, path) {
+    const full = join(repoRoot, path);
+    if (!existsSync(full))
+        return true;
+    try {
+        const first = readFileSync(full, "utf8").split("\n")[0] ?? "";
+        return first.includes("@slowcook-stub");
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Decide whether to write a helper file. Write when the target doesn't
+ * exist. Never clobber an existing helper — the consumer may have
+ * hand-customised it, and the generated version would lose those edits.
+ * Operator can delete the file and re-run testgen to get a fresh
+ * auto-generated helper.
+ */
+function shouldWriteHelper(repoRoot, path) {
+    return !existsSync(join(repoRoot, path));
+}
 function collectTargetSpecs(ctx) {
     const index = readIndex(ctx.repoRoot);
     const all = Object.entries(index.stories)
@@ -185,10 +239,26 @@ export function buildProjectContext(repoRoot) {
     else {
         bits.push("\nNo existing integration tests — this will be the first in the repo.");
     }
+    // List existing API route files so the LLM knows NOT to emit a <stub>
+    // block for them. (A route that already exists has a real impl; stubbing
+    // over it would clobber production code. The consumer may also have
+    // brownfield code that pre-existed slowcook adoption — listed here so
+    // testgen respects what's there.)
+    const appDir = join(repoRoot, "src", "app");
+    if (existsSync(appDir)) {
+        const routes = listAppRouterFiles(appDir).sort();
+        if (routes.length > 0) {
+            bits.push(`\n### Existing API route files (under src/app/)\n\nThese already exist — do NOT emit a \`<stub>\` block for any of them. If the test imports from one of these, assume the route file exists and skip stub generation.`);
+            for (const r of routes.slice(0, 50))
+                bits.push(`- \`${r}\``);
+            if (routes.length > 50)
+                bits.push(`- … (${routes.length - 50} more)`);
+        }
+    }
     // List existing mock helpers so the LLM knows which to import. The
     // helper pattern is load-bearing for the future record-and-replay swap
     // (plans/0.7-testgen-two-tier.md §4.3). Helpers NOT listed here will
-    // surface as TODO(helper) comments in the generated test.
+    // be auto-generated by testgen B2 as <helper> blocks.
     const helpersDir = join(repoRoot, MOCK_HELPERS_DIR);
     if (existsSync(helpersDir)) {
         const helpers = readdirSync(helpersDir)
@@ -214,28 +284,111 @@ export function buildProjectContext(repoRoot) {
         }
     }
     else {
-        bits.push(`\n### Mock helpers\n\nNo \`${MOCK_HELPERS_DIR}/\` directory yet — this project hasn't set up the helper pattern. Emit \`TODO(helper): <service>\` comments for each external dependency the handler calls; an operator will hand-author the helpers before brewing can run (helper auto-generation ships in a later slowcook release).`);
+        bits.push(`\n### Mock helpers\n\nNo \`${MOCK_HELPERS_DIR}/\` directory yet — this project hasn't set up the helper pattern. Emit a \`<helper>\` block for each external dependency the handler calls, matching the helper-file shape in the system prompt. Also emit a \`<helper path="${MOCK_HELPERS_DIR}/index.ts">\` barrel re-exporting your new helpers.`);
     }
     return bits.join("\n");
 }
-async function generateTestFile(spec, ctx, projectContext) {
+/**
+ * Walk src/app/ and return every route file path (repo-relative) that
+ * Next.js App Router treats as an endpoint. We surface these to the
+ * testgen LLM so it doesn't emit a <stub> for a file that already
+ * exists.
+ */
+function listAppRouterFiles(appDir) {
+    const out = [];
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of entries) {
+            const full = join(dir, name);
+            let stat;
+            try {
+                stat = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (stat.isDirectory())
+                walk(full);
+            else if (stat.isFile() && /^(route|page)\.(ts|tsx)$/.test(name)) {
+                // Return repo-relative path. Parent dirs up to "src/app" are derivable
+                // from appDir; we trim appDir and prefix "src/app".
+                const rel = full.slice(full.indexOf("src/app"));
+                out.push(rel);
+            }
+        }
+    };
+    walk(appDir);
+    return out;
+}
+async function generateTestBundle(spec, ctx, projectContext) {
     const systemPrompt = TESTGEN_SYSTEM(projectContext);
-    const userMessage = `Here is the spec YAML. Generate the Vitest integration test file:\n\n\`\`\`yaml\n${YAML.stringify(spec)}\n\`\`\``;
+    const userMessage = `Here is the spec YAML. Generate the tier-1 test bundle (test file + any needed stubs + any needed helpers):\n\n\`\`\`yaml\n${YAML.stringify(spec)}\n\`\`\``;
     const raw = await ctx.llm.complete({
         system: systemPrompt,
         cacheSystem: true,
         model: ctx.model,
         messages: [{ role: "user", content: userMessage }],
-        maxTokens: 8192,
+        maxTokens: 16384,
     });
-    return stripCodeFence(raw);
+    return parseTestgenBundle(raw, spec.story_id);
+}
+/**
+ * Parse XML-tagged multi-artifact output into a TestgenBundle.
+ *
+ * Accepted shape (from the prompt):
+ *   <test_file>...</test_file>
+ *   <stub path="src/app/api/foo/route.ts">...</stub>   (zero or more)
+ *   <helper path="tests/helpers/mocks/bar.ts">...</helper>  (zero or more)
+ *
+ * Tolerant of code-fenced output: if the LLM wraps the whole thing in
+ * ```, we strip it. If a block's contents are themselves code-fenced,
+ * we strip those too — tier-1 test / helper / stub files are raw TS.
+ *
+ * Throws if `<test_file>` is missing or empty — that's the one mandatory
+ * artifact.
+ */
+export function parseTestgenBundle(raw, storyId) {
+    const trimmed = raw.trim();
+    // Strip outer code fence if the LLM wrapped everything
+    const outerFenceMatch = trimmed.match(/^```[a-z]*\s*\n([\s\S]*)\n```$/);
+    const body = outerFenceMatch && outerFenceMatch[1] ? outerFenceMatch[1] : trimmed;
+    const testMatch = body.match(/<test_file>([\s\S]*?)<\/test_file>/);
+    if (!testMatch || !testMatch[1]) {
+        throw new Error(`testgen: LLM output for story-${storyId} missing a <test_file> block. ` +
+            `Got ${body.length} chars starting with: ${body.slice(0, 120)}...`);
+    }
+    const testContent = stripInnerFence(testMatch[1]);
+    const stubs = [];
+    const stubRe = /<stub\s+path="([^"]+)">([\s\S]*?)<\/stub>/g;
+    let m;
+    while ((m = stubRe.exec(body)) !== null) {
+        const p = m[1] ?? "";
+        const c = m[2] ?? "";
+        if (p && c.trim())
+            stubs.push({ path: p, contents: stripInnerFence(c) });
+    }
+    const helpers = [];
+    const helperRe = /<helper\s+path="([^"]+)">([\s\S]*?)<\/helper>/g;
+    while ((m = helperRe.exec(body)) !== null) {
+        const p = m[1] ?? "";
+        const c = m[2] ?? "";
+        if (p && c.trim())
+            helpers.push({ path: p, contents: stripInnerFence(c) });
+    }
+    return { testContent, stubs, helpers };
 }
-function stripCodeFence(raw) {
+function stripInnerFence(raw) {
     const t = raw.trim();
-    const fence = t.match(/^```(?:typescript|ts)?\s*\n([\s\S]*)\n```$/);
+    const fence = t.match(/^```(?:typescript|ts|tsx)?\s*\n([\s\S]*)\n```$/);
     if (fence && fence[1])
         return fence[1];
-    return t;
+    return t + "\n"; // ensure trailing newline for file writes
 }
 /**
  * Two scan modes:
@@ -461,6 +614,24 @@ function buildPrBody(args) {
         const manifestCount = g.manifest.tests.length;
         sections.push(`- \`story-${g.spec.story_id}\` — *${g.spec.title}* — ${manifestCount} test(s) in \`${g.testPath}\``);
     }
+    const allStubs = args.generated.flatMap((g) => g.stubs);
+    if (allStubs.length > 0) {
+        sections.push("");
+        sections.push("## Generated stubs (route files)");
+        sections.push("Minimal throwing route files so tier-1 tests can collect. Each carries an \`@slowcook-stub\` marker on line 1. **Brewing will replace these bodies** with the real implementation across its iterations. Reviewer check: correct file path + export signature + \`@slowcook-stub\` marker present. If the signature is wrong the whole PR is wrong — flag it now.");
+        for (const s of allStubs) {
+            sections.push(`- \`${s.path}\``);
+        }
+    }
+    const allHelpers = args.generated.flatMap((g) => g.helpers);
+    if (allHelpers.length > 0) {
+        sections.push("");
+        sections.push("## Generated mock helpers");
+        sections.push("Signature-asserting fakes for external services the handlers consume. **Three load-bearing properties**: (1) calling the real module's exported function with wrong args throws loudly (catches the class of bug where tests pass via mock-arg-ignoring but production crashes); (2) every chained method pushes to \`client.calls\` so tests assert against that instead of poking \`vi.fn\` internals; (3) config is intent-level (\`user\`, \`tables\`) not implementation-level (\`return_value_for_from\`). Reviewer check: the \`realShaped*\` wrapper exists AND matches the real module's signature from \`src/\`.");
+        for (const h of allHelpers) {
+            sections.push(`- \`${h.path}\``);
+        }
+    }
     if (args.removedStoryIds.length > 0) {
         sections.push("");
         sections.push("## Tests removed (supersede chain)");