wiggum-cli 0.16.0 → 0.17.0

package/dist/agent/memory/ingest.d.ts

@@ -0,0 +1,14 @@
+import type { MemoryStore } from './store.js';
+/**
+ * Ingest strategic docs as lightweight catalog entries (filename + summary).
+ * Full content is read on-demand via the readStrategicDoc tool.
+ */
+export declare function ingestStrategicDocs(projectRoot: string, store: MemoryStore): Promise<number>;
+/**
+ * List available strategic doc filenames.
+ */
+export declare function listStrategicDocs(projectRoot: string): Promise<string[]>;
+/**
+ * Read the full content of a strategic doc.
+ */
+export declare function readStrategicDoc(projectRoot: string, filename: string): Promise<string | null>;

package/dist/agent/memory/ingest.js

@@ -0,0 +1,77 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { createMemoryEntry } from './types.js';
+const SUMMARY_LENGTH = 300;
+/**
+ * Extract the first heading and opening lines as a summary.
+ */
+function summarize(content) {
+    const lines = content.split('\n').filter(l => l.trim());
+    const summary = lines.slice(0, 8).join('\n');
+    return summary.length > SUMMARY_LENGTH
+        ? summary.slice(0, SUMMARY_LENGTH) + '…'
+        : summary;
+}
+/**
+ * Ingest strategic docs as lightweight catalog entries (filename + summary).
+ * Full content is read on-demand via the readStrategicDoc tool.
+ */
+export async function ingestStrategicDocs(projectRoot, store) {
+    const docsDir = join(projectRoot, '.ralph', 'strategic');
+    let allFiles;
+    try {
+        allFiles = await readdir(docsDir);
+    }
+    catch {
+        return 0; // directory does not exist
+    }
+    const files = allFiles.filter(f => f.endsWith('.md'));
+    if (files.length === 0)
+        return 0;
+    const existing = await store.read({ type: 'strategic_context' });
+    const ingestedFiles = new Set(existing.flatMap(e => (e.tags ?? []).filter(t => t.startsWith('source:')).map(t => t.slice(7))));
+    let count = 0;
+    for (const file of files) {
+        if (ingestedFiles.has(file))
+            continue;
+        const content = await readFile(join(docsDir, file), 'utf-8');
+        const summary = summarize(content);
+        const entry = createMemoryEntry({
+            type: 'strategic_context',
+            content: `[${file}] ${summary}`,
+            tags: [`source:${file}`],
+        });
+        await store.append(entry);
+        count++;
+    }
+    return count;
+}
+/**
+ * List available strategic doc filenames.
+ */
+export async function listStrategicDocs(projectRoot) {
+    const docsDir = join(projectRoot, '.ralph', 'strategic');
+    try {
+        const allFiles = await readdir(docsDir);
+        return allFiles.filter(f => f.endsWith('.md'));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Read the full content of a strategic doc.
+ */
+export async function readStrategicDoc(projectRoot, filename) {
+    const docsDir = resolve(projectRoot, '.ralph', 'strategic');
+    const resolved = resolve(docsDir, filename);
+    // Prevent path traversal: resolved path must stay within docsDir
+    if (!resolved.startsWith(docsDir + '/'))
+        return null;
+    try {
+        return await readFile(resolved, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}

package/dist/agent/memory/store.d.ts

@@ -0,0 +1,15 @@
+import type { MemoryEntry, MemoryType } from './types.js';
+export interface ReadOptions {
+    type?: MemoryType;
+    limit?: number;
+    search?: string;
+}
+export declare class MemoryStore {
+    private readonly filePath;
+    private lock;
+    constructor(dirPath: string);
+    private serialize;
+    append(entry: MemoryEntry): Promise<void>;
+    read(options?: ReadOptions): Promise<MemoryEntry[]>;
+    prune(): Promise<number>;
+}

package/dist/agent/memory/store.js

@@ -0,0 +1,98 @@
+import { readFile, writeFile, appendFile, mkdir, rename } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+const MEMORY_FILE = 'memory.jsonl';
+const FILE_MODE = 0o600;
+const PRUNE_AGE_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+const PERMANENT_TYPES = ['decision', 'strategic_context'];
+export class MemoryStore {
+    filePath;
+    lock = Promise.resolve();
+    constructor(dirPath) {
+        this.filePath = join(dirPath, MEMORY_FILE);
+    }
+    serialize(fn) {
+        const p = this.lock.then(fn, fn);
+        this.lock = p.then(() => { }, () => { });
+        return p;
+    }
+    async append(entry) {
+        return this.serialize(async () => {
+            await mkdir(dirname(this.filePath), { recursive: true });
+            await appendFile(this.filePath, JSON.stringify(entry) + '\n', { encoding: 'utf-8', mode: FILE_MODE });
+        });
+    }
+    async read(options = {}) {
+        return this.serialize(async () => {
+            if (!existsSync(this.filePath))
+                return [];
+            const raw = (await readFile(this.filePath, 'utf-8')).trim();
+            if (!raw)
+                return [];
+            let entries = raw
+                .split('\n')
+                .filter(line => line.trim())
+                .map(line => {
+                try {
+                    return JSON.parse(line);
+                }
+                catch {
+                    return null;
+                }
+            })
+                .filter((e) => e !== null);
+            if (options.type) {
+                entries = entries.filter(e => e.type === options.type);
+            }
+            if (options.search) {
+                const term = options.search.toLowerCase();
+                entries = entries.filter(e => e.content.toLowerCase().includes(term));
+            }
+            // Most recent first for limit
+            entries.reverse();
+            if (options.limit && options.limit > 0) {
+                entries = entries.slice(0, options.limit);
+            }
+            return entries;
+        });
+    }
+    async prune() {
+        return this.serialize(async () => {
+            if (!existsSync(this.filePath))
+                return 0;
+            const raw = (await readFile(this.filePath, 'utf-8')).trim();
+            if (!raw)
+                return 0;
+            const entries = raw
+                .split('\n')
+                .filter(line => line.trim())
+                .map(line => {
+                try {
+                    return JSON.parse(line);
+                }
+                catch {
+                    return null;
+                }
+            })
+                .filter((e) => e !== null);
+            const now = Date.now();
+            const kept = entries.filter(entry => {
+                if (PERMANENT_TYPES.includes(entry.type))
+                    return true;
+                const age = now - new Date(entry.timestamp).getTime();
+                if (Number.isNaN(age))
+                    return true; // keep entries with corrupted timestamps
+                return age < PRUNE_AGE_MS;
+            });
+            const pruned = entries.length - kept.length;
+            if (pruned > 0) {
+                // Atomic write: write to temp file then rename
+                const tmpPath = this.filePath + '.tmp';
+                const content = kept.map(e => JSON.stringify(e)).join('\n') + '\n';
+                await writeFile(tmpPath, content, { encoding: 'utf-8', mode: FILE_MODE });
+                await rename(tmpPath, this.filePath);
+            }
+            return pruned;
+        });
+    }
+}

package/dist/agent/memory/types.d.ts

@@ -0,0 +1,16 @@
+export type MemoryType = 'work_log' | 'project_knowledge' | 'decision' | 'strategic_context';
+export interface MemoryEntry {
+    id: string;
+    timestamp: string;
+    type: MemoryType;
+    content: string;
+    tags?: string[];
+    relatedIssue?: number;
+}
+export interface CreateMemoryInput {
+    type: MemoryType;
+    content: string;
+    tags?: string[];
+    relatedIssue?: number;
+}
+export declare function createMemoryEntry(input: CreateMemoryInput): MemoryEntry;

package/dist/agent/memory/types.js

@@ -0,0 +1,14 @@
+import { randomBytes } from 'node:crypto';
+function generateId() {
+    return randomBytes(8).toString('hex');
+}
+export function createMemoryEntry(input) {
+    return {
+        id: generateId(),
+        timestamp: new Date().toISOString(),
+        type: input.type,
+        content: input.content,
+        ...(input.tags && { tags: input.tags }),
+        ...(input.relatedIssue !== undefined && { relatedIssue: input.relatedIssue }),
+    };
+}

package/dist/agent/orchestrator.d.ts

@@ -0,0 +1,7 @@
+import { ToolLoopAgent } from 'ai';
+import type { AgentConfig } from './types.js';
+export declare const AGENT_SYSTEM_PROMPT = "You are wiggum's autonomous development agent. You work through the GitHub issue backlog, shipping features one at a time.\n\n## Workflow\n\n1. Read memory to recall previous work and context\n   - Use listStrategicDocs to see available project documentation\n   - Use readStrategicDoc to read full documents relevant to the current task (architecture, design, implementation plans)\n2. List open issues and cross-reference with memory\n   - Consider: PM priority labels (P0 > P1 > P2), dependencies, strategic context\n   - **Housekeeping:** If memory says an issue was already completed (outcome \"success\" or \"skipped\") but it's still open:\n     1. Call assessFeatureState with the featureName and issueNumber\n     2. If recommendation is \"pr_merged\" or \"linked_pr_merged\": close it with closeIssue. Reflect with outcome \"skipped\". Does NOT count against maxItems.\n     3. If recommendation is anything else (e.g., \"resume_implementation\", \"start_fresh\", \"resume_pr_phase\"): the issue was NOT actually shipped. Do NOT close it. Instead, prioritize it as your next work item and follow the Feature State Decision Tree. This counts against maxItems.\n   - **Retry:** If memory records a previous attempt at an issue with outcome \"failure\" or \"partial\", and it's still open, prioritize it over new issues. Bugs that caused the failure may have been fixed, and existing work (branch, spec, plan) should not be abandoned. Call assessFeatureState to determine the right action \u2014 usually resume_implementation. This counts against maxItems.\n3. For the chosen issue (one NOT already completed):\n   a. Read the full issue details\n   b. Derive a featureName from the issue title (lowercase, hyphens, no spaces)\n   c. **Assess feature state** using assessFeatureState \u2014 MANDATORY before any action\n   d. Follow the Feature State Decision Tree based on the recommendation field\n   e. Monitor progress with checkLoopStatus and readLoopLog\n   f. Report results by commenting on the issue\n\n## Feature State Decision Tree\n\nAfter calling assessFeatureState, follow the recommendation:\n\n| recommendation | action |\n|---|---|\n| start_fresh | generateSpec \u2192 runLoop (fresh) |\n| generate_plan | runLoop without resume (spec exists, needs planning) |\n| resume_implementation | runLoop with resume: true (plan has pending tasks) |\n| resume_pr_phase | runLoop with resume: true (all tasks done, needs PR) |\n| pr_exists_open | Comment on issue, do NOT re-run loop |\n| pr_merged | Verify PR is merged, close issue with closeIssue, reflect with outcome \"skipped\", move on |\n| pr_closed | Decide: restart from scratch or skip |\n| linked_pr_merged | Verify the linked PR is merged, close issue with closeIssue (comment \"shipped via PR #N\"), reflect with outcome \"skipped\", move on |\n| linked_pr_open | Work in progress under a different branch \u2014 comment \"in progress via PR #N\", do NOT re-run loop |\n\n**Critical:**\n- When recommendation is resume_implementation or resume_pr_phase, you MUST pass resume: true to runLoop\n- When recommendation is generate_plan, do NOT pass resume (fresh branch needed)\n- When recommendation is start_fresh, generate a spec first, then run the loop without resume\n- ALWAYS pass issueNumber to assessFeatureState so it can detect work shipped under a different branch name\n- Derive short, stable feature names (2-4 words, kebab-case) from the issue title \u2014 e.g. \"config-module\" not \"config-module-toml-read-write-with-secret-masking\"\n4. After the loop completes (successfully or with failure) \u2014 MANDATORY for EVERY issue, including subsequent ones:\n   a. Call readLoopLog to get the actual log content\n   b. Call assessFeatureState to check the actual state \u2014 do NOT rely solely on loop log output\n   c. **Blocker detection (MANDATORY):** Scan the log for pre-existing test failures (lines like \"All N test failure(s) are pre-existing\"). If found:\n      1. Call listIssues with labels [\"bug\"] to check for existing bug issues covering these failures\n      2. If no existing issue covers them, you MUST call createIssue with title \"Fix N pre-existing test failures\", body listing the failing files, and labels [\"bug\"]. If a \"P0\" label exists on the repo you may add it; if not, just use [\"bug\"].\n      3. Do NOT skip this step just because the loop succeeded \u2014 pre-existing failures degrade CI and must be tracked\n   d. Only close the issue if assessFeatureState confirms a PR was merged (recommendation: \"pr_merged\" or \"linked_pr_merged\")\n   e. When closing: check off acceptance criteria with checkAllBoxes, then close with closeIssue\n   f. If the loop produced code but no PR was created/merged, run the loop again with resume: true to trigger the PR phase\n   g. If the loop failed and code exists on the branch without a PR, this is incomplete work \u2014 do NOT close the issue\n   h. Steps 4\u20136 are MANDATORY after every runLoop \u2014 including the 2nd, 3rd, etc. issue. Do NOT summarize or stop after runLoop returns. The next tool call must be readLoopLog.\n5. Reflect on the outcome:\n   - Call reflectOnWork with structured observations\n   - Use outcome \"skipped\" for issues that were already complete (no real work done) \u2014 these do NOT count against maxItems\n   - Use outcome \"success\"/\"partial\"/\"failure\" for issues where real work was performed\n   - Note what worked, what failed, any patterns discovered\n6. Continue to next issue \u2014 MANDATORY tool call sequence:\n   a. Call listIssues (with NO label filter) to get the full backlog\n   b. Cross-reference with memory to avoid re-doing completed work\n   c. If actionable issues remain and no stop condition is met, immediately call assessFeatureState for the next priority issue \u2014 do NOT generate text\n   d. When assessFeatureState returns, follow the Feature State Decision Tree (step 3d) for that issue \u2014 e.g. start_fresh \u2192 generateSpec \u2192 runLoop. This begins a full new work cycle (steps 3\u20136). Do NOT stop after assessFeatureState.\n   e. Only produce a text-only response (final summary) when the backlog is empty or a stop condition is met\n   f. ANY text without a tool call terminates the session \u2014 there is no \"ask for permission\" step\n\n## Model forwarding\n\nWhen calling generateSpec, ALWAYS forward the model and provider so the spec generation uses the same AI model as this agent session. The values are provided in the Runtime Config section below.\n\nDo NOT forward model/provider to runLoop \u2014 the development loop uses Claude Code internally, which has its own model configuration (opus for planning, sonnet for implementation). Passing a non-Claude model would break the loop.\n\nWhen calling runLoop, pass the reviewMode from the Runtime Config below (if configured). This controls how the loop handles the PR phase:\n- 'manual': stop at PR creation (default)\n- 'auto': create PR + run automated review (no merge)\n- 'merge': create PR + review + merge if approved\n\n## Prioritization\n\nUse hybrid reasoning: respect PM labels (P0 > P1 > P2) but apply your own judgment for ordering within the same priority tier.\n\n**Ordering rules (in priority order):**\n1. PM priority labels: P0 > P1 > P2 > unlabeled\n2. Explicit dependencies: if readIssue returns a `dependsOn` array (parsed from \"depends on #N\" / \"blocked by #N\" in the issue body), complete those issues first\n3. Lower-numbered issues first: within the same priority tier, prefer lower issue numbers \u2014 they are typically more foundational (scaffolding, setup, core infrastructure)\n4. Prefer issues with existing branches: if assessFeatureState shows a branch exists with commits ahead, prefer that issue over one without a branch \u2014 existing branches diverge further from main with every merge, increasing conflict risk\n5. Strategic context from memory and what you learned from previous iterations\n\n## When to stop\n\nStop the loop when:\n- Backlog has no more actionable open issues\n- You've completed the maximum number of items (if configured)\n- A critical failure requires human attention\n- The user has signaled to stop\n\nIMPORTANT: Generating text without tool calls terminates the session immediately. After completing an issue, you MUST call listIssues (step 6) \u2014 never ask \"should I continue?\" or summarize before checking. After assessFeatureState returns for the next issue, you MUST follow the Feature State Decision Tree and call the next tool (e.g. generateSpec for start_fresh). Stopping after assessFeatureState is a bug \u2014 the result tells you what to do next. After runLoop returns, you MUST execute steps 4\u20136 (readLoopLog \u2192 assessFeatureState \u2192 close/comment \u2192 reflectOnWork \u2192 listIssues). Stopping after runLoop is a bug \u2014 there is always post-loop work to do. Your only text-only response is the final summary when ALL issues are processed or a stop condition is met.\n\n## Learning\n\nAfter each issue, always call reflectOnWork. Your memory entries make you progressively better at this specific codebase. Be specific and narrative in what you record. Focus on: what patterns work here, what gotchas exist, which approaches produce better specs and fewer loop iterations.\n\n## Error recovery\n\nIf spec generation fails: retry once with simplified goals. If it fails again, skip the issue and comment explaining why.\nIf a loop fails:\n1. ALWAYS call readLoopLog to get the actual log content\n2. Your issue comment MUST quote or summarize what the log says \u2014 do NOT speculate or guess the cause\n3. Call assessFeatureState to check if a PR was merged despite the loop failure\n4. If assessFeatureState shows \"pr_merged\" or \"linked_pr_merged\" \u2192 close the issue (the work shipped)\n5. If assessFeatureState shows \"resume_pr_phase\" \u2192 the code exists but no PR was created. Run the loop again with resume: true to create and merge the PR. Do NOT close the issue yet.\n6. If the log says \"already complete\" but no PR is merged, the work is stranded on a branch \u2014 resume the loop to ship it\n7. If runLoop returns status \"already_complete\", verify with assessFeatureState before closing\n8. Reflect on what happened, then move to the next issue\nNever close an issue without verifying the code is merged to main. Loop log evidence alone is not sufficient.\n\n## Blocker detection (additional)\n\nBesides the mandatory check in step 4c, also create bug issues for systemic blockers you discover (broken CI, missing infrastructure, flaky tests). Always check with listIssues(labels: [\"bug\"]) before creating to avoid duplicates. After creating blocker issues, continue processing the backlog \u2014 never stop due to blockers alone.";
+export type AgentOrchestrator = ToolLoopAgent<never, any, any>;
+export declare function buildRuntimeConfig(config: AgentConfig): string;
+export declare function buildConstraints(config: AgentConfig): string;
+export declare function createAgentOrchestrator(config: AgentConfig): AgentOrchestrator;

package/dist/agent/orchestrator.js

@@ -0,0 +1,266 @@
+import { MemoryStore } from './memory/store.js';
+import { ingestStrategicDocs } from './memory/ingest.js';
+import { createBacklogTools } from './tools/backlog.js';
+import { createMemoryTools, REFLECT_TOOL_NAME } from './tools/memory.js';
+import { createExecutionTools } from './tools/execution.js';
+import { createReportingTools } from './tools/reporting.js';
+import { createIntrospectionTools } from './tools/introspection.js';
+import { createDryRunExecutionTools, createDryRunReportingTools, createDryRunFeatureStateTools } from './tools/dry-run.js';
+import { createFeatureStateTools } from './tools/feature-state.js';
+import { join } from 'node:path';
+import { logger } from '../utils/logger.js';
+import { getTracedAI } from '../utils/tracing.js';
+export const AGENT_SYSTEM_PROMPT = `You are wiggum's autonomous development agent. You work through the GitHub issue backlog, shipping features one at a time.
+
+## Workflow
+
+1. Read memory to recall previous work and context
+   - Use listStrategicDocs to see available project documentation
+   - Use readStrategicDoc to read full documents relevant to the current task (architecture, design, implementation plans)
+2. List open issues and cross-reference with memory
+   - Consider: PM priority labels (P0 > P1 > P2), dependencies, strategic context
+   - **Housekeeping:** If memory says an issue was already completed (outcome "success" or "skipped") but it's still open:
+     1. Call assessFeatureState with the featureName and issueNumber
+     2. If recommendation is "pr_merged" or "linked_pr_merged": close it with closeIssue. Reflect with outcome "skipped". Does NOT count against maxItems.
+     3. If recommendation is anything else (e.g., "resume_implementation", "start_fresh", "resume_pr_phase"): the issue was NOT actually shipped. Do NOT close it. Instead, prioritize it as your next work item and follow the Feature State Decision Tree. This counts against maxItems.
+   - **Retry:** If memory records a previous attempt at an issue with outcome "failure" or "partial", and it's still open, prioritize it over new issues. Bugs that caused the failure may have been fixed, and existing work (branch, spec, plan) should not be abandoned. Call assessFeatureState to determine the right action — usually resume_implementation. This counts against maxItems.
+3. For the chosen issue (one NOT already completed):
+   a. Read the full issue details
+   b. Derive a featureName from the issue title (lowercase, hyphens, no spaces)
+   c. **Assess feature state** using assessFeatureState — MANDATORY before any action
+   d. Follow the Feature State Decision Tree based on the recommendation field
+   e. Monitor progress with checkLoopStatus and readLoopLog
+   f. Report results by commenting on the issue
+
+## Feature State Decision Tree
+
+After calling assessFeatureState, follow the recommendation:
+
+| recommendation | action |
+|---|---|
+| start_fresh | generateSpec → runLoop (fresh) |
+| generate_plan | runLoop without resume (spec exists, needs planning) |
+| resume_implementation | runLoop with resume: true (plan has pending tasks) |
+| resume_pr_phase | runLoop with resume: true (all tasks done, needs PR) |
+| pr_exists_open | Comment on issue, do NOT re-run loop |
+| pr_merged | Verify PR is merged, close issue with closeIssue, reflect with outcome "skipped", move on |
+| pr_closed | Decide: restart from scratch or skip |
+| linked_pr_merged | Verify the linked PR is merged, close issue with closeIssue (comment "shipped via PR #N"), reflect with outcome "skipped", move on |
+| linked_pr_open | Work in progress under a different branch — comment "in progress via PR #N", do NOT re-run loop |
+
+**Critical:**
+- When recommendation is resume_implementation or resume_pr_phase, you MUST pass resume: true to runLoop
+- When recommendation is generate_plan, do NOT pass resume (fresh branch needed)
+- When recommendation is start_fresh, generate a spec first, then run the loop without resume
+- ALWAYS pass issueNumber to assessFeatureState so it can detect work shipped under a different branch name
+- Derive short, stable feature names (2-4 words, kebab-case) from the issue title — e.g. "config-module" not "config-module-toml-read-write-with-secret-masking"
+4. After the loop completes (successfully or with failure) — MANDATORY for EVERY issue, including subsequent ones:
+   a. Call readLoopLog to get the actual log content
+   b. Call assessFeatureState to check the actual state — do NOT rely solely on loop log output
+   c. **Blocker detection (MANDATORY):** Scan the log for pre-existing test failures (lines like "All N test failure(s) are pre-existing"). If found:
+      1. Call listIssues with labels ["bug"] to check for existing bug issues covering these failures
+      2. If no existing issue covers them, you MUST call createIssue with title "Fix N pre-existing test failures", body listing the failing files, and labels ["bug"]. If a "P0" label exists on the repo you may add it; if not, just use ["bug"].
+      3. Do NOT skip this step just because the loop succeeded — pre-existing failures degrade CI and must be tracked
+   d. Only close the issue if assessFeatureState confirms a PR was merged (recommendation: "pr_merged" or "linked_pr_merged")
+   e. When closing: check off acceptance criteria with checkAllBoxes, then close with closeIssue
+   f. If the loop produced code but no PR was created/merged, run the loop again with resume: true to trigger the PR phase
+   g. If the loop failed and code exists on the branch without a PR, this is incomplete work — do NOT close the issue
+   h. Steps 4–6 are MANDATORY after every runLoop — including the 2nd, 3rd, etc. issue. Do NOT summarize or stop after runLoop returns. The next tool call must be readLoopLog.
+5. Reflect on the outcome:
+   - Call reflectOnWork with structured observations
+   - Use outcome "skipped" for issues that were already complete (no real work done) — these do NOT count against maxItems
+   - Use outcome "success"/"partial"/"failure" for issues where real work was performed
+   - Note what worked, what failed, any patterns discovered
+6. Continue to next issue — MANDATORY tool call sequence:
+   a. Call listIssues (with NO label filter) to get the full backlog
+   b. Cross-reference with memory to avoid re-doing completed work
+   c. If actionable issues remain and no stop condition is met, immediately call assessFeatureState for the next priority issue — do NOT generate text
+   d. When assessFeatureState returns, follow the Feature State Decision Tree (step 3d) for that issue — e.g. start_fresh → generateSpec → runLoop. This begins a full new work cycle (steps 3–6). Do NOT stop after assessFeatureState.
+   e. Only produce a text-only response (final summary) when the backlog is empty or a stop condition is met
+   f. ANY text without a tool call terminates the session — there is no "ask for permission" step
+
+## Model forwarding
+
+When calling generateSpec, ALWAYS forward the model and provider so the spec generation uses the same AI model as this agent session. The values are provided in the Runtime Config section below.
+
+Do NOT forward model/provider to runLoop — the development loop uses Claude Code internally, which has its own model configuration (opus for planning, sonnet for implementation). Passing a non-Claude model would break the loop.
+
+When calling runLoop, pass the reviewMode from the Runtime Config below (if configured). This controls how the loop handles the PR phase:
+- 'manual': stop at PR creation (default)
+- 'auto': create PR + run automated review (no merge)
+- 'merge': create PR + review + merge if approved
+
+## Prioritization
+
+Use hybrid reasoning: respect PM labels (P0 > P1 > P2) but apply your own judgment for ordering within the same priority tier.
+
+**Ordering rules (in priority order):**
+1. PM priority labels: P0 > P1 > P2 > unlabeled
+2. Explicit dependencies: if readIssue returns a \`dependsOn\` array (parsed from "depends on #N" / "blocked by #N" in the issue body), complete those issues first
+3. Lower-numbered issues first: within the same priority tier, prefer lower issue numbers — they are typically more foundational (scaffolding, setup, core infrastructure)
+4. Prefer issues with existing branches: if assessFeatureState shows a branch exists with commits ahead, prefer that issue over one without a branch — existing branches diverge further from main with every merge, increasing conflict risk
+5. Strategic context from memory and what you learned from previous iterations
+
+## When to stop
+
+Stop the loop when:
+- Backlog has no more actionable open issues
+- You've completed the maximum number of items (if configured)
+- A critical failure requires human attention
+- The user has signaled to stop
+
+IMPORTANT: Generating text without tool calls terminates the session immediately. After completing an issue, you MUST call listIssues (step 6) — never ask "should I continue?" or summarize before checking. After assessFeatureState returns for the next issue, you MUST follow the Feature State Decision Tree and call the next tool (e.g. generateSpec for start_fresh). Stopping after assessFeatureState is a bug — the result tells you what to do next. After runLoop returns, you MUST execute steps 4–6 (readLoopLog → assessFeatureState → close/comment → reflectOnWork → listIssues). Stopping after runLoop is a bug — there is always post-loop work to do. Your only text-only response is the final summary when ALL issues are processed or a stop condition is met.
+
+## Learning
+
+After each issue, always call reflectOnWork. Your memory entries make you progressively better at this specific codebase. Be specific and narrative in what you record. Focus on: what patterns work here, what gotchas exist, which approaches produce better specs and fewer loop iterations.
+
+## Error recovery
+
+If spec generation fails: retry once with simplified goals. If it fails again, skip the issue and comment explaining why.
+If a loop fails:
+1. ALWAYS call readLoopLog to get the actual log content
+2. Your issue comment MUST quote or summarize what the log says — do NOT speculate or guess the cause
+3. Call assessFeatureState to check if a PR was merged despite the loop failure
+4. If assessFeatureState shows "pr_merged" or "linked_pr_merged" → close the issue (the work shipped)
+5. If assessFeatureState shows "resume_pr_phase" → the code exists but no PR was created. Run the loop again with resume: true to create and merge the PR. Do NOT close the issue yet.
+6. If the log says "already complete" but no PR is merged, the work is stranded on a branch — resume the loop to ship it
+7. If runLoop returns status "already_complete", verify with assessFeatureState before closing
+8. Reflect on what happened, then move to the next issue
+Never close an issue without verifying the code is merged to main. Loop log evidence alone is not sufficient.
+
+## Blocker detection (additional)
+
+Besides the mandatory check in step 4c, also create bug issues for systemic blockers you discover (broken CI, missing infrastructure, flaky tests). Always check with listIssues(labels: ["bug"]) before creating to avoid duplicates. After creating blocker issues, continue processing the backlog — never stop due to blockers alone.`;
+export function buildRuntimeConfig(config) {
+    const lines = [];
+    if (config.modelId)
+        lines.push(`- model: ${config.modelId}`);
+    if (config.provider)
+        lines.push(`- provider: ${config.provider}`);
+    if (config.reviewMode)
+        lines.push(`- reviewMode: ${config.reviewMode}`);
+    return lines.length > 0
+        ? `\n\n## Runtime Config\n\n${lines.join('\n')}`
+        : '';
+}
+export function buildConstraints(config) {
+    const lines = [];
+    if (config.maxItems != null) {
+        lines.push(`- You MUST stop after completing ${config.maxItems} issue(s). Call reflectOnWork for each, then stop.`);
+    }
+    if (config.labels?.length) {
+        lines.push(`- Only work on issues with these labels: ${config.labels.join(', ')}. Ignore all others.`);
+    }
+    if (config.dryRun) {
+        lines.push('- DRY RUN MODE: Plan what you would do but do NOT execute. Execution and reporting tools return simulated results.');
+    }
+    return lines.length > 0
+        ? `\n\n## Constraints\n\n${lines.join('\n')}`
+        : '';
+}
+export function createAgentOrchestrator(config) {
+    const { model, projectRoot, owner, repo } = config;
+    const memoryDir = join(projectRoot, '.ralph', 'agent');
+    const store = new MemoryStore(memoryDir);
+    const backlog = createBacklogTools(owner, repo, {
+        defaultLabels: config.labels,
+    });
+    const memory = createMemoryTools(store, projectRoot);
+    const execution = config.dryRun
+        ? createDryRunExecutionTools()
+        : createExecutionTools(projectRoot, { onProgress: config.onProgress });
+    const reporting = config.dryRun
+        ? createDryRunReportingTools()
+        : createReportingTools(owner, repo);
+    const introspection = createIntrospectionTools(projectRoot);
+    const featureState = config.dryRun
+        ? createDryRunFeatureStateTools()
+        : createFeatureStateTools(projectRoot);
+    const tools = {
+        ...backlog,
+        ...memory,
+        ...execution,
+        ...reporting,
+        ...introspection,
+        ...featureState,
+    };
+    const constraints = buildConstraints(config);
+    const runtimeConfig = buildRuntimeConfig(config);
+    const fullPrompt = AGENT_SYSTEM_PROMPT + runtimeConfig + constraints;
+    const completedIssues = new Set();
+    const maxSteps = config.maxSteps ?? 200;
+    // Use traced ToolLoopAgent so Braintrust automatically captures
+    // all LLM calls, tool executions, and agent steps.
+    const { ToolLoopAgent: TracedToolLoopAgent } = getTracedAI();
+    return new TracedToolLoopAgent({
+        model,
+        instructions: fullPrompt,
+        tools,
+        experimental_telemetry: {
+            isEnabled: true,
+            functionId: 'agent-orchestrator',
+            metadata: { owner, repo, dryRun: String(config.dryRun ?? false) },
+        },
+        stopWhen: ({ steps }) => {
+            if (steps.length >= maxSteps)
+                return true;
+            if (config.maxItems != null && completedIssues.size >= config.maxItems)
+                return true;
+            return false;
+        },
+        prepareStep: async ({ steps }) => {
+            try {
+                if (steps.length === 0) {
+                    await ingestStrategicDocs(projectRoot, store);
+                    await store.prune();
+                }
+                const all = await store.read({ limit: 50 });
+                const recentLogs = all.filter(e => e.type === 'work_log').slice(0, 5);
+                const knowledge = all.filter(e => e.type === 'project_knowledge').slice(0, 3);
+                const decisions = all.filter(e => e.type === 'decision').slice(0, 2);
+                // Strategic docs are injected as lightweight catalog entries (filename + summary).
+                // The agent reads full content on-demand via readStrategicDoc tool.
+                const strategic = all.filter(e => e.type === 'strategic_context');
+                const memoryContext = [
+                    ...recentLogs.map(e => `[work] ${e.content}`),
+                    ...knowledge.map(e => `[knowledge] ${e.content}`),
+                    ...decisions.map(e => `[decision] ${e.content}`),
+                    ...strategic.map(e => `[strategic-doc] ${e.content}`),
+                ].join('\n');
+                if (!memoryContext)
+                    return undefined;
+                return {
+                    system: [
+                        fullPrompt,
+                        `## Current Memory\n\n${memoryContext}`,
+                    ].join('\n\n'),
+                };
+            }
+            catch (err) {
+                logger.warn(`prepareStep failed, continuing without memory: ${err instanceof Error ? err.message : String(err)}`);
+                return undefined;
+            }
+        },
+        onStepFinish: async ({ toolCalls, toolResults }) => {
+            try {
+                for (const tc of toolCalls) {
+                    if (tc.toolName === REFLECT_TOOL_NAME) {
+                        const input = tc.input;
+                        if (input.issueNumber != null && input.outcome !== 'skipped') {
+                            completedIssues.add(input.issueNumber);
+                        }
+                    }
+                }
+                config.onStepUpdate?.({
+                    toolCalls: toolCalls.map((tc) => ({ toolName: tc.toolName, args: tc.input })),
+                    toolResults: toolResults.map((tr) => ({ toolName: tr.toolName, result: tr.output })),
+                    completedItems: completedIssues.size,
+                });
+            }
+            catch (err) {
+                logger.warn(`onStepFinish failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        },
+    });
+}

package/dist/agent/resolve-config.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared agent environment resolution
+ *
+ * Extracts provider, model, and GitHub remote detection into a reusable
+ * function that **throws** on error (no process.exit). Used by both the
+ * headless agent command and the TUI AgentScreen.
+ */
+import type { LanguageModel } from 'ai';
+import type { AIProvider } from '../ai/providers.js';
+import type { ReviewMode } from './types.js';
+export interface ResolvedAgentEnv {
+    provider: AIProvider;
+    model: LanguageModel;
+    modelId: string | undefined;
+    owner: string;
+    repo: string;
+    projectRoot: string;
+    reviewMode?: ReviewMode;
+}
+/**
+ * Resolve provider, model, and GitHub remote for agent execution.
+ * Throws descriptive errors instead of calling process.exit.
+ */
+export declare function resolveAgentEnv(projectRoot: string, options?: {
+    model?: string;
+}): Promise<ResolvedAgentEnv>;

package/dist/agent/resolve-config.js

@@ -0,0 +1,43 @@
+/**
+ * Shared agent environment resolution
+ *
+ * Extracts provider, model, and GitHub remote detection into a reusable
+ * function that **throws** on error (no process.exit). Used by both the
+ * headless agent command and the TUI AgentScreen.
+ */
+import { getAvailableProvider, getModel, } from '../ai/providers.js';
+import { detectGitHubRemote } from '../utils/github.js';
+import { loadConfigWithDefaults } from '../utils/config.js';
+const VALID_PROVIDERS = new Set(['anthropic', 'openai', 'openrouter']);
+/**
+ * Resolve provider, model, and GitHub remote for agent execution.
+ * Throws descriptive errors instead of calling process.exit.
+ */
+export async function resolveAgentEnv(projectRoot, options) {
+    // 1. Resolve provider (config > env detection)
+    const ralphConfig = await loadConfigWithDefaults(projectRoot);
+    const configProvider = ralphConfig.agent.defaultProvider;
+    const validConfigProvider = VALID_PROVIDERS.has(configProvider)
+        ? configProvider
+        : null;
+    const provider = validConfigProvider || getAvailableProvider();
+    if (!provider) {
+        throw new Error('No AI provider configured. Run `wiggum init` or set ANTHROPIC_API_KEY, OPENAI_API_KEY, or OPENROUTER_API_KEY.');
+    }
+    // 2. Detect GitHub remote
+    const remote = await detectGitHubRemote(projectRoot);
+    if (!remote) {
+        throw new Error('No GitHub remote detected. Run from a repo with a GitHub origin.');
+    }
+    // 3. Resolve model (CLI flag > config > provider default)
+    const modelId = options?.model || ralphConfig.agent.defaultModel || undefined;
+    const { model } = getModel(provider, modelId);
+    return {
+        provider,
+        model,
+        modelId,
+        owner: remote.owner,
+        repo: remote.repo,
+        projectRoot,
+    };
+}

package/dist/agent/tools/backlog.d.ts

@@ -0,0 +1,27 @@
+export interface BacklogToolsOptions {
+    defaultLabels?: string[];
+}
+export declare function createBacklogTools(owner: string, repo: string, options?: BacklogToolsOptions): {
+    listIssues: import("ai").Tool<{
+        limit: number;
+        labels?: string[] | undefined;
+        milestone?: string | undefined;
+    }, {
+        issues: never[];
+        error: string;
+    } | {
+        issues: import("../../utils/github.js").GitHubIssueListItem[];
+        error?: undefined;
+    }>;
+    readIssue: import("ai").Tool<{
+        issueNumber: number;
+    }, {
+        error: string;
+    } | {
+        dependsOn: number[];
+        title: string;
+        body: string;
+        labels: string[];
+        error?: undefined;
+    }>;
+};