@helmiq/crew 0.1.0

package/dist/cli/cli.test.js

@@ -0,0 +1,392 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { mkdtemp, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { execSync } from 'node:child_process';
+import { resolveProtectedPaths } from './run.js';
+const stubProviderFactory = () => ({
+    generateText: async () => ({ text: '', tokensIn: 0, tokensOut: 0, toolCalls: [] }),
+});
+let workspacePath;
+function canRunGit() {
+    try {
+        const testDir = join(tmpdir(), `crew-cli-git-${Date.now()}`);
+        execSync(`mkdir -p ${testDir} && cd ${testDir} && git init`, {
+            stdio: 'ignore',
+        });
+        execSync(`rm -rf ${testDir}`, { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function createFixtureWorkspace() {
+    const base = await mkdtemp(join(tmpdir(), 'crew-cli-test-'));
+    const ws = join(base, 'workspace');
+    const crewDir = join(ws, '.crew');
+    const agentDir = join(crewDir, 'agents', 'test-persona');
+    const rubricDir = join(crewDir, 'rubrics', 'rubrics');
+    const skillDir = join(crewDir, 'skills', 'test-skill');
+    const workDir = join(ws, 'work', 'TEST-01');
+    const runsDir = join(ws, 'runs');
+    await mkdir(agentDir, { recursive: true });
+    await mkdir(rubricDir, { recursive: true });
+    await mkdir(skillDir, { recursive: true });
+    await mkdir(workDir, { recursive: true });
+    await mkdir(runsDir, { recursive: true });
+    await writeFile(join(crewDir, 'config'), `project:
+  name: Test
+  key: TEST
+workspace:
+  path: ${ws}
+  work: work/{EPIC_ID}/
+  runs: runs/
+source:
+  repo: github:test/project
+  path: ../target
+llm:
+  default_model: claude-sonnet
+  providers:
+    anthropic:
+      api_key_env: ANTHROPIC_API_KEY
+      models:
+        claude-sonnet: claude-sonnet-4-20250514
+`, 'utf-8');
+    await writeFile(join(skillDir, 'test-skill.prompt.md'), 'You are a Test Role persona. Produce a test artifact.', 'utf-8');
+    await writeFile(join(agentDir, 'persona.yaml'), `persona:
+  name: test-persona
+  identity:
+    role: Test Role
+  skills:
+    - test-skill
+  perception:
+    per_task:
+      test-task:
+        - artifact: requirements
+          scope: { epic: '{{ .EPIC_ID }}' }
+  tasks:
+    test-task:
+      mode: simple
+      trigger: [manual]
+      skill: test-skill
+      produces: test-output
+  tools:
+    permitted: [read-artifact]
+    denied: []
+  cadence: {}
+  evaluation:
+    rubric: rubrics/test.rubric.yaml
+`, 'utf-8');
+    await writeFile(join(rubricDir, 'test.rubric.yaml'), `rubric:
+  artifact_type: test-output
+  scoring_scale: 10
+  pass_threshold: 7
+  criteria:
+    - name: Completeness
+      weight: blocking
+      description: Output addresses all requirements
+`, 'utf-8');
+    if (canRunGit()) {
+        execSync('git init', { cwd: ws, stdio: 'ignore' });
+        execSync('git config user.email "test@test.com"', {
+            cwd: ws,
+            stdio: 'ignore',
+        });
+        execSync('git config user.name "Test"', { cwd: ws, stdio: 'ignore' });
+        execSync('git commit --allow-empty -m "init"', {
+            cwd: ws,
+            stdio: 'ignore',
+        });
+    }
+    return ws;
+}
+beforeEach(async () => {
+    vi.restoreAllMocks();
+    workspacePath = await createFixtureWorkspace();
+});
+describe('resolveProtectedPaths', () => {
+    it('returns all default protected paths when no writable_paths provided', () => {
+        const paths = resolveProtectedPaths(undefined);
+        expect(paths).toContain('product/');
+        expect(paths).toContain('standards/');
+        expect(paths).toContain('architecture/decisions/');
+    });
+    it('returns all default protected paths for empty writable_paths', () => {
+        const paths = resolveProtectedPaths([]);
+        expect(paths).toContain('product/');
+        expect(paths).toContain('standards/');
+        expect(paths).toContain('architecture/decisions/');
+    });
+    it('excludes writable_paths from protected paths', () => {
+        const paths = resolveProtectedPaths(['architecture/decisions/']);
+        expect(paths).toContain('product/');
+        expect(paths).toContain('standards/');
+        expect(paths).not.toContain('architecture/decisions/');
+    });
+    it('can exclude multiple writable paths', () => {
+        const paths = resolveProtectedPaths(['architecture/decisions/', 'standards/']);
+        expect(paths).toContain('product/');
+        expect(paths).not.toContain('standards/');
+        expect(paths).not.toContain('architecture/decisions/');
+    });
+});
+describe('T-01-008a: CLI triggers full run', () => {
+    it('loads config and executes the pipeline', async () => {
+        vi.resetModules();
+        const crewModule = await import('./run.js');
+        const configModule = await import('../config/index.js');
+        const simpleModule = await import('../engine/simple.js');
+        const evalModule = await import('../evaluation/evaluator.js');
+        const pubModule = await import('../publication/publisher.js');
+        const loadConfigSpy = vi.spyOn(configModule, 'loadConfig');
+        vi.spyOn(simpleModule, 'executeSimpleTask').mockResolvedValue({
+            content: 'Test artifact output',
+            toolCalls: [],
+            tokensIn: 50,
+            tokensOut: 30,
+            durationMs: 500,
+            model: 'claude-sonnet-4-20250514',
+        });
+        vi.spyOn(evalModule, 'evaluate').mockResolvedValue({
+            finalArtifact: 'Test artifact output',
+            evaluation: {
+                scores: [{ name: 'Completeness', weight: 'blocking', score: 8, reasoning: 'Good' }],
+                aggregate: 8,
+                pass: true,
+                iteration: 0,
+                maxIterations: 2,
+            },
+        });
+        vi.spyOn(pubModule, 'publish').mockResolvedValue({
+            artifactPath: join(workspacePath, 'work/TEST-01/test-output.md'),
+            commitSha: 'abc123',
+            provenancePath: join(workspacePath, 'runs/run-test/provenance.yaml'),
+        });
+        try {
+            const result = await crewModule.executeRunCommand({
+                persona: 'test-persona',
+                task: 'test-task',
+                scope: 'TEST-01',
+                workspace: workspacePath,
+                createProvider: stubProviderFactory,
+            });
+            expect(loadConfigSpy).toHaveBeenCalledOnce();
+            expect(result.status).toBe('published');
+            expect(result.artifactPath).toContain('test-output.md');
+            expect(result.provenancePath).toContain('provenance.yaml');
+            expect(result.durationMs).toBeGreaterThan(0);
+        }
+        finally {
+            /* cleanup */
+        }
+    });
+});
+describe('T-01-008b: status and artifact output', () => {
+    it('returns awaiting_review when evaluation fails', async () => {
+        vi.resetModules();
+        const crewModule = await import('./run.js');
+        const simpleModule = await import('../engine/simple.js');
+        const evalModule = await import('../evaluation/evaluator.js');
+        const pubModule = await import('../publication/publisher.js');
+        vi.spyOn(simpleModule, 'executeSimpleTask').mockResolvedValue({
+            content: 'Poor output',
+            toolCalls: [],
+            tokensIn: 50,
+            tokensOut: 30,
+            durationMs: 500,
+            model: 'claude-sonnet-4-20250514',
+        });
+        vi.spyOn(evalModule, 'evaluate').mockResolvedValue({
+            finalArtifact: 'Poor output',
+            evaluation: {
+                scores: [{ name: 'Completeness', weight: 'blocking', score: 4, reasoning: 'Incomplete' }],
+                aggregate: 4,
+                pass: false,
+                iteration: 1,
+                maxIterations: 2,
+            },
+        });
+        vi.spyOn(pubModule, 'publish').mockResolvedValue({
+            artifactPath: join(workspacePath, 'work/TEST-01/test-output.md'),
+            commitSha: 'def456',
+            provenancePath: join(workspacePath, 'runs/run-test/provenance.yaml'),
+        });
+        try {
+            const result = await crewModule.executeRunCommand({
+                persona: 'test-persona',
+                task: 'test-task',
+                scope: 'TEST-01',
+                workspace: workspacePath,
+                createProvider: stubProviderFactory,
+            });
+            expect(result.status).toBe('awaiting_review');
+            expect(result.evaluationScore).toBe(4);
+        }
+        finally {
+            /* cleanup */
+        }
+    });
+});
+describe('T-FR-03: self-evaluation refinement wiring', () => {
+    it('passes a refineCallback to evaluate for artifact refinement', async () => {
+        vi.resetModules();
+        const crewModule = await import('./run.js');
+        const simpleModule = await import('../engine/simple.js');
+        const evalModule = await import('../evaluation/evaluator.js');
+        const pubModule = await import('../publication/publisher.js');
+        vi.spyOn(simpleModule, 'executeSimpleTask').mockResolvedValue({
+            content: 'Review artifact content',
+            toolCalls: [],
+            tokensIn: 50,
+            tokensOut: 30,
+            durationMs: 500,
+            model: 'claude-sonnet-4-20250514',
+        });
+        const evaluateSpy = vi.spyOn(evalModule, 'evaluate').mockResolvedValue({
+            finalArtifact: 'Review artifact content',
+            evaluation: {
+                scores: [{ name: 'Completeness', weight: 'blocking', score: 8, reasoning: 'Good' }],
+                aggregate: 8,
+                pass: true,
+                iteration: 0,
+                maxIterations: 2,
+            },
+        });
+        vi.spyOn(pubModule, 'publish').mockResolvedValue({
+            artifactPath: join(workspacePath, 'work/TEST-01/test-output.md'),
+            commitSha: 'abc',
+            provenancePath: join(workspacePath, 'runs/run-test/provenance.yaml'),
+        });
+        try {
+            await crewModule.executeRunCommand({
+                persona: 'test-persona',
+                task: 'test-task',
+                scope: 'TEST-01',
+                workspace: workspacePath,
+                createProvider: stubProviderFactory,
+            });
+            expect(evaluateSpy).toHaveBeenCalledOnce();
+            const callArgs = evaluateSpy.mock.calls[0];
+            expect(callArgs[0]).toBe('Review artifact content');
+            expect(typeof callArgs[5]).toBe('function');
+        }
+        finally {
+            /* cleanup */
+        }
+    });
+});
+describe('T-01-008c: dry-run mode', () => {
+    it('assembles context without calling LLM', async () => {
+        vi.resetModules();
+        const crewModule = await import('./run.js');
+        const simpleModule = await import('../engine/simple.js');
+        const executeSpy = vi.spyOn(simpleModule, 'executeSimpleTask');
+        const result = await crewModule.executeRunCommand({
+            persona: 'test-persona',
+            task: 'test-task',
+            scope: 'TEST-01',
+            workspace: workspacePath,
+            dryRun: true,
+            createProvider: stubProviderFactory,
+        });
+        expect(result.dryRun).toBe(true);
+        expect(result.status).toBe('running');
+        expect(result.runId).toContain('run-');
+        expect(executeSpy).not.toHaveBeenCalled();
+    });
+});
+describe('T-FR-05: feedback loop iteration tracking', () => {
+    it('sets feedbackIteration based on prior runs for the same persona/task/scope', async () => {
+        vi.resetModules();
+        const runsDir = join(workspacePath, 'runs');
+        await mkdir(join(runsDir, 'run-2026-01-01T00-00-00Z-test-persona-test-task-TEST-01'), {
+            recursive: true,
+        });
+        const crewModule = await import('./run.js');
+        const simpleModule = await import('../engine/simple.js');
+        const evalModule = await import('../evaluation/evaluator.js');
+        const pubModule = await import('../publication/publisher.js');
+        vi.spyOn(simpleModule, 'executeSimpleTask').mockResolvedValue({
+            content: 'Output',
+            toolCalls: [],
+            tokensIn: 50,
+            tokensOut: 30,
+            durationMs: 500,
+            model: 'claude-sonnet-4-20250514',
+        });
+        vi.spyOn(evalModule, 'evaluate').mockResolvedValue({
+            finalArtifact: 'Output',
+            evaluation: {
+                scores: [{ name: 'Completeness', weight: 'blocking', score: 8, reasoning: 'Good' }],
+                aggregate: 8,
+                pass: true,
+                iteration: 0,
+                maxIterations: 2,
+            },
+        });
+        vi.spyOn(pubModule, 'publish').mockResolvedValue({
+            artifactPath: join(workspacePath, 'work/TEST-01/test-output.md'),
+            commitSha: 'abc',
+            provenancePath: join(runsDir, 'run-test/provenance.yaml'),
+        });
+        const result = await crewModule.executeRunCommand({
+            persona: 'test-persona',
+            task: 'test-task',
+            scope: 'TEST-01',
+            workspace: workspacePath,
+            createProvider: stubProviderFactory,
+        });
+        expect(result.feedbackIteration).toBe(1);
+        expect(result.escalated).toBeUndefined();
+    });
+    it('does not set escalated for non-review tasks even with many prior runs', async () => {
+        vi.resetModules();
+        const runsDir = join(workspacePath, 'runs');
+        await mkdir(join(runsDir, 'run-2026-01-01T00-00-00Z-test-persona-test-task-TEST-01'), {
+            recursive: true,
+        });
+        await mkdir(join(runsDir, 'run-2026-01-02T00-00-00Z-test-persona-test-task-TEST-01'), {
+            recursive: true,
+        });
+        await mkdir(join(runsDir, 'run-2026-01-03T00-00-00Z-test-persona-test-task-TEST-01'), {
+            recursive: true,
+        });
+        const crewModule = await import('./run.js');
+        const simpleModule = await import('../engine/simple.js');
+        const evalModule = await import('../evaluation/evaluator.js');
+        const pubModule = await import('../publication/publisher.js');
+        vi.spyOn(simpleModule, 'executeSimpleTask').mockResolvedValue({
+            content: 'Output',
+            toolCalls: [],
+            tokensIn: 50,
+            tokensOut: 30,
+            durationMs: 500,
+            model: 'claude-sonnet-4-20250514',
+        });
+        vi.spyOn(evalModule, 'evaluate').mockResolvedValue({
+            finalArtifact: 'Output',
+            evaluation: {
+                scores: [{ name: 'Completeness', weight: 'blocking', score: 8, reasoning: 'Good' }],
+                aggregate: 8,
+                pass: true,
+                iteration: 0,
+                maxIterations: 2,
+            },
+        });
+        vi.spyOn(pubModule, 'publish').mockResolvedValue({
+            artifactPath: join(workspacePath, 'work/TEST-01/test-output.md'),
+            commitSha: 'abc',
+            provenancePath: join(runsDir, 'run-test/provenance.yaml'),
+        });
+        const result = await crewModule.executeRunCommand({
+            persona: 'test-persona',
+            task: 'test-task',
+            scope: 'TEST-01',
+            workspace: workspacePath,
+            createProvider: stubProviderFactory,
+        });
+        expect(result.feedbackIteration).toBe(3);
+        expect(result.escalated).toBeUndefined();
+    });
+});

package/dist/cli/run.d.ts

@@ -0,0 +1,45 @@
+import type { LlmProvider, RunStatus, ArtifactStore } from '../types/index.js';
+import type { ResolvedModel } from '../config/model-resolver.js';
+export type ProviderFactory = (model: ResolvedModel) => LlmProvider | Promise<LlmProvider>;
+export interface RunCommandOptions {
+    persona: string;
+    task: string;
+    scope: string;
+    workspace: string;
+    dryRun?: boolean;
+    /** Override for testing. When omitted the runtime resolves providers automatically. */
+    createProvider?: ProviderFactory;
+    /** Full story ID (e.g. CREW-03-011). Defaults to scope when not provided. */
+    storyId?: string;
+    /** Optional artifact store enabling read-artifact and write-artifact tools. */
+    artifactStore?: ArtifactStore;
+}
+export interface RunCommandResult {
+    runId: string;
+    status: RunStatus;
+    artifactPath?: string;
+    provenancePath?: string;
+    evaluationScore?: number;
+    durationMs: number;
+    dryRun: boolean;
+    feedbackIteration?: number;
+    escalated?: boolean;
+}
+/**
+ * Resolve protected paths for a persona run. Paths listed in the persona
+ * spec's `tools.writable_paths` are excluded from the default protected set,
+ * allowing that persona to write to those locations via tool calls.
+ */
+export declare function resolveProtectedPaths(writablePaths?: string[], defaults?: string[]): string[];
+/**
+ * Execute the full `crew run` pipeline:
+ * 1. Load config (project, persona, rubric)
+ * 2. Acquire lock
+ * 3. Assemble context
+ * 4. Execute task (simple or composite)
+ * 5. Evaluate output
+ * 6. Publish artifact + provenance
+ * 7. Release lock
+ */
+export declare function executeRunCommand(options: RunCommandOptions): Promise<RunCommandResult>;
+//# sourceMappingURL=run.d.ts.map

package/dist/cli/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EACV,WAAW,EAGX,SAAS,EACT,aAAa,EACd,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAGjE,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;AAE3F,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,uFAAuF;IACvF,cAAc,CAAC,EAAE,eAAe,CAAC;IACjC,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,SAAS,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAMD;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,aAAa,CAAC,EAAE,MAAM,EAAE,EACxB,QAAQ,GAAE,MAAM,EAA4B,GAC3C,MAAM,EAAE,CAKV;AAkBD;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAuP7F"}

package/dist/cli/run.js

@@ -0,0 +1,236 @@
+import { join, resolve } from 'node:path';
+import { mkdir, readdir } from 'node:fs/promises';
+import { loadConfig } from '../config/index.js';
+import { resolveExecutionModel, resolveEvalModel } from '../config/model-resolver.js';
+import { assembleContext } from '../context/index.js';
+import { executeSimpleTask } from '../engine/simple.js';
+import { executeCompositeTask } from '../engine/composite.js';
+import { evaluate } from '../evaluation/evaluator.js';
+import { publish } from '../publication/publisher.js';
+import { acquireLock } from '../control/lock-manager.js';
+import { transitionState, persistState } from '../control/run-state.js';
+import { generateRunId } from '../control/id-generator.js';
+import { createToolRegistry } from '../tools/registry.js';
+import { callLlm } from '../engine/llm-client.js';
+import { resolveProvider } from '../providers/index.js';
+const MAX_FEEDBACK_ITERATIONS = 2;
+const DEFAULT_PROTECTED_PATHS = ['product/', 'standards/', 'architecture/decisions/'];
+/**
+ * Resolve protected paths for a persona run. Paths listed in the persona
+ * spec's `tools.writable_paths` are excluded from the default protected set,
+ * allowing that persona to write to those locations via tool calls.
+ */
+export function resolveProtectedPaths(writablePaths, defaults = DEFAULT_PROTECTED_PATHS) {
+    if (!writablePaths || writablePaths.length === 0) {
+        return defaults;
+    }
+    return defaults.filter((p) => !writablePaths.includes(p));
+}
+async function countPriorRuns(runsDir, persona, task, scope, excludeRunId) {
+    try {
+        const entries = await readdir(runsDir);
+        const suffix = `-${persona}-${task}-${scope}`;
+        return entries.filter((e) => e.endsWith(suffix) && e !== excludeRunId).length;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Execute the full `crew run` pipeline:
+ * 1. Load config (project, persona, rubric)
+ * 2. Acquire lock
+ * 3. Assemble context
+ * 4. Execute task (simple or composite)
+ * 5. Evaluate output
+ * 6. Publish artifact + provenance
+ * 7. Release lock
+ */
+export async function executeRunCommand(options) {
+    const { persona, task, scope, workspace, dryRun, storyId } = options;
+    const createProvider = options.createProvider ?? resolveProvider;
+    const workspacePath = resolve(workspace);
+    const startMs = Date.now();
+    const config = await loadConfig({ workspacePath, personaName: persona });
+    const projectCfg = config.project;
+    const executionModel = resolveExecutionModel(projectCfg.llm);
+    const evalModel = resolveEvalModel(projectCfg.llm, config.persona.persona.evaluation.self_eval_model);
+    const runsDir = join(workspacePath, projectCfg.workspace.runs);
+    const runId = generateRunId(persona, task, scope);
+    const runDir = join(runsDir, runId);
+    await mkdir(runDir, { recursive: true });
+    let record = {
+        run_id: runId,
+        persona,
+        task,
+        scope,
+        status: 'queued',
+        started_at: new Date().toISOString(),
+    };
+    await persistState(runDir, record);
+    const lock = await acquireLock(persona, task, scope, runsDir);
+    try {
+        record = transitionState(record, 'running');
+        await persistState(runDir, record);
+        const taskDef = config.persona.persona.tasks[task];
+        if (!taskDef) {
+            throw new Error(`Task '${task}' not found in persona '${persona}'. Available: ${Object.keys(config.persona.persona.tasks).join(', ')}`);
+        }
+        const context = await assembleContext(config.persona.persona.perception, task, { EPIC_ID: scope, STORY_ID: storyId ?? scope }, projectCfg, workspacePath);
+        if (dryRun) {
+            await lock.release();
+            return {
+                runId,
+                status: 'running',
+                durationMs: Date.now() - startMs,
+                dryRun: true,
+            };
+        }
+        const provider = await createProvider(executionModel);
+        const tools = createToolRegistry({ artifactStore: options.artifactStore });
+        const toolContext = {
+            workspacePath,
+            targetRepoPath: resolve(workspacePath, projectCfg.source.path),
+            project: projectCfg,
+            persona,
+            task,
+            runId,
+            protectedPaths: resolveProtectedPaths(config.persona.persona.tools.writable_paths),
+            logger: (msg) => {
+                /* structured logging deferred */
+                void msg;
+            },
+        };
+        let artifactContent;
+        let totalTokensIn = 0;
+        let totalTokensOut = 0;
+        let compositeResult;
+        if (taskDef.mode === 'simple') {
+            const result = await executeSimpleTask(config.persona, taskDef, context, executionModel, provider, tools, config.skills, toolContext);
+            artifactContent = result.content;
+            totalTokensIn = result.tokensIn;
+            totalTokensOut = result.tokensOut;
+        }
+        else {
+            const result = await executeCompositeTask(config.persona, taskDef, context, executionModel, provider, tools, runDir, config.skills, toolContext);
+            artifactContent = result.content;
+            totalTokensIn = result.tokensIn;
+            totalTokensOut = result.tokensOut;
+            compositeResult = result;
+        }
+        record = transitionState(record, 'evaluating');
+        await persistState(runDir, record);
+        const evalProvider = await createProvider(evalModel);
+        const refineCallback = async (feedback) => {
+            const result = await callLlm({
+                provider,
+                model: executionModel,
+                system: `You are a ${config.persona.persona.identity.role}. You produced an artifact that did not pass quality evaluation. Revise it to address the feedback while preserving the overall structure and content that was acceptable.`,
+                messages: [
+                    {
+                        role: 'user',
+                        content: `--- Original artifact ---\n${artifactContent}\n--- End original artifact ---\n\n--- Evaluation feedback ---\n${feedback}\n--- End feedback ---\n\nProduce a revised version of the artifact that addresses the evaluation feedback. Output only the revised artifact content.`,
+                    },
+                ],
+                maxRetries: 1,
+            });
+            return result.text;
+        };
+        const evalResult = await evaluate(artifactContent, config.rubric, evalModel, evalProvider, undefined, refineCallback);
+        record = transitionState(record, 'publishing');
+        await persistState(runDir, record);
+        const artifactPath = join(projectCfg.workspace.work.replace('{EPIC_ID}', scope), `${taskDef.mode === 'simple' ? taskDef.produces : taskDef.published_artifact}.md`);
+        const feedbackIteration = await countPriorRuns(runsDir, persona, task, scope, runId);
+        const escalated = task === 'review-pr' && feedbackIteration >= MAX_FEEDBACK_ITERATIONS;
+        const provenance = {
+            run_id: runId,
+            persona,
+            task,
+            sub_agent_chain: compositeResult?.subAgentResults.map((r) => r.name),
+            feedback_iteration: feedbackIteration > 0 ? feedbackIteration : undefined,
+            versions: {
+                persona_spec_hash: 'pending',
+                prompt_hashes: {},
+                model: executionModel.concreteModel,
+                rubric_hash: 'pending',
+                runtime_version: '0.0.0',
+            },
+            timestamp: record.started_at,
+            duration_ms: Date.now() - startMs,
+            trigger: 'manual',
+            inputs: {
+                artifacts_read: context.blocks.map((b) => ({
+                    type: b.source.type,
+                    path: b.source.path ?? '',
+                })),
+                context_tokens: context.totalTokens,
+            },
+            outputs: {
+                artifact_produced: {
+                    type: taskDef.mode === 'simple'
+                        ? taskDef.produces
+                        : taskDef.published_artifact,
+                    id: runId,
+                },
+                work_products: compositeResult?.checkpoints.map((c) => c.path),
+            },
+            evaluation: {
+                self_eval_score: evalResult.evaluation.aggregate,
+                self_eval_pass: evalResult.evaluation.pass,
+                self_eval_model: evalModel.concreteModel,
+            },
+            cost: {
+                llm_calls: compositeResult
+                    ? compositeResult.subAgentResults.reduce((sum, r) => sum + r.result.rounds, 0)
+                    : 1,
+                total_tokens: totalTokensIn + totalTokensOut,
+                estimated_cost_usd: 0,
+            },
+            run_state: 'published',
+        };
+        const pubResult = await publish({
+            artifact: evalResult.finalArtifact,
+            artifactPath,
+            metadata: {
+                author: persona,
+                run_id: runId,
+                status: evalResult.evaluation.pass ? 'published' : 'awaiting_review',
+                timestamp: new Date().toISOString(),
+                eval_score: evalResult.evaluation.aggregate,
+                eval_pass: evalResult.evaluation.pass,
+            },
+            provenance,
+            config: projectCfg,
+            runRecord: record,
+            runDir,
+            push: false,
+        });
+        const finalStatus = evalResult.evaluation.pass ? 'published' : 'awaiting_review';
+        record = transitionState(record, finalStatus);
+        await persistState(runDir, record);
+        return {
+            runId,
+            status: record.status,
+            artifactPath: pubResult.artifactPath,
+            provenancePath: pubResult.provenancePath,
+            evaluationScore: evalResult.evaluation.aggregate,
+            durationMs: Date.now() - startMs,
+            dryRun: false,
+            feedbackIteration: feedbackIteration > 0 ? feedbackIteration : undefined,
+            escalated: escalated || undefined,
+        };
+    }
+    catch (err) {
+        try {
+            record = transitionState(record, 'failed');
+            await persistState(runDir, record);
+        }
+        catch {
+            /* state transition may fail if already terminal */
+        }
+        throw err;
+    }
+    finally {
+        await lock.release();
+    }
+}