@jterrats/open-orchestra 0.1.0 → 0.3.0

package/dist/commands.js

@@ -1,11 +1,53 @@
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
 import { initWorkspace } from "./workspace.js";
 import { requireArg } from "./args.js";
+import { AUTONOMOUS_PHASE_SEQUENCE, autonomousRunsPath, checkArchitectSizing, closePhase, createAutonomousRun, initPhase, listAutonomousRuns, markRunDone, markRunFailed, readAutonomousRun, resumePhaseIndex, suspendPhaseForClarification, resumePhaseFromClarification, } from "./autonomous-workflow.js";
+import { listClarifications, openClarification, answerClarification, } from "./clarification.js";
+import { computeBenchmark, recordEstimate, summarizeBenchmark, } from "./benchmark.js";
+import { computeSprintBurndown, renderBurndownAscii } from "./burndown.js";
+import { SIZING_LABELS } from "./types.js";
+import { resolveWorkspaceWritePath } from "./fs-utils.js";
 import { addEvidence, addPlaywrightEvidence, addTask, approveApproval, checkUsageBudget, checkReadiness, checkTaskDependencies, claimLock, completeWithProviderFallback, createHandoff, evaluateWorkflowGate, executeNextReadyTask, executePlanWithBudgetPreflight, executeReadyTaskBatch, generateExecutionPlan, generatePlaywrightTestPlan, generatePullRequestSummary, generateTaskGraphPlan, getUsageReport, getWorkflowStatus, getWorkflowSummary, getTaskContext, getWorkflowConfig, listEvidence, listConfiguredModelProviders, listDecisions, listLocks, listApprovals, listReviews, listRoles, listTasks, rejectApproval, recordReview, recordModelProvenance, recordDecision, releaseLock, setRoleModelProvider, showApproval, updateTask, listModelProvenance, } from "./workflow-services.js";
 import { validateWorkspace } from "./workspace-validator.js";
+import { addAgentLesson, listAgentLessons, listSkills, planSkillsForTask, promoteAgentLessons, readSourceOfTruth, recordSkillPlan, recordSkillRender, renderSkills, validateSkills, } from "./skills.js";
 import { getWebServerAddress, startWebApiServer } from "./web-api.js";
+import { decideTaskDelegation } from "./delegation-decision.js";
+import { lintMermaidDiagram, recordDiagramLintEvidence, } from "./diagram-validation.js";
+import { evaluateMcpOAuthProxy, } from "./mcp-oauth-proxy.js";
+import { detectStaleInstructionFilesFromManifest, resolveInstructionImportsFromFile, updateManagedInstructionFile, } from "./instruction-updates.js";
+import { applyInstructionUpdatesFromManifest } from "./instruction-apply.js";
+import { renderSubagentProtocol, upsertSubagentProtocolBlock, } from "./subagent-protocol.js";
+import { listCollaborationFlows, recommendCollaborationFlow, } from "./collaboration-flows.js";
+import { listWorkflowTemplates, renderWorkflowTemplates, selectWorkflowTemplates, validateWorkflowTemplates, } from "./workflow-templates.js";
+import { listCommandManifest } from "./command-manifest.js";
+import { listRuntimeAdapters, parseRuntimeTarget } from "./runtime-adapters.js";
+import { renderRuntimeBootstrap, upsertRuntimeBootstrapBlock, } from "./runtime-bootstrap.js";
+import { disableTelemetryConsent, enableTelemetryConsent, exportTelemetryDataset, exportTelemetryEvalDataset, getTelemetryConsent, parseTelemetryLevel, requiresSensitiveTelemetryOptIn, submitTelemetryDataset, } from "./telemetry.js";
+import { buildPrBody, createPullRequest } from "./github.js";
 export async function initCommand(options, io) {
-    const base = await initWorkspace({ force: Boolean(options.force) });
+    const root = stringOption(options["target-dir"]) ?? process.cwd();
+    const input = {
+        root,
+        force: Boolean(options.force),
+        advisory: Boolean(options.advisory),
+        confirmUnknown: Boolean(options["confirm-unknown"]),
+    };
+    const bootstrapTargetFile = stringOption(options["bootstrap-file"]);
+    const runtimeTargets = parseRuntimeTargetOptions(options);
+    const base = await initWorkspace({
+        ...input,
+        ...(bootstrapTargetFile ? { bootstrapTargetFile } : {}),
+        ...(runtimeTargets.length > 0 ? { runtimeTargets } : {}),
+    });
     io.log(`Initialized ${base}`);
+    if (options.advisory) {
+        io.log("Advisory mode enabled; root instruction files were not written.");
+    }
+    else {
+        io.log("Prompt registry scaffolded in .generated-prompts/");
+    }
+    io.log("Source catalog and agent lessons scaffolded in .agent-workflow/");
     io.log("Next: add tasks to .agent-workflow/tasks.json and run orchestra status");
 }
 export async function statusCommand(options, io) {
@@ -166,7 +208,7 @@ export async function lockListCommand(options, io) {
 }
 export async function lockClaimCommand(options, io) {
     const lock = await claimLock(removeUndefined({
-        id: stringOption(options.id) ?? `lock-${Date.now()}`,
+        id: stringOption(options.id),
         taskId: requireArg(options, "task"),
         ownerRole: requireArg(options, "role"),
         path: requireArg(options, "path"),
@@ -363,6 +405,16 @@ export async function prSummaryCommand(options, io) {
     }
     io.log(renderPullRequestSummaryMarkdown(summary));
 }
+export async function delegationDecideCommand(options, io) {
+    const decision = await decideTaskDelegation(requireArg(options, "task"), process.cwd(), {
+        record: !options["no-record"],
+    });
+    if (options.json) {
+        io.log(JSON.stringify(decision, null, 2));
+        return;
+    }
+    io.log(renderDelegationDecisionMarkdown(decision));
+}
 export async function contextCommand(options, io) {
     const context = await getTaskContext(requireArg(options, "task"));
     if (options.json) {
@@ -485,6 +537,958 @@ export async function modelCompleteFakeCommand(options, io) {
     }
     io.log(`Fake completion used ${result.provider}/${result.model} fallback=${String(result.fallbackUsed)}`);
 }
+export async function telemetryStatusCommand(options, io) {
+    const telemetry = await getTelemetryConsent();
+    if (options.json) {
+        io.log(JSON.stringify(telemetry, null, 2));
+        return;
+    }
+    io.log("Telemetry: " + (telemetry.enabled ? "enabled" : "off"));
+    io.log("Level: " + telemetry.level);
+    io.log("Policy: " + telemetry.policyVersion);
+}
+export async function telemetryEnableCommand(options, io) {
+    const level = parseTelemetryLevel(stringOption(options.level) ?? "metadata");
+    if (requiresSensitiveTelemetryOptIn(level) && !options["confirm-sensitive"]) {
+        throw new Error("prompt-sample and eval-dataset telemetry require --confirm-sensitive");
+    }
+    const telemetry = await enableTelemetryConsent({
+        level,
+        actor: stringOption(options.actor) ?? "user",
+    });
+    if (options.json) {
+        io.log(JSON.stringify(telemetry, null, 2));
+        return;
+    }
+    io.log("Telemetry enabled at level " + telemetry.level);
+}
+export async function telemetryExportCommand(options, io) {
+    const result = await exportTelemetryDataset({
+        dryRun: Boolean(options["dry-run"]),
+    });
+    if (options.json) {
+        io.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    io.log((result.dryRun ? "Telemetry export dry run" : "Telemetry exported") +
+        ": " +
+        result.recordCount +
+        " record(s)");
+    if (result.file) {
+        io.log("File: " + result.file);
+    }
+}
+export async function telemetrySubmitCommand(options, io) {
+    const result = await submitTelemetryDataset({
+        file: requireArg(options, "file"),
+        endpoint: requireArg(options, "endpoint"),
+    });
+    if (options.json) {
+        io.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    io.log("Telemetry submission recorded: " + result.fileHash);
+}
+export async function telemetryEvalDatasetCommand(options, io) {
+    const result = await exportTelemetryEvalDataset({
+        dryRun: Boolean(options["dry-run"]),
+    });
+    if (options.json) {
+        io.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    io.log((result.dryRun ? "Eval dataset dry run" : "Eval dataset exported") +
+        ": " +
+        result.recordCount +
+        " record(s)");
+    if (result.file) {
+        io.log("File: " + result.file);
+    }
+}
+export async function telemetryDisableCommand(options, io) {
+    const telemetry = await disableTelemetryConsent({
+        actor: stringOption(options.actor) ?? "user",
+    });
+    if (options.json) {
+        io.log(JSON.stringify(telemetry, null, 2));
+        return;
+    }
+    io.log("Telemetry disabled");
+}
+export async function instructionsApplyCommand(options, io) {
+    const report = await applyInstructionUpdatesFromManifest({
+        manifestPath: requireArg(options, "manifest"),
+        check: Boolean(options.check),
+        dryRun: Boolean(options["dry-run"]),
+        force: Boolean(options.force),
+    });
+    if (options.json) {
+        io.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    io.log("Instruction update " +
+        report.mode +
+        ": " +
+        report.totals.changed +
+        " changed, " +
+        report.totals.unchanged +
+        " unchanged, " +
+        report.totals.blocked +
+        " blocked");
+    for (const item of report.items) {
+        io.log(item.status +
+            " " +
+            item.filePath +
+            "#" +
+            item.blockId +
+            " - " +
+            item.reason);
+    }
+}
+export async function instructionsStaleCommand(options, io) {
+    const report = await detectStaleInstructionFilesFromManifest({
+        manifestPath: requireArg(options, "manifest"),
+    });
+    if (options.json) {
+        io.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    io.log("Instruction file status:");
+    for (const item of report.items) {
+        io.log(item.status +
+            " " +
+            item.filePath +
+            "#" +
+            item.blockId +
+            " - " +
+            item.reason);
+    }
+}
+export async function instructionsBlockCommand(options, io) {
+    const result = await updateManagedInstructionFile({
+        filePath: resolveWorkspaceWritePath(process.cwd(), requireArg(options, "file")),
+        contentPath: resolveWorkspaceWritePath(process.cwd(), requireArg(options, "content-file")),
+        input: {
+            blockId: requireArg(options, "block"),
+            generator: stringOption(options.generator) ?? "open-orchestra",
+            version: stringOption(options.version) ?? "1",
+            target: parseInstructionTarget(stringOption(options.target) ?? "generic"),
+            sourceManifest: stringOption(options["source-manifest"]) ?? "local",
+        },
+        check: Boolean(options.check),
+        dryRun: Boolean(options["dry-run"]),
+        force: Boolean(options.force),
+    });
+    if (options.json) {
+        io.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    if (result.drift) {
+        io.log("Drift detected for " + requireArg(options, "block"));
+        return;
+    }
+    io.log(result.changed
+        ? "Instruction block changed"
+        : "Instruction block unchanged");
+}
+export async function instructionsImportsCommand(options, io) {
+    const result = await resolveInstructionImportsFromFile({
+        registryPath: requireArg(options, "registry"),
+        entryId: requireArg(options, "entry"),
+        target: parseInstructionTarget(stringOption(options.target) ?? "generic"),
+    });
+    if (options.json) {
+        io.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    io.log(result.content);
+}
+function parseInstructionTarget(value) {
+    return parseRuntimeTarget(value);
+}
+export async function collaborationFlowsCommand(options, io) {
+    const flows = listCollaborationFlows();
+    if (options.json) {
+        io.log(JSON.stringify(flows, null, 2));
+        return;
+    }
+    for (const flow of flows) {
+        io.log(flow.id + " - " + flow.name);
+        io.log("  roles: " + flow.roles.join(", "));
+    }
+}
+export async function collaborationRecommendCommand(options, io) {
+    const context = await getTaskContext(requireArg(options, "task"));
+    const recommendation = recommendCollaborationFlow(context.task, [
+        ...context.decisions,
+        ...context.handoffs,
+        ...context.reviews,
+        ...context.evidence,
+        ...context.gates,
+    ]);
+    if (options.json) {
+        io.log(JSON.stringify(recommendation, null, 2));
+        return;
+    }
+    if (!recommendation) {
+        io.log("No collaboration flow recommended");
+        return;
+    }
+    io.log(recommendation.flow.id + " - " + recommendation.flow.name);
+    io.log("Missing artifacts: " +
+        (recommendation.missingArtifacts.join(", ") || "none"));
+    io.log("Reviewers: " + (recommendation.optionalReviewers.join(", ") || "none"));
+}
+export async function workflowTemplatesCommand(options, io) {
+    const templates = listWorkflowTemplates();
+    const validationErrors = validateWorkflowTemplates();
+    if (options.json) {
+        io.log(JSON.stringify({ templates, validationErrors }, null, 2));
+        return;
+    }
+    for (const template of templates) {
+        io.log(template.id + " - " + template.name);
+        io.log("  roles: " + template.roles.join(", "));
+    }
+    if (validationErrors.length > 0) {
+        io.log("Validation errors: " + validationErrors.join("; "));
+    }
+}
+export async function workflowTemplateSelectCommand(options, io) {
+    const context = await getTaskContext(requireArg(options, "task"));
+    const events = [
+        ...context.decisions,
+        ...context.handoffs,
+        ...context.reviews,
+        ...context.evidence,
+        ...context.gates,
+    ];
+    const selection = selectWorkflowTemplates(context.task, events);
+    if (options.json) {
+        io.log(JSON.stringify(selection, null, 2));
+        return;
+    }
+    for (const item of selection) {
+        io.log(item.template.id + " (score " + item.score + ")");
+        io.log("  missing evidence: " + (item.missingEvidence.join(", ") || "none"));
+    }
+}
+export async function workflowTemplateRenderCommand(options, io) {
+    const context = await getTaskContext(requireArg(options, "task"));
+    const rendered = renderWorkflowTemplates({
+        task: context.task,
+        target: parseSkillRenderTarget(stringOption(options.target) ?? "generic"),
+        templates: context.workflowTemplates,
+    });
+    if (options.json) {
+        io.log(JSON.stringify(rendered, null, 2));
+        return;
+    }
+    io.log(rendered.content);
+}
+export async function commandsManifestCommand(options, io) {
+    const manifest = listCommandManifest();
+    if (options.json) {
+        io.log(JSON.stringify(manifest, null, 2));
+        return;
+    }
+    for (const command of manifest) {
+        io.log(command.command + " - " + command.summary);
+    }
+}
+export async function runtimeAdaptersCommand(options, io) {
+    const adapters = listRuntimeAdapters();
+    if (options.json) {
+        io.log(JSON.stringify(adapters, null, 2));
+        return;
+    }
+    for (const adapter of adapters) {
+        io.log(adapter.target +
+            " - " +
+            adapter.label +
+            " (" +
+            adapter.defaultInstructionFiles.join(", ") +
+            ")");
+    }
+}
+export async function runtimeBootstrapCommand(options, io) {
+    const target = parseSkillRenderTarget(stringOption(options.target) ?? "generic");
+    const bootstrap = renderRuntimeBootstrap(target);
+    const filePath = stringOption(options.file);
+    if (filePath) {
+        const resolvedFilePath = resolveWorkspaceWritePath(process.cwd(), path.normalize(filePath));
+        const existing = await readFile(resolvedFilePath, "utf8").catch(() => "");
+        const result = upsertRuntimeBootstrapBlock(existing, bootstrap, {
+            force: Boolean(options.force),
+        });
+        if (!options.check && !options["dry-run"] && !result.drift) {
+            await writeFile(resolvedFilePath, result.content);
+        }
+        if (options.json) {
+            io.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        io.log(result.changed
+            ? "Runtime bootstrap changed"
+            : "Runtime bootstrap unchanged");
+        return;
+    }
+    if (options.json) {
+        io.log(JSON.stringify(bootstrap, null, 2));
+        return;
+    }
+    io.log(bootstrap.content);
+}
+export async function protocolRenderCommand(options, io) {
+    const protocol = await renderSubagentProtocol(removeUndefined({
+        target: parseSkillRenderTarget(stringOption(options.target) ?? "generic"),
+        taskId: stringOption(options.task),
+    }));
+    if (options.json) {
+        io.log(JSON.stringify(protocol, null, 2));
+        return;
+    }
+    io.log(protocol.content);
+}
+export async function protocolBlockCommand(options, io) {
+    const filePath = requireArg(options, "file");
+    const protocol = await renderSubagentProtocol(removeUndefined({
+        target: parseSkillRenderTarget(stringOption(options.target) ?? "generic"),
+        taskId: stringOption(options.task),
+    }));
+    const existing = await readFile(filePath, "utf8").catch(() => "");
+    const result = upsertSubagentProtocolBlock(existing, protocol, {
+        force: Boolean(options.force),
+    });
+    const shouldWrite = !options.check && !options["dry-run"] && !result.drift && result.changed;
+    if (shouldWrite) {
+        await writeFile(filePath, result.content);
+    }
+    if (options.json) {
+        io.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    if (result.drift) {
+        io.log("Drift detected for subagent protocol block");
+        return;
+    }
+    io.log(result.changed
+        ? "Subagent protocol block changed"
+        : "Subagent protocol block unchanged");
+}
+export async function diagramsLintCommand(options, io) {
+    const result = await lintMermaidDiagram({
+        filePath: requireArg(options, "file"),
+    });
+    const evidence = stringOption(options.task)
+        ? await recordDiagramLintEvidence({
+            taskId: stringOption(options.task) ?? "",
+            result,
+        })
+        : undefined;
+    const output = removeUndefined({ result, evidence });
+    if (options.json) {
+        io.log(JSON.stringify(output, null, 2));
+    }
+    else {
+        io.log(result.valid ? "Mermaid diagram valid" : "Mermaid diagram invalid");
+        if (result.installHint) {
+            io.log(result.installHint);
+        }
+        if (evidence) {
+            io.log("Created " + evidence.artifact);
+        }
+    }
+    if (!result.valid) {
+        throw new Error("diagram lint failed");
+    }
+}
+export async function mcpOAuthProxyEvaluateCommand(options, io) {
+    const evaluation = evaluateMcpOAuthProxy(removeUndefined({
+        enabled: Boolean(options.enable),
+        mode: parseMcpProxyMode(stringOption(options.mode) ?? "stdio-proxy"),
+        serverUrl: requireArg(options, "server-url"),
+        tokenStorage: parseMcpSecretStorage(stringOption(options["token-storage"]) ?? "keychain"),
+        tokenPath: stringOption(options["token-path"]),
+        refreshWindowSeconds: Number(stringOption(options["refresh-window"]) ?? 300),
+        approvedBy: options.approve
+            ? (stringOption(options.approver) ?? "local-user")
+            : undefined,
+    }));
+    if (options.json) {
+        io.log(JSON.stringify(evaluation, null, 2));
+        return;
+    }
+    io.log(evaluation.approved
+        ? "MCP proxy plan approved"
+        : "MCP proxy plan has risks");
+    for (const risk of evaluation.risks) {
+        io.log("RISK: " + risk);
+    }
+}
+function parseMcpProxyMode(value) {
+    if (["stdio-proxy", "direct-http", "tool-native-oauth"].includes(value)) {
+        return value;
+    }
+    throw new Error("unknown MCP proxy mode: " + value);
+}
+function parseMcpSecretStorage(value) {
+    if (["keychain", "libsecret", "windows-credential", "secure-file"].includes(value)) {
+        return value;
+    }
+    throw new Error("unknown MCP secret storage: " + value);
+}
+export async function skillsValidateCommand(options, io) {
+    const report = await validateSkills();
+    if (options.json) {
+        io.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        io.log(report.valid ? "Skills valid" : "Skills invalid");
+        for (const error of report.errors) {
+            io.log(`ERROR: ${error}`);
+        }
+        for (const warning of report.warnings) {
+            io.log(`WARN: ${warning}`);
+        }
+    }
+    if (!report.valid) {
+        throw new Error("skills validation failed");
+    }
+}
+export async function sourcesListCommand(options, io) {
+    const sources = await readSourceOfTruth();
+    if (options.json) {
+        io.log(JSON.stringify(sources, null, 2));
+        return;
+    }
+    for (const source of sources) {
+        io.log(`${source.id ?? "unknown"} - ${source.name ?? "Unnamed source"}`);
+        io.log(`  ${(source.locations ?? []).join(", ")}`);
+    }
+}
+export async function lessonsListCommand(options, io) {
+    const lessons = await listAgentLessons();
+    if (options.json) {
+        io.log(JSON.stringify(lessons, null, 2));
+        return;
+    }
+    if (lessons.length === 0) {
+        io.log("No lessons");
+        return;
+    }
+    for (const lesson of lessons) {
+        io.log(`${lesson.timestamp} ${lesson.operation}: ${lesson.errorSignature}`);
+    }
+}
+export async function lessonsAddCommand(options, io) {
+    const lesson = await addAgentLesson(removeUndefined({
+        taskId: stringOption(options.task),
+        actor: stringOption(options.actor) ?? "parent",
+        operation: requireArg(options, "operation"),
+        failedAction: requireArg(options, "failed-action"),
+        errorSignature: requireArg(options, "error-signature"),
+        rootCause: requireArg(options, "root-cause"),
+        fix: requireArg(options, "fix"),
+        prevention: requireArg(options, "prevention"),
+        appliesTo: parseCsv(options["applies-to"]),
+        verifiedBy: parseCsv(options["verified-by"]),
+    }));
+    if (options.json) {
+        io.log(JSON.stringify(lesson, null, 2));
+        return;
+    }
+    io.log(`Recorded lesson ${lesson.errorSignature}`);
+}
+export async function lessonsPromoteCommand(options, io) {
+    const result = await promoteAgentLessons(removeUndefined({
+        to: parsePromotionTarget(stringOption(options.to) ?? "doc"),
+        filter: stringOption(options.filter),
+    }));
+    if (options.json) {
+        io.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    io.log(`Created ${result.artifact}`);
+    io.log(`Promoted lessons: ${result.lessons.length}`);
+}
+function parsePromotionTarget(value) {
+    if (["skill", "rule", "doc"].includes(value)) {
+        return value;
+    }
+    throw new Error(`unknown promotion target: ${value}`);
+}
+export async function skillsListCommand(options, io) {
+    const skills = listSkills();
+    if (options.json) {
+        io.log(JSON.stringify(skills, null, 2));
+        return;
+    }
+    for (const skill of skills) {
+        io.log(`${skill.id} - ${skill.name} (${skill.loadBudget})`);
+        io.log(`  ${skill.summary}`);
+        io.log(`  sources: ${skill.sourceGroups.join(", ")}`);
+    }
+}
+export async function skillsPlanCommand(options, io) {
+    const plan = await planSkillsForTask(requireArg(options, "task"));
+    await recordSkillPlan(plan);
+    if (options.json) {
+        io.log(JSON.stringify(plan, null, 2));
+        return;
+    }
+    io.log(`Skills for ${plan.taskId}:`);
+    for (const item of plan.selected) {
+        io.log(`  ${item.skill.id} (score ${item.score})`);
+        for (const reason of item.rationale) {
+            io.log(`    - ${reason}`);
+        }
+    }
+    io.log(`Source groups: ${plan.sourceGroups.join(", ")}`);
+}
+export async function skillsRenderCommand(options, io) {
+    const target = parseSkillRenderTarget(stringOption(options.target) ?? "generic");
+    const rendered = await renderSkills({
+        target,
+        taskId: stringOption(options.task),
+        skillIds: parseCsv(options.skills),
+    });
+    await recordSkillRender(rendered);
+    if (options.json) {
+        io.log(JSON.stringify(rendered, null, 2));
+        return;
+    }
+    io.log(rendered.content);
+}
+function parseSkillRenderTarget(value) {
+    return parseRuntimeTarget(value);
+}
+// --- Autonomous workflow commands ---
+const GATE_MODES = ["none", "phase", "all"];
+export async function workflowRunCommand(options, io) {
+    const cwd = process.cwd();
+    const taskId = requireArg(options, "task");
+    const gates = (stringOption(options.gates) ?? "phase");
+    const maxIterations = numberOption(options["max-iterations"], 5);
+    const file = autonomousRunsPath(cwd);
+    if (!GATE_MODES.includes(gates)) {
+        throw new Error(`--gates must be one of: ${GATE_MODES.join(", ")}`);
+    }
+    if (options["dry-run"]) {
+        return workflowDryRun(options, io, taskId, gates, maxIterations);
+    }
+    let run;
+    let startIndex;
+    if (options.resume) {
+        const existing = await readAutonomousRun(cwd, String(options.resume));
+        if (!existing)
+            throw new Error(`workflow run not found: ${String(options.resume)}`);
+        run = existing;
+        startIndex = resumePhaseIndex(run);
+        if (startIndex === -1) {
+            io.log(`Workflow ${run.id} is already complete`);
+            if (options.json)
+                io.log(JSON.stringify({ run, file, cwd }, null, 2));
+            return;
+        }
+        io.log(`Resuming run ${run.id} from phase ${AUTONOMOUS_PHASE_SEQUENCE[startIndex]?.phase}`);
+    }
+    else {
+        run = await createAutonomousRun(cwd, { taskId, gates, maxIterations });
+        startIndex = 0;
+        io.log(`Started autonomous workflow ${run.id} for task ${taskId} [gates=${gates}]`);
+    }
+    run = await executePhases(cwd, run, startIndex, io);
+    const result = { run, file, cwd };
+    if (options.json) {
+        io.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    io.log(run.status === "done"
+        ? `Workflow complete [run=${run.id}]`
+        : run.status === "paused"
+            ? `Workflow paused — approve gate review then run: orchestra workflow run --task ${taskId} --resume ${run.id}`
+            : `Workflow ${run.status} [run=${run.id}]`);
+}
+export async function workflowRunListCommand(options, io) {
+    const cwd = process.cwd();
+    const runs = await listAutonomousRuns(cwd);
+    if (options.json) {
+        io.log(JSON.stringify(runs, null, 2));
+        return;
+    }
+    if (runs.length === 0) {
+        io.log("No workflow runs");
+        return;
+    }
+    for (const run of runs) {
+        const phases = run.phases.map((p) => `${p.phase}:${p.status}`).join(" → ");
+        io.log(`${run.id} [${run.status}] task=${run.taskId} gates=${run.gates}`);
+        if (phases)
+            io.log(`  ${phases}`);
+    }
+}
+const CLARIFICATION_TARGETS = ["po", "architect"];
+const CLARIFICATION_ALLOWED_PHASES = new Set(["developer", "qa"]);
+export async function workflowClarifyCommand(options, io) {
+    const cwd = process.cwd();
+    const runId = requireArg(options, "run");
+    const from = requireArg(options, "from");
+    const to = requireArg(options, "to");
+    const question = requireArg(options, "question");
+    if (!CLARIFICATION_TARGETS.includes(to)) {
+        throw new Error(`--to must be one of: ${CLARIFICATION_TARGETS.join(", ")}`);
+    }
+    const run = await readAutonomousRun(cwd, runId);
+    if (!run)
+        throw new Error(`workflow run not found: ${runId}`);
+    // Find the active phase (running or already awaiting_clarification)
+    const activePhaseIdx = run.phases.findIndex((p) => p.role === from &&
+        (p.status === "running" || p.status === "awaiting_clarification"));
+    if (activePhaseIdx === -1) {
+        throw new Error(`no active phase found for role ${from} in run ${runId}`);
+    }
+    const activePhase = run.phases[activePhaseIdx];
+    if (!CLARIFICATION_ALLOWED_PHASES.has(activePhase.phase)) {
+        throw new Error(`clarification is only allowed from developer or qa phases (active: ${activePhase.phase})`);
+    }
+    // Open clarification record
+    const record = await openClarification(cwd, {
+        runId,
+        taskId: run.taskId,
+        fromRole: from,
+        to,
+        question,
+    });
+    // Suspend the phase if it's still running
+    if (activePhase.status === "running") {
+        const phaseSeqIdx = AUTONOMOUS_PHASE_SEQUENCE.findIndex((d) => d.phase === activePhase.phase);
+        await suspendPhaseForClarification(cwd, run, phaseSeqIdx);
+    }
+    if (options.json) {
+        io.log(JSON.stringify(record, null, 2));
+        return;
+    }
+    io.log(`Clarification ${record.id} opened — waiting for ${record.toRole}`);
+    io.log(`  Question: ${record.question}`);
+    io.log(`  Respond with:`);
+    io.log(`  orchestra workflow clarify-respond --run ${runId} --clarification ${record.id} --answer "<text>"`);
+}
+export async function workflowClarifyRespondCommand(options, io) {
+    const cwd = process.cwd();
+    const runId = requireArg(options, "run");
+    const clarificationId = requireArg(options, "clarification");
+    const answer = requireArg(options, "answer");
+    const run = await readAutonomousRun(cwd, runId);
+    if (!run)
+        throw new Error(`workflow run not found: ${runId}`);
+    const record = await answerClarification(cwd, {
+        id: clarificationId,
+        answer,
+    });
+    // Resume the suspended phase back to running
+    const phaseSeqIdx = AUTONOMOUS_PHASE_SEQUENCE.findIndex((d) => d.role === record.fromRole);
+    if (phaseSeqIdx !== -1) {
+        const phase = run.phases.find((p) => p.role === record.fromRole);
+        if (phase?.status === "awaiting_clarification") {
+            await resumePhaseFromClarification(cwd, run, phaseSeqIdx);
+        }
+    }
+    if (options.json) {
+        io.log(JSON.stringify(record, null, 2));
+        return;
+    }
+    io.log(`Clarification ${record.id} answered`);
+    io.log(`  Answer: ${record.answer}`);
+    io.log(`  Resume with:`);
+    io.log(`  orchestra workflow run --task ${run.taskId} --resume ${runId}`);
+}
+export async function workflowClarifyListCommand(options, io) {
+    const cwd = process.cwd();
+    const runId = requireArg(options, "run");
+    const clarifications = await listClarifications(cwd, runId);
+    if (options.json) {
+        io.log(JSON.stringify(clarifications, null, 2));
+        return;
+    }
+    if (clarifications.length === 0) {
+        io.log(`No clarifications for run ${runId}`);
+        return;
+    }
+    for (const c of clarifications) {
+        const status = c.status === "answered" ? "✓" : "⏳";
+        io.log(`${status} [${c.id}] ${c.fromRole} → ${c.toRole}`);
+        io.log(`  Q: ${c.question}`);
+        if (c.answer)
+            io.log(`  A: ${c.answer}`);
+    }
+}
+const DEV_PHASE_INDEX = AUTONOMOUS_PHASE_SEQUENCE.findIndex((d) => d.phase === "developer");
+async function executePhases(cwd, run, startIndex, io) {
+    let current = run;
+    let qaFailNotes;
+    for (let i = startIndex; i < AUTONOMOUS_PHASE_SEQUENCE.length; i++) {
+        const def = AUTONOMOUS_PHASE_SEQUENCE[i];
+        // Init phase task (skip if already has a running/done/clarification record from resume)
+        const existing = current.phases.find((p) => p.phase === def.phase && p.status !== "qa_failed");
+        if (!existing || existing.status === "pending") {
+            const retryContext = def.phase === "developer" && qaFailNotes ? qaFailNotes : undefined;
+            const phaseRecord = await initPhase(cwd, current, i, retryContext);
+            current = { ...current, phases: [...current.phases, phaseRecord] };
+            if (retryContext) {
+                io.log(`↺ ${def.phase} (${def.role}) retry — QA findings: ${retryContext.slice(0, 80)}`);
+            }
+            else {
+                io.log(`→ ${def.phase} (${def.role}) task=${phaseRecord.taskId}`);
+            }
+        }
+        else if (existing.status === "awaiting_clarification") {
+            io.log(`↺ ${def.phase} (${def.role}) resuming after clarification`);
+        }
+        // Architect sizing gate — always enforced regardless of --gates mode
+        if (def.phase === "architect") {
+            const sizing = await checkArchitectSizing(cwd, current.taskId);
+            if (!sizing.found) {
+                io.log(`⚠ Architect phase requires a sizing decision before handoff to developer.`);
+                io.log(`  Record one with:`);
+                io.log(`  orchestra decision add --task ${current.taskId} --owner architect --title "Story sizing" --decision "<xs|s|m|l|xl> [N points]" --context "..." --consequences "..." --status accepted`);
+                io.log(`  Then resume: orchestra workflow run --task ${current.taskId} --resume ${current.id}`);
+                current = await markRunFailed(cwd, current, "Architect sizing decision required before developer handoff");
+                return current;
+            }
+            io.log(`  ✓ sizing=${sizing.sizing}${sizing.points !== undefined ? ` (${sizing.points} pts)` : ""}`);
+        }
+        // QA loop guard
+        if (def.phase === "qa" && current.qaIterations >= current.maxIterations) {
+            io.log(`✗ QA failed after ${current.maxIterations} iterations — workflow blocked`);
+            current = await markRunFailed(cwd, current, `Max QA iterations (${current.maxIterations}) reached`);
+            return current;
+        }
+        // Determine outcome — QA phase can fail and route back to developer
+        // When LLM execution lands (ORCH-019), this will be the actual QA verdict.
+        // For now the outcome is always done; qa_fail is exercised via tests/simulation.
+        const outcome = {
+            kind: "done",
+            notes: def.summary,
+        };
+        const result = await closePhase(cwd, current, i, outcome);
+        current = result.run;
+        if (result.handoffArtifact) {
+            io.log(`  ✓ handoff → ${AUTONOMOUS_PHASE_SEQUENCE[i + 1]?.role ?? "end"} (${result.handoffArtifact})`);
+        }
+        if (result.reviewArtifact) {
+            io.log(`  ⏸ gate ${def.phase}→${AUTONOMOUS_PHASE_SEQUENCE[i + 1]?.phase} — review: ${result.reviewArtifact}`);
+            io.log(`  Approve: orchestra workflow run --task ${current.taskId} --resume ${current.id}`);
+            return current;
+        }
+        // QA failure — loop back to developer with findings as context
+        const closedPhase = current.phases.find((p) => p.phase === def.phase && p.status === "qa_failed");
+        if (closedPhase) {
+            qaFailNotes = closedPhase.notes ?? "QA findings — see QA phase artifact";
+            io.log(`  ✗ qa failed (iteration ${current.qaIterations}/${current.maxIterations}) — routing back to developer`);
+            i = DEV_PHASE_INDEX - 1; // will be incremented to DEV_PHASE_INDEX at top of loop
+            continue;
+        }
+        // Release phase: auto-create PR if configured
+        if (def.phase === "release") {
+            const config = await getWorkflowConfig(cwd);
+            if (config.github?.autoCreatePr) {
+                try {
+                    const prSummary = await generatePullRequestSummary(current.taskId, cwd);
+                    const prBody = buildPrBody(prSummary, current.qaIterations);
+                    const prTitle = `${current.taskId}: ${prSummary.task.title}`;
+                    const prResult = await createPullRequest({
+                        title: prTitle,
+                        body: prBody,
+                        ...(config.github.baseBranch
+                            ? { baseBranch: config.github.baseBranch }
+                            : {}),
+                    });
+                    await addEvidence({
+                        task: current.taskId,
+                        role: "release_manager",
+                        type: "report",
+                        summary: `PR created: ${prResult.url}`,
+                    }, cwd);
+                    io.log(`  ✓ PR created: ${prResult.url}`);
+                }
+                catch (err) {
+                    io.log(`  ⚠ PR creation failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        }
+    }
+    current = await markRunDone(cwd, current);
+    return current;
+}
+async function workflowDryRun(options, io, taskId, gates, maxIterations) {
+    const gateTransitions = new Set(["po→architect", "qa→release"]);
+    io.log(`Dry run — no records will be created`);
+    io.log(`Task: ${taskId}  gates: ${gates}  max-iterations: ${maxIterations}`);
+    io.log(``);
+    for (let i = 0; i < AUTONOMOUS_PHASE_SEQUENCE.length; i++) {
+        const def = AUTONOMOUS_PHASE_SEQUENCE[i];
+        const next = AUTONOMOUS_PHASE_SEQUENCE[i + 1];
+        const transitionKey = next ? `${def.phase}→${next.phase}` : "";
+        const gateLabel = gates === "all"
+            ? "gate=yes"
+            : gates === "phase" && gateTransitions.has(transitionKey)
+                ? "gate=yes"
+                : "gate=no";
+        io.log(`  ${def.phase} (${def.role})  ${gateLabel}`);
+    }
+    if (options.json) {
+        io.log(JSON.stringify({
+            dryRun: true,
+            taskId,
+            gates,
+            maxIterations,
+            phases: AUTONOMOUS_PHASE_SEQUENCE,
+        }, null, 2));
+    }
+}
+// --- Estimate & Benchmark commands ---
+const CONFIDENCE_LEVELS = ["low", "medium", "high"];
+export async function estimateCommand(options, io) {
+    const cwd = process.cwd();
+    const taskId = requireArg(options, "task");
+    const sizingRaw = requireArg(options, "sizing");
+    const soloDays = numberOption(options["solo-days"], 0);
+    const aiDays = numberOption(options["ai-unguided-days"], 0);
+    const confidence = (stringOption(options.confidence) ??
+        "medium");
+    const declaredBy = stringOption(options["declared-by"]) ?? "pm";
+    if (!SIZING_LABELS.includes(sizingRaw)) {
+        throw new Error(`--sizing must be one of: ${SIZING_LABELS.join(", ")}`);
+    }
+    if (!CONFIDENCE_LEVELS.includes(confidence)) {
+        throw new Error(`--confidence must be one of: ${CONFIDENCE_LEVELS.join(", ")}`);
+    }
+    if (soloDays <= 0)
+        throw new Error(`--solo-days must be > 0`);
+    if (aiDays <= 0)
+        throw new Error(`--ai-unguided-days must be > 0`);
+    const record = await recordEstimate(cwd, {
+        taskId,
+        sizingLabel: sizingRaw,
+        soloEstimateDays: soloDays,
+        aiUnguidedEstimateDays: aiDays,
+        confidence,
+        declaredBy,
+    });
+    if (options.json) {
+        io.log(JSON.stringify(record, null, 2));
+        return;
+    }
+    io.log(`Estimate recorded for ${taskId} [${record.id}]`);
+    io.log(`  Sizing:      ${record.sizingLabel}`);
+    io.log(`  Solo:        ${record.soloEstimateDays}d`);
+    io.log(`  AI-unguided: ${record.aiUnguidedEstimateDays}d`);
+    io.log(`  Confidence:  ${record.confidence}`);
+    io.log(`  Declared by: ${record.declaredBy}`);
+}
+export async function benchmarkCommand(options, io) {
+    const cwd = process.cwd();
+    if (options.summary) {
+        const summary = await summarizeBenchmark(cwd);
+        if (options.json) {
+            io.log(JSON.stringify(summary, null, 2));
+            return;
+        }
+        if (summary.stories.length === 0) {
+            io.log("No estimates recorded yet. Use: orchestra estimate --task <id> ...");
+            return;
+        }
+        const header = `${"Story".padEnd(14)} ${"Size".padEnd(4)} ${"Solo".padEnd(6)} ${"AI".padEnd(6)} ${"Actual".padEnd(8)} ${"vs Solo".padEnd(8)} ${"vs AI".padEnd(8)} ${"QA".padEnd(4)} ${"Rev".padEnd(4)} ${"Blk".padEnd(4)} ${"Ev".padEnd(4)} ${"Les"}`;
+        io.log(header);
+        io.log("─".repeat(header.length));
+        for (const s of summary.stories) {
+            const actual = s.actualDays !== null ? `${s.actualDays}d` : "pending";
+            const vsSolo = s.vsSoloPct !== null
+                ? `${s.vsSoloPct > 0 ? "+" : ""}${s.vsSoloPct}%`
+                : "—";
+            const vsAi = s.vsAiUnguidedPct !== null
+                ? `${s.vsAiUnguidedPct > 0 ? "+" : ""}${s.vsAiUnguidedPct}%`
+                : "—";
+            io.log(`${s.taskId.padEnd(14)} ${s.sizingLabel.padEnd(4)} ${`${s.soloEstimateDays}d`.padEnd(6)} ${`${s.aiUnguidedEstimateDays}d`.padEnd(6)} ${actual.padEnd(8)} ${vsSolo.padEnd(8)} ${vsAi.padEnd(8)} ${String(s.qaIterations).padEnd(4)} ${String(s.quality.reviewCount).padEnd(4)} ${String(s.quality.blockingReviews).padEnd(4)} ${String(s.quality.evidenceCount).padEnd(4)} ${s.quality.lessonCount}`);
+        }
+        if (summary.totalWithActuals > 0) {
+            io.log("");
+            io.log(`Avg savings vs solo:        ${summary.avgVsSoloPct}%`);
+            io.log(`Avg savings vs AI-unguided: ${summary.avgVsAiUnguidedPct}%`);
+            io.log(`Stories with actuals:       ${summary.totalWithActuals}/${summary.stories.length}`);
+        }
+        return;
+    }
+    const taskId = requireArg(options, "task");
+    const result = await computeBenchmark(cwd, taskId);
+    if (options.json) {
+        io.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    io.log(`Benchmark: ${taskId}  [${result.status}]`);
+    io.log(`  Sizing:      ${result.sizingLabel}`);
+    io.log(`  Solo:        ${result.soloEstimateDays}d  (declared)`);
+    io.log(`  AI-unguided: ${result.aiUnguidedEstimateDays}d  (declared)`);
+    io.log(`  Actual:      ${result.actualDays !== null ? `${result.actualDays}d` : "pending — run not complete"}`);
+    if (result.vsSoloPct !== null) {
+        const sign = result.vsSoloPct > 0 ? "+" : "";
+        io.log(`  vs Solo:     ${sign}${result.vsSoloPct}%`);
+        io.log(`  vs AI:       ${result.vsAiUnguidedPct !== null ? `${result.vsAiUnguidedPct > 0 ? "+" : ""}${result.vsAiUnguidedPct}%` : "—"}`);
+    }
+    io.log(`  QA loops:    ${result.qaIterations}`);
+    io.log(`  Reviews:     ${result.quality.reviewCount} (${result.quality.blockingReviews} blocking)`);
+    io.log(`  Evidence:    ${result.quality.evidenceCount} artifacts`);
+    io.log(`  Gate blocks: ${result.quality.gateBlockCount}`);
+    io.log(`  Lessons:     ${result.quality.lessonCount}`);
+    if (result.quality.totalInputTokens > 0 ||
+        result.quality.totalOutputTokens > 0) {
+        io.log(`  Tokens:      ${result.quality.totalInputTokens}in / ${result.quality.totalOutputTokens}out`);
+        io.log(`  Cost:        $${result.quality.estimatedCostUsd}`);
+    }
+}
+// --- Burndown command ---
+export async function burndownCommand(options, io) {
+    const cwd = process.cwd();
+    const sprintCsv = requireArg(options, "sprint");
+    const sprintTaskIds = sprintCsv
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    if (sprintTaskIds.length === 0)
+        throw new Error(`--sprint requires at least one task id`);
+    const series = await computeSprintBurndown(cwd, sprintTaskIds);
+    if (options.json) {
+        io.log(JSON.stringify(series, null, 2));
+        return;
+    }
+    for (const w of series.warnings)
+        io.log(`⚠ ${w}`);
+    if (series.totalPoints === 0) {
+        io.log("No points to chart — record estimates first with: orchestra estimate --task <id> ...");
+        return;
+    }
+    io.log(`Sprint burndown  total=${series.totalPoints} pts  tasks=${series.sprintTaskIds.length}`);
+    io.log("");
+    io.log(renderBurndownAscii(series));
+    io.log("");
+    io.log("Task breakdown:");
+    for (const t of series.taskBreakdown) {
+        const arch = t.architectPoints !== null ? `arch=${t.architectPoints}` : "arch=—";
+        const dev = t.developerPoints !== null ? `dev=${t.developerPoints}` : "dev=—";
+        const done = t.completedAt
+            ? `done ${t.completedAt.slice(0, 10)}`
+            : "pending";
+        io.log(`  ${t.taskId.padEnd(14)} ${arch.padEnd(10)} ${dev.padEnd(10)} resolved=${t.resolvedPoints}  ${done}`);
+    }
+}
+function parseRuntimeTargetOptions(options) {
+    const targetValues = [
+        ...parseCsv(options.target),
+        ...parseCsv(options.targets),
+    ];
+    return [...new Set(targetValues)].map((target) => parseRuntimeTarget(target));
+}
 function parseCsv(value) {
     if (typeof value !== "string" || value.trim() === "") {
         return [];
@@ -759,6 +1763,20 @@ function renderPullRequestSummaryMarkdown(summary) {
         "## Risks",
         ...listOrNone(summary.risks),
         "",
+        "## Review Routing",
+        `- Merge blocked: ${summary.review.mergeBlocked}`,
+        `- Required reviewers: ${summary.review.requiredReviewers.join(", ") || "none"}`,
+        `- Missing reviewers: ${summary.review.missingReviewers.join(", ") || "none"}`,
+        "",
+        "## Review Checklist",
+        ...listOrNone(summary.review.checklist),
+        "",
+        "## Evidence Gaps",
+        ...listOrNone(summary.review.evidenceGaps),
+        "",
+        "## Merge Blockers",
+        ...listOrNone(summary.review.mergeBlockers),
+        "",
         "## Gates",
         ...eventLines(summary.gates),
         "",
@@ -784,6 +1802,34 @@ function renderPullRequestSummaryMarkdown(summary) {
         "",
     ].join("\n");
 }
+function renderDelegationDecisionMarkdown(decision) {
+    return [
+        `# Delegation Decision: ${decision.taskId}`,
+        "",
+        `- Recommendation: ${decision.recommendation}`,
+        `- Complexity score: ${decision.complexityScore}`,
+        `- Urgency: ${decision.urgency}`,
+        `- Disjoint write scopes: ${String(decision.disjointWriteScopes)}`,
+        "",
+        "## Rationale",
+        ...listOrNone(decision.rationale),
+        "",
+        "## Blocking Conditions",
+        ...listOrNone(decision.blockingConditions),
+        "",
+        "## Context Bundle",
+        ...listOrNone(decision.contextBundle),
+        "",
+        "## Delegates",
+        ...(decision.delegates.length === 0
+            ? ["- none"]
+            : decision.delegates.map((delegate) => `- ${delegate.role} [${delegate.mode}] scopes=${delegate.writeScopes.join(",") || "none"}`)),
+        "",
+        "## Expected Outputs",
+        ...listOrNone(decision.expectedOutputs),
+        "",
+    ].join("\n");
+}
 function renderTaskContextMarkdown(context) {
     return [
         `# Task Context: ${context.task.id}`,
@@ -794,6 +1840,27 @@ function renderTaskContextMarkdown(context) {
         `- Dependencies: ${context.dependencies.isSatisfied ? "satisfied" : "blocked"}`,
         `- Locks: ${context.locks.length}`,
         `- Risks: ${context.risks.length}`,
+        `- Delegation: ${context.delegation?.recommendation ?? "not decided"}`,
+        "",
+        "## Collaboration Flow",
+        ...(context.collaborationFlow
+            ? [
+                `- ${context.collaborationFlow.flow.id}: ${context.collaborationFlow.flow.name}`,
+                `- Missing artifacts: ${context.collaborationFlow.missingArtifacts.join(", ") || "none"}`,
+                `- Reviewers: ${context.collaborationFlow.optionalReviewers.join(", ") || "none"}`,
+            ]
+            : ["- none"]),
+        "",
+        "## Workflow Templates",
+        ...(context.workflowTemplates.length === 0
+            ? ["- none"]
+            : context.workflowTemplates.map((item) => `- ${item.template.id} (score ${item.score}, missing evidence ${item.missingEvidence.join(", ") || "none"})`)),
+        "",
+        "## Skills",
+        ...(context.skills.selected.length === 0
+            ? ["- none"]
+            : context.skills.selected.map((item) => `- ${item.skill.id} (score ${item.score}): ${item.rationale.join("; ")}`)),
+        `- Source groups: ${context.skills.sourceGroups.join(", ") || "none"}`,
         "",
         "## Decisions",
         ...eventLines(context.decisions),