ticket-to-pr 1.3.0 → 1.4.1

package/README.md

@@ -214,6 +214,9 @@ ticket-to-pr --dry-run --once
 | `doctor` | Diagnostic check — verifies environment, Notion connectivity, database schema, tools, and projects |
 | `model` | View current models and available options |
 | `model <review\|execute\|both> <model>` | Set the Claude model for an agent. Accepts aliases (`opus`, `sonnet`, `haiku`) or full model IDs. |
+| `learnings` | View accumulated project learnings from past agent runs |
+| `learnings <project>` | View learnings for a specific project |
+| `learnings clear <project>` | Clear a project's learnings file |
 | *(none)* | Continuous polling every 30s |
 | `--once` | Poll once, wait for agents to finish, exit |
 | `--dry-run` | Poll and log what would happen, don't run agents |
@@ -351,6 +354,23 @@ Available model aliases:
 
 You can also pass a full model ID directly (e.g. `ticket-to-pr model review claude-sonnet-4-5-20250929`). Changes are saved to `.env.local` and take effect on the next poll cycle.
 
+### `learnings` — Project Memory
+
+TicketToPR accumulates learnings from every agent run — successes, failures, patterns, and mistakes. These are automatically injected into future agent prompts so the AI gets smarter about your project over time.
+
+```bash
+# View all project learnings
+ticket-to-pr learnings
+
+# View learnings for a specific project
+ticket-to-pr learnings MyProject
+
+# Clear learnings for a project (start fresh)
+ticket-to-pr learnings clear MyProject
+```
+
+Learnings are stored in each project directory at `.ticket-to-pr/learnings.md` (auto-gitignored). Failed tickets are especially valuable — the agent learns what not to do next time.
+
 ### Your First Ticket
 
 1. Click **"+ New"** on your Notion board
@@ -424,7 +444,7 @@ The review agent explores your codebase without modifying anything:
 
 - **Tools**: Read, Glob, Grep, Task
 - **Context**: Reads your project's `CLAUDE.md` for architecture rules. If `blockedFiles` are configured, the review agent factors those constraints into scoring.
-- **Output**: Ease score, confidence score, implementation spec, impact report, affected files, risks
+- **Output**: Ease score, confidence score, implementation spec, impact report, affected files, risks, **acceptance test cases**
 - **Budget**: $2.00 max, 25 turns max
 - **Typical cost**: $0.15 - $0.50
 
@@ -446,7 +466,7 @@ The review agent explores your codebase without modifying anything:
 
 ### Execute Agent (Write Access)
 
-The execute agent implements the code based on the spec:
+The execute agent implements the code based on the spec. When the review agent generates acceptance tests, the execute agent follows a **test-first workflow** — writing test files before implementation code.
 
 - **Tools**: Read, Glob, Grep, Edit, Write + limited Bash (git, build, test only)
 - **Dev access** (opt-in): When `devAccess` is enabled, additionally allows `npx tsx`, `node`, `npm run`, `npx vitest`, `npx jest`, `npx prisma`, `python`, and `curl` to localhost/127.0.0.1 only
@@ -459,14 +479,15 @@ The execute agent implements the code based on the spec:
 
 1. TicketToPR **fetches the latest** from `origin/<baseBranch>` (configurable per project, auto-detected by default)
 2. Creates branch `notion/{8-char-id}/{ticket-slug}` based on the fresh remote state
-3. Claude implements changes and makes atomic commits
-4. TicketToPR runs your build command (if configured)
-5. If `blockedFiles` patterns are configured, validates no off-limits files were touched
-6. Build passes + no blocked file violations: pushes branch to origin
-7. Creates a GitHub PR via `gh pr create` targeting the base branch (unless `skipPR` is enabled)
-8. PR URL written back to the Notion ticket
-9. Ticket moves to **PR Ready**
-10. Build fails or blocked file violation: no code is pushed, ticket moves to **Failed**
+3. Claude implements changes and makes atomic commits (test-first if acceptance tests were generated)
+4. **Diff review**: a lightweight Haiku agent reviews the diff against the spec — catches issues before push
+5. TicketToPR runs your build command (if configured)
+6. If `blockedFiles` patterns are configured, validates no off-limits files were touched
+7. All checks pass: pushes branch to origin
+8. Creates a GitHub PR via `gh pr create` targeting the base branch (unless `skipPR` is enabled)
+9. PR URL written back to the Notion ticket
+10. Ticket moves to **PR Ready**
+11. Any check fails (diff review, build, blocked files): no code is pushed, ticket moves to **Failed**
 
 ## Costs
 

package/dist/cli.d.ts

@@ -1,3 +1,4 @@
 export declare function runDoctor(): Promise<void>;
 export declare function runInit(): Promise<void>;
 export declare function runModel(args: string[]): Promise<void>;
+export declare function runLearnings(args: string[]): Promise<void>;

package/dist/cli.js

@@ -2,7 +2,8 @@ import { createInterface } from 'node:readline';
 import { execSync } from 'node:child_process';
 import { readFileSync, existsSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { mask, shellEscape, writeEnvFile, updateProjectsFile, getDefaultBranch, parseEnvFile } from './lib/utils.js';
+import { mask, shellEscape, writeEnvFile, updateProjectsFile, getDefaultBranch, parseEnvFile, readLearnings } from './lib/utils.js';
+import { unlinkSync } from 'node:fs';
 import { getProjectNames, getProjectDir, getBaseBranch, getBlockedFiles, getSkipPR } from './lib/projects.js';
 import { CONFIG_DIR } from './lib/paths.js';
 // -- Colors --
@@ -849,3 +850,78 @@ export async function runModel(args) {
     }
     console.log(`${DIM}Saved to .env.local. Takes effect on next poll cycle.${RESET}\n`);
 }
+// -- Learnings --
+export async function runLearnings(args) {
+    const projectNames = getProjectNames();
+    if (projectNames.length === 0) {
+        console.log(`${RED}No projects configured.${RESET} Run ${DIM}ticket-to-pr init${RESET} first.`);
+        process.exitCode = 1;
+        return;
+    }
+    const subCmd = args[0]?.toLowerCase();
+    const projectArg = args[1];
+    // ticket-to-pr learnings clear <project>
+    if (subCmd === 'clear') {
+        if (!projectArg) {
+            console.log(`${RED}Usage: ticket-to-pr learnings clear <project>${RESET}`);
+            console.log(`${DIM}Projects: ${projectNames.join(', ')}${RESET}`);
+            process.exitCode = 1;
+            return;
+        }
+        const dir = getProjectDir(projectArg);
+        if (!dir) {
+            console.log(`${RED}Unknown project "${projectArg}".${RESET} Available: ${projectNames.join(', ')}`);
+            process.exitCode = 1;
+            return;
+        }
+        const learningsPath = join(dir, '.ticket-to-pr', 'learnings.md');
+        if (existsSync(learningsPath)) {
+            unlinkSync(learningsPath);
+            printStatus(true, `Cleared learnings for ${projectArg}`);
+        }
+        else {
+            console.log(`${DIM}No learnings file found for ${projectArg}.${RESET}`);
+        }
+        return;
+    }
+    // ticket-to-pr learnings [project]
+    // If a project name is given, show only that project
+    const projectsToShow = subCmd && projectNames.includes(subCmd)
+        ? [subCmd]
+        : subCmd && getProjectDir(subCmd)
+            ? [subCmd]
+            : projectNames;
+    // If an unknown arg was passed
+    if (subCmd && subCmd !== 'clear' && !getProjectDir(subCmd) && !projectNames.some(p => p.toLowerCase() === subCmd)) {
+        console.log(`${RED}Unknown project or subcommand "${args[0]}".${RESET}`);
+        console.log(`\n${BOLD}Usage:${RESET}`);
+        console.log(`  ticket-to-pr learnings                   ${DIM}# view all projects${RESET}`);
+        console.log(`  ticket-to-pr learnings <project>          ${DIM}# view one project${RESET}`);
+        console.log(`  ticket-to-pr learnings clear <project>    ${DIM}# clear a project's learnings${RESET}`);
+        console.log(`\n${DIM}Projects: ${projectNames.join(', ')}${RESET}`);
+        process.exitCode = 1;
+        return;
+    }
+    let anyFound = false;
+    for (const name of projectsToShow) {
+        const dir = getProjectDir(name);
+        if (!dir)
+            continue;
+        const content = readLearnings(dir);
+        if (content) {
+            anyFound = true;
+            console.log(`\n${BOLD}${name}${RESET} ${DIM}${dir}/.ticket-to-pr/learnings.md${RESET}\n`);
+            console.log(content);
+        }
+        else {
+            console.log(`\n${BOLD}${name}${RESET} ${DIM}no learnings yet${RESET}`);
+        }
+    }
+    if (!anyFound) {
+        console.log(`\n${DIM}Learnings accumulate automatically as tickets are processed.${RESET}`);
+    }
+    console.log(`\n${BOLD}Commands:${RESET}`);
+    console.log(`  ticket-to-pr learnings                   ${DIM}# view all projects${RESET}`);
+    console.log(`  ticket-to-pr learnings <project>          ${DIM}# view one project${RESET}`);
+    console.log(`  ticket-to-pr learnings clear <project>    ${DIM}# clear a project's learnings${RESET}\n`);
+}

package/dist/config.d.ts

@@ -11,10 +11,13 @@ export declare const CONFIG: {
     };
     readonly REVIEW_BUDGET_USD: 2;
     readonly EXECUTE_BUDGET_USD: 15;
+    readonly DIFF_REVIEW_BUDGET_USD: 0.5;
     readonly REVIEW_MODEL: string;
     readonly EXECUTE_MODEL: string;
+    readonly DIFF_REVIEW_MODEL: string;
     readonly REVIEW_MAX_TURNS: 25;
     readonly EXECUTE_MAX_TURNS: 50;
+    readonly DIFF_REVIEW_MAX_TURNS: 10;
     readonly STALE_LOCK_MS: number;
     readonly MAX_CONCURRENT_AGENTS: number;
     readonly FREE_MAX_PROJECTS: 1;
@@ -47,8 +50,32 @@ export declare const REVIEW_OUTPUT_SCHEMA: {
         readonly risks: {
             readonly type: "string";
         };
+        readonly testCases: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+    };
+    readonly required: readonly ["easeScore", "confidenceScore", "spec", "impactReport", "affectedFiles", "testCases"];
+};
+export declare const DIFF_REVIEW_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly approved: {
+            readonly type: "boolean";
+        };
+        readonly issues: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly summary: {
+            readonly type: "string";
+        };
     };
-    readonly required: readonly ["easeScore", "confidenceScore", "spec", "impactReport", "affectedFiles"];
+    readonly required: readonly ["approved", "issues", "summary"];
 };
 export interface NotionTicket {
     id: string;
@@ -69,6 +96,12 @@ export interface ReviewOutput {
     impactReport: string;
     affectedFiles: string[];
     risks?: string;
+    testCases: string[];
+}
+export interface DiffReviewOutput {
+    approved: boolean;
+    issues: string[];
+    summary: string;
 }
 export interface LockEntry {
     mode: 'review' | 'execute';

package/dist/config.js

@@ -46,6 +46,7 @@ export const CONFIG = {
     // Agent budgets
     REVIEW_BUDGET_USD: 2.00,
     EXECUTE_BUDGET_USD: 15.00,
+    DIFF_REVIEW_BUDGET_USD: 0.50,
     // Agent models (env override → default)
     get REVIEW_MODEL() {
         return process.env.REVIEW_MODEL || 'claude-sonnet-4-6';
@@ -53,9 +54,13 @@ export const CONFIG = {
     get EXECUTE_MODEL() {
         return process.env.EXECUTE_MODEL || 'claude-opus-4-6';
     },
+    get DIFF_REVIEW_MODEL() {
+        return process.env.DIFF_REVIEW_MODEL || 'claude-haiku-4-5-20251001';
+    },
     // Agent limits
     REVIEW_MAX_TURNS: 25,
     EXECUTE_MAX_TURNS: 50,
+    DIFF_REVIEW_MAX_TURNS: 10,
     // Stale lock timeout (30 minutes)
     STALE_LOCK_MS: 30 * 60 * 1000,
     // Maximum concurrent agents (review + execute combined)
@@ -75,6 +80,17 @@ export const REVIEW_OUTPUT_SCHEMA = {
         impactReport: { type: 'string' },
         affectedFiles: { type: 'array', items: { type: 'string' } },
         risks: { type: 'string' },
+        testCases: { type: 'array', items: { type: 'string' } },
+    },
+    required: ['easeScore', 'confidenceScore', 'spec', 'impactReport', 'affectedFiles', 'testCases'],
+};
+// JSON schema for diff review agent structured output
+export const DIFF_REVIEW_SCHEMA = {
+    type: 'object',
+    properties: {
+        approved: { type: 'boolean' },
+        issues: { type: 'array', items: { type: 'string' } },
+        summary: { type: 'string' },
     },
-    required: ['easeScore', 'confidenceScore', 'spec', 'impactReport', 'affectedFiles'],
+    required: ['approved', 'issues', 'summary'],
 };

package/dist/index.js

@@ -2,8 +2,8 @@ import { readFileSync } from 'node:fs';
 import { execSync } from 'node:child_process';
 import { join } from 'node:path';
 import { query } from '@anthropic-ai/claude-agent-sdk';
-import { CONFIG, REVIEW_OUTPUT_SCHEMA, isPro } from './config.js';
-import { sleep, clamp, extractJsonFromOutput, shellEscape, extractNumber, loadEnv, parseEnvFile, createWorktree, removeWorktree, getDefaultBranch, validateNoBlockedFiles } from './lib/utils.js';
+import { CONFIG, REVIEW_OUTPUT_SCHEMA, DIFF_REVIEW_SCHEMA, isPro } from './config.js';
+import { sleep, clamp, extractJsonFromOutput, shellEscape, extractNumber, loadEnv, parseEnvFile, createWorktree, removeWorktree, getDefaultBranch, validateNoBlockedFiles, readLearnings, appendLearning } from './lib/utils.js';
 import { getProjectDir, getProjectNames, getBuildCommand, getBaseBranch, getBlockedFiles, getSkipPR, getDevAccess, getEnvFile } from './lib/projects.js';
 import { fetchTicketsByStatus, fetchTicketDetails, writeReviewResults, writeExecutionResults, moveTicketStatus, writeFailure, addComment, } from './lib/notion.js';
 import { PACKAGE_ROOT, CONFIG_DIR } from './lib/paths.js';
@@ -13,11 +13,14 @@ loadEnv(join(CONFIG_DIR, '.env.local'));
 delete process.env.CLAUDECODE;
 // -- Subcommand routing --
 const subcommand = process.argv[2];
-if (subcommand === 'init' || subcommand === 'doctor' || subcommand === 'model') {
-    const { runInit, runDoctor, runModel } = await import('./cli.js');
+if (subcommand === 'init' || subcommand === 'doctor' || subcommand === 'model' || subcommand === 'learnings') {
+    const { runInit, runDoctor, runModel, runLearnings } = await import('./cli.js');
     if (subcommand === 'model') {
         await runModel(process.argv.slice(3));
     }
+    else if (subcommand === 'learnings') {
+        await runLearnings(process.argv.slice(3));
+    }
     else {
         await (subcommand === 'init' ? runInit() : runDoctor());
     }
@@ -48,6 +51,8 @@ function log(color, label, msg) {
 // -- Prompt loading (bundled with the package) --
 const reviewPrompt = readFileSync(join(PACKAGE_ROOT, 'prompts', 'review.md'), 'utf-8');
 const executePrompt = readFileSync(join(PACKAGE_ROOT, 'prompts', 'execute.md'), 'utf-8');
+const diffReviewPrompt = readFileSync(join(PACKAGE_ROOT, 'prompts', 'diff-review.md'), 'utf-8');
+const retroPrompt = readFileSync(join(PACKAGE_ROOT, 'prompts', 'retro.md'), 'utf-8');
 // -- Agent Runner --
 async function runReviewAgent(ticket) {
     const projectDir = getProjectDir(ticket.project);
@@ -72,6 +77,10 @@ async function runReviewAgent(ticket) {
     if (blockedFiles.length > 0) {
         promptParts.push('', '## BLOCKED FILES — CANNOT BE MODIFIED', 'The following file patterns are off-limits. Factor this into your scoring — if the natural implementation would touch these files, lower the ease and confidence scores and note it in risks.', '', ...blockedFiles.map(p => `- \`${p}\``));
     }
+    const learnings = readLearnings(projectDir);
+    if (learnings) {
+        promptParts.push('', '## Project Learnings', 'These are patterns and lessons learned from previous work on this project:', '', learnings);
+    }
     const prompt = promptParts.join('\n');
     const messages = query({
         prompt,
@@ -139,6 +148,7 @@ async function runReviewAgent(ticket) {
         impactReport: String(parsed.impactReport ?? ''),
         affectedFiles: Array.isArray(parsed.affectedFiles) ? parsed.affectedFiles.map(String) : [],
         risks: parsed.risks ? String(parsed.risks) : undefined,
+        testCases: Array.isArray(parsed.testCases) ? parsed.testCases.map(String) : [],
     };
     await writeReviewResults(ticket.id, results);
     await moveTicketStatus(ticket.id, CONFIG.COLUMNS.SCORED);
@@ -151,8 +161,223 @@ async function runReviewAgent(ticket) {
         `Cost: $${cost.toFixed(2)} | Duration: ${duration}s`,
     ].join('\n');
     await addComment(ticket.id, comment);
+    appendLearning(projectDir, [
+        `**Review: ${ticket.title}**`,
+        `Ease: ${results.easeScore}/10, Confidence: ${results.confidenceScore}/10`,
+        `Affected files: ${results.affectedFiles.join(', ')}`,
+        results.risks ? `Risks: ${results.risks}` : '',
+    ].filter(Boolean).join('\n'));
     log(GREEN, 'REVIEW', `Done: ease=${results.easeScore} confidence=${results.confidenceScore} cost=$${cost.toFixed(2)}`);
 }
+async function runDiffReviewAgent(worktreeDir, baseBranch, spec, description, affectedFiles) {
+    // Get the full diff
+    let diff = '';
+    try {
+        diff = execSync(`git diff origin/${shellEscape(baseBranch)}...HEAD`, { cwd: worktreeDir, stdio: 'pipe', maxBuffer: 10 * 1024 * 1024 }).toString();
+    }
+    catch {
+        // If diff fails (e.g. no commits), treat as empty
+        diff = '';
+    }
+    // Nothing to review if no changes
+    if (!diff.trim()) {
+        return {
+            result: { approved: true, issues: [], summary: 'No changes to review' },
+            cost: 0,
+        };
+    }
+    // Truncate very large diffs to stay within budget
+    const maxDiffLength = 100_000;
+    const truncatedDiff = diff.length > maxDiffLength
+        ? diff.slice(0, maxDiffLength) + '\n\n... (diff truncated)'
+        : diff;
+    const prompt = [
+        diffReviewPrompt,
+        '',
+        '## Spec',
+        spec || '(no spec provided)',
+        '',
+        '## Ticket Description',
+        description || '(no description provided)',
+        '',
+        '## Affected Files (from review)',
+        affectedFiles.length > 0 ? affectedFiles.map(f => `- ${f}`).join('\n') : '(none listed)',
+        '',
+        '## Diff',
+        '```diff',
+        truncatedDiff,
+        '```',
+    ].join('\n');
+    const messages = query({
+        prompt,
+        options: {
+            model: CONFIG.DIFF_REVIEW_MODEL,
+            cwd: worktreeDir,
+            allowedTools: ['Read'],
+            maxTurns: CONFIG.DIFF_REVIEW_MAX_TURNS,
+            maxBudgetUsd: CONFIG.DIFF_REVIEW_BUDGET_USD,
+            permissionMode: 'bypassPermissions',
+            allowDangerouslySkipPermissions: true,
+            systemPrompt: { type: 'preset', preset: 'claude_code' },
+            outputFormat: {
+                type: 'json_schema',
+                schema: DIFF_REVIEW_SCHEMA,
+            },
+            stderr: (data) => {
+                if (data.trim())
+                    log(DIM, 'STDERR', data.trim());
+            },
+        },
+    });
+    let output = '';
+    let structuredOutput = undefined;
+    let cost = 0;
+    for await (const message of messages) {
+        if (message.type === 'assistant') {
+            const content = message.message?.content;
+            if (Array.isArray(content)) {
+                for (const block of content) {
+                    if (block.type === 'text') {
+                        output = block.text;
+                    }
+                }
+            }
+            else if (typeof content === 'string') {
+                output = content;
+            }
+        }
+        if (message.type === 'result') {
+            cost = message.total_cost_usd ?? 0;
+            if (message.subtype !== 'success') {
+                throw new Error(`Diff review agent failed: ${message.subtype}`);
+            }
+            if ('structured_output' in message && message.structured_output != null) {
+                structuredOutput = message.structured_output;
+            }
+            if (message.result) {
+                output = message.result;
+            }
+        }
+    }
+    const parsed = structuredOutput ?? extractJsonFromOutput(output);
+    if (!parsed) {
+        // If we can't parse the output, default to approved to avoid blocking
+        return {
+            result: { approved: true, issues: [], summary: 'Diff review agent did not return structured output; defaulting to approved' },
+            cost,
+        };
+    }
+    return {
+        result: {
+            approved: Boolean(parsed.approved),
+            issues: Array.isArray(parsed.issues) ? parsed.issues.map(String) : [],
+            summary: String(parsed.summary ?? ''),
+        },
+        cost,
+    };
+}
+async function runRetroAgent(projectDir, worktreeDir, baseBranch, ticket, outcome) {
+    try {
+        // Get the diff (may be empty if agent failed before committing)
+        let diff = '';
+        try {
+            diff = execSync(`git diff origin/${shellEscape(baseBranch)}...HEAD`, {
+                cwd: worktreeDir, stdio: 'pipe', timeout: 15_000,
+            }).toString();
+        }
+        catch {
+            // No diff available
+        }
+        // Read existing learnings to avoid repeats
+        const existingLearnings = readLearnings(projectDir);
+        // Build the retro prompt
+        const parts = [
+            retroPrompt,
+            '',
+            `## Ticket: ${ticket.title}`,
+            '',
+            '**Description**:',
+            ticket.description,
+            '',
+            '**Spec**:',
+            ticket.spec ?? '(none)',
+            '',
+            `## Outcome: ${outcome.success ? 'SUCCESS' : 'FAILED'}`,
+        ];
+        if (!outcome.success && outcome.error) {
+            parts.push('', '**Error**:', outcome.error.slice(0, 1000));
+        }
+        if (outcome.diffReviewIssues && outcome.diffReviewIssues.length > 0) {
+            parts.push('', '**Diff Review Issues**:', ...outcome.diffReviewIssues.map(i => `- ${i}`));
+        }
+        if (outcome.buildFailed) {
+            parts.push('', '**Build**: FAILED');
+        }
+        if (diff) {
+            const truncatedDiff = diff.length > 50_000 ? diff.slice(0, 50_000) + '\n...(truncated)' : diff;
+            parts.push('', '## Diff', '```diff', truncatedDiff, '```');
+        }
+        else {
+            parts.push('', '## Diff', 'No diff available (agent may have failed before committing).');
+        }
+        if (existingLearnings) {
+            parts.push('', '## Existing Learnings (do not repeat these)', existingLearnings);
+        }
+        const prompt = parts.join('\n');
+        const messages = query({
+            prompt,
+            options: {
+                model: CONFIG.DIFF_REVIEW_MODEL, // Reuse Haiku config
+                cwd: projectDir,
+                tools: ['Read', 'Glob', 'Grep'],
+                allowedTools: ['Read', 'Glob', 'Grep'],
+                maxTurns: 5,
+                maxBudgetUsd: 0.25,
+                permissionMode: 'bypassPermissions',
+                allowDangerouslySkipPermissions: true,
+                settingSources: ['project'],
+                systemPrompt: { type: 'preset', preset: 'claude_code' },
+                stderr: () => { },
+            },
+        });
+        let output = '';
+        for await (const message of messages) {
+            if (message.type === 'assistant') {
+                const content = message.message?.content;
+                if (Array.isArray(content)) {
+                    for (const block of content) {
+                        if (block.type === 'text')
+                            output = block.text;
+                    }
+                }
+                else if (typeof content === 'string') {
+                    output = content;
+                }
+            }
+            if (message.type === 'result') {
+                if ('result' in message && message.result) {
+                    output = message.result;
+                }
+            }
+        }
+        // Only save if the retro produced something meaningful
+        const trimmed = output.trim();
+        if (trimmed && !trimmed.toLowerCase().includes('no new learnings')) {
+            const header = outcome.success
+                ? `**Retro (success): ${ticket.title}**`
+                : `**Retro (failed): ${ticket.title}**`;
+            appendLearning(projectDir, `${header}\n${trimmed}`);
+            log(DIM, 'RETRO', `Saved ${trimmed.split('\n').filter(l => l.startsWith('-') || l.startsWith('*')).length} learnings`);
+        }
+        else {
+            log(DIM, 'RETRO', 'No new learnings');
+        }
+    }
+    catch (e) {
+        // Retro is best-effort — never block the pipeline
+        log(DIM, 'RETRO', `Skipped: ${e instanceof Error ? e.message : e}`);
+    }
+}
 async function runExecuteAgent(ticket) {
     const projectDir = getProjectDir(ticket.project);
     if (!projectDir) {
@@ -181,6 +406,7 @@ async function runExecuteAgent(ticket) {
     createWorktree(projectDir, branchName, worktreeDir, baseBranch);
     let cost = 0;
     let commitCount = 0;
+    let retroOutcome = { success: false };
     try {
         const promptParts = [
             executePrompt,
@@ -200,12 +426,20 @@ async function runExecuteAgent(ticket) {
             '**Page Content**:',
             ticket.bodyBlocks,
         ];
+        // Highlight acceptance tests if present in the spec
+        if (ticket.spec && ticket.spec.includes('## Acceptance Tests')) {
+            promptParts.push('', '**IMPORTANT**: The spec above includes Acceptance Tests. Write test files FIRST, then implement code to make them pass. Run the tests to verify.');
+        }
         if (blockedFiles.length > 0) {
             promptParts.push('', '## BLOCKED FILES — DO NOT TOUCH', 'The following file patterns are off-limits. Do NOT create, modify, or delete any files matching these patterns. Violations will cause the entire run to fail.', '', ...blockedFiles.map((p) => `- \`${p}\``));
         }
         if (devAccess) {
             promptParts.push('', '## DEV ENVIRONMENT ACCESS', 'You have access to run scripts and dev tools in this project. Use this to:', '- Write and run scripts to understand database schema or existing data', '- Hit local API endpoints with curl to understand response shapes', '- Run tests to verify your implementation', '- Use ORM tools (e.g. `npx prisma studio`) to inspect the data model', '', '### Rules', '- Do NOT run database migrations (`prisma migrate`, `db push`, `alembic`, etc.)', '- Do NOT drop, truncate, or bulk-delete data', '- Do NOT make requests to external/production hosts — only localhost and 127.0.0.1', '- Clean up any temporary scripts you create before your final commit', '- If you create test data, document it in a commit message so reviewers know');
         }
+        const learnings = readLearnings(projectDir);
+        if (learnings) {
+            promptParts.push('', '## Project Learnings', 'These are patterns and lessons learned from previous work on this project:', '', learnings);
+        }
         const prompt = promptParts.join('\n');
         // Build agent environment when envFile is configured
         let agentEnv;
@@ -267,6 +501,15 @@ async function runExecuteAgent(ticket) {
             // If branch doesn't exist or no commits, count is 0
             commitCount = 0;
         }
+        // Post-execution: diff review
+        log(YELLOW, 'REVIEW', 'Running diff review...');
+        const diffReview = await runDiffReviewAgent(worktreeDir, baseBranch, ticket.spec ?? '', ticket.description, []);
+        cost += diffReview.cost;
+        if (!diffReview.result.approved) {
+            retroOutcome = { success: false, error: 'Diff review rejected the changes', diffReviewIssues: diffReview.result.issues };
+            throw new Error(`Diff review failed:\n${diffReview.result.issues.map(i => `  - ${i}`).join('\n')}`);
+        }
+        log(GREEN, 'REVIEW', `Diff review passed: ${diffReview.result.summary}`);
         // Post-execution: validate build
         const buildCmd = getBuildCommand(ticket.project);
         let buildPassed = true;
@@ -346,6 +589,7 @@ async function runExecuteAgent(ticket) {
             `Cost: $${cost.toFixed(2)} | Duration: ${duration}s`,
         ].join('\n');
         await addComment(ticket.id, comment);
+        retroOutcome = { success: true };
         log(GREEN, 'EXECUTE', `Done: branch=${branchName} cost=$${cost.toFixed(2)}${prUrl ? ` pr=${prUrl}` : ''}`);
     }
     catch (error) {
@@ -359,9 +603,17 @@ async function runExecuteAgent(ticket) {
             `Cost: $${cost.toFixed(2)} | Duration: ${duration}s`,
         ].join('\n');
         await addComment(ticket.id, comment);
+        retroOutcome = {
+            success: false,
+            error: errMsg,
+            buildFailed: errMsg.includes('Build validation failed'),
+        };
         throw error;
     }
     finally {
+        // Run retro before cleaning up worktree (so it can read the diff)
+        log(DIM, 'RETRO', 'Running post-execution retrospective...');
+        await runRetroAgent(projectDir, worktreeDir, baseBranch, ticket, retroOutcome);
         // Always clean up the worktree
         removeWorktree(projectDir, worktreeDir);
     }
@@ -404,6 +656,16 @@ async function handleTicket(mode, ticket) {
             ].join('\n');
             await addComment(ticket.id, comment);
         }
+        // Append failure learning (execute handles its own in runExecuteAgent catch)
+        if (mode === 'review') {
+            const projectDir = getProjectDir(ticket.project);
+            if (projectDir) {
+                appendLearning(projectDir, [
+                    `**Failed review: ${ticket.title}**`,
+                    `Error: ${errMsg.slice(0, 200)}`,
+                ].join('\n'));
+            }
+        }
         try {
             await writeFailure(ticket.id, errMsg);
         }

package/dist/lib/notion.js

@@ -129,12 +129,17 @@ export async function fetchTicketDetails(pageId) {
  * Write review results back to the ticket properties.
  */
 export async function writeReviewResults(pageId, results) {
+    // Build spec content, appending test cases if present
+    let specContent = results.spec;
+    if (results.testCases && results.testCases.length > 0) {
+        specContent += '\n\n## Acceptance Tests\n' + results.testCases.map(tc => `- ${tc}`).join('\n');
+    }
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const properties = {
         Ease: { number: results.easeScore },
         Confidence: { number: results.confidenceScore },
         Spec: {
-            rich_text: chunkRichText(results.spec),
+            rich_text: chunkRichText(specContent),
         },
         Impact: {
             rich_text: chunkRichText(`${results.impactReport}\n\nFiles: ${results.affectedFiles.join(', ')}${results.risks ? `\n\nRisks: ${results.risks}` : ''}`),

package/dist/lib/utils.d.ts

@@ -26,3 +26,5 @@ export declare function ensureWorktreesIgnored(projectDir: string): void;
 export declare function createWorktree(projectDir: string, branchName: string, worktreeDir: string, baseBranch?: string): void;
 export declare function validateNoBlockedFiles(worktreeDir: string, baseBranch: string, blockedPatterns: string[]): string[];
 export declare function removeWorktree(projectDir: string, worktreeDir: string): void;
+export declare function readLearnings(projectDir: string): string;
+export declare function appendLearning(projectDir: string, entry: string): void;

package/dist/lib/utils.js

@@ -204,11 +204,21 @@ export function _resetDefaultBranchCache() {
 export function ensureWorktreesIgnored(projectDir) {
     const gitignorePath = join(projectDir, '.gitignore');
     try {
-        const content = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf-8') : '';
+        let content = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf-8') : '';
         const lines = content.split('\n');
+        let modified = false;
         if (!lines.some((line) => line.trim() === '.worktrees' || line.trim() === '.worktrees/')) {
             const separator = content.length > 0 && !content.endsWith('\n') ? '\n' : '';
-            writeFileSync(gitignorePath, content + separator + '.worktrees/\n');
+            content = content + separator + '.worktrees/\n';
+            modified = true;
+        }
+        if (!lines.some((line) => line.trim() === '.ticket-to-pr' || line.trim() === '.ticket-to-pr/')) {
+            const separator = content.length > 0 && !content.endsWith('\n') ? '\n' : '';
+            content = content + separator + '.ticket-to-pr/\n';
+            modified = true;
+        }
+        if (modified) {
+            writeFileSync(gitignorePath, content);
         }
     }
     catch {
@@ -351,3 +361,36 @@ export function removeWorktree(projectDir, worktreeDir) {
         }
     }
 }
+// -- Per-project learnings --
+const MAX_LEARNINGS_ENTRIES = 100;
+export function readLearnings(projectDir) {
+    const learningsPath = join(projectDir, '.ticket-to-pr', 'learnings.md');
+    try {
+        return readFileSync(learningsPath, 'utf-8');
+    }
+    catch {
+        return '';
+    }
+}
+export function appendLearning(projectDir, entry) {
+    const dir = join(projectDir, '.ticket-to-pr');
+    mkdirSync(dir, { recursive: true });
+    const learningsPath = join(dir, 'learnings.md');
+    let content = '';
+    try {
+        content = readFileSync(learningsPath, 'utf-8');
+    }
+    catch {
+        // File doesn't exist yet
+    }
+    // Add timestamped entry
+    const timestamp = new Date().toISOString().slice(0, 10);
+    const newEntry = `### ${timestamp}\n${entry}\n`;
+    content = content + '\n' + newEntry;
+    // Trim to max entries
+    const entries = content.split(/(?=^### \d{4}-\d{2}-\d{2}$)/m).filter(e => e.trim());
+    if (entries.length > MAX_LEARNINGS_ENTRIES) {
+        content = entries.slice(-MAX_LEARNINGS_ENTRIES).join('');
+    }
+    writeFileSync(learningsPath, content.trim() + '\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticket-to-pr",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "Drag a Notion ticket, get a pull request. AI-powered dev automation.",
   "type": "module",
   "bin": {

package/prompts/diff-review.md

@@ -0,0 +1,28 @@
+You are a code reviewer checking a diff against its specification.
+
+## Your Task
+1. Read the diff carefully
+2. Compare it against the original spec and ticket description
+3. Check for common issues
+4. Approve or reject with specific reasons
+
+## Check For
+- Does the diff implement what the spec asked for?
+- Are there modified files not mentioned in the affected files list?
+- Any hardcoded values, debug code, console.logs, or TODOs left behind?
+- Any obvious security issues (exposed secrets, SQL injection, XSS)?
+- Any deleted tests or reduced test coverage?
+- Are imports and exports consistent?
+- Does the code follow the patterns visible in the diff context?
+
+## Output
+Return a JSON object:
+```json
+{
+  "approved": true/false,
+  "issues": ["issue 1", "issue 2"],
+  "summary": "Brief summary of the review"
+}
+```
+
+If approved is false, be specific about what needs to change. An empty issues array with approved: true means the diff looks good.

package/prompts/execute.md

@@ -17,5 +17,15 @@ You have been given a ticket with an implementation spec. Follow the spec and im
 11. If your prompt includes a "BLOCKED FILES" section, you MUST NOT modify any files matching those patterns. Violations will cause the entire run to fail.
 12. If your prompt includes a "DEV ENVIRONMENT ACCESS" section, you may run scripts and dev tools as described. Always prefer reading code directly over running scripts when possible.
 
+## Test-First Development
+If the spec includes acceptance tests, follow this workflow:
+1. Read the acceptance tests carefully before writing any code
+2. Write a test file first that captures the acceptance criteria as executable tests
+3. Implement the code to make the tests pass
+4. Run the tests to verify your implementation
+5. If tests fail, fix the implementation until they pass
+
+If no test framework is configured in the project, implement the code directly but use the acceptance tests as a checklist — verify each criterion is met before committing.
+
 ## When Done
 Commit all changes with a final commit message summarizing what was done. The commit message should reference the ticket title.

package/prompts/retro.md

@@ -0,0 +1,27 @@
+You are conducting a retrospective on an AI agent's work on a codebase.
+
+## Your Task
+Analyze what happened during this ticket execution and extract lessons that will help future agent runs on this same project. You are writing notes for a future AI agent, not a human.
+
+## What to Look For
+
+### On Success
+- **Conventions discovered**: file naming, import patterns, export style, component structure, API response shapes, error handling patterns
+- **What worked**: approaches or patterns that led to clean implementation
+- **Codebase quirks**: path aliases, custom configs, non-obvious setup requirements, framework-specific patterns
+
+### On Failure
+- **Root cause**: what specifically went wrong and why (not just the error message)
+- **What to do differently**: concrete, actionable advice for next time
+- **Codebase constraints**: things the agent didn't know about that caused the failure
+
+### Always
+- **Capability assessment**: what types of changes are easy/hard in this project
+- **Suggestions**: improvements to the project's CLAUDE.md or configuration that would help future runs
+
+## Output Rules
+- Write 2-5 bullet points. Each must be a specific, actionable lesson.
+- Start each bullet with a category tag: `[convention]`, `[mistake]`, `[capability]`, or `[suggestion]`
+- Be specific to THIS project. "Use TypeScript" is useless. "This project uses strict TypeScript with no implicit any — always add explicit return types on exported functions" is useful.
+- Don't repeat lessons that already exist in the project learnings.
+- If nothing useful was learned (e.g., trivial change, obvious outcome), just write: `No new learnings.`

package/prompts/review.md

@@ -30,10 +30,23 @@ You MUST end your response with a JSON code block containing exactly these field
   "spec": "<step-by-step implementation plan in markdown>",
   "impactReport": "<which files change and why, in markdown>",
   "affectedFiles": ["<file1>", "<file2>"],
-  "risks": "<any concerns or blockers, optional>"
+  "risks": "<any concerns or blockers, optional>",
+  "testCases": ["<test case 1>", "<test case 2>", "..."]
 }
 ```
 
+### Test Cases
+
+Generate 3-8 acceptance test cases depending on ticket complexity. These are framework-agnostic acceptance criteria (not full test files) that the execute agent must satisfy.
+
+- Write each test case as a "GIVEN... WHEN... THEN..." statement or a simple assertion
+- Focus on verifiable outcomes, not implementation details
+- Cover happy path, edge cases, and error handling as appropriate
+- Examples:
+  - "GET /api/health returns 200 with JSON body containing status:'ok' and a valid ISO timestamp"
+  - "Calling formatDate(null) returns empty string"
+  - "GIVEN a user is not authenticated WHEN they request /api/private THEN they receive a 401 response"
+
 ## Rules
 - DO NOT modify any files. You are read-only.
 - Be honest about confidence. A low score is valuable information.