peaks-cli 1.3.0 → 1.3.2

package/dist/src/services/slice/slice-check-service.js

@@ -0,0 +1,267 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { isDirectory } from '../../shared/fs.js';
+import { getCurrentChangeId } from '../../shared/change-id.js';
+import { verifyPipeline } from '../workflow/pipeline-verify-service.js';
+function runCommand(command, args, cwd, timeoutMs) {
+    const start = Date.now();
+    try {
+        const stdout = execFileSync(command, args, {
+            cwd,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: timeoutMs,
+            maxBuffer: 32 * 1024 * 1024
+        }).toString('utf8');
+        return {
+            status: 'pass',
+            stdout,
+            stderr: '',
+            exitCode: 0,
+            durationMs: Date.now() - start
+        };
+    }
+    catch (error) {
+        const stdout = (error?.stdout ?? '').toString('utf8');
+        const stderr = (error?.stderr ?? '').toString('utf8');
+        return {
+            status: 'fail',
+            stdout,
+            stderr,
+            exitCode: typeof error?.status === 'number' ? error.status : 1,
+            durationMs: Date.now() - start
+        };
+    }
+}
+function tailLines(text, max) {
+    const lines = text.split('\n').filter((l) => l.trim().length > 0);
+    if (lines.length <= max)
+        return lines.join('\n');
+    return [...lines.slice(0, 3), `... (${lines.length - max} more lines) ...`, ...lines.slice(-max + 3)].join('\n');
+}
+async function runTypecheck(projectRoot) {
+    const start = Date.now();
+    const result = runCommand('npx', ['tsc', '--noEmit'], projectRoot, 180_000);
+    const testFiles = result.stdout.match(/(tests?\/.*\.test\.ts)/g) ?? [];
+    return {
+        name: 'typecheck',
+        description: 'npx tsc --noEmit (no JS emit, type-only check)',
+        status: result.status,
+        durationMs: result.durationMs,
+        detail: result.status === 'pass'
+            ? `Typecheck passed in ${result.durationMs}ms.`
+            : tailLines(result.stdout + result.stderr, 10) || `tsc exited with code ${result.exitCode}.`,
+        data: { exitCode: result.exitCode }
+    };
+}
+function parseVitestSummary(stdout, fallbackDuration) {
+    // Vitest 2.x prints e.g. "Test Files  1 passed (1)" and "Tests  1 passed (1)"
+    // and "Duration  0.50s" or "Duration  1.23s". Be lenient with regex.
+    const testsMatch = /Tests?\s+(\d+)\s+(?:passed|run)/.exec(stdout);
+    const failedMatch = /Tests?\s+(\d+)\s+failed/.exec(stdout);
+    const skippedMatch = /Tests?\s+(\d+)\s+skipped/.exec(stdout);
+    const durationMatch = /Duration[^\d]*(\d+(?:\.\d+)?)\s*s/.exec(stdout);
+    return {
+        tests: testsMatch ? parseInt(testsMatch[1], 10) : 0,
+        passed: 0,
+        failed: failedMatch ? parseInt(failedMatch[1], 10) : 0,
+        skipped: skippedMatch ? parseInt(skippedMatch[1], 10) : 0,
+        durationMs: durationMatch ? Math.round(parseFloat(durationMatch[1]) * 1000) : fallbackDuration
+    };
+}
+async function runUnitTests(projectRoot) {
+    const start = Date.now();
+    const result = runCommand('npx', ['vitest', 'run', '--reporter=default', '--coverage=false'], projectRoot, 600_000);
+    const summary = parseVitestSummary(result.stdout, result.durationMs);
+    // Vitest doesn't always print the per-bucket counts cleanly; infer "passed"
+    // as total - failed - skipped when failed/skipped buckets are present.
+    const passed = Math.max(summary.tests - summary.failed - summary.skipped, 0);
+    return {
+        name: 'unit-tests',
+        description: 'npx vitest run (full test suite, coverage off)',
+        status: result.status,
+        durationMs: result.durationMs,
+        detail: result.status === 'pass'
+            ? `All tests passed in ${result.durationMs}ms.`
+            : tailLines(result.stdout + result.stderr, 12) || `vitest exited with code ${result.exitCode}.`,
+        data: {
+            tests: summary.tests,
+            passed,
+            failed: summary.failed,
+            skipped: summary.skipped,
+            exitCode: result.exitCode
+        }
+    };
+}
+const REVIEW_FILES = [
+    { name: 'code-review', path: 'rd/code-review.md', label: 'code-review' },
+    { name: 'security-review', path: 'rd/security-review.md', label: 'security-review' },
+    { name: 'perf-baseline', path: 'rd/perf-baseline.md', label: 'perf-baseline' }
+];
+async function runReviewFanout(projectRoot, rid, refresh) {
+    const start = Date.now();
+    if (refresh) {
+        // `peaks-rd` does the 3-way fan-out when the slice is in `spec-locked` or
+        // `implemented` state. The actual fan-out is invoked via the `peaks-rd`
+        // skill body, not via a CLI subcommand (each sub-agent is invoked with
+        // its own prompt). When `--refresh-fanout` is set, we emit a
+        // nextAction that tells the caller to invoke `Skill(skill="peaks-rd")`
+        // (the role skill owns the 3 review artifact writes).
+        return {
+            name: 'review-fanout',
+            description: '3-way review fan-out (code-review + security-review + perf baseline)',
+            status: 'skipped',
+            durationMs: Date.now() - start,
+            detail: '3-way fan-out is dispatched via Skill(skill="peaks-rd"); invoke it to regenerate the review artifacts.',
+            data: { refresh: true, rid }
+        };
+    }
+    // Default: verify all 3 review files exist with non-empty content. The
+    // files can live under EITHER `.peaks/<rid>/rd/` (active change-id) or
+    // `.peaks/retrospective/<rid>/rd/` (shipped). The boundary check
+    // accepts either — the LLM may be at a slice that's still active
+    // (not yet archived) or one that just shipped.
+    const scopes = [rid, `retrospective/${rid}`];
+    const missing = [];
+    const found = [];
+    for (const review of REVIEW_FILES) {
+        let hit = null;
+        for (const scope of scopes) {
+            const abs = join(projectRoot, '.peaks', scope, review.path);
+            if (existsSync(abs)) {
+                const bytes = statSync(abs).size;
+                if (bytes >= 20) {
+                    hit = { abs, scope, bytes };
+                    break;
+                }
+            }
+        }
+        if (hit === null) {
+            missing.push(review.label);
+            continue;
+        }
+        found.push({ name: review.name, path: hit.abs, bytes: hit.bytes, scope: hit.scope });
+    }
+    const status = missing.length === 0 ? 'pass' : 'fail';
+    return {
+        name: 'review-fanout',
+        description: '3-way review fan-out (code-review + security-review + perf baseline)',
+        status,
+        durationMs: Date.now() - start,
+        detail: status === 'pass'
+            ? `All 3 review artifacts present (${found.map((f) => f.name).join(', ')}; scope: ${found[0]?.scope}).`
+            : `Missing or empty: ${missing.join(', ')}. Re-run with --refresh-fanout or invoke Skill(skill="peaks-rd") to regenerate.`,
+        data: { found, missing }
+    };
+}
+async function runGateVerifyPipeline(projectRoot, rid, changeId) {
+    const start = Date.now();
+    try {
+        const result = await verifyPipeline({ projectRoot, rid, changeId });
+        const duration = Date.now() - start;
+        return {
+            name: 'gate-verify-pipeline',
+            description: 'peaks workflow verify-pipeline (RD/QA gate checks against .peaks/<changeId>/)',
+            status: result.complete ? 'pass' : 'fail',
+            durationMs: duration,
+            detail: result.complete
+                ? `All gates passed in ${duration}ms.`
+                : `${result.violations.length} violation(s): ${result.violations.join('; ')}`,
+            data: {
+                rdGates: result.rdPhase.gates.length,
+                qaGates: result.qaPhase.gates.length,
+                rdState: result.rdPhase.state,
+                qaState: result.qaPhase.state,
+                violations: result.violations,
+                nextActions: result.nextActions
+            }
+        };
+    }
+    catch (error) {
+        return {
+            name: 'gate-verify-pipeline',
+            description: 'peaks workflow verify-pipeline (RD/QA gate checks against .peaks/<changeId>/)',
+            status: 'fail',
+            durationMs: Date.now() - start,
+            detail: error?.message ?? 'verify-pipeline threw',
+            data: {}
+        };
+    }
+}
+export async function sliceCheck(options) {
+    const peaksRoot = join(options.projectRoot, '.peaks');
+    if (!(await isDirectory(peaksRoot))) {
+        throw new Error(`.peaks/ not found at ${options.projectRoot}. Run peaks workspace init first.`);
+    }
+    // Resolve rid: explicit > current-change binding > null
+    let rid = options.rid;
+    if (rid === undefined) {
+        const bound = getCurrentChangeId(options.projectRoot);
+        if (bound !== null) {
+            rid = bound;
+        }
+    }
+    if (rid === undefined) {
+        throw new Error('No --rid and no current-change binding. Pass --rid <id> or run peaks workspace init --change-id <id> first.');
+    }
+    const totalStart = Date.now();
+    const stages = [];
+    // Stage 1: typecheck
+    stages.push(await runTypecheck(options.projectRoot));
+    // Stage 2: full vitest
+    if (!options.skipTests) {
+        const unitTests = await runUnitTests(options.projectRoot);
+        // Opt-in override: if --allow-pre-existing-failures is set AND the
+        // unit-test stage failed, downgrade `failed` to `skipped` with a
+        // reason that names the failure count and points to the long-term
+        // fix. Does NOT affect the other 3 stages.
+        if (options.allowPreExistingFailures === true &&
+            unitTests.status === 'fail') {
+            const failureCount = unitTests.data?.failed ?? 0;
+            stages.push({
+                name: 'unit-tests',
+                description: 'npx vitest run (overridden via --allow-pre-existing-failures)',
+                status: 'skipped',
+                durationMs: unitTests.durationMs,
+                detail: `pre-existing failures: ${failureCount} failing test(s) under coverage.exclude or unrelated to this slice; user opted in via --allow-pre-existing-failures. For the long-term fix, mark these tests .skip or move to coverage.exclude (see dogfood-2-f1-f4.md F17c).`,
+                data: { ...(unitTests.data ?? {}), overriddenFrom: 'fail', failureCount }
+            });
+        }
+        else {
+            stages.push(unitTests);
+        }
+    }
+    else {
+        stages.push({
+            name: 'unit-tests',
+            description: 'npx vitest run (skipped per --skip-tests)',
+            status: 'skipped',
+            durationMs: 0,
+            detail: 'Skipped: --skip-tests was set.'
+        });
+    }
+    // Stage 3: 3-way review fanout check
+    stages.push(await runReviewFanout(options.projectRoot, rid, options.refreshFanout));
+    // Stage 4: gate verify-pipeline
+    stages.push(await runGateVerifyPipeline(options.projectRoot, rid, rid));
+    const boundaryReady = stages.every((s) => s.status === 'pass' || s.status === 'skipped');
+    const nextActions = [];
+    if (!boundaryReady) {
+        const failed = stages.filter((s) => s.status === 'fail');
+        for (const f of failed) {
+            nextActions.push(`Fix ${f.name}: ${f.detail.split('\n')[0]}`);
+        }
+    }
+    else {
+        nextActions.push(`peaks request transition ${rid} --role rd --state qa-handoff --confirm --project <path>`);
+        nextActions.push(`peaks request transition ${rid} --role qa --state verdict-issued --confirm --project <path>`);
+    }
+    return {
+        projectRoot: options.projectRoot,
+        rid,
+        stages,
+        boundaryReady,
+        totalDurationMs: Date.now() - totalStart,
+        nextActions
+    };
+}

package/dist/src/services/slice/slice-check-types.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Type envelope for the `peaks slice check` CLI command.
+ *
+ * `peaks slice check` is the boundary check for the RD micro-cycle
+ * (see `skills/peaks-solo/references/micro-cycle.md`). It bundles the
+ * 4 self-checks that must pass at slice end before the slice is handed
+ * off to peaks-qa:
+ *
+ *   1. typecheck (`npx tsc --noEmit`)
+ *   2. unit tests (`npx vitest run`)
+ *   3. 3-way review fan-out (code-review + security-review + perf-baseline)
+ *   4. gate machinery (`peaks workflow verify-pipeline --rid <rid>`)
+ *
+ * The micro-cycle itself (per-bug TDD) runs OUTSIDE slice check — only
+ * single-test runs (`vitest -t "<name>"`) are allowed in micro-cycles.
+ * This command is for the BOUNDARY, not the inner loop.
+ */
+export type SliceCheckStageStatus = 'pass' | 'fail' | 'skipped';
+export type SliceCheckStage = {
+    /** Stable id for the stage (matches the runbook's check list). */
+    name: 'typecheck' | 'unit-tests' | 'review-fanout' | 'gate-verify-pipeline';
+    /** Human-readable description. */
+    description: string;
+    status: SliceCheckStageStatus;
+    /** Wall-clock duration in ms; null if skipped. */
+    durationMs: number | null;
+    /** Free-form detail (summary line + last error line). */
+    detail: string;
+    /** Optional structured data (e.g. test counts, gate counts). */
+    data?: Record<string, unknown>;
+};
+export type SliceCheckResult = {
+    /** Absolute project root the command operated on. */
+    projectRoot: string;
+    /** Request id the boundary check applies to; null if no slice is active. */
+    rid: string | null;
+    /** All stages in execution order. */
+    stages: SliceCheckStage[];
+    /** True iff every stage passed (or was skipped) and the boundary is OK to hand off. */
+    boundaryReady: boolean;
+    /** Total wall-clock duration in ms. */
+    totalDurationMs: number;
+    /** Next steps suggested when boundaryReady is false. */
+    nextActions: string[];
+};
+export type SliceCheckOptions = {
+    projectRoot: string;
+    /** When omitted, slice check inspects `.peaks/_runtime/current-change` to find the active rid. */
+    rid?: string;
+    /**
+     * When true, re-run the 3-way review fan-out (peaks-rd's code-review +
+     * security-review + perf-baseline sub-agents) even if the review files
+     * already exist. The default is to verify presence and skip if all 3 are present.
+     */
+    refreshFanout: boolean;
+    /**
+     * When true, skip the unit-test stage. Useful when a slice has no unit
+     * tests (e.g. a docs-only or config-only slice).
+     */
+    skipTests: boolean;
+    /**
+     * When true, an `unit-tests` stage that fails is reported as `skipped`
+     * (with a `reason` naming the pre-existing failure count) instead of
+     * `failed`. Used to opt in to bypassing the 28 pre-existing Windows
+     * test failures documented in dogfood-2-f1-f4.md F17. Does NOT affect
+     * the other 3 stages (typecheck / review-fanout / gate-verify-pipeline).
+     * Default: false. The service treats `undefined` the same as `false`.
+     */
+    allowPreExistingFailures?: boolean;
+};

package/dist/src/services/slice/slice-check-types.js

@@ -0,0 +1,18 @@
+/**
+ * Type envelope for the `peaks slice check` CLI command.
+ *
+ * `peaks slice check` is the boundary check for the RD micro-cycle
+ * (see `skills/peaks-solo/references/micro-cycle.md`). It bundles the
+ * 4 self-checks that must pass at slice end before the slice is handed
+ * off to peaks-qa:
+ *
+ *   1. typecheck (`npx tsc --noEmit`)
+ *   2. unit tests (`npx vitest run`)
+ *   3. 3-way review fan-out (code-review + security-review + perf-baseline)
+ *   4. gate machinery (`peaks workflow verify-pipeline --rid <rid>`)
+ *
+ * The micro-cycle itself (per-bug TDD) runs OUTSIDE slice check — only
+ * single-test runs (`vitest -t "<name>"`) are allowed in micro-cycles.
+ * This command is for the BOUNDARY, not the inner loop.
+ */
+export {};

package/dist/src/services/workflow/pipeline-verify-service.d.ts

@@ -7,7 +7,7 @@ export type PipelineGate = {
 };
 export type PipelineVerification = {
     rid: string;
-    sessionId: string;
+    changeId: string;
     requestType: RequestType;
     complete: boolean;
     rdPhase: {
@@ -26,6 +26,9 @@ export type PipelineVerification = {
 export declare function verifyPipeline(options: {
     projectRoot: string;
     rid: string;
-    sessionId: string;
+    /** Optional explicit change-id; when omitted, the RD/QA on-disk location
+     * is resolved via showRequestArtifact (which scans all top-level dirs and
+     * returns the actual change-id the file lives in). */
+    changeId?: string;
     requestType?: string;
 }): Promise<PipelineVerification>;

package/dist/src/services/workflow/pipeline-verify-service.js

@@ -1,15 +1,7 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { readFile } from 'node:fs/promises';
 import { isRequestType } from '../artifacts/artifact-prerequisites.js';
-async function readFileContent(path) {
-    try {
-        return await readFile(path, 'utf8');
-    }
-    catch {
-        return null;
-    }
-}
+import { showRequestArtifact } from '../artifacts/request-artifact-service.js';
 function extractState(markdown) {
     for (const rawLine of markdown.split(/\r?\n/)) {
         const match = /^-\s*state:\s*(.+?)\s*$/.exec(rawLine.trim());
@@ -18,23 +10,19 @@ function extractState(markdown) {
     }
     return 'unknown';
 }
-async function findRequestFile(projectRoot, sessionId, role, rid) {
-    const dir = join(projectRoot, '.peaks', sessionId, role, 'requests');
-    if (!existsSync(dir))
+/**
+ * As of slice 2026-06-05-change-id-as-unit-of-work, the file's durable
+ * scope is the change-id (the `.peaks/<changeId>/` dir the file lives
+ * in), NOT the session-id. We resolve the on-disk location via
+ * `showRequestArtifact` (which scans all top-level dirs and returns the
+ * actual dir the file was found in) instead of assuming
+ * `.peaks/<sessionId>/<role>/requests/`.
+ */
+async function findRequestFile(projectRoot, role, rid) {
+    const artifact = await showRequestArtifact({ projectRoot, role: role, requestId: rid });
+    if (artifact === null)
         return null;
-    const { readdir } = await import('node:fs/promises');
-    const entries = await readdir(dir, { withFileTypes: true });
-    for (const entry of entries) {
-        if (!entry.isFile() || !entry.name.endsWith('.md'))
-            continue;
-        if (entry.name === `${rid}.md` || (/^\d+-/.test(entry.name) && entry.name.endsWith(`-${rid}.md`))) {
-            const path = join(dir, entry.name);
-            const content = await readFileContent(path);
-            if (content)
-                return { path, content };
-        }
-    }
-    return null;
+    return { path: artifact.path, content: artifact.content, changeId: artifact.changeId };
 }
 function rdGatesForType(requestType) {
     const gates = [
@@ -78,31 +66,42 @@ export async function verifyPipeline(options) {
     const nextActions = [];
     const rdGates = rdGatesForType(requestType);
     const qaGates = qaGatesForType(requestType);
-    // Check RD phase
-    const rdFile = await findRequestFile(options.projectRoot, options.sessionId, 'rd', options.rid);
+    // Resolve RD + QA on-disk locations via showRequestArtifact (the change-id
+    // is whatever dir the file actually lives in, not the caller's session-id).
+    const rdFile = await findRequestFile(options.projectRoot, 'rd', options.rid);
     let rdInvoked = false;
     let rdState = 'missing';
+    // The resolved change-id is the on-disk location the file actually
+    // lives in. The caller's `options.changeId` is a hint used for
+    // path construction (nextActions strings), NOT for the resolved
+    // changeId field — the on-disk location is the source of truth.
+    let resolvedChangeId = '';
     if (rdFile) {
         rdInvoked = true;
         rdState = extractState(rdFile.content);
         rdGates[0].passed = true;
         rdGates[0].detail = `found at ${rdFile.path}`;
+        resolvedChangeId = rdFile.changeId;
     }
     else {
         violations.push('RD phase skipped: peaks-rd was never invoked for this request (no RD request artifact found)');
         nextActions.push('Invoke Skill(skill="peaks-rd") with the request-id, then run unit tests + code review + security review');
         rdGates[0].detail = 'not found';
     }
-    // Check RD evidence files
+    // Check RD evidence files (under the change-id dir the RD request lives in)
     const RD_EVIDENCE_FILE = {
         'tech-doc': 'tech-doc.md',
         'bug-analysis': 'bug-analysis.md',
         'code-review': 'code-review.md',
         'security-review': 'security-review.md'
     };
+    // The evidence dir: prefer the on-disk changeId; fall back to the
+    // caller's hint; final fallback to the requestId (back-compat for
+    // pre-1.3.0 trees where the file lived under .peaks/<rid>/).
+    const rdEvidenceDir = resolvedChangeId || options.changeId || options.rid;
     for (const gate of rdGates.slice(1)) {
         const fileName = RD_EVIDENCE_FILE[gate.name];
-        const evidencePath = join(options.projectRoot, '.peaks', options.sessionId, 'rd', fileName);
+        const evidencePath = join(options.projectRoot, '.peaks', rdEvidenceDir, 'rd', fileName);
         if (existsSync(evidencePath)) {
             gate.passed = true;
             gate.detail = evidencePath;
@@ -110,7 +109,7 @@ export async function verifyPipeline(options) {
         else {
             gate.detail = `missing: ${evidencePath}`;
             violations.push(`RD evidence missing: ${gate.description} (${fileName})`);
-            nextActions.push(`Create .peaks/${options.sessionId}/rd/${fileName}`);
+            nextActions.push(`Create .peaks/${rdEvidenceDir}/rd/${fileName}`);
         }
     }
     // Check if RD reached qa-handoff
@@ -119,7 +118,7 @@ export async function verifyPipeline(options) {
         nextActions.push(`Complete RD gates → peaks request transition ${options.rid} --role rd --state qa-handoff`);
     }
     // Check QA phase
-    const qaFile = await findRequestFile(options.projectRoot, options.sessionId, 'qa', options.rid);
+    const qaFile = await findRequestFile(options.projectRoot, 'qa', options.rid);
     let qaInvoked = false;
     let qaState = 'missing';
     if (qaFile) {
@@ -127,13 +126,14 @@ export async function verifyPipeline(options) {
         qaState = extractState(qaFile.content);
         qaGates[0].passed = true;
         qaGates[0].detail = `found at ${qaFile.path}`;
+        resolvedChangeId = qaFile.changeId || resolvedChangeId;
     }
     else {
         violations.push('QA phase skipped: peaks-qa was never invoked for this request (no QA request artifact found)');
         nextActions.push('Invoke Skill(skill="peaks-qa") with the request-id for functional/performance/security testing');
         qaGates[0].detail = 'not found';
     }
-    // Check QA evidence files
+    // Check QA evidence files (under the same change-id dir)
     const QA_EVIDENCE_FILE = {
         'test-cases': `test-cases/${options.rid}.md`,
         'test-report': `test-reports/${options.rid}.md`,
@@ -142,7 +142,7 @@ export async function verifyPipeline(options) {
     };
     for (const gate of qaGates.slice(1)) {
         const fileName = QA_EVIDENCE_FILE[gate.name];
-        const evidencePath = join(options.projectRoot, '.peaks', options.sessionId, 'qa', fileName);
+        const evidencePath = join(options.projectRoot, '.peaks', rdEvidenceDir, 'qa', fileName);
         if (existsSync(evidencePath)) {
             gate.passed = true;
             gate.detail = evidencePath;
@@ -150,7 +150,7 @@ export async function verifyPipeline(options) {
         else {
             gate.detail = `missing: ${evidencePath}`;
             violations.push(`QA evidence missing: ${gate.description} (${fileName})`);
-            nextActions.push(`Create .peaks/${options.sessionId}/qa/${fileName}`);
+            nextActions.push(`Create .peaks/${rdEvidenceDir}/qa/${fileName}`);
         }
     }
     // Check if QA reached verdict-issued
@@ -169,7 +169,7 @@ export async function verifyPipeline(options) {
         && RD_QA_HANDOFF_STATES.has(rdState) && QA_COMPLETE_STATES.has(qaState);
     return {
         rid: options.rid,
-        sessionId: options.sessionId,
+        changeId: resolvedChangeId,
         requestType,
         complete,
         rdPhase: { invoked: rdInvoked, state: rdState, gates: rdGates },

package/dist/src/services/workspace/migrate-service.d.ts

@@ -0,0 +1,2 @@
+import type { MigrateOptions, MigrateResult } from './migrate-types.js';
+export declare function migrateWorkspace(options: MigrateOptions): Promise<MigrateResult>;