edsger 0.58.0 → 0.59.0

package/dist/api/cross-product.js

@@ -56,7 +56,6 @@ export async function listAllReadyIssues(verbose) {
             const allIssues = (data || []).map((row) => {
                 // The `product` join lands as a nested object; lift its name onto
                 // the row to keep the wire shape stable.
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any -- shape from PostgREST join
                 const r = row;
                 return {
                     ...r,

package/dist/api/issues/issue-utils.js

@@ -41,7 +41,6 @@ export async function claimNextIssue(productId, verbose) {
             }
             // RPC returns rows with `issue_*` prefixed column names — unwrap to
             // the IssueInfo shape callers already consume.
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- raw RPC row
             const r = row;
             const issue = {
                 id: r.issue_id,

package/dist/api/issues/update-issue.js

@@ -91,7 +91,7 @@ export async function markWorkflowPhaseCompleted(issueId, phaseName, verbose) {
                 // Fall through to MCP
             }
         }
-        if (issue == null) {
+        if (!issue) {
             const response = (await callMcpEndpoint('issues/get', {
                 issue_id: issueId,
             }));

package/dist/commands/agent-workflow/chat-worker.js

@@ -354,7 +354,7 @@ function startRealtime() {
             registerChannel(payload.new);
             // A channel created with messages already in it (unlikely but
             // possible if INSERTs race) deserves an immediate sweep.
-            const id = payload.new.id;
+            const { id } = payload.new;
             if (id) {
                 void claimAndProcess(id);
             }

package/dist/commands/checklists/index.js

@@ -116,7 +116,7 @@ export async function runChecklists(options) {
         ? createChecklistsMcpServer({ kind: 'team', teamId: teamId })
         : createChecklistsMcpServer({
             kind: 'product',
-            productId: productId,
+            productId,
         });
     const promptParts = isTeamScope
         ? [

package/dist/commands/product-techniques/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * CLI command: edsger product-techniques <productId> --techniques-id <id>
+ *
+ * Clones the product's repo, asks Claude to write a catalogue of the
+ * techniques the repo uses, and stores the markdown body in
+ * product_techniques. The desktop UI creates a pending row first then
+ * invokes the CLI with --techniques-id; the CLI flips status running →
+ * success/failed and populates the content/summary fields.
+ */
+export interface ProductTechniquesCliOptions {
+    techniquesId: string;
+    guidance?: string;
+    verbose?: boolean;
+}
+export declare function runProductTechniques(productId: string, options: ProductTechniquesCliOptions): Promise<void>;

package/dist/commands/product-techniques/index.js

@@ -0,0 +1,37 @@
+/**
+ * CLI command: edsger product-techniques <productId> --techniques-id <id>
+ *
+ * Clones the product's repo, asks Claude to write a catalogue of the
+ * techniques the repo uses, and stores the markdown body in
+ * product_techniques. The desktop UI creates a pending row first then
+ * invokes the CLI with --techniques-id; the CLI flips status running →
+ * success/failed and populates the content/summary fields.
+ */
+import { runProductTechniquesPhase } from '../../phases/product-techniques/index.js';
+import { logError, logInfo, logSuccess } from '../../utils/logger.js';
+export async function runProductTechniques(productId, options) {
+    const { techniquesId, guidance, verbose } = options;
+    if (!productId) {
+        throw new Error('Product ID is required for product-techniques');
+    }
+    if (!techniquesId) {
+        throw new Error('--techniques-id is required (the pending product_techniques row id)');
+    }
+    logInfo(`Starting techniques generation for product ${productId}`);
+    const result = await runProductTechniquesPhase({
+        productId,
+        techniquesId,
+        guidance,
+        verbose,
+    });
+    if (result.status === 'success') {
+        logSuccess(result.message);
+        if (result.summary) {
+            logInfo(`\nSummary: ${result.summary}`);
+        }
+    }
+    else {
+        logError(result.message);
+        process.exit(1);
+    }
+}

package/dist/commands/workflow/executors/phase-executor.js

@@ -3,7 +3,7 @@
  */
 import { checkApprovalBeforePhaseExecution } from '../../../api/issues/approval-checker.js';
 import { updateIssueStatusForPhase } from '../../../api/issues/index.js';
-import { logIssuePhaseEvent, } from '../../../services/audit-logs.js';
+import { logIssuePhaseEvent } from '../../../services/audit-logs.js';
 import { getChecklistsForPhase, processChecklistItemResultsFromResponse, processChecklistResultsFromResponse, validateChecklistsForPhase, validateRequiredChecklistResults, } from '../../../services/checklist.js';
 import { runHooksForPhase } from '../../../services/phase-hooks/index.js';
 import { logDebug, logInfo, logWarning } from '../../../utils/logger.js';

package/dist/index.js

@@ -19,17 +19,18 @@ import { runFindBugs } from './commands/find-bugs/index.js';
 import { runFindFeatures } from './commands/find-features/index.js';
 import { parseCategoriesOption, runFindSmells, } from './commands/find-smells/index.js';
 import { runGrowthAnalysis } from './commands/growth-analysis/index.js';
-import { runScreenFlow } from './commands/screen-flow/index.js';
 import { runInit } from './commands/init/index.js';
 import { runIntelligence } from './commands/intelligence/index.js';
 import { runIssueAnalysisCommand } from './commands/issue-analysis/index.js';
 import { runPRResolve } from './commands/pr-resolve/index.js';
 import { runPRReview } from './commands/pr-review/index.js';
+import { runProductTechniques } from './commands/product-techniques/index.js';
 import { runProductTestCases } from './commands/product-test-cases/index.js';
 import { runQualityBenchmarkCli } from './commands/quality-benchmark/index.js';
 import { runRefactor } from './commands/refactor/refactor.js';
 import { runReleaseSyncCommand } from './commands/release-sync/index.js';
 import { runRunSheetCommand } from './commands/run-sheet/index.js';
+import { runScreenFlow } from './commands/screen-flow/index.js';
 import { runSmokeTestCommand } from './commands/smoke-test/index.js';
 import { runSyncGithubIssues } from './commands/sync-github-issues/index.js';
 import { runSyncSentryIssues } from './commands/sync-sentry-issues/index.js';
@@ -694,6 +695,28 @@ program
     }
 });
 // ============================================================
+// Subcommand: edsger product-techniques <productId>
+// ============================================================
+program
+    .command('product-techniques <productId>')
+    .description("Generate a catalogue of the techniques a product's repo uses (languages, frameworks, patterns, state idioms, build & deploy, notable bits). Writes the result to the pending product_techniques row identified by --techniques-id.")
+    .requiredOption('--techniques-id <id>', 'Pending product_techniques row id to populate')
+    .option('-g, --guidance <text>', 'Human direction for the AI (focus areas, exclusions)')
+    .option('-v, --verbose', 'Verbose output')
+    .action(async (productId, opts) => {
+    try {
+        await runProductTechniques(productId, {
+            techniquesId: opts.techniquesId,
+            guidance: opts.guidance,
+            verbose: opts.verbose,
+        });
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+});
+// ============================================================
 // Subcommand: edsger pr-resolve <productId>
 // ============================================================
 program

package/dist/phases/analyze-logs/index.js

@@ -5,11 +5,11 @@
  * user's session logs (only if the latest log is >1 hour old), and creates
  * product_user_feedbacks for any issues or improvement suggestions found.
  */
+import { callMcpEndpoint } from '../../api/mcp-client.js';
 import { getProduct } from '../../api/products.js';
 import { getPendingLogsByUser, markLogsAnalyzed, } from '../../services/product-logs.js';
 import { getSupabase, hasSupabaseSession } from '../../supabase/client.js';
 import { logError, logInfo, logSuccess } from '../../utils/logger.js';
-import { callMcpEndpoint } from '../../api/mcp-client.js';
 import { executeLogAnalysis } from './agent.js';
 import { createAnalyzeLogsSystemPrompt, createAnalyzeLogsUserPrompt, } from './prompts.js';
 /**

package/dist/phases/bug-fixing/context-fetcher.js

@@ -41,8 +41,10 @@ export async function fetchBugFixingContext(issueId, verbose) {
                     // Fall through to MCP
                 }
             }
-            if (raw == null) {
-                const testReportResult = (await callMcpEndpoint('test_reports/latest', { issue_id: issueId }));
+            if (!raw) {
+                const testReportResult = (await callMcpEndpoint('test_reports/latest', {
+                    issue_id: issueId,
+                }));
                 raw = testReportResult.test_report ?? null;
             }
             if (raw) {

package/dist/phases/find-features/index.js

@@ -267,7 +267,7 @@ async function fetchIntelligenceReports(productId, focusReportId) {
                 if (error) {
                     throw new Error(error.message);
                 }
-                reports = (data || []);
+                reports = data || [];
                 usedSdk = true;
             }
             catch {

package/dist/phases/product-techniques/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * product-techniques phase: clone the product's repo, ask Claude (via the
+ * `submit_techniques` MCP tool) to write a catalogue of the techniques the
+ * repo uses, and persist the result to product_techniques via the Supabase
+ * SDK.
+ *
+ * Mirrors the screen-flow pattern. Production-grade behaviours layered on
+ * top of the basic generate-and-write loop:
+ *
+ *   - Heartbeat: `last_heartbeat_at` is refreshed on every assistant message
+ *     so the reader can detect stalled / crashed runs (see services/db/
+ *     product-techniques.ts for the lazy reaper).
+ *   - Cancellation-safe writes: markRunning / markSuccess / markFailed only
+ *     touch rows whose status is in {pending, running}. If the user clicked
+ *     Stop and the row is now 'cancelled', the final write no-ops.
+ *   - Tool-based submission: validated server-side via Zod + content checks
+ *     (mcp-server.ts). Falls back to fenced JSON parsing for resilience.
+ */
+import type { SupabaseClient } from '@supabase/supabase-js';
+export interface ProductTechniquesOptions {
+    productId: string;
+    techniquesId: string;
+    guidance?: string;
+    verbose?: boolean;
+}
+export interface ProductTechniquesResult {
+    status: 'success' | 'error' | 'cancelled';
+    message: string;
+    summary?: string;
+}
+export declare function runProductTechniquesPhase(options: ProductTechniquesOptions): Promise<ProductTechniquesResult>;
+/**
+ * Claim the row by flipping `pending` → `running`. Returns true on success
+ * (we won the claim) and false when the row has already moved on (e.g. user
+ * cancelled before the CLI started). Bounded by the status filter so we
+ * can't accidentally resurrect a 'cancelled' row.
+ */
+export declare function markRunning(supabase: SupabaseClient, techniquesId: string): Promise<boolean>;
+/**
+ * Touch the heartbeat. Best-effort — if it fails (network blip, RLS), the
+ * agent loop keeps running; the reader treats this row as stale and marks
+ * it failed on next read, which is the correct behaviour.
+ */
+export declare function heartbeat(supabase: SupabaseClient, techniquesId: string): Promise<void>;
+/**
+ * Write failure status iff the row is still in an active state. Returns
+ * true if the row was actually updated (so the caller knows whether the
+ * agent's verdict made it to the DB). Returns false when the row has
+ * already been cancelled or otherwise resolved by someone else.
+ */
+export declare function markFailed(supabase: SupabaseClient, techniquesId: string, errorMessage: string): Promise<boolean>;
+export declare function markSuccess(supabase: SupabaseClient, techniquesId: string, summary: string, content: string): Promise<boolean>;

package/dist/phases/product-techniques/index.js

@@ -0,0 +1,268 @@
+/**
+ * product-techniques phase: clone the product's repo, ask Claude (via the
+ * `submit_techniques` MCP tool) to write a catalogue of the techniques the
+ * repo uses, and persist the result to product_techniques via the Supabase
+ * SDK.
+ *
+ * Mirrors the screen-flow pattern. Production-grade behaviours layered on
+ * top of the basic generate-and-write loop:
+ *
+ *   - Heartbeat: `last_heartbeat_at` is refreshed on every assistant message
+ *     so the reader can detect stalled / crashed runs (see services/db/
+ *     product-techniques.ts for the lazy reaper).
+ *   - Cancellation-safe writes: markRunning / markSuccess / markFailed only
+ *     touch rows whose status is in {pending, running}. If the user clicked
+ *     Stop and the row is now 'cancelled', the final write no-ops.
+ *   - Tool-based submission: validated server-side via Zod + content checks
+ *     (mcp-server.ts). Falls back to fenced JSON parsing for resilience.
+ */
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { getGitHubConfigByProduct } from '../../api/github.js';
+import { DEFAULT_MODEL } from '../../constants.js';
+import { getSupabase } from '../../supabase/client.js';
+import { logError, logInfo, logSuccess, logWarning, } from '../../utils/logger.js';
+import { cleanupIssueRepo, cloneIssueRepo, ensureWorkspaceDir, } from '../../workspace/workspace-manager.js';
+import { fetchProductBasics } from '../find-shared/mcp.js';
+import { createPromptGenerator, extractTextFromContent, tryExtractResult, } from '../pr-shared/agent-utils.js';
+import { createTechniquesCaptureState, createTechniquesMcpServer, validateContent, } from './mcp-server.js';
+import { createProductTechniquesSystemPrompt, createProductTechniquesUserPrompt, } from './prompts.js';
+import { isTechniquesExtraction, TECHNIQUES_CONTENT_MAX, TECHNIQUES_SUMMARY_MAX, } from './types.js';
+const WORKSPACE_KEY = 'product-techniques';
+const MAX_TURNS = 120;
+// Heartbeat cadence: at most one DB write per HEARTBEAT_MIN_INTERVAL_MS.
+// Triggered on every assistant message so a stalled agent (no messages
+// flowing) lets the row go stale and the reader can mark it failed.
+const HEARTBEAT_MIN_INTERVAL_MS = 15_000;
+export async function runProductTechniquesPhase(options) {
+    const { productId, techniquesId, guidance, verbose } = options;
+    logInfo(`Starting product-techniques generation for product ${productId}`);
+    const supabase = getSupabase();
+    const claimed = await markRunning(supabase, techniquesId);
+    if (!claimed) {
+        return {
+            status: 'cancelled',
+            message: 'Techniques row is no longer in a runnable state (likely cancelled before the CLI started)',
+        };
+    }
+    const githubConfig = await getGitHubConfigByProduct(productId, verbose);
+    if (!githubConfig.configured ||
+        !githubConfig.token ||
+        !githubConfig.owner ||
+        !githubConfig.repo) {
+        const msg = githubConfig.message ||
+            'GitHub repository not configured for this product. Connect a repo first.';
+        await markFailed(supabase, techniquesId, msg);
+        return { status: 'error', message: msg };
+    }
+    let repoPath;
+    let succeeded = false;
+    try {
+        const workspaceRoot = ensureWorkspaceDir();
+        const repoKey = `${WORKSPACE_KEY}-${productId}`;
+        ({ repoPath } = cloneIssueRepo(workspaceRoot, repoKey, githubConfig.owner, githubConfig.repo, githubConfig.token));
+        const product = await fetchProductBasics(productId);
+        const systemPrompt = createProductTechniquesSystemPrompt();
+        const userPrompt = createProductTechniquesUserPrompt({
+            productName: product.name,
+            productDescription: product.description,
+            guidance,
+        });
+        logInfo('Running Claude agent to write techniques catalogue...');
+        const captureState = createTechniquesCaptureState();
+        const mcpServer = createTechniquesMcpServer(captureState);
+        let lastAssistantResponse = '';
+        let lastHeartbeatAt = 0;
+        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,
+                mcpServers: {
+                    'product-techniques': mcpServer,
+                },
+            },
+        })) {
+            if (message.type === 'assistant') {
+                lastAssistantResponse += extractTextFromContent(message.message?.content ?? [], verbose);
+                // Throttled heartbeat. Awaited (cheap UPDATE) so we don't pile up
+                // unresolved promises on a long run.
+                const now = Date.now();
+                if (now - lastHeartbeatAt >= HEARTBEAT_MIN_INTERVAL_MS) {
+                    lastHeartbeatAt = now;
+                    await heartbeat(supabase, techniquesId);
+                }
+                continue;
+            }
+            if (message.type !== 'result') {
+                continue;
+            }
+            // Prefer the MCP-captured extraction. Fall back to fenced JSON only
+            // if the agent ignored the tool — robustness, not a contract.
+            const fromTool = captureState.captured;
+            const fromFallback = fromTool
+                ? null
+                : tryFallbackParse(message, lastAssistantResponse);
+            const extraction = fromTool ?? fromFallback;
+            if (!extraction) {
+                const msg = message.subtype === 'success'
+                    ? 'Techniques generation failed: agent did not call submit_techniques and no parseable fallback was found'
+                    : `Techniques generation failed: agent ${message.subtype}`;
+                const written = await markFailed(supabase, techniquesId, msg);
+                return {
+                    status: written ? 'error' : 'cancelled',
+                    message: written
+                        ? msg
+                        : 'Generation was cancelled while the agent was running',
+                };
+            }
+            if (fromFallback) {
+                logWarning('Agent skipped submit_techniques; used fenced fallback JSON instead');
+            }
+            const written = await markSuccess(supabase, techniquesId, extraction.summary, extraction.content);
+            if (!written) {
+                return {
+                    status: 'cancelled',
+                    message: 'Generation was cancelled before the result could be written',
+                };
+            }
+            succeeded = true;
+            logSuccess(`Techniques catalogue generated (${extraction.content.length} chars of markdown)`);
+            return {
+                status: 'success',
+                message: 'Techniques catalogue generated',
+                summary: extraction.summary,
+            };
+        }
+        // Loop ended without a 'result' message — treat as failure.
+        const msg = 'Techniques generation ended without a result message';
+        await markFailed(supabase, techniquesId, msg);
+        return { status: 'error', message: msg };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logError(`Techniques generation failed: ${errorMessage}`);
+        await markFailed(supabase, techniquesId, errorMessage);
+        return { status: 'error', message: errorMessage };
+    }
+    finally {
+        if (succeeded) {
+            cleanupIssueRepo(repoPath);
+        }
+    }
+}
+// Fallback parser: extract a fenced `techniques` JSON block from the final
+// assistant text if the agent skipped the submit_techniques tool. Backstop
+// only — we expect the tool path to be the norm.
+function tryFallbackParse(resultMessage, assistantText) {
+    const responseText = resultMessage.subtype === 'success'
+        ? resultMessage.result || assistantText
+        : assistantText;
+    const parsed = tryExtractResult(responseText, 'techniques');
+    if (!isTechniquesExtraction(parsed)) {
+        return null;
+    }
+    if (parsed.summary.length > TECHNIQUES_SUMMARY_MAX) {
+        return null;
+    }
+    if (parsed.content.length > TECHNIQUES_CONTENT_MAX) {
+        return null;
+    }
+    const { error } = validateContent(parsed.content);
+    if (error) {
+        return null;
+    }
+    return parsed;
+}
+// ============================================================================
+// Persistence — exported for unit tests
+// ============================================================================
+/**
+ * Claim the row by flipping `pending` → `running`. Returns true on success
+ * (we won the claim) and false when the row has already moved on (e.g. user
+ * cancelled before the CLI started). Bounded by the status filter so we
+ * can't accidentally resurrect a 'cancelled' row.
+ */
+export async function markRunning(supabase, techniquesId) {
+    const { data, error } = await supabase
+        .from('product_techniques')
+        .update({
+        status: 'running',
+        error: null,
+        last_heartbeat_at: new Date().toISOString(),
+    })
+        .eq('id', techniquesId)
+        .in('status', ['pending', 'running'])
+        .select('id')
+        .maybeSingle();
+    if (error) {
+        logWarning(`Could not mark techniques as running: ${error.message}`);
+        return false;
+    }
+    return data !== null;
+}
+/**
+ * Touch the heartbeat. Best-effort — if it fails (network blip, RLS), the
+ * agent loop keeps running; the reader treats this row as stale and marks
+ * it failed on next read, which is the correct behaviour.
+ */
+export async function heartbeat(supabase, techniquesId) {
+    const { error } = await supabase
+        .from('product_techniques')
+        .update({ last_heartbeat_at: new Date().toISOString() })
+        .eq('id', techniquesId)
+        .eq('status', 'running');
+    if (error) {
+        logWarning(`Heartbeat failed: ${error.message}`);
+    }
+}
+/**
+ * Write failure status iff the row is still in an active state. Returns
+ * true if the row was actually updated (so the caller knows whether the
+ * agent's verdict made it to the DB). Returns false when the row has
+ * already been cancelled or otherwise resolved by someone else.
+ */
+export async function markFailed(supabase, techniquesId, errorMessage) {
+    const { data, error } = await supabase
+        .from('product_techniques')
+        .update({
+        status: 'failed',
+        error: errorMessage,
+        completed_at: new Date().toISOString(),
+    })
+        .eq('id', techniquesId)
+        .in('status', ['pending', 'running'])
+        .select('id')
+        .maybeSingle();
+    if (error) {
+        logWarning(`Could not mark techniques as failed: ${error.message}`);
+        return false;
+    }
+    return data !== null;
+}
+export async function markSuccess(supabase, techniquesId, summary, content) {
+    const { data, error } = await supabase
+        .from('product_techniques')
+        .update({
+        status: 'success',
+        summary,
+        content,
+        error: null,
+        completed_at: new Date().toISOString(),
+    })
+        .eq('id', techniquesId)
+        .in('status', ['pending', 'running'])
+        .select('id')
+        .maybeSingle();
+    if (error) {
+        logWarning(`Could not mark techniques as success: ${error.message}`);
+        return false;
+    }
+    return data !== null;
+}

package/dist/phases/product-techniques/mcp-server.d.ts

@@ -0,0 +1,41 @@
+/**
+ * In-process MCP server exposing a single tool — `submit_techniques` — that
+ * the Claude Agent SDK session calls to return the final markdown catalogue.
+ *
+ * Using a tool call instead of parsing a fenced JSON block lets the SDK
+ * enforce the schema (via Zod) and lets the agent self-correct when
+ * validation fails: the error message goes back as the tool result and the
+ * agent can re-call the tool with corrected data.
+ *
+ * The capture pattern: callers pass in a `TechniquesCaptureState`. The tool
+ * handler stores the validated args on `state.captured`. The orchestrator
+ * reads it after the SDK loop ends.
+ */
+import { z } from 'zod';
+import { type TechniquesExtraction } from './types.js';
+export interface TechniquesCaptureState {
+    captured: TechniquesExtraction | null;
+}
+export declare function createTechniquesCaptureState(): TechniquesCaptureState;
+/**
+ * Validation that goes beyond the basic Zod schema: enforce that the
+ * markdown actually has the H2 sections the prompt asks for. The agent gets
+ * an actionable error and can re-submit.
+ *
+ * We don't require ALL six sections — agents on tiny repos often legitimately
+ * collapse some. We require at least the first one ("Languages & Runtime")
+ * plus "Notable Techniques", which the prompt calls out as the whole point.
+ */
+export declare function validateContent(content: string): {
+    error: string | null;
+};
+/**
+ * Build the `submit_techniques` tool. Exported separately from the server
+ * so tests can exercise the handler directly without going through MCP
+ * transport.
+ */
+export declare function createSubmitTechniquesTool(state: TechniquesCaptureState): import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{
+    summary: z.ZodString;
+    content: z.ZodString;
+}>;
+export declare function createTechniquesMcpServer(state: TechniquesCaptureState): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;

package/dist/phases/product-techniques/mcp-server.js

@@ -0,0 +1,96 @@
+/**
+ * In-process MCP server exposing a single tool — `submit_techniques` — that
+ * the Claude Agent SDK session calls to return the final markdown catalogue.
+ *
+ * Using a tool call instead of parsing a fenced JSON block lets the SDK
+ * enforce the schema (via Zod) and lets the agent self-correct when
+ * validation fails: the error message goes back as the tool result and the
+ * agent can re-call the tool with corrected data.
+ *
+ * The capture pattern: callers pass in a `TechniquesCaptureState`. The tool
+ * handler stores the validated args on `state.captured`. The orchestrator
+ * reads it after the SDK loop ends.
+ */
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { TECHNIQUES_CONTENT_MAX, TECHNIQUES_SUMMARY_MAX, } from './types.js';
+export function createTechniquesCaptureState() {
+    return { captured: null };
+}
+/**
+ * Validation that goes beyond the basic Zod schema: enforce that the
+ * markdown actually has the H2 sections the prompt asks for. The agent gets
+ * an actionable error and can re-submit.
+ *
+ * We don't require ALL six sections — agents on tiny repos often legitimately
+ * collapse some. We require at least the first one ("Languages & Runtime")
+ * plus "Notable Techniques", which the prompt calls out as the whole point.
+ */
+export function validateContent(content) {
+    const required = [
+        /^##\s+Languages\s*&\s*Runtime\b/im,
+        /^##\s+Notable\s+Techniques\b/im,
+    ];
+    for (const re of required) {
+        if (!re.test(content)) {
+            return {
+                error: `content is missing the required section matching ${re.source}. Add the section and re-call submit_techniques.`,
+            };
+        }
+    }
+    return { error: null };
+}
+/**
+ * Build the `submit_techniques` tool. Exported separately from the server
+ * so tests can exercise the handler directly without going through MCP
+ * transport.
+ */
+export function createSubmitTechniquesTool(state) {
+    return tool('submit_techniques', [
+        'Submit the final techniques catalogue. Call this EXACTLY once, when',
+        'you have finished cataloguing every technique. Pass the summary and',
+        'the full markdown content as arguments. After this call succeeds, end',
+        'your turn — do NOT also paste the same content as a fenced code block.',
+        'If validation fails, the error message tells you what to fix; call the',
+        'tool again with corrected data.',
+    ].join(' '), {
+        summary: z
+            .string()
+            .min(1)
+            .max(TECHNIQUES_SUMMARY_MAX)
+            .describe('1-2 sentence summary suitable for a tab header. Plain text, no markdown.'),
+        content: z
+            .string()
+            .min(1)
+            .max(TECHNIQUES_CONTENT_MAX)
+            .describe('Full markdown body with H2 sections: Languages & Runtime, Frameworks & Libraries, Architecture Patterns, State & Data Techniques, Build & Deploy Techniques, Notable Techniques.'),
+    }, async (args) => {
+        const extraction = {
+            summary: args.summary,
+            content: args.content,
+        };
+        const { error } = validateContent(extraction.content);
+        if (error) {
+            return {
+                content: [{ type: 'text', text: error }],
+                isError: true,
+            };
+        }
+        state.captured = extraction;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Captured techniques catalogue (${extraction.content.length} chars). End your turn now.`,
+                },
+            ],
+        };
+    });
+}
+export function createTechniquesMcpServer(state) {
+    return createSdkMcpServer({
+        name: 'product-techniques',
+        version: '1.0.0',
+        tools: [createSubmitTechniquesTool(state)],
+    });
+}

package/dist/phases/product-techniques/prompts.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Prompts for the product-level techniques phase.
+ *
+ * Agent's job: explore the cloned product repo and write a markdown catalogue
+ * of the techniques it actually uses — languages, frameworks, patterns, state
+ * idioms, build/deploy choices, plus the clever non-obvious bits. Focused on
+ * what a new engineer needs to recognize and recreate, not feature lists.
+ *
+ * The final result is submitted via the `submit_techniques` MCP tool, NOT a
+ * fenced JSON block. Tool calls let the SDK enforce the schema with Zod and
+ * let the agent self-correct on validation errors. See mcp-server.ts.
+ */
+export interface ProductTechniquesPromptContext {
+    productName: string;
+    productDescription?: string;
+    guidance?: string;
+}
+export declare function createProductTechniquesSystemPrompt(): string;
+export declare function createProductTechniquesUserPrompt(context: ProductTechniquesPromptContext): string;

package/dist/phases/product-techniques/prompts.js

@@ -0,0 +1,66 @@
+/**
+ * Prompts for the product-level techniques phase.
+ *
+ * Agent's job: explore the cloned product repo and write a markdown catalogue
+ * of the techniques it actually uses — languages, frameworks, patterns, state
+ * idioms, build/deploy choices, plus the clever non-obvious bits. Focused on
+ * what a new engineer needs to recognize and recreate, not feature lists.
+ *
+ * The final result is submitted via the `submit_techniques` MCP tool, NOT a
+ * fenced JSON block. Tool calls let the SDK enforce the schema with Zod and
+ * let the agent self-correct on validation errors. See mcp-server.ts.
+ */
+export function createProductTechniquesSystemPrompt() {
+    return `You are a senior staff engineer cataloguing the techniques a product's codebase uses.
+
+The current working directory is a fresh clone of the product's repository. Use Glob/Grep/Read (and Bash for git/log when helpful) to explore it before writing.
+
+Your audience: a new engineer joining the team. They need to recognize WHICH techniques this repo employs — what frameworks, what patterns, what idioms — so they can read code without surprise and contribute in the codebase's existing style. This is not a feature list and not an architecture proposal. Anchor every technique in the actual code; reference real file paths.
+
+## Output protocol
+
+When you are ready to submit, call the \`submit_techniques\` tool EXACTLY ONCE with:
+- \`summary\` — 1-2 sentence summary suitable for a tab header (plain text, no markdown).
+- \`content\` — the full markdown body, structured as described below.
+
+Do NOT also paste the same content as a fenced code block — the tool call is the only channel for the result. If validation fails, the tool response tells you what to fix; call the tool again with corrected data.
+
+## Required sections in \`content\`
+
+The markdown body MUST contain these H2 sections, in this order:
+
+1. **## Languages & Runtime** — languages used (with versions if pinned), runtime targets (Node / Bun / Deno / browser / native / etc), package manager.
+2. **## Frameworks & Libraries** — the major frameworks and libraries this repo depends on, and what each one is doing here. Don't just list package names; explain the role. Group by area (UI, server, data, infra) if it helps.
+3. **## Architecture Patterns** — the architectural choices the code embodies: layering / module boundaries / dependency direction / how features are organised. Include one Mermaid \`flowchart TD\` showing the dominant pattern (≤ 10 nodes). Name the pattern when you can ("repository pattern", "feature-sliced design", "hexagonal", "BFF", etc.).
+4. **## State & Data Techniques** — state management, data fetching, caching, optimistic updates, validation, type-safety across boundaries. How is server state vs client state handled? How are forms managed? How is data flowing between server and client?
+5. **## Build & Deploy Techniques** — bundler / compiler choices, code-splitting, environment handling, monorepo tooling, CI/CD specifics, deployment target (edge / serverless / containers / static).
+6. **## Notable Techniques** — the genuinely interesting bits that aren't obvious from the stack: clever abstractions, performance optimizations, security hardening, custom hooks/utilities worth knowing, intentional deviations from defaults, surprising workarounds. Each one: what it is, where it lives (file path), why it matters. This section is the whole point — be specific and useful here.
+
+The validator will reject content missing the "Languages & Runtime" or "Notable Techniques" headings.
+
+## Rules
+
+- Use relative file paths from the repo root (e.g. \`src/services/auth.ts\`). Link to specific files where the technique is most visible.
+- Mermaid blocks must be valid (no unclosed quotes, no unsupported node shapes). Prefer simple \`flowchart TD\` syntax.
+- Don't invent or guess. If a section has nothing distinctive ("just a stock CRA app"), say so briefly — don't pad.
+- Focus on TECHNIQUES, not features. Bad: "the app has a login screen". Good: "uses next-auth's credentials provider with a custom JWT callback at src/lib/auth.ts:42".
+- The whole document should fit in one screen-readable scroll — aim for ~1500-3000 words of content. Less is fine for small repos.`;
+}
+export function createProductTechniquesUserPrompt(context) {
+    const lines = [];
+    lines.push(`# Product: ${context.productName}`);
+    if (context.productDescription) {
+        lines.push('');
+        lines.push('## Description');
+        lines.push(context.productDescription);
+    }
+    if (context.guidance && context.guidance.trim()) {
+        lines.push('');
+        lines.push('## Reviewer guidance (focus or exclusions)');
+        lines.push(context.guidance.trim());
+    }
+    lines.push('');
+    lines.push('## Task');
+    lines.push('Explore the cloned repository and produce the techniques catalogue, then submit it via the `submit_techniques` MCP tool as specified in your system prompt. Pay particular attention to the "Notable Techniques" section — that is the real value to the reader.');
+    return lines.join('\n');
+}

package/dist/phases/product-techniques/types.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shape returned by the agent via the `submit_techniques` MCP tool. Mirrors
+ * the Zod schema in `mcp-server.ts` — kept duplicated as a plain TS type so
+ * consumers (the phase orchestrator, persistence helpers, tests) don't have
+ * to inflate Zod into their dependency graph.
+ */
+export interface TechniquesExtraction {
+    summary: string;
+    content: string;
+}
+export declare function isTechniquesExtraction(v: unknown): v is TechniquesExtraction;
+export declare const TECHNIQUES_SUMMARY_MAX = 500;
+export declare const TECHNIQUES_CONTENT_MAX = 200000;

package/dist/phases/product-techniques/types.js

@@ -0,0 +1,13 @@
+export function isTechniquesExtraction(v) {
+    if (!v || typeof v !== 'object') {
+        return false;
+    }
+    const obj = v;
+    return typeof obj.summary === 'string' && typeof obj.content === 'string';
+}
+// Defensive caps mirroring the DB CHECK constraints from
+// 20260521000000_create_product_techniques.sql. Keeping the limits here
+// too lets the MCP tool reject oversized output with an actionable error
+// message instead of getting a Postgres constraint violation.
+export const TECHNIQUES_SUMMARY_MAX = 500;
+export const TECHNIQUES_CONTENT_MAX = 200_000;

package/dist/phases/screen-flow/mcp-server.d.ts

@@ -42,10 +42,10 @@ export declare function createSubmitScreenFlowTool(state: ScreenFlowCaptureState
         file: z.ZodOptional<z.ZodString>;
         kind: z.ZodEnum<{
             page: "page";
+            state: "state";
             modal: "modal";
             drawer: "drawer";
             tab: "tab";
-            state: "state";
         }>;
         layout: z.ZodEnum<{
             split: "split";

package/dist/services/branches.js

@@ -30,7 +30,7 @@ export async function getBranches(options) {
             // Fall through to MCP
         }
     }
-    if (branches == null) {
+    if (!branches) {
         const result = (await callMcpEndpoint('branches/list', {
             issue_id: issueId,
         }));
@@ -79,7 +79,7 @@ export async function createBranches(options, branches) {
             // Fall through to MCP
         }
     }
-    if (createdBranches == null) {
+    if (!createdBranches) {
         const result = (await callMcpEndpoint('branches/create', {
             issue_id: issueId,
             branches,
@@ -119,7 +119,7 @@ export async function updateBranch(branchId, updates, verbose) {
             // Fall through to MCP
         }
     }
-    if (updated == null) {
+    if (!updated) {
         const result = (await callMcpEndpoint('branches/update', {
             branch_id: branchId,
             ...updates,

package/dist/services/phase-hooks/hook-executor.js

@@ -7,7 +7,7 @@ import { DEFAULT_MODEL } from '../../constants.js';
 import { logDebug } from '../../utils/logger.js';
 import { loadSkillFile } from './plugin-loader.js';
 const defaultDeps = {
-    loadSkillFile: loadSkillFile,
+    loadSkillFile,
     queryFn: query,
 };
 // ---- Prompt building (pure) ----

package/dist/services/phase-ratings.js

@@ -116,7 +116,7 @@ export async function getPhaseRatings(issueId, phase, verbose) {
                 // Fall through to MCP
             }
         }
-        if (ratings == null) {
+        if (!ratings) {
             const result = await callMcpEndpoint('phase_ratings/list', {
                 issue_id: issueId,
                 phase,

package/dist/services/product-logs.js

@@ -46,7 +46,7 @@ export async function getPendingLogsByUser(productId, verbose) {
             // Fall through to MCP
         }
     }
-    if (groups == null) {
+    if (!groups) {
         const result = (await callMcpEndpoint('product_logs/pending_by_user', {
             product_id: productId,
         }));

package/dist/services/pull-requests.js

@@ -30,7 +30,7 @@ export async function getPullRequests(options) {
             // Fall through to MCP
         }
     }
-    if (pullRequests == null) {
+    if (!pullRequests) {
         const result = (await callMcpEndpoint('pull_requests/list', {
             issue_id: issueId,
         }));
@@ -66,7 +66,7 @@ export async function createPullRequests(options, pullRequests) {
             // Fall through to MCP
         }
     }
-    if (created == null) {
+    if (!created) {
         const result = (await callMcpEndpoint('pull_requests/create', {
             issue_id: issueId,
             pull_requests: pullRequests,
@@ -106,7 +106,7 @@ export async function updatePullRequest(prId, updates, verbose) {
             // Fall through to MCP
         }
     }
-    if (updated == null) {
+    if (!updated) {
         const result = (await callMcpEndpoint('pull_requests/update', {
             pull_request_id: prId,
             ...updates,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edsger",
-  "version": "0.58.0",
+  "version": "0.59.0",
   "type": "module",
   "bin": {
     "edsger": "dist/index.js"

package/vitest.config.ts

@@ -16,6 +16,7 @@ export default defineConfig({
       'src/phases/sync-sentry-issues/__tests__/**/*.test.ts',
       'src/phases/sync-shared/__tests__/**/*.test.ts',
       'src/phases/screen-flow/__tests__/**/*.test.ts',
+      'src/phases/product-techniques/__tests__/**/*.test.ts',
       'src/types/__tests__/**/*.test.ts',
       'src/commands/find-smells/__tests__/**/*.test.ts',
     ],