peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/workflow/workflow-router-service.d.ts

@@ -0,0 +1,85 @@
+import { type ModelProviderConfig, type WorkspaceConfig } from '../config/config-types.js';
+import { type RdPlanResult } from '../rd/rd-service.js';
+import { type TechPlanResult, type TechStatus } from '../tech/tech-service.js';
+export type WorkflowMode = 'code' | 'team';
+export type CodeMode = 'full-auto' | 'guided' | 'rnd';
+export type ModelTier = 'top-tier' | 'mid-tier';
+export type ModelRole = 'strongest' | 'execution';
+export type WorkflowRoutePolicy = 'code-broad-multi-model' | 'team-rd-limited-multi-model';
+export type WorkflowStepStage = 'product-direction' | 'design-direction' | 'tech-direction' | 'tech-review' | 'rd-planning' | 'coding-execution' | 'unit-test-execution' | 'quality-review';
+export type WorkflowStepOwner = 'peaks-code' | 'peaks-rd' | 'peaks-tech' | 'human';
+export type WorkflowRouterRequest = {
+    sessionId: string;
+    goal: string;
+    mode: WorkflowMode;
+    codeMode?: CodeMode;
+    maxWorkers?: number;
+    dryRun: true;
+    artifactWorkspacePath?: string;
+    workspace?: WorkspaceConfig;
+    config?: {
+        economyMode?: boolean;
+        swarmMode?: boolean;
+        providers?: ModelProviderConfig;
+    };
+};
+export type WorkflowRouterStep = {
+    readonly id: string;
+    readonly stage: WorkflowStepStage;
+    readonly owner: WorkflowStepOwner;
+    readonly modelTier: ModelTier;
+    readonly modelRole: ModelRole;
+    readonly modelId: string;
+    readonly reason: string;
+    readonly dryRunOnly: true;
+    readonly invokesAgents: false;
+    readonly writesArtifacts: false;
+    readonly dependsOn: readonly string[];
+};
+export type WorkflowModelRouting = {
+    readonly strongestModel: {
+        readonly modelId: string;
+        readonly uses: readonly WorkflowStepStage[];
+    };
+    readonly executionModel: {
+        readonly modelId: string;
+        readonly uses: readonly WorkflowStepStage[];
+    };
+};
+export type WorkflowModelAssignment = {
+    readonly stage: WorkflowStepStage;
+    readonly owner: WorkflowStepOwner;
+    readonly modelTier: ModelTier;
+    readonly modelRole: ModelRole;
+    readonly modelId: string;
+};
+export type WorkflowModeStatus = {
+    readonly economyModeEnabled: boolean;
+    readonly swarmModeEnabled: boolean;
+    readonly executionModelId: string;
+    readonly executionModelSource: string;
+    readonly summary: string;
+};
+export type WorkflowRouterPlan = {
+    readonly sessionId: string;
+    readonly goal: string;
+    readonly mode: WorkflowMode;
+    readonly codeMode?: CodeMode;
+    readonly executionMode: 'autonomous';
+    readonly decisionProfile: string;
+    readonly dryRun: true;
+    readonly routePolicy: WorkflowRoutePolicy;
+    readonly modelRouting: WorkflowModelRouting;
+    readonly modelAssignments: readonly WorkflowModelAssignment[];
+    readonly modeStatus: WorkflowModeStatus;
+    readonly techStatus: TechStatus;
+    readonly techPlan: TechPlanResult;
+    readonly rdPlan: RdPlanResult;
+    readonly steps: readonly WorkflowRouterStep[];
+    readonly blockedReasons: readonly string[];
+    readonly nextActions: readonly string[];
+    readonly constraints: readonly string[];
+};
+export declare function isWorkflowMode(mode: string): mode is WorkflowMode;
+export declare function isCodeMode(value: string): value is CodeMode;
+export declare function createWorkflowRouterPlan(request: WorkflowRouterRequest): WorkflowRouterPlan;

package/dist/services/workflow/workflow-router-service.js

@@ -0,0 +1,235 @@
+import { getConfiguredExecutionModelId, getStrongestModelId } from '../config/model-routing.js';
+import { getLocalArtifactPath } from '../artifacts/workspace-service.js';
+import { createRdSwarmPlan } from '../rd/rd-service.js';
+import { createTechPlan, getTechStatus } from '../tech/tech-service.js';
+// Slice 2026-06-29-change-id-root-removal: `validateChangeIdOrThrow`
+// was removed with the change-id axis. Path-safety helpers now live
+// at `shared/path-safety.ts` if this module ever needs them.
+import { WORKSPACE_UNAVAILABLE_NEXT_ACTIONS } from '../../shared/planner-response.js';
+const WORKFLOW_CONSTRAINTS = Object.freeze([
+    'dry-run-only',
+    'requires-swarm-execution-for-rd-and-qa-when-enabled',
+    'execution-model-from-config-providers',
+    'do-not-launch-agents',
+    'do-not-write-artifacts',
+    'do-not-mutate-target-repo'
+]);
+const EXECUTION_STAGES = ['coding-execution', 'unit-test-execution'];
+const GUIDED_DECISION_STAGES = ['product-direction', 'design-direction'];
+const GOVERNED_DECISION_STAGES = ['product-direction', 'design-direction', 'tech-direction', 'tech-review'];
+export function isWorkflowMode(mode) {
+    return mode === 'code' || mode === 'team';
+}
+function assertSupportedMode(mode) {
+    if (!isWorkflowMode(mode)) {
+        throw new Error('Unsupported workflow mode');
+    }
+}
+function normalizeGoal(goal) {
+    const normalized = goal.trim();
+    if (!normalized) {
+        throw new Error('Goal must be non-empty');
+    }
+    return normalized;
+}
+function assertCodeModeAllowed(mode, codeMode) {
+    if (mode !== 'code' && codeMode !== undefined) {
+        throw new Error('codeMode requires code workflow mode');
+    }
+}
+function step(input, executionModelId, strongestModelId) {
+    const modelRole = EXECUTION_STAGES.includes(input.stage) ? 'execution' : 'strongest';
+    return {
+        ...input,
+        modelRole,
+        modelId: modelRole === 'execution' ? executionModelId : strongestModelId,
+        dryRunOnly: true,
+        invokesAgents: false,
+        writesArtifacts: false
+    };
+}
+export function isCodeMode(value) {
+    return value === 'full-auto' || value === 'guided' || value === 'rnd';
+}
+function getDecisionProfileSummary(mode, codeMode) {
+    if (mode === 'team') {
+        return 'Team mode keeps product and design governance on a human-controlled path while RD execution follows recommended defaults.';
+    }
+    if (codeMode === 'guided') {
+        return 'Guided mode keeps the user in the decision loop for the early recommended defaults, while later execution remains bounded by the routing plan.';
+    }
+    if (codeMode === 'rnd') {
+        return 'R&D mode asks for technical confirmation up front, then applies recommended defaults for implementation, testing, review, and safety checks.';
+    }
+    return 'Full-auto mode applies recommended defaults for product, design, and tech decisions, then runs the engineering pipeline end to end under routing gates.';
+}
+function annotateSteps(steps, codeMode) {
+    const decisionStages = codeMode === 'guided'
+        ? GUIDED_DECISION_STAGES
+        : GOVERNED_DECISION_STAGES;
+    return steps.map((currentStep) => {
+        const isDecisionStage = decisionStages.includes(currentStep.stage);
+        const reasonPrefix = isDecisionStage
+            ? `[${codeMode}] decision stage`
+            : '[routed] execution stage';
+        return {
+            ...currentStep,
+            reason: `${reasonPrefix}: ${currentStep.reason}`
+        };
+    });
+}
+function createSoloSteps(executionModelId, strongestModelId, economyMode) {
+    const executionTier = economyMode === false ? 'top-tier' : 'mid-tier';
+    return [
+        step({ id: 'code-product-direction', stage: 'product-direction', owner: 'peaks-code', modelTier: 'top-tier', reason: 'Product direction needs strong judgment before execution work is delegated.', dependsOn: [] }, executionModelId, strongestModelId),
+        step({ id: 'code-design-direction', stage: 'design-direction', owner: 'peaks-code', modelTier: 'top-tier', reason: 'Design direction uses the recommended default before cheaper implementation work.', dependsOn: ['code-product-direction'] }, executionModelId, strongestModelId),
+        step({ id: 'code-tech-direction', stage: 'tech-direction', owner: 'peaks-tech', modelTier: 'top-tier', reason: 'Technical boundaries and approval gates use the recommended default with high-confidence planning.', dependsOn: ['code-design-direction'] }, executionModelId, strongestModelId),
+        step({ id: 'code-tech-review', stage: 'tech-review', owner: 'peaks-tech', modelTier: 'top-tier', reason: 'Tech artifacts and gate decisions require strong review and a recommended default path.', dependsOn: ['code-tech-direction'] }, executionModelId, strongestModelId),
+        step({ id: 'code-rd-planning', stage: 'rd-planning', owner: 'peaks-rd', modelTier: 'top-tier', reason: 'RD task decomposition and acceptance criteria use the recommended default before execution delegation.', dependsOn: ['code-tech-review'] }, executionModelId, strongestModelId),
+        step({ id: 'code-coding-execution', stage: 'coding-execution', owner: 'peaks-rd', modelTier: executionTier, reason: `Coding and routine refactoring must use the configured execution worker model ${executionModelId}.`, dependsOn: ['code-rd-planning'] }, executionModelId, strongestModelId),
+        step({ id: 'code-unit-test-execution', stage: 'unit-test-execution', owner: 'peaks-rd', modelTier: executionTier, reason: `Unit test authoring and focused test runs must use the configured execution worker model ${executionModelId}.`, dependsOn: ['code-coding-execution'] }, executionModelId, strongestModelId),
+        step({ id: 'code-quality-review', stage: 'quality-review', owner: 'peaks-code', modelTier: 'top-tier', reason: 'Reducer and final quality gates need strong synthesis and risk review.', dependsOn: ['code-unit-test-execution'] }, executionModelId, strongestModelId)
+    ];
+}
+function createSoloStepsForMode(codeMode, executionModelId, strongestModelId, economyMode) {
+    return annotateSteps(createSoloSteps(executionModelId, strongestModelId, economyMode), codeMode);
+}
+function createTeamSteps(executionModelId, strongestModelId, economyMode) {
+    const executionTier = economyMode === false ? 'top-tier' : 'mid-tier';
+    return [
+        step({ id: 'team-product-direction', stage: 'product-direction', owner: 'human', modelTier: 'top-tier', reason: 'Team product direction should stay on the governed planning path.', dependsOn: [] }, executionModelId, strongestModelId),
+        step({ id: 'team-design-direction', stage: 'design-direction', owner: 'human', modelTier: 'top-tier', reason: 'Team design direction should preserve reviewability and accountability.', dependsOn: ['team-product-direction'] }, executionModelId, strongestModelId),
+        step({ id: 'team-tech-direction', stage: 'tech-direction', owner: 'peaks-tech', modelTier: 'top-tier', reason: 'Team technical plans should remain strongly governed before RD execution.', dependsOn: ['team-design-direction'] }, executionModelId, strongestModelId),
+        step({ id: 'team-tech-review', stage: 'tech-review', owner: 'peaks-tech', modelTier: 'top-tier', reason: 'Team tech approval requires strong review before execution.', dependsOn: ['team-tech-direction'] }, executionModelId, strongestModelId),
+        step({ id: 'team-rd-planning', stage: 'rd-planning', owner: 'peaks-rd', modelTier: 'top-tier', reason: 'Team RD task decomposition remains on the governed strongest-model path.', dependsOn: ['team-tech-review'] }, executionModelId, strongestModelId),
+        step({ id: 'team-coding-execution', stage: 'coding-execution', owner: 'peaks-rd', modelTier: executionTier, reason: `Bounded coding tasks must use the configured execution worker model ${executionModelId}.`, dependsOn: ['team-rd-planning'] }, executionModelId, strongestModelId),
+        step({ id: 'team-unit-test-execution', stage: 'unit-test-execution', owner: 'peaks-rd', modelTier: executionTier, reason: `Unit-test tasks must use the configured execution worker model ${executionModelId}.`, dependsOn: ['team-coding-execution'] }, executionModelId, strongestModelId),
+        step({ id: 'team-quality-review', stage: 'quality-review', owner: 'peaks-rd', modelTier: 'top-tier', reason: 'Team RD outputs still need reducer and quality review gates.', dependsOn: ['team-unit-test-execution'] }, executionModelId, strongestModelId)
+    ];
+}
+function uniqueStrings(values) {
+    return [...new Set(values)];
+}
+function createModelRouting(steps, executionModelId, strongestModelId) {
+    return {
+        strongestModel: {
+            modelId: strongestModelId,
+            uses: steps.filter((step) => step.modelRole === 'strongest').map((step) => step.stage)
+        },
+        executionModel: {
+            modelId: executionModelId,
+            uses: steps.filter((step) => step.modelRole === 'execution').map((step) => step.stage)
+        }
+    };
+}
+function createModelAssignments(steps) {
+    return steps.map((step) => ({
+        stage: step.stage,
+        owner: step.owner,
+        modelTier: step.modelTier,
+        modelRole: step.modelRole,
+        modelId: step.modelId
+    }));
+}
+function getTechPlanBlockedReasons(techPlan) {
+    return techPlan.available ? techPlan.blockedReasons : techPlan.preview.blockedReasons;
+}
+function getTechPlanNextActions(techPlan) {
+    return [...techPlan.nextActions];
+}
+function createModeStatus(economyMode, swarmMode, executionModelId, executionModelSource, strongestModelId) {
+    const economySummary = economyMode
+        ? `Economy mode enabled: code worker and test worker strictly use ${executionModelId} from config providers.`
+        : `Economy mode disabled: code worker and test worker use ${strongestModelId}, matching planner/reviewer.`;
+    const swarmSummary = swarmMode
+        ? 'Swarm mode enabled: peaks-rd coding, unit-test, and peaks-qa quality work must be represented as swarm worker tasks.'
+        : 'Swarm mode disabled: swarm worker graph generation is bypassed.';
+    return {
+        economyModeEnabled: economyMode,
+        swarmModeEnabled: swarmMode,
+        executionModelId,
+        executionModelSource,
+        summary: `${economySummary} ${swarmSummary}`
+    };
+}
+function getCodeMode(mode, codeMode) {
+    if (mode !== 'code') {
+        return undefined;
+    }
+    if (codeMode === undefined) {
+        return 'full-auto';
+    }
+    if (!isCodeMode(codeMode)) {
+        throw new Error('Unsupported code mode');
+    }
+    return codeMode;
+}
+export function createWorkflowRouterPlan(request) {
+    assertSupportedMode(request.mode);
+    assertCodeModeAllowed(request.mode, request.codeMode);
+    // Slice 2026-06-29-change-id-root-removal: change-id is metadata-only;
+    // no structural validation gate fires here.
+    const goal = normalizeGoal(request.goal);
+    const maxWorkers = request.maxWorkers ?? 40;
+    // Slice 2.0.1-bug1 round 3: project policy defaults. The slim 2.0.1 DEFAULT_CONFIG
+    // no longer carries economyMode / swarmMode (those moved to per-project preferences),
+    // so we cannot fall back to `DEFAULT_CONFIG.economyMode` / `swarmMode` here. Both
+    // flags are project-policy opt-outs: the absence of an explicit `false` means
+    // "enabled" (matches the pre-2.0.1 implicit default).
+    const economyMode = request.config?.economyMode ?? true;
+    const swarmMode = request.config?.swarmMode ?? true;
+    // Pre-2.0.1 DEFAULT_CONFIG carried an implicit provider for test fixtures
+    // that did not pass `config.providers`. The slim DEFAULT_CONFIG removed that
+    // field, so we re-supply it here only when the caller did not pass any
+    // providers at all. An explicit empty object (`config: { providers: {} }`)
+    // still surfaces the "must be configured" error from
+    // `getConfiguredExecutionModelId`.
+    const effectiveProviders = request.config?.providers ?? { anthropic: { model: 'claude-opus-4-7' } };
+    // Slice 2026-07-09 add-zcode-adapter (A.3): the strongest
+    // planner/reviewer model is now resolved via `getStrongestModelId`,
+    // which reads `config.model` (if present) or falls back to the
+    // env-var-overridable default. This decouples the strongest-model
+    // pick from any specific vendor constant.
+    const strongestModelId = getStrongestModelId(request.config);
+    const executionModelId = economyMode !== false ? getConfiguredExecutionModelId(effectiveProviders) : strongestModelId;
+    const modeStatus = createModeStatus(economyMode, swarmMode, executionModelId, economyMode ? 'config.providers' : 'planner-reviewer-strongest-model', strongestModelId);
+    const codeMode = getCodeMode(request.mode, request.codeMode);
+    const decisionProfile = getDecisionProfileSummary(request.mode, codeMode);
+    const artifactWorkspacePath = request.artifactWorkspacePath ?? (request.workspace ? getLocalArtifactPath(request.workspace) : undefined);
+    const sharedWorkspaceOptions = {
+        ...(artifactWorkspacePath ? { artifactWorkspacePath } : {}),
+        ...(request.workspace ? { workspace: request.workspace } : {})
+    };
+    const techStatus = getTechStatus({ sessionId: request.sessionId, ...sharedWorkspaceOptions });
+    const techPlan = createTechPlan({ sessionId: request.sessionId, goal, swarm: swarmMode, dryRun: true, ...sharedWorkspaceOptions });
+    const rdPlan = createRdSwarmPlan({ skill: 'rd', sessionId: request.sessionId, goal, maxWorkers, swarmMode, executionModelId, dryRun: true, ...sharedWorkspaceOptions });
+    const steps = codeMode ? createSoloStepsForMode(codeMode, executionModelId, strongestModelId, economyMode) : createTeamSteps(executionModelId, strongestModelId, economyMode);
+    const blockedReasons = uniqueStrings([
+        ...techStatus.blockedReasons,
+        ...getTechPlanBlockedReasons(techPlan),
+        ...rdPlan.blockedReasons
+    ]);
+    const nextActions = blockedReasons.includes('artifact-workspace-unavailable')
+        ? [...WORKSPACE_UNAVAILABLE_NEXT_ACTIONS]
+        : uniqueStrings([...techStatus.nextActions, ...getTechPlanNextActions(techPlan), ...rdPlan.nextActions]);
+    return {
+        sessionId: request.sessionId,
+        goal,
+        mode: request.mode,
+        ...(codeMode ? { codeMode } : {}),
+        executionMode: 'autonomous',
+        decisionProfile,
+        dryRun: true,
+        routePolicy: request.mode === 'code' ? 'code-broad-multi-model' : 'team-rd-limited-multi-model',
+        modelRouting: createModelRouting(steps, executionModelId, strongestModelId),
+        modelAssignments: createModelAssignments(steps),
+        modeStatus,
+        techStatus,
+        techPlan,
+        rdPlan,
+        steps,
+        blockedReasons,
+        nextActions,
+        constraints: [...WORKFLOW_CONSTRAINTS]
+    };
+}

package/dist/services/workflow/workflow-skip-service.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Slice 2026-06-13-peaks-workflow-skip — `peaks workflow skip` service.
+ *
+ * Pure-function classifier (`canSkipSlice`) + side-effecting applicator
+ * (`applySkip`). Both are testable without filesystem mocks (the
+ * applicator accepts an injected `readSkipState` / `writeSkipState`
+ * pair so the unit tests use in-memory fakes; the production caller
+ * passes the real store from `workflow-state-store.ts`).
+ *
+ * Three rules (per RD §Why + Tech Doc §2-4):
+ *   - Rule 1 (slice type allowlist): `bugfix` / `feature` / `refactor`
+ *     can never skip QA, regardless of `--reason`. The allowlist is
+ *     `['docs', 'config', 'chore']`.
+ *   - Rule 2 (one-time semantics): if a skip-marker already exists for
+ *     this rid AND the requested skip is the same → idempotent
+ *     no-op (`applied: false, idempotent: true`). If different → deny
+ *     with `reason: "rid already has a different skip applied"`.
+ *   - Rule 3 (role-based authorization): scripts (caller kind derived
+ *     from `$PEAKS_CALLER_ID` env var) MUST pass `--i-have-reviewed`
+ *     in addition to `--reason`.
+ */
+import { type WorkflowSkipState } from './workflow-state-store.js';
+import type { RequestType } from '../artifacts/artifact-prerequisites.js';
+export type SkipArgs = {
+    /** Request id this skip applies to. */
+    rid: string;
+    /** Comma-separated gate names from the CLI; parsed to string[]. */
+    gatesRaw: string;
+    /** Required, free-text justification. */
+    reason: string;
+    /** Optional. When set, the apply is previewed but no state is written. */
+    dryRun?: boolean;
+    /** Required for script callers (see Rule 3). */
+    iHaveReviewed?: boolean;
+    /** Caller kind, derived from $PEAKS_CALLER_ID by the CLI. When omitted,
+     *  defaults to 'human' (the CLI's normal terminal path). */
+    callerKind?: 'human' | 'llm' | 'script';
+};
+export type CanSkipVerdict = {
+    allowed: true;
+    reason: null;
+    sliceType: RequestType;
+    callerKind: 'human' | 'llm' | 'script';
+} | {
+    allowed: false;
+    reason: string;
+    sliceType?: RequestType;
+};
+export type ApplySkipResult = {
+    applied: true;
+    idempotent: false;
+    skippedGates: string[];
+    rid: string;
+    persistedTo: string;
+    sliceType: RequestType;
+} | {
+    applied: false;
+    idempotent: true;
+    skippedGates: string[];
+    rid: string;
+    persistedTo: string | null;
+    sliceType: RequestType;
+} | {
+    applied: false;
+    idempotent: false;
+    skippedGates: string[];
+    rid: string;
+    persistedTo: string | null;
+    sliceType?: RequestType;
+    reason: string;
+};
+/** Parse the `--gates` CLI arg (e.g. "QA,slice-check") into string[]. */
+export declare function parseGatesList(raw: string): string[];
+/**
+ * Determine the caller kind for Rule 3. CLI passes
+ * `args.callerKind` directly when the user invoked the command
+ * interactively; for script callers (CI / postinstall) the CLI
+ * inspects `$PEAKS_CALLER_ID` and passes 'script'.
+ */
+export declare function detectCallerKind(envCallerId: string | undefined): 'human' | 'llm' | 'script';
+/**
+ * Pure three-rule classifier. Does NOT touch the filesystem; the
+ * `currentState` argument is the result of a prior `readSkipState`
+ * call (or null if no state file exists). The slice type is
+ * read from the RD request artifact via `showRequestArtifact`.
+ *
+ * Returns a verdict; the caller is expected to either apply or
+ * surface the rejection reason. Reasons are user-readable English
+ * suitable for the `nextActions` envelope.
+ */
+export declare function canSkipSlice(projectRoot: string, sessionId: string, args: SkipArgs, currentState: WorkflowSkipState | null): Promise<CanSkipVerdict>;
+/**
+ * Apply a skip. Caller is expected to have already called
+ * `canSkipSlice` and received `allowed: true`. The function is
+ * still defensive — if the verdict is `allowed: false`, it returns
+ * the rejection as `applied: false` without writing.
+ */
+export declare function applySkip(projectRoot: string, sessionId: string, args: SkipArgs): Promise<ApplySkipResult>;
+declare function sameStringSet(a: readonly string[], b: readonly string[]): boolean;
+/** Exposed for tests. */
+export declare const _internal: {
+    SKIPPABLE_TYPES: readonly RequestType[];
+    SCRIPT_CALLER_IDS: readonly string[];
+    sameStringSet: typeof sameStringSet;
+};
+export {};

package/dist/services/workflow/workflow-skip-service.js

@@ -0,0 +1,209 @@
+/**
+ * Slice 2026-06-13-peaks-workflow-skip — `peaks workflow skip` service.
+ *
+ * Pure-function classifier (`canSkipSlice`) + side-effecting applicator
+ * (`applySkip`). Both are testable without filesystem mocks (the
+ * applicator accepts an injected `readSkipState` / `writeSkipState`
+ * pair so the unit tests use in-memory fakes; the production caller
+ * passes the real store from `workflow-state-store.ts`).
+ *
+ * Three rules (per RD §Why + Tech Doc §2-4):
+ *   - Rule 1 (slice type allowlist): `bugfix` / `feature` / `refactor`
+ *     can never skip QA, regardless of `--reason`. The allowlist is
+ *     `['docs', 'config', 'chore']`.
+ *   - Rule 2 (one-time semantics): if a skip-marker already exists for
+ *     this rid AND the requested skip is the same → idempotent
+ *     no-op (`applied: false, idempotent: true`). If different → deny
+ *     with `reason: "rid already has a different skip applied"`.
+ *   - Rule 3 (role-based authorization): scripts (caller kind derived
+ *     from `$PEAKS_CALLER_ID` env var) MUST pass `--i-have-reviewed`
+ *     in addition to `--reason`.
+ */
+import { readSkipState, writeSkipState } from './workflow-state-store.js';
+import { showRequestArtifact } from '../artifacts/request-artifact-service.js';
+const SKIPPABLE_TYPES = ['docs', 'config', 'chore'];
+const SCRIPT_CALLER_IDS = ['ci', 'postinstall', 'cron'];
+/** Parse the `--gates` CLI arg (e.g. "QA,slice-check") into string[]. */
+export function parseGatesList(raw) {
+    return raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/**
+ * Determine the caller kind for Rule 3. CLI passes
+ * `args.callerKind` directly when the user invoked the command
+ * interactively; for script callers (CI / postinstall) the CLI
+ * inspects `$PEAKS_CALLER_ID` and passes 'script'.
+ */
+export function detectCallerKind(envCallerId) {
+    if (envCallerId === undefined || envCallerId.length === 0) {
+        return 'human';
+    }
+    return SCRIPT_CALLER_IDS.includes(envCallerId) ? 'script' : 'llm';
+}
+/**
+ * Pure three-rule classifier. Does NOT touch the filesystem; the
+ * `currentState` argument is the result of a prior `readSkipState`
+ * call (or null if no state file exists). The slice type is
+ * read from the RD request artifact via `showRequestArtifact`.
+ *
+ * Returns a verdict; the caller is expected to either apply or
+ * surface the rejection reason. Reasons are user-readable English
+ * suitable for the `nextActions` envelope.
+ */
+export async function canSkipSlice(projectRoot, sessionId, args, currentState) {
+    // Argument validation (no filesystem).
+    if (args.reason.trim().length === 0) {
+        return { allowed: false, reason: 'skip requires --reason; what is the user-visible justification for this QA bypass?' };
+    }
+    const gates = parseGatesList(args.gatesRaw);
+    if (gates.length === 0) {
+        return { allowed: false, reason: '--gates must list at least one gate name (e.g. "QA" or "QA,slice-check")' };
+    }
+    // Resolve caller kind.
+    const callerKind = args.callerKind ?? 'human';
+    // Rule 3: script callers must carry --i-have-reviewed.
+    if (callerKind === 'script' && args.iHaveReviewed !== true) {
+        return { allowed: false, reason: 'script caller must pass --i-have-reviewed' };
+    }
+    // Read the slice type from the RD request.
+    let sliceType;
+    try {
+        const rdArtifact = await showRequestArtifact({ projectRoot, role: 'rd', requestId: args.rid });
+        if (rdArtifact === null) {
+            return { allowed: false, reason: `RD request artifact not found for rid "${args.rid}"; cannot determine slice type` };
+        }
+        sliceType = rdArtifact.requestType;
+    }
+    catch (error) {
+        return {
+            allowed: false,
+            reason: `failed to read slice type from RD artifact: ${error instanceof Error ? error.message : 'unknown error'}`
+        };
+    }
+    // Rule 1: type allowlist.
+    if (!SKIPPABLE_TYPES.includes(sliceType)) {
+        return {
+            allowed: false,
+            reason: `slice type "${sliceType}" cannot skip QA (allowlist: docs, config, chore)`,
+            sliceType
+        };
+    }
+    // Rule 2: one-time semantics — same skip on the same rid is idempotent.
+    if (currentState !== null) {
+        const sameGates = sameStringSet(currentState.skippedGates, gates);
+        if (sameGates) {
+            return { allowed: true, reason: null, sliceType, callerKind };
+        }
+        return {
+            allowed: false,
+            reason: `rid already has a different skip applied (existing: [${currentState.skippedGates.join(', ')}]; requested: [${gates.join(', ')}]); abandon or amend manually`,
+            sliceType
+        };
+    }
+    return { allowed: true, reason: null, sliceType, callerKind };
+}
+/**
+ * Apply a skip. Caller is expected to have already called
+ * `canSkipSlice` and received `allowed: true`. The function is
+ * still defensive — if the verdict is `allowed: false`, it returns
+ * the rejection as `applied: false` without writing.
+ */
+export async function applySkip(projectRoot, sessionId, args) {
+    const verdict = await canSkipSlice(projectRoot, sessionId, args, readSkipState(projectRoot, sessionId, args.rid));
+    if (!verdict.allowed) {
+        return {
+            applied: false,
+            idempotent: false,
+            skippedGates: parseGatesList(args.gatesRaw),
+            rid: args.rid,
+            persistedTo: null,
+            reason: verdict.reason
+        };
+    }
+    const gates = parseGatesList(args.gatesRaw);
+    const existing = readSkipState(projectRoot, sessionId, args.rid);
+    if (existing !== null && sameStringSet(existing.skippedGates, gates)) {
+        // Idempotent re-skip.
+        return {
+            applied: false,
+            idempotent: true,
+            skippedGates: existing.skippedGates,
+            rid: args.rid,
+            persistedTo: existing ? pathFromStateFile(projectRoot, sessionId, args.rid) : null,
+            sliceType: verdict.sliceType
+        };
+    }
+    if (args.dryRun === true) {
+        return {
+            applied: false,
+            idempotent: false,
+            skippedGates: gates,
+            rid: args.rid,
+            persistedTo: null,
+            sliceType: verdict.sliceType,
+            reason: 'dry-run: no state written'
+        };
+    }
+    const callerKind = verdict.callerKind;
+    const state = {
+        rid: args.rid,
+        skippedGates: gates,
+        skipReason: args.reason.trim(),
+        skipAppliedAt: new Date().toISOString(),
+        skipAppliedBy: resolveSkipAppliedBy(),
+        callerKind
+    };
+    const persistedTo = writeSkipState(projectRoot, sessionId, state);
+    return {
+        applied: true,
+        idempotent: false,
+        skippedGates: gates,
+        rid: args.rid,
+        persistedTo,
+        sliceType: verdict.sliceType
+    };
+}
+function sameStringSet(a, b) {
+    if (a.length !== b.length)
+        return false;
+    const aSorted = [...a].sort();
+    const bSorted = [...b].sort();
+    return aSorted.every((v, i) => v === bSorted[i]);
+}
+function pathFromStateFile(projectRoot, sessionId, rid) {
+    // Re-export the path-computation from the state store. We avoid
+    // importing the internal helper to keep the public surface narrow.
+    return `${projectRoot}/.peaks/_runtime/${sessionId}/workflow-state/${rid}.json`;
+}
+/** Resolve the author of the skip. Reads `git config --global user.name`
+ *  synchronously; falls back to the OS user if git config is
+ *  unavailable. Never throws. */
+function resolveSkipAppliedBy() {
+    try {
+        // Lazy require so the unit tests can stub via process.env.
+        const { execFileSync } = require('node:child_process');
+        const out = execFileSync('git', ['config', '--global', 'user.name'], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore']
+        });
+        const trimmed = out.trim();
+        if (trimmed.length > 0) {
+            return trimmed;
+        }
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        // fall through
+    }
+    try {
+        const os = require('node:os');
+        const info = os.userInfo();
+        return info.username;
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/** Exposed for tests. */
+export const _internal = { SKIPPABLE_TYPES, SCRIPT_CALLER_IDS, sameStringSet };

package/dist/services/workflow/workflow-spec-lint.d.ts

@@ -0,0 +1,13 @@
+/**
+ * peaks-workflow v3.0.0 — `lintWorkflowSpec` (moved verbatim per rid-006)
+ *
+ * Pure lint over a typed `WorkflowSpec`. No parser/build helpers, no
+ * YAML helpers — lint is pure on the typed spec. The slimmed
+ * `workflow-spec.ts` re-exports `lintWorkflowSpec` under its original
+ * name so existing call sites compile unchanged.
+ *
+ * File budget: ≤ 400 lines (rid-006 split).
+ */
+import type { WorkflowLintReport, WorkflowSpec } from './workflow-spec-types.js';
+/** Lint a parsed spec — returns a report with semantic errors / warnings. */
+export declare function lintWorkflowSpec(spec: WorkflowSpec): WorkflowLintReport;