peaks-loop 4.1.2 → 4.1.4

package/dist/cli/commands/workflow-plan-helpers.js

@@ -0,0 +1,103 @@
+// The planning helpers `peaks refactor | tech | workflow | swarm` share: the workspace
+// context readers, the injected-input parsers, and the pre-step that builds
+// peaks-context before peaks-rd runs. No command is registered here.
+import { printResult } from '../cli-helpers.js';
+import { fail } from 'peaks-loop-shared/result';
+import { isCodeMode } from '../../services/workflow/workflow-router-service.js';
+import { getWorkspaceConfigForPath } from '../../services/config/config-service.js';
+import { getLocalArtifactPath } from '../../services/artifacts/workspace-service.js';
+import { getSessionId } from '../../services/session/session-manager.js';
+import { getSessionDir } from '../../services/session/getSessionDir.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+// Plan 1 / Task 9 — auto-build peaks-context before peaks-rd runs.
+import { buildContext } from '../../services/context/context-builder.js';
+// Plan 1 / Task 10 — production fetcher (replaces mockFetcher).
+import { createDocCacheFetcher } from '../../services/context/doc-cache-fetcher.js';
+export function buildDocFetcher(sid) {
+    return createDocCacheFetcher({
+        cacheDir: `.peaks/_runtime/${sid}/doc-cache`
+        // remoteFetcher wired in a future slice.
+    });
+}
+export async function ensureContextForRd(goal, project, sid) {
+    const out = `.peaks/_runtime/${sid}/context.json`;
+    try {
+        await buildContext({
+            goal,
+            project,
+            audience: 'peaks-rd',
+            depsMode: 'locked',
+            docBudgetTokens: 8000,
+            out,
+            fetcher: buildDocFetcher(sid)
+        });
+    }
+    catch (error) {
+        // Plan 1 / Task 9 — context is a pre-step, not a precondition.
+        // If the Collector (e.g. missing package.json) or DocRetriever
+        // fails, we still want the rd slice to proceed. Task 11
+        // upgrades this to a hard precondition once the rd slice
+        // actually consumes context.json.
+        const message = error instanceof Error ? error.message : 'unknown context build failure';
+        process.stderr.write(`[peaks-context] rd pre-step skipped: ${message}\n`);
+    }
+}
+export function getCurrentWorkspaceContext() {
+    try {
+        const projectRoot = findProjectRoot(process.cwd()) ?? process.cwd();
+        const sessionId = getSessionId(projectRoot);
+        return sessionId ? { sessionId, sessionDir: getSessionDir(projectRoot, sessionId) } : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function getWorkflowWorkspaceContext() {
+    try {
+        const projectRoot = findProjectRoot(process.cwd()) ?? process.cwd();
+        const workspace = getWorkspaceConfigForPath(projectRoot);
+        if (!workspace)
+            return { projectRoot };
+        return { projectRoot, workspace, artifactWorkspacePath: getLocalArtifactPath(workspace) };
+    }
+    catch {
+        return {};
+    }
+}
+export function parseMaxWorkers(io, command, value, asJson) {
+    const maxWorkers = Number(value);
+    if (!Number.isInteger(maxWorkers) || maxWorkers < 1) {
+        printResult(io, fail(command, 'INVALID_MAX_WORKERS', 'max-workers must be a positive integer', {}, [
+            'Use --max-workers with a positive integer value'
+        ]), asJson);
+        process.exitCode = 1;
+        return null;
+    }
+    return maxWorkers;
+}
+export function validatePlanningInput(goal) {
+    // v2.17.0: change-id axis removed. The planning input is now keyed
+    // by the session id (already bound via `peaks workspace init`),
+    // not by a user-supplied change-id. Only the goal is validated.
+    if (!goal.trim()) {
+        throw new Error('Goal must be non-empty');
+    }
+}
+export function parseCodeMode(io, command, mode, codeMode, asJson) {
+    if (mode !== 'code' && codeMode) {
+        printResult(io, fail(command, 'CODE_MODE_REQUIRES_CODE_WORKFLOW', '--code-mode can only be used with --mode code', {}, ['Remove --code-mode or use --mode code']), asJson);
+        process.exitCode = 1;
+        return null;
+    }
+    if (mode !== 'code' || !codeMode) {
+        return undefined;
+    }
+    if (!isCodeMode(codeMode)) {
+        printResult(io, fail(command, 'UNSUPPORTED_CODE_MODE', `Unsupported code mode ${codeMode}`, {}, [
+            'Use --code-mode full-auto, guided, or rnd'
+        ]), asJson);
+        process.exitCode = 1;
+        return null;
+    }
+    return codeMode;
+}

package/dist/cli/commands/workflow-planning-commands.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerWorkflowPlanningCommands(program: Command, io: ProgramIO): Command;

package/dist/cli/commands/workflow-planning-commands.js

@@ -0,0 +1,56 @@
+import { addJsonOption, failUnsupportedNonDryRun, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { createRefactorDryRun } from '../../services/refactor/refactor-service.js';
+// `peaks tech status-change-id`). Additive; the existing session-axis
+// `peaks tech plan` / `peaks tech status` registrations are untouched.
+import { registerTechCommands } from './tech-commands.js';
+import { addTechPlanOptions, addTechStatusOptions, addWorkflowRouteOptions, runAutonomousWorkflow, runTechPlan, runTechStatus, runWorkflowRoute } from './workflow-tech-actions.js';
+import { addAutonomousResumeInitOptions, runAutonomousResumeInit } from './workflow-swarm-actions.js';
+/** The `peaks refactor` registration, lifted verbatim out of the planning registrar. */
+function registerRefactorCommand(program, io) {
+    const refactor = program
+        .command('refactor')
+        .description('Plan a Peaks refactor run without modifying code');
+    addJsonOption(refactor
+        .option('--code', 'use peaks-code orchestration mode')
+        .option('--rd', 'use peaks-rd direct mode')
+        .option('--dry-run', 'print gates and required artifacts', true)
+        .option('--no-dry-run', 'unsupported: do not modify code from this command')).action((options) => {
+        if (options.dryRun === false) {
+            failUnsupportedNonDryRun(io, 'refactor', options.json);
+            return;
+        }
+        if (options.code && options.rd) {
+            printResult(io, fail('refactor', 'CONFLICTING_REFACTOR_MODE', 'Choose either --code or --rd, not both', {}, ['Run peaks refactor --code --dry-run']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        const mode = options.rd ? 'rd' : 'code';
+        printResult(io, ok('refactor', createRefactorDryRun(mode), [], ['This dry run never edits code']), options.json);
+    });
+}
+export function registerWorkflowPlanningCommands(program, io) {
+    registerRefactorCommand(program, io);
+    const tech = program.command('tech').description('Plan and inspect technical dry-run gates');
+    addTechPlanOptions(tech.command('plan')).action((options) => runTechPlan(io, options));
+    addTechStatusOptions(tech.command('status')).action((options) => runTechStatus(io, options));
+    addTechPlanOptions(program.command('tech-plan')).action((options) => runTechPlan(io, options));
+    addTechStatusOptions(program.command('tech-status')).action((options) => runTechStatus(io, options));
+    // (`peaks tech plan-change-id` / `peaks tech status-change-id`).
+    // Additive; the session-axis registrations above are byte-for-byte untouched.
+    registerTechCommands(program, io);
+    const workflow = program.command('workflow').description('Plan workflow routing dry-run graphs');
+    addWorkflowRouteOptions(workflow.command('route'), 'Plan a workflow routing dry-run summary').action((options) => runWorkflowRoute(io, options));
+    addWorkflowRouteOptions(program.command('route'), 'Plan a workflow routing dry-run summary').action((options) => runWorkflowRoute(io, options));
+    addWorkflowRouteOptions(workflow.command('autonomous'), 'Plan an autonomous workflow handoff summary').action((options) => runAutonomousWorkflow(io, options));
+    addWorkflowRouteOptions(program.command('autonomous'), 'Plan an autonomous workflow handoff summary').action((options) => runAutonomousWorkflow(io, options));
+    const autonomousResume = workflow
+        .command('autonomous-resume')
+        .description('Manage autonomous workflow resume artifacts');
+    addAutonomousResumeInitOptions(autonomousResume.command('init')).action((options) => runAutonomousResumeInit(io, options));
+    const autonomousResumeAlias = program
+        .command('autonomous-resume')
+        .description('Manage autonomous workflow resume artifacts');
+    addAutonomousResumeInitOptions(autonomousResumeAlias.command('init')).action((options) => runAutonomousResumeInit(io, options));
+    return workflow;
+}

package/dist/cli/commands/workflow-swarm-actions.d.ts

@@ -0,0 +1,7 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+import { type AutonomousResumeInitOptions, type SwarmPlanOptions } from './workflow-plan-helpers.js';
+export declare function runSwarmPlan(io: ProgramIO, options: SwarmPlanOptions): Promise<void>;
+export declare function runAutonomousResumeInit(io: ProgramIO, options: AutonomousResumeInitOptions): Promise<void>;
+export declare function addSwarmPlanOptions(command: Command, includeSkill: boolean): Command;
+export declare function addAutonomousResumeInitOptions(command: Command): Command;

package/dist/cli/commands/workflow-swarm-actions.js

@@ -0,0 +1,109 @@
+import { createRdSwarmPlan } from '../../services/rd/rd-service.js';
+import { writeAutonomousResumeArtifacts } from '../../services/workflow/autonomous-resume-writer.js';
+import { readConfig } from '../../services/config/config-service.js';
+import { getEconomyAwareExecutionModelId } from '../../services/config/model-routing.js';
+import { getSessionId } from '../../services/session/session-manager.js';
+import { addJsonOption, failUnsupportedNonDryRun, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+// catch site below (swarm.plan) so provider-config errors surface as
+// `INVALID_PROVIDERS` instead of being silently re-labelled `INVALID_GOAL`.
+import { mapServiceError } from './_cli-error-envelope.js';
+import { ensureContextForRd, getWorkflowWorkspaceContext, parseMaxWorkers, validatePlanningInput } from './workflow-plan-helpers.js';
+export async function runSwarmPlan(io, options) {
+    if ((options.skill ?? 'rd') !== 'rd') {
+        printResult(io, fail('swarm.plan', 'UNSUPPORTED_SWARM_SKILL', `Unsupported skill ${options.skill}`, {}, [
+            'Use --skill rd'
+        ]), options.json);
+        process.exitCode = 1;
+        return;
+    }
+    if (options.dryRun === false) {
+        failUnsupportedNonDryRun(io, 'swarm.plan', options.json);
+        return;
+    }
+    const maxWorkers = parseMaxWorkers(io, 'swarm.plan', options.maxWorkers, options.json);
+    if (maxWorkers === null)
+        return;
+    try {
+        validatePlanningInput(options.goal);
+        const workspaceContext = getWorkflowWorkspaceContext();
+        const config = readConfig();
+        // Plan 1 / Task 9 — pre-build peaks-context before peaks-rd runs.
+        const projectRoot = workspaceContext.projectRoot ?? process.cwd();
+        const sid = getSessionId(projectRoot) ?? 'ad-hoc';
+        await ensureContextForRd(options.goal, projectRoot, sid);
+        const plan = createRdSwarmPlan({
+            skill: 'rd',
+            sessionId: '',
+            goal: options.goal,
+            maxWorkers,
+            dryRun: true,
+            swarmMode: config.swarmMode ?? true,
+            executionModelId: getEconomyAwareExecutionModelId(config),
+            ...(options.strictStandards ? { strictStandards: true } : {}),
+            ...workspaceContext
+        });
+        // The service-layer stamps `standardsErrorCode` onto the envelope; the
+        // CLI is responsible for translating it into a non-zero exit.
+        if (plan.gateStatus.standardsErrorCode === 'EPEAKS_NO_STANDARDS') {
+            process.exitCode = 1;
+        }
+        printResult(io, ok('swarm.plan', plan), options.json);
+    }
+    catch (error) {
+        const mapping = mapServiceError(error);
+        printResult(io, fail('swarm.plan', mapping.code, getErrorMessage(error), {}, [...mapping.nextActions]), options.json);
+        process.exitCode = 1;
+    }
+}
+export async function runAutonomousResumeInit(io, options) {
+    try {
+        if (!options.project || !options.project.trim()) {
+            throw new Error('Project path must be non-empty');
+        }
+        // gone. The CLI surfaces a deterministic placeholder
+        // (`session-default`) when the user does not pass a change-id, so
+        // the on-disk session-dir join via `getSessionDir` succeeds (the
+        // writer still requires a safe non-empty string).
+        const result = await writeAutonomousResumeArtifacts({
+            sessionId: 'session-default',
+            goal: options.goal,
+            artifactWorkspacePath: options.project,
+            apply: options.apply === true
+        });
+        const data = {
+            applied: result.applied,
+            files: result.files.map((file) => file.path)
+        };
+        const nextActions = result.applied
+            ? ['Run peaks workflow autonomous --goal "<goal>" --json to verify resumePlan.status']
+            : ['Re-run with --apply to write the resume scaffold to disk'];
+        printResult(io, ok('autonomous-resume.init', data, [], nextActions), options.json);
+    }
+    catch (error) {
+        printResult(io, fail('autonomous-resume.init', 'AUTONOMOUS_RESUME_INIT_FAILED', getErrorMessage(error), {}, [
+            'Use a non-empty goal and a writable project path'
+        ]), options.json);
+        process.exitCode = 1;
+    }
+}
+export function addSwarmPlanOptions(command, includeSkill) {
+    const configured = command
+        .description('Plan an RD swarm dry-run graph')
+        .requiredOption('--goal <goal>', 'planning goal')
+        .option('--max-workers <count>', 'maximum worker count', '40')
+        .option('--dry-run', 'preview without writing files', true)
+        .option('--no-dry-run', 'unsupported: do not execute RD planning from this CLI')
+        .option('--strict-standards', 'hard-fail (exit non-zero) when project-local standards are missing; surfaces EPEAKS_NO_STANDARDS in the JSON envelope');
+    if (includeSkill) {
+        configured.requiredOption('--skill <skill>', 'skill to plan for');
+    }
+    return addJsonOption(configured);
+}
+export function addAutonomousResumeInitOptions(command) {
+    return addJsonOption(command
+        .description('Write the autonomous resume artifact scaffold for the active change-id')
+        .requiredOption('--goal <goal>', 'planning goal')
+        .requiredOption('--project <path>', 'artifact workspace path to write under')
+        .option('--apply', 'write the artifacts to disk (default is dry-run preview)'));
+}

package/dist/cli/commands/workflow-swarm-commands.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerWorkflowSwarmCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/workflow-swarm-commands.js

@@ -0,0 +1,138 @@
+import { addJsonOption, isRecommendationWorkflow, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { createRecommendationPlan } from '../../services/recommendations/recommendation-service.js';
+import { readConfig } from '../../services/config/config-service.js';
+import { registerSwarmCommands } from './swarm-commands.js';
+// `registerTechCommands` registrations are byte-for-byte untouched.
+import { registerAutonomousSwarmCommands } from './autonomous-swarm-commands.js';
+// Slice 4.0.8 — workflow lifecycle (init / graph show / graph list / node
+// prepare / node ack / node mark-lost / terminalize). Registered as a
+// sibling command group, not merged with planning handlers, per RD §4.
+import { registerWorkflowLifecycleCommand } from './workflow-lifecycle-commands.js';
+import { addSwarmPlanOptions, runSwarmPlan } from './workflow-swarm-actions.js';
+/** The `13.2` pipeline placeholder action, lifted verbatim out of the registrar. */
+function runSwarmPipelinePlaceholder(options, io) {
+    printResult(io, ok('swarm.pipeline', {
+        project: options.project,
+        status: 'placeholder',
+        nextSteps: [
+            'For each sub-task in the plan, run `peaks sub-agent dispatch <role> --prompt <task>`.',
+            'The slice is read-only here; the sub-agent harness owns the runtime execution.'
+        ]
+    }, [], [
+        'swarm.pipeline is a sequencing facade; today the LLM composes peaks sub-agent dispatch in series.'
+    ]), options.json);
+}
+/** The `13.3` speculative-dispatch placeholder action, lifted verbatim out of the registrar. */
+function runSwarmDispatchPlaceholder(options, io) {
+    printResult(io, ok('swarm.dispatch', {
+        project: options.project,
+        speculative: options.speculative,
+        status: 'placeholder'
+    }, [], [
+        options.speculative
+            ? 'Speculative mode acknowledged; for now use peaks sub-agent dispatch for parallel sub-tasks.'
+            : 'Pass --speculative to acknowledge speculative mode (no-op for now).'
+    ]), options.json);
+}
+/** The `13.4` adversarial-verification placeholder action, lifted verbatim out of the registrar. */
+function runSwarmVerifyPlaceholder(options, io) {
+    const n = Number.parseInt(options.skeptics, 10);
+    const iterations = Number.isFinite(n) && n > 0 ? n : 1;
+    const history = [];
+    for (let i = 1; i <= iterations; i++) {
+        history.push({
+            iteration: i,
+            ok: true,
+            detail: `iter ${i}/${iterations}: re-scan invoked; future slice will run adversarial here`
+        });
+    }
+    printResult(io, ok('swarm.verify', {
+        project: options.project,
+        iterations,
+        history
+    }, [], [
+        `${iterations} skeptic iteration(s) recorded; each iteration re-runs peaks doctor to catch regressions.`,
+        'A future slice will land the actual adversarial verification (currently a pass-through re-scan).'
+    ]), options.json);
+}
+/** The `13.5` loop-until-dry placeholder action, lifted verbatim out of the registrar. */
+function runSwarmLoopPlaceholder(options, io) {
+    const history = [];
+    for (let i = 1; i <= 10; i++) {
+        const failCount = 0;
+        history.push({ iteration: i, failCount, status: failCount === 0 ? 'dry' : 'still-failing' });
+        if (i > 1 && history[i - 2]?.failCount === failCount)
+            break;
+    }
+    const finalStatus = history[history.length - 1]?.failCount === 0 ? 'dry' : 'still-failing';
+    printResult(io, ok('swarm.loop', {
+        project: options.project,
+        iterations: history.length,
+        history,
+        status: finalStatus
+    }, [], [
+        `loop ran ${history.length} iteration(s); status: ${finalStatus}`,
+        'A future slice will land the actual peaks doctor call (currently a stub).'
+    ]), options.json);
+}
+/** The `peaks recommend` action, lifted verbatim out of the registrar. */
+function runRecommendAction(options, io) {
+    if (!isRecommendationWorkflow(options.workflow)) {
+        printResult(io, fail('recommend', 'UNSUPPORTED_RECOMMENDATION_WORKFLOW', `Unsupported recommendation workflow ${options.workflow}`, {}, ['Use --workflow code-refactor, product-refactor, or frontend-design']), options.json);
+        process.exitCode = 1;
+        return;
+    }
+    printResult(io, ok('recommend', createRecommendationPlan({
+        workflow: options.workflow,
+        language: options.language ?? readConfig().language ?? 'en'
+    })), options.json);
+}
+/** The four slice-#13 placeholder subcommands of `peaks swarm`, lifted verbatim out of the registrar. */
+function registerSwarmPlaceholderCommands(swarm, io) {
+    addJsonOption(swarm
+        .command('pipeline')
+        .description('13.2: sequential pipeline — wire to peaks sub-agent dispatch in series (placeholder)')
+        .requiredOption('--project <path>', 'target project root')).action((options) => runSwarmPipelinePlaceholder(options, io));
+    addJsonOption(swarm
+        .command('dispatch')
+        .description('13.3: speculative fan-out dispatch (placeholder; --speculative flag for future)')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--speculative', 'enable speculative mode (placeholder)', false)).action((options) => runSwarmDispatchPlaceholder(options, io));
+    addJsonOption(swarm
+        .command('verify')
+        .description('13.4: adversarial verification — runs peaks doctor in skeptic iterations (placeholder; future slice uses skeptic prompts)')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--skeptics <count>', 'number of skeptic iterations to run (default 1)', '1')).action((options) => runSwarmVerifyPlaceholder(options, io));
+    addJsonOption(swarm
+        .command('loop')
+        .description('13.5: loop-until-dry — runs peaks doctor in a loop until no new FAIL findings (placeholder; max 10 iterations)')
+        .requiredOption('--project <path>', 'target project root')).action((options) => runSwarmLoopPlaceholder(options, io));
+}
+export function registerWorkflowSwarmCommands(program, io) {
+    // `registerSwarmCommands` (a thin wrapper around the new
+    // `planRdSwarmGraph` service). The legacy `peaks swarm plan` /
+    // `peaks swarm-plan` registrations above stay in-place for back-compat
+    const swarm = program.command('swarm').description('Plan RD swarm dry-run graphs');
+    addSwarmPlanOptions(swarm.command('plan'), true).action(async (options) => {
+        await runSwarmPlan(io, options);
+    });
+    addSwarmPlanOptions(program.command('swarm-plan'), false).action(async (options) => {
+        await runSwarmPlan(io, options);
+    });
+    registerSwarmCommands(program, io);
+    // above are byte-for-byte untouched.
+    registerAutonomousSwarmCommands(program, io);
+    // Slice 4.0.8 — workflow lifecycle CLI (init / graph show / graph list /
+    // node prepare / node ack / node mark-lost / terminalize). Registered
+    // sibling to planning handlers per RD §4.
+    registerWorkflowLifecycleCommand(program, io);
+    // Slice #13 Swarm Algorithm Upgrade — 4 additional subcommands.
+    // (peaks swarm plan above is slice #13.1; the 4 below are 13.2-13.5).
+    registerSwarmPlaceholderCommands(swarm, io);
+    addJsonOption(program
+        .command('recommend')
+        .description('Create a dry-run recommendation plan for a workflow')
+        .requiredOption('--workflow <workflow>', 'workflow: code-refactor, product-refactor, or frontend-design')
+        .option('--language <language>', 'human presentation language')).action((options) => runRecommendAction(options, io));
+}

package/dist/cli/commands/workflow-tech-actions.d.ts

@@ -0,0 +1,10 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+import { type TechPlanOptions, type TechStatusOptions, type WorkflowRouteOptions } from './workflow-plan-helpers.js';
+export declare function runTechPlan(io: ProgramIO, options: TechPlanOptions): void;
+export declare function runTechStatus(io: ProgramIO, options: TechStatusOptions): void;
+export declare function runWorkflowRoute(io: ProgramIO, options: WorkflowRouteOptions): void;
+export declare function runAutonomousWorkflow(io: ProgramIO, options: WorkflowRouteOptions): void;
+export declare function addTechPlanOptions(command: Command): Command;
+export declare function addTechStatusOptions(command: Command): Command;
+export declare function addWorkflowRouteOptions(command: Command, description: string): Command;

package/dist/cli/commands/workflow-tech-actions.js

@@ -0,0 +1,150 @@
+import { createTechPlan, getTechStatus } from '../../services/tech/tech-service.js';
+import { createWorkflowRouterPlan, isWorkflowMode } from '../../services/workflow/workflow-router-service.js';
+import { createAutonomousWorkflowPlan } from '../../services/workflow/workflow-autonomous-service.js';
+import { readConfig } from '../../services/config/config-service.js';
+import { addJsonOption, failUnsupportedNonDryRun, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+// catch sites below (tech.plan / workflow.route / workflow.autonomous /
+// swarm.plan) so provider-config errors surface as `INVALID_PROVIDERS`
+// instead of being silently re-labelled `INVALID_GOAL`.
+import { mapServiceError } from './_cli-error-envelope.js';
+import { getCurrentWorkspaceContext, getWorkflowWorkspaceContext, parseCodeMode, parseMaxWorkers, validatePlanningInput } from './workflow-plan-helpers.js';
+export function runTechPlan(io, options) {
+    if (options.dryRun === false) {
+        failUnsupportedNonDryRun(io, 'tech.plan', options.json);
+        return;
+    }
+    try {
+        validatePlanningInput(options.goal);
+        const workspaceContext = getCurrentWorkspaceContext();
+        // gone. The planner derives scope from the active session; the
+        // legacy `sessionId` field is passed as empty string for back-compat
+        // with the existing service signature.
+        const plan = createTechPlan({
+            sessionId: '',
+            goal: options.goal,
+            swarm: options.swarm ?? false,
+            dryRun: true,
+            ...workspaceContext
+        });
+        printResult(io, ok('tech.plan', plan), options.json);
+    }
+    catch (error) {
+        const mapping = mapServiceError(error);
+        printResult(io, fail('tech.plan', mapping.code, getErrorMessage(error), {}, [...mapping.nextActions]), options.json);
+        process.exitCode = 1;
+    }
+}
+export function runTechStatus(io, options) {
+    try {
+        const workspaceContext = getCurrentWorkspaceContext();
+        printResult(io, ok('tech.status', getTechStatus({ sessionId: '', ...workspaceContext })), options.json);
+    }
+    catch (error) {
+        printResult(io, fail('tech.status', 'TECH_STATUS_FAILED', getErrorMessage(error), {}, [
+            'Verify the project setup'
+        ]), options.json);
+        process.exitCode = 1;
+    }
+}
+/**
+ * The dry-run / mode / maxWorkers / codeMode preamble the two workflow planners
+ * share. Lifted from their common prefix verbatim, parameterised only by the
+ * command label both already spelled out; it runs at the same point in the
+ * sequence and returns `null` where the original returned early.
+ */
+function resolveWorkflowPlanInputs(io, label, options) {
+    if (options.dryRun === false) {
+        failUnsupportedNonDryRun(io, label, options.json);
+        return null;
+    }
+    if (!isWorkflowMode(options.mode)) {
+        printResult(io, fail(label, 'UNSUPPORTED_WORKFLOW_MODE', `Unsupported workflow mode ${options.mode}`, {}, [
+            'Use --mode code or --mode team'
+        ]), options.json);
+        process.exitCode = 1;
+        return null;
+    }
+    const maxWorkers = parseMaxWorkers(io, label, options.maxWorkers, options.json);
+    if (maxWorkers === null)
+        return null;
+    const codeMode = parseCodeMode(io, label, options.mode, options.codeMode, options.json);
+    if (codeMode === null)
+        return null;
+    // `options.mode` is narrowed to `WorkflowMode` by the `isWorkflowMode` guard
+    // above; carrying it out with the pair keeps the call sites free of a cast.
+    return { maxWorkers, codeMode, mode: options.mode };
+}
+export function runWorkflowRoute(io, options) {
+    const inputs = resolveWorkflowPlanInputs(io, 'workflow.route', options);
+    if (inputs === null)
+        return;
+    try {
+        validatePlanningInput(options.goal);
+        const workspaceContext = getWorkflowWorkspaceContext();
+        const plan = createWorkflowRouterPlan({
+            sessionId: '',
+            goal: options.goal,
+            mode: inputs.mode,
+            ...(inputs.codeMode ? { codeMode: inputs.codeMode } : {}),
+            maxWorkers: inputs.maxWorkers,
+            dryRun: true,
+            config: readConfig(),
+            ...workspaceContext
+        });
+        printResult(io, ok('workflow.route', plan), options.json);
+    }
+    catch (error) {
+        const mapping = mapServiceError(error);
+        printResult(io, fail('workflow.route', mapping.code, getErrorMessage(error), {}, [...mapping.nextActions]), options.json);
+        process.exitCode = 1;
+    }
+}
+export function runAutonomousWorkflow(io, options) {
+    const inputs = resolveWorkflowPlanInputs(io, 'workflow.autonomous', options);
+    if (inputs === null)
+        return;
+    try {
+        validatePlanningInput(options.goal);
+        const workspaceContext = getWorkflowWorkspaceContext();
+        const plan = createAutonomousWorkflowPlan({
+            sessionId: '',
+            goal: options.goal,
+            mode: inputs.mode,
+            ...(inputs.codeMode ? { codeMode: inputs.codeMode } : {}),
+            maxWorkers: inputs.maxWorkers,
+            dryRun: true,
+            config: readConfig(),
+            ...workspaceContext
+        });
+        printResult(io, ok('workflow.autonomous', plan), options.json);
+    }
+    catch (error) {
+        const mapping = mapServiceError(error);
+        printResult(io, fail('workflow.autonomous', mapping.code, getErrorMessage(error), {}, [
+            ...mapping.nextActions
+        ]), options.json);
+        process.exitCode = 1;
+    }
+}
+export function addTechPlanOptions(command) {
+    return addJsonOption(command
+        .description('Generate a technical dry-run graph')
+        .requiredOption('--goal <goal>', 'planning goal')
+        .option('--swarm', 'opt into swarm-oriented planning')
+        .option('--dry-run', 'preview without writing files', true)
+        .option('--no-dry-run', 'unsupported: do not execute tech planning from this CLI'));
+}
+export function addTechStatusOptions(command) {
+    return addJsonOption(command.description('Inspect technical approval status'));
+}
+export function addWorkflowRouteOptions(command, description) {
+    return addJsonOption(command
+        .description(description)
+        .requiredOption('--mode <mode>', 'workflow mode: code or team')
+        .requiredOption('--goal <goal>', 'planning goal')
+        .option('--code-mode <mode>', 'code mode: full-auto, guided, or rnd')
+        .option('--max-workers <count>', 'maximum worker count', '40')
+        .option('--dry-run', 'preview without writing files', true)
+        .option('--no-dry-run', 'unsupported: do not execute workflow planning from this CLI'));
+}

package/dist/cli/commands/workflow-terminalize-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerWorkflowTerminalizeCommand(workflow: Command, io: ProgramIO): void;

package/dist/cli/commands/workflow-terminalize-command.js

@@ -0,0 +1,56 @@
+// src/cli/commands/workflow-terminalize-command.ts
+//
+// `peaks workflow terminalize` — atomically terminalize a workflow (lease +
+// graph + index + observability event). Split out of
+// `workflow-lifecycle-commands.ts`; the verb name, its options, the
+// `--require-consumed` passthrough and the envelope shape are unchanged.
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { terminalizeWorkflow } from '../../services/workflow/workflow-presence-lifecycle.js';
+import { TERMINAL_REASONS } from '../../services/workflow/workflow-graph-types.js';
+import { deriveCallerId, deriveProjectRoot, deriveSessionId } from './workflow-command-shared.js';
+async function runWorkflowTerminalize(io, options) {
+    const asJson = options.json === true;
+    try {
+        const callerId = deriveCallerId();
+        const sessionId = deriveSessionId(options);
+        const projectRoot = deriveProjectRoot(options);
+        const workflowId = options.workflow ?? '';
+        if (!workflowId)
+            throw new Error('workflowId is required');
+        if (!TERMINAL_REASONS.includes(options.reason)) {
+            throw new Error(`PEAKS_TERMINAL_REASON_INVALID: ${options.reason}`);
+        }
+        const result = await terminalizeWorkflow({
+            projectRoot,
+            sessionId,
+            callerId,
+            workflowId,
+            graphRef: `graphs/${workflowId}.json`,
+            reason: options.reason,
+            ...(options.requireConsumed ? { requireConsumed: true } : {})
+        });
+        printResult(io, ok('workflow.terminalize', {
+            envelopeVersion: '4.0.8',
+            lease: result.lease,
+            graph: result.graph,
+            events: result.events,
+            indexCleared: result.indexCleared
+        }), asJson);
+    }
+    catch (err) {
+        const code = err.code ?? 'PEAKS_TERMINALIZE_ATOMICITY_FAILED';
+        printResult(io, fail('workflow.terminalize', code, getErrorMessage(err), { lease: null }, []), asJson);
+        process.exitCode = 1;
+    }
+}
+export function registerWorkflowTerminalizeCommand(workflow, io) {
+    addJsonOption(workflow
+        .command('terminalize')
+        .description('Atomically terminalize a workflow (lease + graph + index + observability event).')
+        .requiredOption('--workflow <id>', 'workflow id')
+        .requiredOption('--reason <reason>', `terminal reason: ${TERMINAL_REASONS.join(' | ')}`)
+        .option('--session-id <sid>', 'session id')
+        .option('--project <path>', 'project root')
+        .option('--require-consumed', 'fail if there are unconsumed envelopes')).action((options) => runWorkflowTerminalize(io, options));
+}