peaks-loop 4.1.2 → 4.1.4

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

@@ -0,0 +1,116 @@
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { getSessionId } from '../../services/session/session-manager.js';
+import { verifyPipeline } from '../../services/workflow/pipeline-verify-service.js';
+import { applySkip, detectCallerKind } from '../../services/workflow/workflow-skip-service.js';
+const VERIFY_PIPELINE_DESCRIPTION = 'Verify the complete rd→qa pipeline was followed for a request. Scans the v2.17.0 canonical session-axis layout (artifacts under _runtime per-session) and falls back to the legacy v2.16.0 change-axis forms during the 1-minor-release deprecation window.';
+const SKIP_DESCRIPTION = 'Skip specific gates for a request (RD/QA). Use --dry-run to preview without writing. Allowed gate names: QA / RD (phase shortcuts) or specific gate names (rd-request-exists, prd-handoff, bug-analysis, code-review, security-review, perf-baseline, qa-request-exists, test-cases, test-report). Three rules apply: (1) only docs/config/chore slices can skip; (2) skip is one-time per rid; (3) script callers must also pass --i-have-reviewed.';
+/** The action body, lifted to a module-level function so both it and the registrar fit in 50 lines. */
+async function runVerifyPipeline(options, io) {
+    try {
+        const result = await verifyPipeline({
+            projectRoot: options.project,
+            rid: options.rid,
+            ...(options.type ? { requestType: options.type } : {}),
+            ...(options.sessionId ? { sessionId: options.sessionId } : {})
+        });
+        const exitOk = result.complete ? 0 : 1;
+        printResult(io, result.complete
+            ? ok('workflow.verify-pipeline', result)
+            : fail('workflow.verify-pipeline', 'PIPELINE_INCOMPLETE', `${result.violations.length} violation(s): ${result.violations.join('; ')}`, result, result.nextActions), options.json);
+        process.exitCode = exitOk;
+    }
+    catch (error) {
+        printResult(io, fail('workflow.verify-pipeline', 'VERIFY_FAILED', getErrorMessage(error), { acceptedForm: 'none', gateC: 'fail' }, ['Check that --project and --rid are correct.']), options.json);
+        process.exitCode = 1;
+    }
+}
+/** The `no peaks-code session binding` branch, lifted verbatim out of the skip action body. */
+function reportSkipNoActiveSession(io, options) {
+    printResult(io, fail('workflow.skip', 'NO_ACTIVE_SESSION', `project "${options.project}" has no peaks-code session binding; run \`peaks workspace init --project ${options.project} --json\` first`, { applied: false }, [`peaks workspace init --project ${options.project} --json`]), options.json);
+    process.exitCode = 1;
+}
+/**
+ * The applied / idempotent / rejected tail of the skip action, lifted verbatim
+ * out of its body; it runs at the same point in the sequence and the caller
+ * returns where the original returned early.
+ */
+function reportSkipOutcome(io, options, sessionId, result) {
+    if (result.applied) {
+        printResult(io, ok('workflow.skip', result, [], [
+            `Skip applied for rid "${options.rid}": gates [${result.skippedGates.join(', ')}] marked as status: 'skipped' on next verify-pipeline.`,
+            `State file: ${result.persistedTo}`,
+            `Run \`peaks workflow verify-pipeline --rid ${options.rid} --project ${options.project} --session-id ${sessionId} --json\` to confirm.`
+        ]), options.json);
+        return;
+    }
+    if (result.idempotent) {
+        printResult(io, ok('workflow.skip', result, [], [`Skip already applied for rid "${options.rid}"; idempotent no-op.`]), options.json);
+        return;
+    }
+    // applied:false + reason → rejection.
+    printResult(io, fail('workflow.skip', 'SKIP_REJECTED', result.reason ?? 'unknown rejection', result, [
+        'See RD request for the three rules: docs/config/chore only, one-time per rid, script callers need --i-have-reviewed.'
+    ]), options.json);
+    process.exitCode = 1;
+}
+/** The catch branch, lifted verbatim out of the skip action body. */
+function reportSkipFailure(io, error, json) {
+    printResult(io, fail('workflow.skip', 'SKIP_FAILED', getErrorMessage(error), { applied: false }, [
+        'Check that --project and --rid are correct; --reason and --gates are required.'
+    ]), json);
+    process.exitCode = 1;
+}
+/** The action body, lifted to a module-level function so both it and the registrar fit in 50 lines. */
+async function runWorkflowSkip(options, io) {
+    try {
+        // Resolve the session id from the project's current binding
+        // (CLI is the single source of truth per the dev-preference
+        // rules). The skip-state is keyed by session id, so the
+        // operator's current session determines where the marker
+        // lives. Auto-rotation on outer-mismatch is irrelevant here
+        // because we read, not write, the binding.
+        const sessionId = getSessionId(options.project);
+        if (sessionId === null) {
+            reportSkipNoActiveSession(io, options);
+            return;
+        }
+        const callerKind = detectCallerKind(process.env['PEAKS_CALLER_ID']);
+        const skipArgs = {
+            rid: options.rid,
+            gatesRaw: options.gates,
+            reason: options.reason,
+            ...(options.dryRun === true ? { dryRun: true } : {}),
+            ...(options.iHaveReviewed === true ? { iHaveReviewed: true } : {}),
+            callerKind
+        };
+        const result = await applySkip(options.project, sessionId, skipArgs);
+        reportSkipOutcome(io, options, sessionId, result);
+    }
+    catch (error) {
+        reportSkipFailure(io, error, options.json);
+    }
+}
+export function registerWorkflowGateCommands(workflow, io) {
+    addJsonOption(workflow
+        .command('verify-pipeline')
+        .description(VERIFY_PIPELINE_DESCRIPTION)
+        .requiredOption('--rid <rid>', 'request identifier')
+        .requiredOption('--project <path>', 'project root path')
+        .option('--type <type>', 'request type: feature, bugfix, refactor, docs, config, chore', 'feature')
+        .option('--session-id <sid>', 'slice 2026-06-13-peaks-workflow-skip: session id under which to read the skip-state file. When omitted, no skip-state is consulted (legacy behavior).')).action((options) => runVerifyPipeline(options, io));
+    // Mark gates as bypassed for a specific rid, so the next
+    // `verify-pipeline` reports them as `status: 'skipped'` instead of
+    // missing-evidence violations. See RD
+    // for the three-rule classifier (type allowlist, one-time
+    // semantics, role-based auth).
+    addJsonOption(workflow
+        .command('skip')
+        .description(SKIP_DESCRIPTION)
+        .requiredOption('--rid <rid>', 'request identifier')
+        .requiredOption('--project <path>', 'project root path')
+        .requiredOption('--gates <list>', 'comma-separated gate names (e.g. "QA" or "QA,slice-check" or "code-review,security-review")')
+        .requiredOption('--reason <text>', 'free-text justification; persisted in the state file and surfaced in verify-pipeline nextActions')
+        .option('--dry-run', 'preview the skip; do not write the state file')
+        .option('--i-have-reviewed', 'required when caller is a script (CI / postinstall / cron). LLM and human callers do not need this.')).action((options) => runWorkflowSkip(options, io));
+}

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

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

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

@@ -0,0 +1,73 @@
+// src/cli/commands/workflow-graph-commands.ts
+//
+// `peaks workflow graph show` / `graph list` — the workflow graph read
+// commands. Split out of `workflow-lifecycle-commands.ts`; both verb names,
+// their options and both envelope shapes are unchanged.
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { printResult } from '../cli-helpers.js';
+import { readGraph } from '../../services/workflow/workflow-graph-store.js';
+import { WORKFLOW_ID_REGEX } from '../../services/workflow/workflow-graph-types.js';
+import { deriveProjectRoot, deriveSessionId, UNKNOWN_SESSION_ID } from './workflow-command-shared.js';
+function runWorkflowGraphShow(io, options) {
+    const asJson = options.json === true;
+    try {
+        const sessionId = deriveSessionId(options);
+        const projectRoot = deriveProjectRoot(options);
+        const workflowId = options.workflow ?? '';
+        if (!workflowId || !WORKFLOW_ID_REGEX.test(workflowId)) {
+            throw new Error('workflowId is required');
+        }
+        const graph = readGraph({
+            projectRoot,
+            sessionId,
+            graphRef: `graphs/${workflowId}.json`,
+            workflowId
+        });
+        printResult(io, ok('workflow.graph.show', { envelopeVersion: '4.0.8', graph }), asJson);
+    }
+    catch (err) {
+        const code = err.code ?? 'PEAKS_GRAPH_NOT_FOUND';
+        printResult(io, fail('workflow.graph.show', code, getErrorMessage(err), { graph: null }, []), asJson);
+        process.exitCode = 1;
+    }
+}
+function runWorkflowGraphList(io, options) {
+    const asJson = options.json === true;
+    try {
+        const sessionId = deriveSessionId(options);
+        if (sessionId === UNKNOWN_SESSION_ID) {
+            throw new Error('PEAKS_SESSION_NOT_BOUND: no session id');
+        }
+        const result = { envelopeVersion: '4.0.8', sessionId, graphs: [] };
+        printResult(io, ok('workflow.graph.list', result), asJson);
+    }
+    catch (err) {
+        const code = err.code ?? 'PEAKS_SESSION_NOT_BOUND';
+        printResult(io, fail('workflow.graph.list', code, getErrorMessage(err), { graphs: [] }, []), asJson);
+        process.exitCode = 1;
+    }
+}
+export function registerWorkflowGraphCommands(workflow, io) {
+    // Note: `.command('graph show')` and `.command('graph list')` each
+    // implicitly create a NEW `graph` parent under `workflow` in
+    // Commander v12 (no auto-reuse), so calling them in sequence throws
+    // "cannot add command 'graph' as already have command 'graph'" at
+    // startup. Reuse the first created `graph` parent for the second
+    // registration.
+    const graphCmd = workflow.command('graph').description('workflow graph read commands');
+    graphCmd
+        .command('show')
+        .description('Read a workflow graph.')
+        .option('--workflow <id>', 'workflow id')
+        .option('--session-id <sid>', 'session id')
+        .option('--project <path>', 'project root')
+        .option('--json', 'json output')
+        .action((options) => runWorkflowGraphShow(io, options));
+    graphCmd
+        .command('list')
+        .description('List workflow graphs (metadata only).')
+        .option('--session-id <sid>', 'session id')
+        .option('--project <path>', 'project root')
+        .option('--json', 'json output')
+        .action((options) => runWorkflowGraphList(io, options));
+}

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

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

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

@@ -0,0 +1,68 @@
+// src/cli/commands/workflow-init-command.ts
+//
+// `peaks workflow init` — initialize a workflow graph + canonical lease + caller
+// index. Split out of `workflow-lifecycle-commands.ts`; the verb name, its
+// options, the session-binding refusal and the envelope shape are unchanged.
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { initWorkflow } from '../../services/workflow/workflow-presence-lifecycle.js';
+import { WORKFLOW_ID_REGEX } from '../../services/workflow/workflow-graph-types.js';
+import { deriveCallerId, deriveProjectRoot, deriveSessionId, GENERATED_ID_RADIX, UNKNOWN_SESSION_ID } from './workflow-command-shared.js';
+/**
+ * Tier 3 resolving to `unknown-sid` means NO session is bound at all. A
+ * `workflow` subcommand that WRITES must fail loudly on that rather than
+ * create a bucket named after a failure — `graph list` already does (see its
+ * `PEAKS_SESSION_NOT_BOUND` guard); `init` did not.
+ */
+function buildSessionNotBoundEnvelope(sessionId, projectRoot) {
+    return fail('workflow.init', 'PEAKS_SESSION_NOT_BOUND', `No peaks session is bound for '${projectRoot}' (derived session id '${sessionId}'): --session-id, PEAKS_SESSION_ID and the project binding are all absent.`, { workflowId: null }, [
+        'Run `peaks workspace init --project <p>` to bind a session, then re-run.',
+        'Or pass `--session-id <sid>` explicitly.'
+    ]);
+}
+async function runWorkflowInit(io, options) {
+    const asJson = options.json === true;
+    try {
+        const callerId = deriveCallerId();
+        const projectRoot = deriveProjectRoot(options);
+        const sessionId = deriveSessionId(options);
+        if (sessionId === UNKNOWN_SESSION_ID) {
+            printResult(io, buildSessionNotBoundEnvelope(sessionId, projectRoot), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        const workflowId = options.workflowId ?? `wf-${Date.now().toString(GENERATED_ID_RADIX)}`;
+        if (!WORKFLOW_ID_REGEX.test(workflowId)) {
+            throw new Error(`workflowId shape invalid: ${workflowId}`);
+        }
+        const result = await initWorkflow({
+            projectRoot,
+            sessionId,
+            callerId,
+            skill: options.skill ?? 'peaks-code',
+            workflowId,
+            ...(options.parentWorkflow ? { parentWorkflowId: options.parentWorkflow } : {})
+        });
+        printResult(io, ok('workflow.init', {
+            envelopeVersion: '4.0.8',
+            workflowId: result.workflowId,
+            graphRef: result.graphRef,
+            events: result.events
+        }), asJson);
+    }
+    catch (err) {
+        const code = err.code ?? 'PEAKS_GRAPH_WRITE_FAILED';
+        printResult(io, fail('workflow.init', code, getErrorMessage(err), { workflowId: null }, []), asJson);
+        process.exitCode = 1;
+    }
+}
+export function registerWorkflowInitCommand(workflow, io) {
+    addJsonOption(workflow
+        .command('init')
+        .description('Initialize a workflow graph + canonical lease + caller index.')
+        .requiredOption('--skill <name>', 'the skill owning this workflow (e.g. peaks-code)')
+        .option('--workflow-id <id>', 'optional explicit workflowId (auto-generated if omitted)')
+        .option('--parent-workflow <id>', 'parent workflowId for nested runs')
+        .option('--session-id <sid>', 'override session id (default: derived from session.json / env)')
+        .option('--project <path>', 'target project root (defaults to cwd)')).action((options) => runWorkflowInit(io, options));
+}

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

@@ -5,65 +5,15 @@
  * prepare / node ack / node mark-lost / terminalize`. All commands
  * delegate to the canonical services. Each action emits the typed
  * envelope via `ok` / `fail` so the LLM runner can branch on `code`.
+ *
+ * The verb implementations live beside this file, one module per verb group:
+ * `workflow-init-command.ts`, `workflow-graph-commands.ts`,
+ * `workflow-node-commands.ts`, `workflow-terminalize-command.ts`, with the
+ * option vocabulary and the caller / project / session derivation in
+ * `workflow-command-shared.ts`.
  */
 import type { Command } from 'commander';
-import { type ProgramIO } from '../cli-helpers.js';
-export interface WorkflowInitOptions {
-    readonly skill?: string;
-    readonly parentWorkflow?: string;
-    readonly workflowId?: string;
-    readonly project?: string;
-    readonly sessionId?: string;
-    readonly json?: boolean;
-}
-export interface WorkflowGraphShowOptions {
-    readonly workflow?: string;
-    readonly project?: string;
-    readonly sessionId?: string;
-    readonly json?: boolean;
-}
-export interface WorkflowGraphListOptions {
-    readonly project?: string;
-    readonly sessionId?: string;
-    readonly json?: boolean;
-}
-export interface WorkflowNodePrepareOptions {
-    readonly workflow?: string;
-    readonly node?: string;
-    readonly kind?: string;
-    readonly label?: string;
-    readonly dependsOn?: string;
-    readonly project?: string;
-    readonly sessionId?: string;
-    readonly json?: boolean;
-}
-export interface WorkflowNodeAckOptions {
-    readonly workflow?: string;
-    readonly node?: string;
-    readonly project?: string;
-    readonly sessionId?: string;
-    readonly json?: boolean;
-}
-export interface WorkflowNodeMarkLostOptions {
-    readonly workflow?: string;
-    readonly node?: string;
-    readonly reason?: string;
-    readonly project?: string;
-    readonly sessionId?: string;
-    readonly json?: boolean;
-}
-export interface WorkflowTerminalizeOptions {
-    readonly workflow?: string;
-    readonly reason?: string;
-    readonly project?: string;
-    readonly sessionId?: string;
-    readonly requireConsumed?: boolean;
-    readonly json?: boolean;
-}
-/**
- * The literal that means "no session could be resolved". Kept as a named
- * constant because three call sites now have to ASK whether resolution
- * failed rather than consume the value as if it were an id.
- */
-export declare const UNKNOWN_SESSION_ID = "unknown-sid";
+import type { ProgramIO } from '../cli-helpers.js';
+export type { WorkflowGraphListOptions, WorkflowGraphShowOptions, WorkflowInitOptions, WorkflowNodeAckOptions, WorkflowNodeMarkLostOptions, WorkflowNodePrepareOptions, WorkflowTerminalizeOptions } from './workflow-command-shared.js';
+export { UNKNOWN_SESSION_ID } from './workflow-command-shared.js';
 export declare function registerWorkflowLifecycleCommand(parent: Command, io: ProgramIO): void;