@kody-ade/engine 0.1.0

package/dist/learning/auto-learn.js

@@ -0,0 +1,169 @@
+import * as fs from "fs";
+import * as path from "path";
+import { logger } from "../logger.js";
+function stripAnsi(str) {
+    return str.replace(/\x1b\[[0-9;]*m/g, "");
+}
+export function autoLearn(ctx) {
+    try {
+        const memoryDir = path.join(ctx.projectDir, ".kody", "memory");
+        if (!fs.existsSync(memoryDir)) {
+            fs.mkdirSync(memoryDir, { recursive: true });
+        }
+        const learnings = [];
+        const timestamp = new Date().toISOString().slice(0, 10);
+        // Extract from verify.md (strip ANSI codes first)
+        const verifyPath = path.join(ctx.taskDir, "verify.md");
+        if (fs.existsSync(verifyPath)) {
+            const verify = stripAnsi(fs.readFileSync(verifyPath, "utf-8"));
+            if (/vitest/i.test(verify))
+                learnings.push("- Uses vitest for testing");
+            if (/jest/i.test(verify))
+                learnings.push("- Uses jest for testing");
+            if (/eslint/i.test(verify))
+                learnings.push("- Uses eslint for linting");
+            if (/prettier/i.test(verify))
+                learnings.push("- Uses prettier for formatting");
+            if (/tsc\b/i.test(verify))
+                learnings.push("- Uses TypeScript (tsc)");
+            if (/jsdom/i.test(verify))
+                learnings.push("- Test environment: jsdom");
+            if (/node/i.test(verify) && /environment/i.test(verify))
+                learnings.push("- Test environment: node");
+        }
+        // Extract from review.md
+        const reviewPath = path.join(ctx.taskDir, "review.md");
+        if (fs.existsSync(reviewPath)) {
+            const review = fs.readFileSync(reviewPath, "utf-8");
+            if (/\.js extension/i.test(review))
+                learnings.push("- Imports use .js extensions (ESM)");
+            if (/barrel export/i.test(review))
+                learnings.push("- Uses barrel exports (index.ts)");
+            if (/timezone/i.test(review))
+                learnings.push("- Timezone handling is a concern in this codebase");
+            if (/UTC/i.test(review))
+                learnings.push("- Date operations should consider UTC vs local time");
+        }
+        // Extract from task.json
+        const taskJsonPath = path.join(ctx.taskDir, "task.json");
+        if (fs.existsSync(taskJsonPath)) {
+            try {
+                const raw = stripAnsi(fs.readFileSync(taskJsonPath, "utf-8"));
+                const cleaned = raw.replace(/^```json\s*\n?/m, "").replace(/\n?```\s*$/m, "");
+                const task = JSON.parse(cleaned);
+                if (task.scope && Array.isArray(task.scope)) {
+                    const dirs = [...new Set(task.scope.map((s) => s.split("/").slice(0, -1).join("/")).filter(Boolean))];
+                    if (dirs.length > 0)
+                        learnings.push(`- Active directories: ${dirs.join(", ")}`);
+                }
+            }
+            catch {
+                // Ignore
+            }
+        }
+        if (learnings.length > 0) {
+            const conventionsPath = path.join(memoryDir, "conventions.md");
+            const entry = `\n## Learned ${timestamp} (task: ${ctx.taskId})\n${learnings.join("\n")}\n`;
+            fs.appendFileSync(conventionsPath, entry);
+            logger.info(`Auto-learned ${learnings.length} convention(s)`);
+        }
+        // Auto-detect architecture
+        autoLearnArchitecture(ctx.projectDir, memoryDir, timestamp);
+    }
+    catch {
+        // Auto-learn is best-effort — don't fail the pipeline
+    }
+}
+function autoLearnArchitecture(projectDir, memoryDir, timestamp) {
+    const archPath = path.join(memoryDir, "architecture.md");
+    // Only auto-detect if architecture.md doesn't exist yet
+    if (fs.existsSync(archPath))
+        return;
+    const detected = [];
+    // Detect framework from package.json
+    const pkgPath = path.join(projectDir, "package.json");
+    if (fs.existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+            const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+            // Frameworks
+            if (allDeps.next)
+                detected.push(`- Framework: Next.js ${allDeps.next}`);
+            else if (allDeps.react)
+                detected.push(`- Framework: React ${allDeps.react}`);
+            else if (allDeps.express)
+                detected.push(`- Framework: Express ${allDeps.express}`);
+            else if (allDeps.fastify)
+                detected.push(`- Framework: Fastify ${allDeps.fastify}`);
+            // Language
+            if (allDeps.typescript)
+                detected.push(`- Language: TypeScript ${allDeps.typescript}`);
+            // Testing
+            if (allDeps.vitest)
+                detected.push(`- Testing: vitest ${allDeps.vitest}`);
+            else if (allDeps.jest)
+                detected.push(`- Testing: jest ${allDeps.jest}`);
+            // Linting
+            if (allDeps.eslint)
+                detected.push(`- Linting: eslint ${allDeps.eslint}`);
+            // Database
+            if (allDeps.prisma || allDeps["@prisma/client"])
+                detected.push("- Database: Prisma ORM");
+            if (allDeps.drizzle || allDeps["drizzle-orm"])
+                detected.push("- Database: Drizzle ORM");
+            if (allDeps.pg || allDeps.postgres)
+                detected.push("- Database: PostgreSQL");
+            // CMS
+            if (allDeps.payload || allDeps["@payloadcms/next"])
+                detected.push(`- CMS: Payload CMS`);
+            // Module type
+            if (pkg.type === "module")
+                detected.push("- Module system: ESM");
+            else
+                detected.push("- Module system: CommonJS");
+            // Package manager
+            if (fs.existsSync(path.join(projectDir, "pnpm-lock.yaml")))
+                detected.push("- Package manager: pnpm");
+            else if (fs.existsSync(path.join(projectDir, "yarn.lock")))
+                detected.push("- Package manager: yarn");
+            else if (fs.existsSync(path.join(projectDir, "package-lock.json")))
+                detected.push("- Package manager: npm");
+        }
+        catch {
+            // Ignore parse errors
+        }
+    }
+    // Detect directory structure
+    const topDirs = [];
+    try {
+        const entries = fs.readdirSync(projectDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules") {
+                topDirs.push(entry.name);
+            }
+        }
+        if (topDirs.length > 0)
+            detected.push(`- Top-level directories: ${topDirs.join(", ")}`);
+    }
+    catch {
+        // Ignore
+    }
+    // Detect src structure
+    const srcDir = path.join(projectDir, "src");
+    if (fs.existsSync(srcDir)) {
+        try {
+            const srcEntries = fs.readdirSync(srcDir, { withFileTypes: true });
+            const srcDirs = srcEntries.filter((e) => e.isDirectory()).map((e) => e.name);
+            if (srcDirs.length > 0)
+                detected.push(`- src/ structure: ${srcDirs.join(", ")}`);
+        }
+        catch {
+            // Ignore
+        }
+    }
+    if (detected.length > 0) {
+        const content = `# Architecture (auto-detected ${timestamp})\n\n## Overview\n${detected.join("\n")}\n`;
+        fs.writeFileSync(archPath, content);
+        logger.info(`Auto-detected architecture (${detected.length} items)`);
+    }
+}

package/dist/logger.d.ts

@@ -0,0 +1,14 @@
+export declare const logger: {
+    debug: (msg: string) => void;
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+};
+export declare function createStageLogger(stage: string, taskId?: string): {
+    debug: (msg: string) => void;
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+};
+export declare function ciGroup(title: string): void;
+export declare function ciGroupEnd(): void;

package/dist/logger.js

@@ -0,0 +1,51 @@
+const isCI = !!process.env.GITHUB_ACTIONS;
+const LEVELS = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+function getLevel() {
+    const env = process.env.LOG_LEVEL;
+    return LEVELS[env ?? "info"] ?? LEVELS.info;
+}
+function timestamp() {
+    return new Date().toISOString().slice(11, 19);
+}
+function log(level, msg) {
+    if (LEVELS[level] < getLevel())
+        return;
+    const prefix = `[${timestamp()}] ${level.toUpperCase().padEnd(5)}`;
+    if (level === "error") {
+        console.error(`${prefix} ${msg}`);
+    }
+    else if (level === "warn") {
+        console.warn(`${prefix} ${msg}`);
+    }
+    else {
+        console.log(`${prefix} ${msg}`);
+    }
+}
+export const logger = {
+    debug: (msg) => log("debug", msg),
+    info: (msg) => log("info", msg),
+    warn: (msg) => log("warn", msg),
+    error: (msg) => log("error", msg),
+};
+export function createStageLogger(stage, taskId) {
+    const prefix = taskId ? `[${stage}:${taskId}]` : `[${stage}]`;
+    return {
+        debug: (msg) => logger.debug(`${prefix} ${msg}`),
+        info: (msg) => logger.info(`${prefix} ${msg}`),
+        warn: (msg) => logger.warn(`${prefix} ${msg}`),
+        error: (msg) => logger.error(`${prefix} ${msg}`),
+    };
+}
+export function ciGroup(title) {
+    if (isCI)
+        process.stdout.write(`::group::${title}\n`);
+}
+export function ciGroupEnd() {
+    if (isCI)
+        process.stdout.write(`::endgroup::\n`);
+}

package/dist/memory.d.ts

@@ -0,0 +1 @@
+export declare function readProjectMemory(projectDir: string): string;

package/dist/memory.js

@@ -0,0 +1,20 @@
+import * as fs from "fs";
+import * as path from "path";
+export function readProjectMemory(projectDir) {
+    const memoryDir = path.join(projectDir, ".kody", "memory");
+    if (!fs.existsSync(memoryDir))
+        return "";
+    const files = fs.readdirSync(memoryDir).filter((f) => f.endsWith(".md")).sort();
+    if (files.length === 0)
+        return "";
+    const sections = [];
+    for (const file of files) {
+        const content = fs.readFileSync(path.join(memoryDir, file), "utf-8").trim();
+        if (content) {
+            sections.push(`## ${file.replace(".md", "")}\n${content}`);
+        }
+    }
+    if (sections.length === 0)
+        return "";
+    return `# Project Memory\n\n${sections.join("\n\n")}\n`;
+}

package/dist/observer.d.ts

@@ -0,0 +1,9 @@
+import type { AgentRunner } from "./types.js";
+export type FailureClassification = "fixable" | "infrastructure" | "pre-existing" | "retry" | "abort";
+export interface DiagnosisResult {
+    classification: FailureClassification;
+    reason: string;
+    resolution: string;
+}
+export declare function diagnoseFailure(stageName: string, errorOutput: string, modifiedFiles: string[], runner: AgentRunner, model: string): Promise<DiagnosisResult>;
+export declare function getModifiedFiles(projectDir: string): string[];

package/dist/observer.js

@@ -0,0 +1,80 @@
+import { execFileSync } from "child_process";
+import { logger } from "./logger.js";
+const DIAGNOSIS_PROMPT = `You are a pipeline failure diagnosis agent. Analyze the error and classify it.
+
+Output ONLY valid JSON. No markdown fences. No explanation.
+
+{
+  "classification": "fixable | infrastructure | pre-existing | retry | abort",
+  "reason": "One sentence explaining what went wrong",
+  "resolution": "Specific instructions for fixing (if fixable) or what the user needs to do (if infrastructure)"
+}
+
+Classification rules:
+- fixable: Error is in code that was just written/modified. The resolution should describe exactly what to change.
+- infrastructure: External dependency not available (database, API, service). The resolution should say what the user needs to set up.
+- pre-existing: Error exists in code that was NOT modified. Safe to skip. The resolution should note which files.
+- retry: Transient error (network timeout, rate limit, flaky test). Worth retrying once.
+- abort: Unrecoverable error (permission denied, corrupted state, out of disk). Pipeline should stop.
+
+Error context:
+`;
+export async function diagnoseFailure(stageName, errorOutput, modifiedFiles, runner, model) {
+    const context = [
+        `Stage: ${stageName}`,
+        ``,
+        `Error output:`,
+        errorOutput.slice(-2000), // Last 2000 chars of error
+        ``,
+        modifiedFiles.length > 0
+            ? `Files modified by build stage:\n${modifiedFiles.map((f) => `- ${f}`).join("\n")}`
+            : "No files were modified (build may not have run yet).",
+    ].join("\n");
+    const prompt = DIAGNOSIS_PROMPT + context;
+    try {
+        const result = await runner.run("diagnosis", prompt, model, 30_000, // 30s timeout — this should be fast
+        "");
+        if (result.outcome === "completed" && result.output) {
+            const cleaned = result.output
+                .replace(/^```json\s*\n?/m, "")
+                .replace(/\n?```\s*$/m, "")
+                .trim();
+            const parsed = JSON.parse(cleaned);
+            const validClassifications = [
+                "fixable", "infrastructure", "pre-existing", "retry", "abort",
+            ];
+            if (validClassifications.includes(parsed.classification)) {
+                logger.info(`  Diagnosis: ${parsed.classification} — ${parsed.reason}`);
+                return {
+                    classification: parsed.classification,
+                    reason: parsed.reason ?? "Unknown reason",
+                    resolution: parsed.resolution ?? "",
+                };
+            }
+        }
+    }
+    catch (err) {
+        logger.warn(`  Diagnosis error: ${err instanceof Error ? err.message : err}`);
+    }
+    // Default: assume fixable (safest — will attempt autofix)
+    logger.warn("  Diagnosis failed — defaulting to fixable");
+    return {
+        classification: "fixable",
+        reason: "Could not diagnose failure",
+        resolution: errorOutput.slice(-500),
+    };
+}
+export function getModifiedFiles(projectDir) {
+    try {
+        const output = execFileSync("git", ["diff", "--name-only", "HEAD~1"], {
+            encoding: "utf-8",
+            cwd: projectDir,
+            timeout: 5000,
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim();
+        return output ? output.split("\n").filter(Boolean) : [];
+    }
+    catch {
+        return [];
+    }
+}

package/dist/pipeline/complexity.d.ts

@@ -0,0 +1,3 @@
+import type { StageDefinition } from "../types.js";
+export declare function filterByComplexity(stages: StageDefinition[], complexity: string): StageDefinition[];
+export declare function isValidComplexity(value: string): boolean;

package/dist/pipeline/complexity.js

@@ -0,0 +1,12 @@
+const COMPLEXITY_SKIP = {
+    low: ["plan", "review", "review-fix"],
+    medium: ["review-fix"],
+    high: [],
+};
+export function filterByComplexity(stages, complexity) {
+    const skip = COMPLEXITY_SKIP[complexity] ?? [];
+    return stages.filter((s) => !skip.includes(s.name));
+}
+export function isValidComplexity(value) {
+    return value in COMPLEXITY_SKIP;
+}

package/dist/pipeline/executor-registry.d.ts

@@ -0,0 +1,3 @@
+import type { StageName, StageDefinition, StageResult, PipelineContext } from "../types.js";
+export type StageExecutor = (ctx: PipelineContext, def: StageDefinition) => StageResult | Promise<StageResult>;
+export declare function getExecutor(name: StageName): StageExecutor;

package/dist/pipeline/executor-registry.js

@@ -0,0 +1,20 @@
+import { executeAgentStage } from "../stages/agent.js";
+import { executeVerifyWithAutofix } from "../stages/verify.js";
+import { executeReviewWithFix } from "../stages/review.js";
+import { executeShipStage } from "../stages/ship.js";
+const EXECUTOR_REGISTRY = {
+    taskify: executeAgentStage,
+    plan: executeAgentStage,
+    build: executeAgentStage,
+    verify: executeVerifyWithAutofix,
+    review: executeReviewWithFix,
+    "review-fix": executeAgentStage,
+    ship: executeShipStage,
+};
+export function getExecutor(name) {
+    const executor = EXECUTOR_REGISTRY[name];
+    if (!executor) {
+        throw new Error(`No executor registered for stage: ${name}`);
+    }
+    return executor;
+}

package/dist/pipeline/hooks.d.ts

@@ -0,0 +1,17 @@
+import type { StageDefinition, PipelineStatus, PipelineContext } from "../types.js";
+export declare function applyPreStageLabel(ctx: PipelineContext, def: StageDefinition): void;
+/**
+ * Check for clarifying questions after taskify/plan.
+ * Returns the paused PipelineStatus if pipeline should stop, null to continue.
+ */
+export declare function checkQuestionsAfterStage(ctx: PipelineContext, def: StageDefinition, state: PipelineStatus): PipelineStatus | null;
+/**
+ * Auto-detect complexity from task.json after taskify.
+ * Returns new complexity + activeStages if detected, null otherwise.
+ */
+export declare function autoDetectComplexity(ctx: PipelineContext, def: StageDefinition): {
+    complexity: "low" | "medium" | "high";
+    activeStages: StageDefinition[];
+} | null;
+export declare function commitAfterStage(ctx: PipelineContext, def: StageDefinition): void;
+export declare function postSkippedStagesComment(ctx: PipelineContext, complexity: string, activeStages: StageDefinition[]): void;

package/dist/pipeline/hooks.js

@@ -0,0 +1,110 @@
+import * as fs from "fs";
+import * as path from "path";
+import { STAGES } from "../definitions.js";
+import { setLifecycleLabel, setLabel, postComment } from "../github-api.js";
+import { commitAll } from "../git-utils.js";
+import { checkForQuestions } from "./questions.js";
+import { filterByComplexity, isValidComplexity } from "./complexity.js";
+import { writeState } from "./state.js";
+import { logger } from "../logger.js";
+// ─── Pre-stage ──────────────────────────────────────────────────────────────
+export function applyPreStageLabel(ctx, def) {
+    if (!ctx.input.issueNumber || ctx.input.local)
+        return;
+    if (def.name === "build")
+        setLifecycleLabel(ctx.input.issueNumber, "building");
+    if (def.name === "review")
+        setLifecycleLabel(ctx.input.issueNumber, "review");
+}
+// ─── Post-stage (success) ───────────────────────────────────────────────────
+/**
+ * Check for clarifying questions after taskify/plan.
+ * Returns the paused PipelineStatus if pipeline should stop, null to continue.
+ */
+export function checkQuestionsAfterStage(ctx, def, state) {
+    if (def.name !== "taskify" && def.name !== "plan")
+        return null;
+    if (ctx.input.dryRun)
+        return null;
+    const paused = checkForQuestions(ctx, def.name);
+    if (!paused)
+        return null;
+    state.state = "failed";
+    state.stages[def.name] = {
+        ...state.stages[def.name],
+        state: "completed",
+        error: "paused: waiting for answers",
+    };
+    writeState(state, ctx.taskDir);
+    logger.info(`  Pipeline paused — questions posted on issue`);
+    return state;
+}
+/**
+ * Auto-detect complexity from task.json after taskify.
+ * Returns new complexity + activeStages if detected, null otherwise.
+ */
+export function autoDetectComplexity(ctx, def) {
+    if (def.name !== "taskify")
+        return null;
+    if (ctx.input.complexity)
+        return null;
+    try {
+        const taskJsonPath = path.join(ctx.taskDir, "task.json");
+        if (!fs.existsSync(taskJsonPath))
+            return null;
+        const raw = fs.readFileSync(taskJsonPath, "utf-8");
+        const cleaned = raw.replace(/^```json\s*\n?/m, "").replace(/\n?```\s*$/m, "");
+        const taskJson = JSON.parse(cleaned);
+        if (!taskJson.risk_level || !isValidComplexity(taskJson.risk_level))
+            return null;
+        const complexity = taskJson.risk_level;
+        const activeStages = filterByComplexity(STAGES, complexity);
+        logger.info(`  Complexity auto-detected: ${complexity} (${activeStages.map(s => s.name).join(" → ")})`);
+        if (ctx.input.issueNumber && !ctx.input.local) {
+            try {
+                setLifecycleLabel(ctx.input.issueNumber, complexity);
+            }
+            catch { /* ignore */ }
+            if (taskJson.task_type) {
+                try {
+                    setLabel(ctx.input.issueNumber, `kody:${taskJson.task_type}`);
+                }
+                catch { /* ignore */ }
+            }
+        }
+        return { complexity, activeStages };
+    }
+    catch {
+        return null;
+    }
+}
+export function commitAfterStage(ctx, def) {
+    if (ctx.input.dryRun || !ctx.input.issueNumber)
+        return;
+    if (def.name === "build") {
+        try {
+            commitAll(`feat(${ctx.taskId}): implement task`, ctx.projectDir);
+        }
+        catch { /* ignore */ }
+    }
+    if (def.name === "review-fix") {
+        try {
+            commitAll(`fix(${ctx.taskId}): address review`, ctx.projectDir);
+        }
+        catch { /* ignore */ }
+    }
+}
+// ─── Skip logic ─────────────────────────────────────────────────────────────
+export function postSkippedStagesComment(ctx, complexity, activeStages) {
+    if (!ctx.input.issueNumber || ctx.input.local || ctx.input.dryRun)
+        return;
+    const skipped = STAGES
+        .filter(s => !activeStages.find(a => a.name === s.name))
+        .map(s => s.name);
+    if (skipped.length === 0)
+        return;
+    try {
+        postComment(ctx.input.issueNumber, `⚡ **Complexity: ${complexity}** — skipping ${skipped.join(", ")} (not needed for ${complexity}-risk tasks)`);
+    }
+    catch { /* ignore */ }
+}

package/dist/pipeline/questions.d.ts

@@ -0,0 +1,2 @@
+import type { PipelineContext } from "../types.js";
+export declare function checkForQuestions(ctx: PipelineContext, stageName: string): boolean;

package/dist/pipeline/questions.js

@@ -0,0 +1,44 @@
+import * as fs from "fs";
+import * as path from "path";
+import { postComment, setLifecycleLabel } from "../github-api.js";
+export function checkForQuestions(ctx, stageName) {
+    if (ctx.input.local || !ctx.input.issueNumber)
+        return false;
+    try {
+        if (stageName === "taskify") {
+            const taskJsonPath = path.join(ctx.taskDir, "task.json");
+            if (!fs.existsSync(taskJsonPath))
+                return false;
+            const raw = fs.readFileSync(taskJsonPath, "utf-8");
+            const cleaned = raw.replace(/^```json\s*\n?/m, "").replace(/\n?```\s*$/m, "");
+            const taskJson = JSON.parse(cleaned);
+            if (taskJson.questions && Array.isArray(taskJson.questions) && taskJson.questions.length > 0) {
+                const body = `🤔 **Kody has questions before proceeding:**\n\n${taskJson.questions.map((q, i) => `${i + 1}. ${q}`).join("\n")}\n\nReply with \`@kody approve\` and your answers in the comment body.`;
+                postComment(ctx.input.issueNumber, body);
+                setLifecycleLabel(ctx.input.issueNumber, "waiting");
+                return true;
+            }
+        }
+        if (stageName === "plan") {
+            const planPath = path.join(ctx.taskDir, "plan.md");
+            if (!fs.existsSync(planPath))
+                return false;
+            const plan = fs.readFileSync(planPath, "utf-8");
+            const questionsMatch = plan.match(/## Questions\s*\n([\s\S]*?)(?=\n## |\n*$)/);
+            if (questionsMatch) {
+                const questionsText = questionsMatch[1].trim();
+                const questions = questionsText.split("\n").filter((l) => l.startsWith("- ")).map((l) => l.slice(2));
+                if (questions.length > 0) {
+                    const body = `🏗️ **Kody has architecture questions:**\n\n${questions.map((q, i) => `${i + 1}. ${q}`).join("\n")}\n\nReply with \`@kody approve\` and your answers in the comment body.`;
+                    postComment(ctx.input.issueNumber, body);
+                    setLifecycleLabel(ctx.input.issueNumber, "waiting");
+                    return true;
+                }
+            }
+        }
+    }
+    catch {
+        // Don't fail pipeline on question parsing errors
+    }
+    return false;
+}

package/dist/pipeline/runner-selection.d.ts

@@ -0,0 +1,2 @@
+import type { PipelineContext, AgentRunner } from "../types.js";
+export declare function getRunnerForStage(ctx: PipelineContext, stageName: string): AgentRunner;

package/dist/pipeline/runner-selection.js

@@ -0,0 +1,13 @@
+import { getProjectConfig } from "../config.js";
+export function getRunnerForStage(ctx, stageName) {
+    const config = getProjectConfig();
+    const runnerName = config.agent.stageRunners?.[stageName] ??
+        config.agent.defaultRunner ??
+        Object.keys(ctx.runners)[0] ??
+        "claude";
+    const runner = ctx.runners[runnerName];
+    if (!runner) {
+        throw new Error(`Runner "${runnerName}" not found for stage ${stageName}. Available: ${Object.keys(ctx.runners).join(", ")}`);
+    }
+    return runner;
+}

package/dist/pipeline/state.d.ts

@@ -0,0 +1,4 @@
+import type { PipelineStatus } from "../types.js";
+export declare function loadState(taskId: string, taskDir: string): PipelineStatus | null;
+export declare function writeState(state: PipelineStatus, taskDir: string): void;
+export declare function initState(taskId: string): PipelineStatus;

package/dist/pipeline/state.js

@@ -0,0 +1,37 @@
+import * as fs from "fs";
+import * as path from "path";
+import { STAGES } from "../definitions.js";
+export function loadState(taskId, taskDir) {
+    const p = path.join(taskDir, "status.json");
+    if (!fs.existsSync(p))
+        return null;
+    try {
+        const raw = JSON.parse(fs.readFileSync(p, "utf-8"));
+        if (raw.taskId === taskId)
+            return raw;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeState(state, taskDir) {
+    const updated = {
+        ...state,
+        updatedAt: new Date().toISOString(),
+    };
+    const target = path.join(taskDir, "status.json");
+    const tmp = target + ".tmp";
+    fs.writeFileSync(tmp, JSON.stringify(updated, null, 2));
+    fs.renameSync(tmp, target);
+    // Sync the caller's reference
+    state.updatedAt = updated.updatedAt;
+}
+export function initState(taskId) {
+    const stages = {};
+    for (const stage of STAGES) {
+        stages[stage.name] = { state: "pending", retries: 0 };
+    }
+    const now = new Date().toISOString();
+    return { taskId, state: "running", stages, createdAt: now, updatedAt: now };
+}

package/dist/pipeline.d.ts

@@ -0,0 +1,3 @@
+import type { PipelineStatus, PipelineContext } from "./types.js";
+export declare function runPipeline(ctx: PipelineContext): Promise<PipelineStatus>;
+export declare function printStatus(taskId: string, taskDir: string): void;