edsger 0.56.3 → 0.57.0

package/dist/phases/output-contracts.js

@@ -499,6 +499,92 @@ You MUST return ONLY a JSON object. Do NOT include any text before or after the
 - "frame_background": customize the gradient/color behind the device (e.g., "linear-gradient(135deg, #667eea 0%, #764ba2 100%)")
 - "frame_browser_url": set a realistic URL for browser frames (e.g., "app.yourproduct.com/dashboard")
 - If should_generate_video is false, scenes array should be empty
+`,
+    'user-psychology': `
+**CRITICAL - Result Format**:
+You MUST return ONLY a JSON object inside a \`\`\`json code block. Do NOT include any text before or after the JSON.
+
+\`\`\`json
+{
+  "analysis": {
+    "product_id": "PRODUCT_ID",
+    "status": "success",
+    "analysis_content": "3-4 sentence executive summary of who these users are and what they really care about. Concrete, not generic.",
+    "target_personas": [
+      {
+        "name": "Asha, the burned-out solo founder",
+        "archetype": "One-line description of who they are and what they do",
+        "demographics": {
+          "role": "Solo founder of a 1-5 person SaaS",
+          "seniority": "5-10 years experience",
+          "context": "Other specifics that matter (team size, tools, stage, etc.)"
+        },
+        "goals": ["Goal 1", "Goal 2"],
+        "frustrations": ["Frustration 1 in their voice", "Frustration 2"],
+        "values": "What they believe makes them good at their job",
+        "decision_drivers": ["What tips them toward yes", "Another driver"],
+        "anti_persona_note": "Who looks similar but is the wrong fit",
+        "evidence": "Which feature/file/context-line supports this persona"
+      }
+    ],
+    "jobs_to_be_done": [
+      {
+        "statement": "When [situation], I want to [motivation], so I can [outcome].",
+        "type": "functional|emotional|social",
+        "current_alternatives": ["Competitor / spreadsheet / nothing"],
+        "switching_cost": "What makes it hard to switch",
+        "persona": "Which persona this job belongs to (name from target_personas)"
+      }
+    ],
+    "pain_points": [
+      {
+        "pain": "Single sentence in the user's voice",
+        "trigger": "What event makes the pain acute",
+        "severity": "critical|chronic|occasional",
+        "evidence": "Which feature, file, or context line implies this pain"
+      }
+    ],
+    "motivations": {
+      "autonomy": "How the product serves their need for control / removes oversight (or 'not addressed')",
+      "competence": "How the product makes them feel capable",
+      "relatedness": "How the product connects them to others or signals belonging"
+    },
+    "behavior_triggers": [
+      {
+        "behavior": "Specific desired action (e.g., 'invite first teammate')",
+        "motivation_level": "high|medium|low",
+        "motivation_reason": "Why",
+        "ability_barrier": "What is hard about doing it",
+        "prompt": "What cue would trigger this right now",
+        "recommendation": "Concrete change to lift motivation, reduce barrier, or improve prompt"
+      }
+    ],
+    "messaging_angles": [
+      {
+        "angle_name": "Short label",
+        "hook": "The headline in 10-15 words, in the user's voice",
+        "persona": "Persona name this speaks to",
+        "job": "JTBD statement (or short reference) this answers",
+        "psychological_lever": "loss_aversion|social_proof|identity_affirmation|curiosity_gap|status|reciprocity|other",
+        "why_it_works": "One sentence on the lever"
+      }
+    ]
+  }
+}
+\`\`\`
+
+**Required field rules**:
+- 3-5 personas (collapse overlapping ones)
+- 4-8 jobs_to_be_done — cover at least one emotional and one social job, not just functional
+- 3-8 pain_points
+- behavior_triggers should target 3-5 high-value actions (signup, activation, retention, expansion)
+- 3-6 messaging_angles, each tied to a real persona + job
+
+**Anti-rules — these fail validation**:
+- No placeholder text ([role], [insert benefit], "users want to be productive")
+- No demographic-only personas — psychographics or skip the field
+- No "users struggle with X" phrasing in pain_points — write in the user's voice
+- No JTBD that is just a feature description ("user wants to use Feature Y")
 `,
     'intelligence-analysis': `
 **Output Format**:
@@ -809,5 +895,48 @@ You MUST end your response with a JSON object containing the code refine results
   }
 }
 \`\`\`
+`,
+    'screen-flow': `
+**CRITICAL — Output Format**:
+
+After finishing your investigation, emit a single fenced code block tagged \`screen_flow\` containing the structured extraction. Do not emit any other JSON blocks.
+
+\`\`\`screen_flow
+{
+  "summary": "1-3 sentence narrative of what kind of app this is and its primary user flows",
+  "nodes": [
+    {
+      "slug": "login",
+      "name": "Login",
+      "route": "/signin",
+      "file": "src/pages/Login.tsx",
+      "kind": "page",
+      "layout": "centered",
+      "header": { "title": "Sign in", "actions": [{ "label": "Sign up", "variant": "ghost" }] },
+      "body": [
+        {
+          "type": "form",
+          "submitLabel": "Sign in",
+          "fields": [
+            { "label": "Email", "kind": "email", "required": true },
+            { "label": "Password", "kind": "password", "required": true }
+          ]
+        }
+      ]
+    }
+  ],
+  "edges": [
+    {
+      "fromSlug": "login",
+      "toSlug": "home",
+      "triggerLabel": "Submit credentials",
+      "triggerFile": "src/pages/Login.tsx",
+      "kind": "navigate"
+    }
+  ]
+}
+\`\`\`
+
+All node \`slug\` values must be unique. Every \`fromSlug\` / \`toSlug\` in edges must reference a slug that appears in \`nodes\`. Section \`type\` values are restricted to: \`form\`, \`list\`, \`card-grid\`, \`table\`, \`kanban\`, \`text\`, \`image\`, \`chart\`, \`stats\`, \`empty-state\`, \`tabs\`, \`custom\`. Edge \`kind\` values are restricted to: \`navigate\`, \`modal\`, \`redirect\`, \`back\`.
 `,
 };

package/dist/phases/pr-resolve/github-reply.d.ts

@@ -3,10 +3,13 @@
  * Reuses GraphQL patterns from code-refine-verification.
  */
 import { type Octokit } from '@octokit/rest';
+export declare function buildResolveMarker(action: 'changed' | 'skipped'): string;
+export declare function hasResolveMarker(body: string | undefined | null): boolean;
 /**
- * Reply to a review thread on GitHub using GraphQL.
+ * Reply to a review thread on GitHub using GraphQL. Appends a marker so the
+ * next run can detect that we've already responded to this thread.
  */
-export declare function replyToReviewThread(octokit: Octokit, threadId: string, body: string, verbose?: boolean): Promise<boolean>;
+export declare function replyToReviewThread(octokit: Octokit, threadId: string, body: string, action: 'changed' | 'skipped', verbose?: boolean): Promise<boolean>;
 /**
  * Resolve a review thread on GitHub using GraphQL.
  */

package/dist/phases/pr-resolve/github-reply.js

@@ -4,9 +4,24 @@
  */
 import { logError, logInfo } from '../../utils/logger.js';
 /**
- * Reply to a review thread on GitHub using GraphQL.
+ * Marker appended to every reply we post so subsequent runs can recognise
+ * their own prior comments and avoid posting duplicates.
  */
-export async function replyToReviewThread(octokit, threadId, body, verbose) {
+const RESOLVE_MARKER_PREFIX = '<!-- edsger:pr-resolve';
+export function buildResolveMarker(action) {
+    return `${RESOLVE_MARKER_PREFIX}:${action} -->`;
+}
+export function hasResolveMarker(body) {
+    if (!body) {
+        return false;
+    }
+    return body.includes(RESOLVE_MARKER_PREFIX);
+}
+/**
+ * Reply to a review thread on GitHub using GraphQL. Appends a marker so the
+ * next run can detect that we've already responded to this thread.
+ */
+export async function replyToReviewThread(octokit, threadId, body, action, verbose) {
     try {
         const mutation = `
       mutation($threadId: ID!, $body: String!) {
@@ -20,7 +35,8 @@ export async function replyToReviewThread(octokit, threadId, body, verbose) {
         }
       }
     `;
-        await octokit.graphql(mutation, { threadId, body });
+        const bodyWithMarker = `${body}\n\n${buildResolveMarker(action)}`;
+        await octokit.graphql(mutation, { threadId, body: bodyWithMarker });
         if (verbose) {
             logInfo(`Replied to thread ${threadId}`);
         }

package/dist/phases/pr-resolve/index.js

@@ -14,7 +14,7 @@ import { fetchUnresolvedReviewThreads } from '../code-refine-verification/github
 import { createPromptGenerator, extractTextFromContent, tryExtractResult, } from '../pr-shared/agent-utils.js';
 import { parsePullRequestUrl } from '../pr-shared/context.js';
 import { learnFromReviewFeedback } from './checklist-learner.js';
-import { replyToReviewThread, resolveReviewThread } from './github-reply.js';
+import { hasResolveMarker, replyToReviewThread, resolveReviewThread, } from './github-reply.js';
 import { createResolveSystemPrompt, createResolveUserPrompt, } from './prompts.js';
 import { isResolveResult } from './types.js';
 import { hasNewCommits, hasUncommittedChanges, prepareWorkspace, pushChanges, } from './workspace.js';
@@ -35,12 +35,26 @@ export async function resolveStandalonePR(options) {
         const octokit = new Octokit({ auth: githubToken });
         // Fetch unresolved review threads
         logInfo('Fetching unresolved review threads...');
-        const unresolvedThreads = await fetchUnresolvedReviewThreads(octokit, owner, repo, prInfo.prNumber, verbose);
+        const allUnresolvedThreads = await fetchUnresolvedReviewThreads(octokit, owner, repo, prInfo.prNumber, verbose);
+        // Skip threads whose last comment already carries our marker — they were
+        // handled in a previous pr-resolve run and replying again would just spam.
+        // If a human has commented after our reply, the last comment will no
+        // longer be ours and the thread will be picked up again.
+        const unresolvedThreads = allUnresolvedThreads.filter((thread) => {
+            const lastComment = thread.comments.nodes[thread.comments.nodes.length - 1];
+            return !hasResolveMarker(lastComment?.body);
+        });
+        const alreadyHandled = allUnresolvedThreads.length - unresolvedThreads.length;
+        if (alreadyHandled > 0) {
+            logInfo(`Skipping ${alreadyHandled} thread(s) already addressed in a previous resolve run`);
+        }
         if (unresolvedThreads.length === 0) {
             logSuccess('No unresolved review threads found.');
             return {
                 status: 'success',
-                message: 'No unresolved review threads to resolve',
+                message: alreadyHandled > 0
+                    ? `All ${alreadyHandled} unresolved thread(s) were already addressed in a previous resolve run`
+                    : 'No unresolved review threads to resolve',
                 threadsAddressed: 0,
                 threadsSkipped: 0,
             };
@@ -162,7 +176,7 @@ export async function resolveStandalonePR(options) {
                     }
                     // eslint-disable-next-line max-depth
                     try {
-                        const replied = await replyToReviewThread(octokit, threadId, comment.reply, verbose);
+                        const replied = await replyToReviewThread(octokit, threadId, comment.reply, comment.action, verbose);
                         // eslint-disable-next-line max-depth
                         if (replied && comment.action === 'changed') {
                             // Resolve the thread since the change was made
@@ -192,7 +206,7 @@ export async function resolveStandalonePR(options) {
                         const genericReply = agentMadeChanges
                             ? 'Changes were made to address review feedback. Please re-review.'
                             : 'Reviewed this comment. No changes were made at this time.';
-                        const replied = await replyToReviewThread(octokit, thread.id, genericReply, verbose);
+                        const replied = await replyToReviewThread(octokit, thread.id, genericReply, agentMadeChanges ? 'changed' : 'skipped', verbose);
                         // eslint-disable-next-line max-depth
                         if (replied) {
                             threadsSkipped++;

package/dist/phases/pr-resolve/prompts.js

@@ -8,27 +8,26 @@
 export function createResolveSystemPrompt() {
     return `You are an expert software engineer resolving code review feedback on a pull request.
 
-**Your Goal**: For each review comment, evaluate whether the suggested change genuinely improves the code. If it does, make the change. If you disagree, do NOT make the change.
+**Your Goal**: For each review comment, make the change unless the reviewer is factually wrong or has misunderstood the code. The default is to accept the feedback.
 
-**Decision Criteria - Make the change when**:
-- The suggestion fixes a real bug or logic error
-- The suggestion improves correctness, security, or error handling
-- The suggestion makes the code clearer or more maintainable
-- The suggestion follows established best practices for the language/framework
+**Make the change when** (this is the default — apply it broadly):
+- The suggestion would improve the code in any way: correctness, security, error handling, clarity, maintainability, performance, design, naming, structure, tests, docs
+- The suggestion aligns with best practices for the language or framework
+- Apply the change even if it is large, touches many files, or requires non-trivial refactoring — workload is not a reason to skip
 
-**Skip the change when**:
-- The suggestion is purely stylistic preference without clear benefit
-- The suggestion would increase complexity without proportional value
-- The suggestion conflicts with the codebase's established patterns
-- You disagree with the technical rationale
+**Skip the change ONLY when** (the bar is high — be conservative about skipping):
+- The reviewer is factually wrong (e.g., claims the code does X when it actually does Y, or asserts a behavior that does not exist)
+- The reviewer has misunderstood the code's purpose, the surrounding context, or how this piece interacts with other parts of the system
+- Following the suggestion would actually make the code worse or introduce a regression
+
+Personal preference, "I'd prefer a different style", "this is more complex than I'd like", or "this conflicts with a pattern I prefer" are NOT valid reasons to skip. If the change would make the code better, do it.
 
 **Process**:
 1. Read all the review comments carefully
-2. For each comment, examine the relevant code
-3. If you agree: make the change in the file
-4. If you disagree: skip it (do NOT modify the file for that comment)
-5. After making all changes, commit them with a descriptive message summarizing what was resolved (do NOT push)
-6. After committing, output a JSON summary
+2. For each comment, examine the relevant code so you actually understand what it does
+3. Default: make the change in the file. Only skip if you can articulate a specific factual error or misunderstanding by the reviewer.
+4. After making all changes, commit them with a descriptive message summarizing what was resolved (do NOT push)
+5. After committing, output a JSON summary
 
 **CRITICAL - Result Format**:
 After making all changes, you MUST output a JSON result. Use the exact comment_id from each comment (comment_1, comment_2, etc.):
@@ -56,7 +55,7 @@ After making all changes, you MUST output a JSON result. Use the exact comment_i
 
 **Reply Guidelines**:
 - For "changed": briefly describe what was changed (1-2 sentences)
-- For "skipped": provide a clear, respectful technical explanation of why the current code is better (2-3 sentences)
+- For "skipped": clearly explain the specific factual error or misunderstanding — point to the exact line, behavior, or invariant the reviewer got wrong (2-3 sentences). Do not skip with a vague "I disagree" — name the misunderstanding.
 - Be professional and constructive in all replies
 - You MUST include an entry for EVERY comment_id`;
 }
@@ -101,7 +100,7 @@ export function createResolveUserPrompt(unresolvedThreads) {
     sections.push('## Instructions');
     sections.push('');
     sections.push('For each comment above, read the referenced file and evaluate the suggestion.');
-    sections.push('Make changes only when they genuinely improve the code. Skip changes you disagree with.');
+    sections.push('Default to making the change — even if it is large or touches many files. Only skip when the reviewer is factually wrong or has misunderstood the code, and explain the specific misunderstanding in your reply.');
     sections.push('After processing all comments, output the JSON resolve_result with your decisions and reply messages.');
     sections.push(`Use the exact comment IDs: ${Array.from(commentIdToThreadId.keys()).join(', ')}`);
     return { prompt: sections.join('\n'), commentIdToThreadId };

package/dist/phases/product-test-cases/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Product-test-cases phase: clone the product's repo, ask Claude to draft a
+ * product-level regression suite (deduping against existing cases), and save
+ * the new ones as drafts via MCP. Approved test cases are NEVER touched —
+ * only draft/pending_approval entries may be replaced.
+ *
+ * Mirrors the find-bugs pattern: clone to ~/edsger/product-test-cases-<id>,
+ * run a bounded Claude session, persist via MCP, cleanup on success.
+ */
+export interface GenerateProductTestCasesOptions {
+    productId: string;
+    githubToken: string;
+    owner: string;
+    repo: string;
+    branch?: string;
+    verbose?: boolean;
+}
+export interface GenerateProductTestCasesResult {
+    status: 'success' | 'error';
+    message: string;
+    createdCount?: number;
+    deletedCount?: number;
+    summary?: string;
+}
+export declare function generateProductTestCases(options: GenerateProductTestCasesOptions): Promise<GenerateProductTestCasesResult>;

package/dist/phases/product-test-cases/index.js

@@ -0,0 +1,174 @@
+/**
+ * Product-test-cases phase: clone the product's repo, ask Claude to draft a
+ * product-level regression suite (deduping against existing cases), and save
+ * the new ones as drafts via MCP. Approved test cases are NEVER touched —
+ * only draft/pending_approval entries may be replaced.
+ *
+ * Mirrors the find-bugs pattern: clone to ~/edsger/product-test-cases-<id>,
+ * run a bounded Claude session, persist via MCP, cleanup on success.
+ */
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { batchDeleteTestCases } from '../../api/issues/batch-operations.js';
+import { createProductTestCases, getProductTestCases, } from '../../api/products/test-cases.js';
+import { DEFAULT_MODEL } from '../../constants.js';
+import { logError, logInfo, logSuccess, logWarning, } from '../../utils/logger.js';
+import { cleanupIssueRepo, cloneIssueRepo, ensureWorkspaceDir, syncRepoToRef, } from '../../workspace/workspace-manager.js';
+import { detectDefaultBranch } from '../find-shared/git.js';
+import { fetchProductBasics } from '../find-shared/mcp.js';
+import { createScanStateModule } from '../find-shared/scan-state.js';
+import { createPromptGenerator, extractTextFromContent, tryExtractResult, } from '../pr-shared/agent-utils.js';
+import { createProductTestCasesSystemPrompt, createProductTestCasesUserPrompt, } from './prompts.js';
+import { isProductTestCasesAgentResult, } from './types.js';
+const WORKSPACE_KEY = 'product-test-cases';
+// Generation is read-heavy and open-scope. 200 turns matches find-bugs and is
+// enough for a mid-sized repo while still bounding cost.
+const MAX_TURNS = 200;
+// Per-product lock so two concurrent invocations (e.g. user clicks twice in
+// the UI, or CLI + desktop fire at once) don't race on the shared clone dir.
+// We don't persist any state besides the lock — generation is stateless.
+const lockModule = createScanStateModule({
+    dirName: 'product-test-cases-state',
+});
+// UUID regex matching MCP-issued ids — defensive filter before we trust
+// strings the agent puts in deleted_test_case_ids.
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+// eslint-disable-next-line complexity
+export async function generateProductTestCases(options) {
+    const { productId, githubToken, owner, repo, verbose } = options;
+    logInfo(`Starting product test-cases generation for product ${productId} (${owner}/${repo})`);
+    const lock = lockModule.acquireLock(productId);
+    if (!lock) {
+        logWarning(`Another product test-cases generation is already running for product ${productId}; skipping.`);
+        return {
+            status: 'error',
+            message: 'Another product test-cases generation is already running for this product',
+        };
+    }
+    let repoPath;
+    let succeeded = false;
+    try {
+        const workspaceRoot = ensureWorkspaceDir();
+        const repoKey = `${WORKSPACE_KEY}-${productId}`;
+        ({ repoPath } = cloneIssueRepo(workspaceRoot, repoKey, owner, repo, githubToken));
+        const branch = options.branch ?? detectDefaultBranch(repoPath);
+        logInfo(`Syncing ${owner}/${repo} to branch ${branch}`);
+        syncRepoToRef(repoPath, { branch }, githubToken);
+        const [product, existing] = await Promise.all([
+            fetchProductBasics(productId),
+            getProductTestCases(productId, verbose),
+        ]);
+        const approved = [];
+        const replaceable = [];
+        for (const tc of existing) {
+            const slot = {
+                id: tc.id,
+                name: tc.name,
+                description: tc.description,
+                is_critical: tc.is_critical,
+                status: tc.status ?? 'draft',
+            };
+            if (slot.status === 'approved') {
+                approved.push(slot);
+            }
+            else {
+                replaceable.push(slot);
+            }
+        }
+        const replaceableIds = new Set(replaceable.map((tc) => tc.id));
+        logInfo(`Existing test cases: ${approved.length} approved (locked), ${replaceable.length} replaceable`);
+        const systemPrompt = createProductTestCasesSystemPrompt();
+        const userPrompt = createProductTestCasesUserPrompt({
+            productName: product.name,
+            productDescription: product.description,
+            approvedTestCases: approved,
+            replaceableTestCases: replaceable,
+        });
+        let lastAssistantResponse = '';
+        let agentResult = null;
+        logInfo('Running Claude agent to draft test cases...');
+        for await (const message of query({
+            prompt: createPromptGenerator(userPrompt),
+            options: {
+                systemPrompt: {
+                    type: 'preset',
+                    preset: 'claude_code',
+                    append: systemPrompt,
+                },
+                model: DEFAULT_MODEL,
+                maxTurns: MAX_TURNS,
+                permissionMode: 'bypassPermissions',
+                cwd: repoPath,
+            },
+        })) {
+            if (message.type === 'assistant') {
+                lastAssistantResponse += extractTextFromContent(message.message?.content ?? [], verbose);
+                continue;
+            }
+            if (message.type !== 'result') {
+                continue;
+            }
+            const responseText = message.subtype === 'success'
+                ? message.result || lastAssistantResponse
+                : lastAssistantResponse;
+            const parsed = tryExtractResult(responseText, 'test_cases_result');
+            if (isProductTestCasesAgentResult(parsed)) {
+                agentResult = parsed;
+            }
+            else if (message.subtype !== 'success') {
+                logError(`Agent run incomplete: ${message.subtype}`);
+            }
+        }
+        if (!agentResult) {
+            return {
+                status: 'error',
+                message: 'Test cases generation failed: could not parse a test_cases_result from the agent',
+            };
+        }
+        // Apply deletions. Filter to only ids that are valid UUIDs AND belong
+        // to the replaceable set — never trust the agent's word that an id
+        // is deletable. Approved cases must never be removed.
+        let deletedCount = 0;
+        const requestedDeletes = (agentResult.deleted_test_case_ids ?? []).filter((id) => typeof id === 'string' && UUID_RE.test(id) && replaceableIds.has(id));
+        if (requestedDeletes.length > 0) {
+            logInfo(`Deleting ${requestedDeletes.length} obsolete replaceable test cases...`);
+            const ok = await batchDeleteTestCases(requestedDeletes, verbose);
+            if (ok) {
+                deletedCount = requestedDeletes.length;
+            }
+            else {
+                logWarning('Some deletions failed; leaving any remaining cases in place.');
+            }
+        }
+        const { createdIds } = await createProductTestCases(productId, agentResult.created_test_cases.map((tc) => ({
+            name: tc.name,
+            description: tc.description,
+            is_critical: tc.is_critical ?? false,
+        })), verbose);
+        logSuccess(`Created ${createdIds.length} test cases, deleted ${deletedCount} obsolete entries. ${agentResult.summary}`);
+        succeeded = true;
+        return {
+            status: 'success',
+            message: `Generated ${createdIds.length} test cases (deleted ${deletedCount})`,
+            createdCount: createdIds.length,
+            deletedCount,
+            summary: agentResult.summary,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logError(`Product test cases generation failed: ${message}`);
+        return {
+            status: 'error',
+            message: `Product test cases generation failed: ${message}`,
+        };
+    }
+    finally {
+        if (succeeded) {
+            cleanupIssueRepo(repoPath);
+        }
+        else if (repoPath) {
+            logInfo(`Workspace preserved for inspection: ${repoPath}`);
+        }
+        lock.release();
+    }
+}

package/dist/phases/product-test-cases/prompts.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Prompts for the product-level test cases phase.
+ *
+ * Agent's job: explore the cloned product repo and propose a regression-suite
+ * worth of test cases for the whole product (not a single issue). Existing
+ * test cases — both approved (locked) and unapproved (replaceable) — are
+ * included in the context so the agent doesn't duplicate work and so the
+ * unapproved set can be refreshed when the codebase has drifted.
+ */
+export interface ExistingProductTestCase {
+    id: string;
+    name: string;
+    description: string;
+    is_critical: boolean;
+    status: string;
+}
+export interface ProductTestCasesPromptContext {
+    productName: string;
+    productDescription?: string;
+    approvedTestCases: ExistingProductTestCase[];
+    replaceableTestCases: ExistingProductTestCase[];
+}
+export declare function createProductTestCasesSystemPrompt(): string;
+export declare function createProductTestCasesUserPrompt(context: ProductTestCasesPromptContext): string;

package/dist/phases/product-test-cases/prompts.js

@@ -0,0 +1,80 @@
+/**
+ * Prompts for the product-level test cases phase.
+ *
+ * Agent's job: explore the cloned product repo and propose a regression-suite
+ * worth of test cases for the whole product (not a single issue). Existing
+ * test cases — both approved (locked) and unapproved (replaceable) — are
+ * included in the context so the agent doesn't duplicate work and so the
+ * unapproved set can be refreshed when the codebase has drifted.
+ */
+export function createProductTestCasesSystemPrompt() {
+    return `You are a senior QA engineer drafting a product-level regression test suite.
+
+The current working directory is a fresh clone of the product's repository. Use Glob/Grep/Read to explore it and understand the surface area: entry points, public APIs, user-facing flows, critical paths. Look at recent commits with Bash if it helps.
+
+Output a single JSON result of the form:
+\`\`\`json
+{
+  "test_cases_result": {
+    "summary": "Short 1-2 sentence summary of what you covered",
+    "created_test_cases": [
+      {
+        "name": "Concise name (max 200 chars)",
+        "description": "Markdown describing Given/When/Then steps + expected result",
+        "is_critical": true
+      }
+    ],
+    "deleted_test_case_ids": [
+      "uuid-of-replaceable-test-case-you-want-removed"
+    ],
+    "deletion_reasons": {
+      "uuid": "Why this test case is no longer relevant"
+    }
+  }
+}
+\`\`\`
+
+Rules:
+- DO NOT duplicate any test case in the "Approved test cases" or "Replaceable test cases" sections. If an existing case already covers a behaviour, skip it.
+- You MAY propose deletions ONLY for entries in the "Replaceable test cases" list. Approved test cases are locked by the human reviewer and cannot be touched.
+- Mark \`is_critical: true\` only for must-pass flows (auth, payments, data loss risks, primary user journeys).
+- Aim for 5-30 high-signal cases total. Quality over quantity.
+- Each test case must be executable by a human tester reading the description alone.
+- The "deleted_test_case_ids" and "deletion_reasons" fields are optional; omit or use [] / {} when you have nothing to delete.
+- Wrap the final JSON in a single \`\`\`json fenced block. No extra prose after it.`;
+}
+export function createProductTestCasesUserPrompt(context) {
+    const lines = [];
+    lines.push(`# Product: ${context.productName}`);
+    if (context.productDescription) {
+        lines.push('');
+        lines.push(`## Description`);
+        lines.push(context.productDescription);
+    }
+    lines.push('');
+    lines.push('## Approved test cases (locked — do not duplicate, cannot delete)');
+    if (context.approvedTestCases.length === 0) {
+        lines.push('_(none)_');
+    }
+    else {
+        for (const tc of context.approvedTestCases) {
+            lines.push(`- **${tc.name}**${tc.is_critical ? ' [critical]' : ''}`);
+            lines.push(`  ${tc.description.replace(/\n/g, '\n  ')}`);
+        }
+    }
+    lines.push('');
+    lines.push('## Replaceable test cases (draft / pending_approval — may be deleted if obsolete or duplicated)');
+    if (context.replaceableTestCases.length === 0) {
+        lines.push('_(none)_');
+    }
+    else {
+        for (const tc of context.replaceableTestCases) {
+            lines.push(`- \`${tc.id}\` (${tc.status})${tc.is_critical ? ' [critical]' : ''} — **${tc.name}**`);
+            lines.push(`  ${tc.description.replace(/\n/g, '\n  ')}`);
+        }
+    }
+    lines.push('');
+    lines.push('## Task');
+    lines.push('Explore the repository (Glob/Grep/Read/Bash) and propose product-level regression test cases. Follow the JSON output contract in your system prompt.');
+    return lines.join('\n');
+}

package/dist/phases/product-test-cases/types.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Wire shape for the product-test-cases agent output. The agent is asked to
+ * emit `{ test_cases_result: { ... } }`; we validate it loosely so a single
+ * stray field doesn't kill an otherwise-good run.
+ */
+export interface ProductTestCaseDraft {
+    name: string;
+    description: string;
+    is_critical?: boolean;
+}
+export interface ProductTestCasesAgentResult {
+    summary: string;
+    created_test_cases: ProductTestCaseDraft[];
+    deleted_test_case_ids?: string[];
+    deletion_reasons?: Record<string, string>;
+}
+export declare function isProductTestCasesAgentResult(value: unknown): value is ProductTestCasesAgentResult;