peaks-cli 1.3.6 → 1.3.7

package/dist/src/cli/commands/slice-commands.js

@@ -5,25 +5,29 @@ import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 export function registerSliceCommands(program, io) {
     const slice = program.command('slice').description('Run slice-level checks (TDD micro-cycle boundary, see ' +
         'skills/peaks-solo/references/micro-cycle.md). `peaks slice check` bundles ' +
-        'tsc + vitest + 3-way review fan-out + gate verify-pipeline. ' +
+        'tsc + vitest (changed-only by default) + 3-way review fan-out + gate verify-pipeline. ' +
         'Boundaries only; do NOT run inside a micro-cycle.');
     addJsonOption(slice
         .command('check')
         .description('Boundary check for a slice (post-micro-cycle, pre-peaks-qa). ' +
-        'Runs 4 stages in order: typecheck → unit-tests → review-fanout → ' +
-        'gate-verify-pipeline. Each stage reports pass / fail / skipped. ' +
+        'Runs 4 stages in order: typecheck → unit-tests (changed-only by default; ' +
+        'use --run-tests for the full suite, or --skip-tests to opt out) → ' +
+        'review-fanout → gate-verify-pipeline. ' +
+        'Each stage reports pass / fail / skipped. ' +
         'Exit 0 only if every stage passes or is skipped.')
         .option('--project <path>', 'target project root', '.')
         .option('--rid <rid>', 'request id; defaults to the active current-change binding')
         .option('--refresh-fanout', 're-run the 3-way review fan-out (peaks-rd) even if the review files already exist', false)
-        .option('--skip-tests', 'skip the unit-test stage (e.g. docs-only slices)', false)
-        .option('--allow-pre-existing-failures', 'opt-in: if the unit-test stage fails, report it as `skipped` with a reason naming the failure count (useful when the repo has unrelated pre-existing failures; the long-term fix is to .skip or coverage.exclude those tests)', false)).action(async (options) => {
+        .option('--run-tests', 'opt in to the FULL test suite at the boundary (default is the changed-only suite via `vitest run --changed`); use the peaks-solo-test skill to run the full suite standalone', false)
+        .option('--skip-tests', 'skip the unit-test stage entirely (e.g. docs-only slices); use the peaks-solo-test skill to run the full suite manually if you want a separate check', false)
+        .option('--allow-pre-existing-failures', 'opt-in: if the unit-test stage fails, report it as `skipped` with a reason naming the failure count (useful when the repo has unrelated pre-existing failures; the long-term fix is to .skip or coverage.exclude those tests). Only meaningful with --run-tests or the default changed-only mode.', false)).action(async (options) => {
         try {
             const projectRoot = resolveCanonicalProjectRoot(options.project);
             const result = await sliceCheck({
                 projectRoot,
                 ...(options.rid ? { rid: options.rid } : {}),
                 refreshFanout: options.refreshFanout === true,
+                runTests: options.runTests === true,
                 skipTests: options.skipTests === true,
                 allowPreExistingFailures: options.allowPreExistingFailures === true
             });

package/dist/src/cli/commands/workspace-commands.js

@@ -4,7 +4,7 @@ import { createInterface } from 'node:readline';
 import { initWorkspace, InvalidSessionIdError, ConflictingSessionError } from '../../services/workspace/workspace-service.js';
 import { reconcileWorkspace } from '../../services/workspace/reconcile-service.js';
 import { migrateWorkspace } from '../../services/workspace/migrate-service.js';
-import { ensureSession } from '../../services/session/session-manager.js';
+import { ensureSessionWithRotation } from '../../services/session/session-manager.js';
 import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
 import { applyHookInstall, readHookStatus } from '../../services/skills/hooks-settings-service.js';
 import { fail, ok } from '../../shared/result.js';
@@ -93,6 +93,7 @@ export function registerWorkspaceCommands(program, io) {
         .requiredOption('--project <path>', 'target project root')
         .option('--session-id <id>', 'optional session id in YYYY-MM-DD-<kebab-slug> format. When omitted, the CLI is the single source of truth: an existing binding is reused, otherwise a fresh id is auto-generated.')
         .option('--allow-session-rebind', 'overwrite an existing session binding when the requested session id differs from the project current one', false)
+        .option('--no-rotate-on-outer-mismatch', 'suppress the auto-rotation of the project session binding when the outer (Claude / harness) session id has changed. Default rotates on mismatch.')
         .option('--change-id <id>', 'bind the change-id for reviewable artifacts (writes route to .peaks/<change-id>/<role>/, tracked in git). When omitted, the change-id binding is left unchanged.', (value) => {
         if (value.length === 0) {
             throw new Error('--change-id must not be empty');
@@ -124,12 +125,41 @@ export function registerWorkspaceCommands(program, io) {
             // the 5/27-5/29 sessions). When startPath is not inside any
             // git repo, the helper falls through to the cwd verbatim.
             const projectRoot = resolveCanonicalProjectRoot(options.project);
+            // Slice 018: outer-session-mismatch auto-rotation. When the
+            // user did NOT pass --session-id explicitly, run
+            // `ensureSessionWithRotation` so the binding is rotated on
+            // outer-mismatch before `initWorkspace` is called. The
+            // rotation result is surfaced in the JSON envelope via
+            // `data.rotation`. When --session-id IS passed, the user has
+            // explicitly told us which session to bind — we honor that
+            // verbatim and do NOT rotate (rotation only fires for the
+            // auto-detect path).
             let sessionId;
+            let rotation = {
+                previousSessionId: null,
+                reason: null
+            };
             if (options.sessionId !== undefined && options.sessionId.length > 0) {
                 sessionId = options.sessionId;
             }
             else {
-                sessionId = await ensureSession(projectRoot);
+                const result = await ensureSessionWithRotation(projectRoot, {
+                    // Commander translates `--no-rotate-on-outer-mismatch` into
+                    // `options.rotateOnOuterMismatch = false` (the `--no-` prefix
+                    // is consumed and the remainder becomes the JS property name,
+                    // with the boolean value flipped). The pre-slice-014 anti-
+                    // pattern (reading `options.<flag-with-no-prefix> === true`)
+                    // is NOT used here. The default (no flag) leaves
+                    // `options.rotateOnOuterMismatch` undefined, which is not
+                    // equal to `false`, so the default is "rotate on mismatch"
+                    // (the new auto-roll).
+                    skipRotateOnOuterMismatch: options.rotateOnOuterMismatch === false
+                });
+                sessionId = result.sessionId;
+                rotation = {
+                    previousSessionId: result.previousSessionId,
+                    reason: result.rotationReason
+                };
             }
             const report = await initWorkspace({
                 projectRoot,
@@ -141,6 +171,14 @@ export function registerWorkspaceCommands(program, io) {
             if (report.previousSessionId !== null && report.bound) {
                 nextActions.push(`Replaced prior session binding "${report.previousSessionId}" with "${report.sessionId}".`);
             }
+            if (rotation.previousSessionId !== null && rotation.reason === 'outer-session-mismatch') {
+                // Outer-session-mismatch rotation: the previous Claude / harness
+                // session is no longer the LLM driver. The new binding is fresh,
+                // the old session dir is preserved on disk.
+                nextActions.push(`Auto-rotated session binding: outer session id changed (was "${rotation.previousSessionId}"). ` +
+                    `New binding is "${sessionId}". The previous session dir is preserved at .peaks/_runtime/${rotation.previousSessionId}/. ` +
+                    `Re-run with --no-rotate-on-outer-mismatch to suppress this rotation.`);
+            }
             if (report.created.length === 0) {
                 nextActions.push('Workspace already initialized — proceed to project scan.');
             }
@@ -168,6 +206,12 @@ export function registerWorkspaceCommands(program, io) {
             }
             printResult(io, ok('workspace.init', {
                 ...report,
+                // Slice 018: surface outer-session-mismatch rotation in the
+                // JSON envelope so the LLM and the human both see the swap.
+                // Field is omitted (not null) when no rotation fired.
+                ...(rotation.previousSessionId !== null && rotation.reason !== null
+                    ? { rotation: { previousSessionId: rotation.previousSessionId, reason: rotation.reason } }
+                    : {}),
                 hooksInstall: {
                     decision: hooksOutcome.decision,
                     action: hooksOutcome.action,

package/dist/src/services/session/session-manager.d.ts

@@ -89,7 +89,62 @@ export declare function setSessionTitle(projectRoot: string, sessionId: string,
  * release) but is not authoritative.
  */
 export declare function listSessionMetas(projectRoot: string): SessionMeta[];
+export type EnsureSessionOptions = {
+    /**
+     * When `true`, suppress the outer-session-mismatch auto-rotation.
+     * The caller wants today's "stamp the field, do not rotate" behaviour
+     * even when the outer session id has changed. Used by
+     * `peaks workspace init --no-rotate-on-outer-mismatch`.
+     */
+    skipRotateOnOuterMismatch?: boolean;
+};
+/**
+ * Result of `ensureSessionWithRotation`. When the bound session was
+ * rotated because the outer session id had changed, `previousSessionId`
+ * is the id of the unbound session and `rotationReason` is the structured
+ * reason code the CLI surfaces in its JSON envelope.
+ */
+export type EnsureSessionResult = {
+    sessionId: string;
+    previousSessionId: string | null;
+    rotationReason: 'outer-session-mismatch' | null;
+};
 export declare function ensureSession(projectRoot: string): Promise<string>;
+/**
+ * Outer-session-aware wrapper around `ensureSession`.
+ *
+ * Slice 018 (auto-roll on outer-mismatch). When the current outer
+ * session id (sourced from `PEAKS_OUTER_SESSION_ID` with
+ * `CLAUDE_CODE_SESSION_ID` as the Claude-Code fallback) differs from
+ * the outer session id recorded on the *bound* peaks session's
+ * `.peaks/_runtime/<sid>/session.json`, the project-level session
+ * binding is rotated before `ensureSession` is called. The old
+ * session dir is preserved on disk (data is never wiped) — only the
+ * binding changes — and the rotation is surfaced in the return value
+ * so the CLI can include it in the JSON envelope.
+ *
+ * Rotation is suppressed in three cases (all false-positive guards):
+ *
+ *   1. The current outer session id is undefined (no env var set) —
+ *      there is no signal to compare against, defaulting to "do not
+ *      rotate" avoids orphaning the session.
+ *   2. The bound session has no recorded `outerSessionId` (legacy
+ *      session predating the outer-session contract) — there is no
+ *      signal on the other side either.
+ *   3. The bound session's recorded outer session id matches the
+ *      current one (reconnect within the same Claude session) — this
+ *      is the common case, not a swap.
+ *
+ * When `options.skipRotateOnOuterMismatch === true`, the rotation
+ * check is short-circuited and the binding is preserved (opt-out for
+ * `peaks workspace init --no-rotate-on-outer-mismatch`). The wrapper
+ * still delegates to `ensureSession` so the caller gets the existing
+ * binding on a reconnect and a fresh id on a first run.
+ *
+ * Existing public surface is preserved: `ensureSession` is unchanged.
+ * This wrapper is the new entry point the CLI uses.
+ */
+export declare function ensureSessionWithRotation(projectRoot: string, options?: EnsureSessionOptions): Promise<EnsureSessionResult>;
 /**
  * Get the current session ID without creating a new one.
  * Returns null if no session exists.

package/dist/src/services/session/session-manager.js

@@ -421,6 +421,74 @@ export async function ensureSession(projectRoot) {
     });
     return sessionId;
 }
+/**
+ * Outer-session-aware wrapper around `ensureSession`.
+ *
+ * Slice 018 (auto-roll on outer-mismatch). When the current outer
+ * session id (sourced from `PEAKS_OUTER_SESSION_ID` with
+ * `CLAUDE_CODE_SESSION_ID` as the Claude-Code fallback) differs from
+ * the outer session id recorded on the *bound* peaks session's
+ * `.peaks/_runtime/<sid>/session.json`, the project-level session
+ * binding is rotated before `ensureSession` is called. The old
+ * session dir is preserved on disk (data is never wiped) — only the
+ * binding changes — and the rotation is surfaced in the return value
+ * so the CLI can include it in the JSON envelope.
+ *
+ * Rotation is suppressed in three cases (all false-positive guards):
+ *
+ *   1. The current outer session id is undefined (no env var set) —
+ *      there is no signal to compare against, defaulting to "do not
+ *      rotate" avoids orphaning the session.
+ *   2. The bound session has no recorded `outerSessionId` (legacy
+ *      session predating the outer-session contract) — there is no
+ *      signal on the other side either.
+ *   3. The bound session's recorded outer session id matches the
+ *      current one (reconnect within the same Claude session) — this
+ *      is the common case, not a swap.
+ *
+ * When `options.skipRotateOnOuterMismatch === true`, the rotation
+ * check is short-circuited and the binding is preserved (opt-out for
+ * `peaks workspace init --no-rotate-on-outer-mismatch`). The wrapper
+ * still delegates to `ensureSession` so the caller gets the existing
+ * binding on a reconnect and a fresh id on a first run.
+ *
+ * Existing public surface is preserved: `ensureSession` is unchanged.
+ * This wrapper is the new entry point the CLI uses.
+ */
+export async function ensureSessionWithRotation(projectRoot, options) {
+    const skipRotate = options?.skipRotateOnOuterMismatch === true;
+    const currentOuterSessionId = getCurrentOuterSessionId();
+    // Compute the rotation decision up front. We only rotate when ALL
+    // three pre-conditions hold: (a) the current outer session id is
+    // defined, (b) the bound session has a recorded outer session id,
+    // and (c) the two differ. The bound session id is the *first*
+    // read so we can use it both for the comparison and for the
+    // rotation result.
+    const boundSessionId = getSessionId(projectRoot);
+    let rotated = null;
+    let rotationReason = null;
+    if (boundSessionId !== null && currentOuterSessionId !== undefined) {
+        const boundMeta = getSessionMeta(projectRoot, boundSessionId);
+        const boundOuter = boundMeta?.outerSessionId;
+        if (typeof boundOuter === 'string' &&
+            boundOuter.length > 0 &&
+            boundOuter !== currentOuterSessionId &&
+            !skipRotate) {
+            rotated = rotateSessionBinding(projectRoot);
+            rotationReason = 'outer-session-mismatch';
+        }
+    }
+    // After the rotation, `ensureSession` will either reuse the
+    // canonical-fallback binding (when one still exists, e.g. a sibling
+    // projectRoot form) or auto-generate a fresh id. We pass through.
+    void rotated; // rotated is the *previous* session id; preserved for the caller via the return value
+    const sessionId = await ensureSession(projectRoot);
+    return {
+        sessionId,
+        previousSessionId: rotated,
+        rotationReason
+    };
+}
 /**
  * Get the current session ID without creating a new one.
  * Returns null if no session exists.

package/dist/src/services/skills/skill-presence-service.d.ts

@@ -22,10 +22,16 @@ export type SkillPresence = {
      * Set by `setSkillPresence` when the outer session id changed
      * between the last presence write and this one AND the bound
      * peaks session has a different (or no) recorded outer session id.
-     * The field is informational only — `setSkillPresence` does not
-     * roll a new session on its own. peaks-solo's Step 0 reads the
-     * field off the presence file and turns it into an
-     * AskUserQuestion: "Start a new peaks session / Keep this one".
+     *
+     * As of slice 018 (auto-roll on outer-mismatch), the field is
+     * informational only — it tells the statusline and any log /
+     * observability consumer that an outer-session swap was observed
+     * on the previous heartbeat. The actual binding rotation is
+     * performed by `ensureSessionWithRotation` (slice 018), not by
+     * `setSkillPresence`. `peaks-solo`'s Step 0 used to read this
+     * field and turn it into an AskUserQuestion; that ask is no
+     * longer needed because the rotation already happened by the time
+     * the skill is invoked.
      */
     outerSessionMismatch?: {
         previous?: string;

package/dist/src/services/skills/skill-presence-service.js

@@ -124,18 +124,23 @@ function getBoundOuterSessionId(projectRootOverride) {
  * Used to detect "the LLM just opened a fresh outer session" — if
  * the previously-recorded outer session id differs from the one we
  * are about to stamp, the user probably closed the previous outer
- * session and is now driving peaks from a new one. We do NOT auto-
- * roll a new peaks session (that is destructive — it would leave
- * the in-flight session with no LLM watching it). Instead we emit
- * a structured `outerSessionMismatch` field on the presence
- * envelope, and peaks-solo's Step 0 turns that into an
- * AskUserQuestion. The user can opt to keep the current session
- * (most common when the swap is a no-op reconnect) or to roll a
- * fresh session (when the new outer session is genuinely a new
- * task).
+ * session and is now driving peaks from a new one.
  *
- * Reads from `.peaks/_runtime/active-skill.json` first; falls back to
- * the legacy `.peaks/.active-skill.json` for one minor release.
+ * As of slice 018 (auto-roll on outer-mismatch), the actual rotation
+ * is `ensureSessionWithRotation`'s job, not this one. The presence
+ * service still emits the structured `outerSessionMismatch` field on
+ * the presence envelope (useful for the statusline to render a stale
+ * marker and for the QA / log consumers to know an outer-session swap
+ * happened), but it no longer carries the implicit "ask the user"
+ * promise — `peaks-solo`'s Step 0 no longer needs to surface an
+ * AskUserQuestion, because the rotation already fired by the time the
+ * skill is invoked.
+ *
+ * `getPreviousOuterSessionId` keeps its read-side role: it powers the
+ * informational `outerSessionMismatch` field below and the legacy
+ * `claudeSessionId` back-compat. Reads from
+ * `.peaks/_runtime/active-skill.json` first; falls back to the
+ * legacy `.peaks/.active-skill.json` for one minor release.
  */
 function getPreviousOuterSessionId(projectRootOverride) {
     const result = readSkillPresenceBackCompat(projectRootOverride);

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

@@ -69,16 +69,27 @@ function parseVitestSummary(stdout, fallbackDuration) {
         durationMs: durationMatch ? Math.round(parseFloat(durationMatch[1]) * 1000) : fallbackDuration
     };
 }
-async function runUnitTests(projectRoot) {
+async function runUnitTests(projectRoot, runTests) {
     const start = Date.now();
-    const result = runCommand('npx', ['vitest', 'run', '--reporter=default', '--coverage=false'], projectRoot, 600_000);
+    // Default: changed-only suite (`vitest run --changed`) — runs only tests
+    // related to git-changed files. Cost drops from 30s+ to ~1-3s in steady
+    // state. Opt-in to the full suite via `runTests: true` (CLI flag
+    // `--run-tests`). See `references/runbook.md` for the rationale and
+    // `tests/unit/slice-check-service.test.ts` for the regression net.
+    const args = runTests
+        ? ['vitest', 'run', '--reporter=default', '--coverage=false']
+        : ['vitest', 'run', '--changed', '--reporter=default', '--coverage=false'];
+    const description = runTests
+        ? 'npx vitest run (full test suite, coverage off)'
+        : 'npx vitest run --changed (tests for git-changed files only, coverage off)';
+    const result = runCommand('npx', args, 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)',
+        description,
         status: result.status,
         durationMs: result.durationMs,
         detail: result.status === 'pass'
@@ -89,6 +100,7 @@ async function runUnitTests(projectRoot) {
             passed,
             failed: summary.failed,
             skipped: summary.skipped,
+            mode: runTests ? 'full' : 'changed',
             exitCode: result.exitCode
         }
     };
@@ -206,40 +218,45 @@ export async function sliceCheck(options) {
     }
     const totalStart = Date.now();
     const stages = [];
+    let unitTestsRunMode = 'skipped';
     // 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
+    // Stage 2: unit-tests — by default changed-only suite, opt-in to full
+    if (options.skipTests) {
+        stages.push({
+            name: 'unit-tests',
+            description: 'npx vitest run (skipped per --skip-tests)',
+            status: 'skipped',
+            durationMs: 0,
+            detail: 'Skipped: --skip-tests was set. Use the peaks-solo-test skill to run the full suite manually.'
+        });
+        unitTestsRunMode = 'skipped';
+    }
+    else {
+        const unitTests = await runUnitTests(options.projectRoot, options.runTests === true);
         // 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.
+        // fix. Does NOT affect the other 3 stages. Only meaningful when
+        // the stage actually runs (skipped-tests bypass short-circuits
+        // above).
         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)',
+                description: `npx vitest run ${options.runTests === true ? '' : '--changed '} (overridden via --allow-pre-existing-failures)`.trim(),
                 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 }
             });
+            unitTestsRunMode = 'overridden';
         }
         else {
             stages.push(unitTests);
+            unitTestsRunMode = options.runTests === true ? 'full' : 'changed';
         }
     }
-    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
@@ -260,6 +277,7 @@ export async function sliceCheck(options) {
         projectRoot: options.projectRoot,
         rid,
         stages,
+        unitTestsRunMode,
         boundaryReady,
         totalDurationMs: Date.now() - totalStart,
         nextActions

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

@@ -7,13 +7,23 @@
  * off to peaks-qa:
  *
  *   1. typecheck (`npx tsc --noEmit`)
- *   2. unit tests (`npx vitest run`)
+ *   2. unit tests — by default the **changed-only** suite
+ *      (`npx vitest run --changed`). Pass `--run-tests` to opt in to the
+ *      full suite (`npx vitest run`); pass `--skip-tests` to skip
+ *      entirely (e.g. docs-only or config-only slices).
  *   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.
+ *
+ * The unit-test stage emits a `unitTestsRunMode` field on the result
+ * envelope so downstream tooling and the QA test-report can record
+ * which mode actually ran: `"changed"` (default), `"full"` (with
+ * `--run-tests`), `"skipped"` (with `--skip-tests`), or `"overridden"`
+ * (with `--allow-pre-existing-failures` when the run failed and the
+ * stage was downgraded to `skipped` with a reason).
  */
 export type SliceCheckStageStatus = 'pass' | 'fail' | 'skipped';
 export type SliceCheckStage = {
@@ -36,6 +46,15 @@ export type SliceCheckResult = {
     rid: string | null;
     /** All stages in execution order. */
     stages: SliceCheckStage[];
+    /**
+     * Which unit-test mode actually ran. One of:
+     * - `"changed"` — default: `npx vitest run --changed` (tests for git-changed files only)
+     * - `"full"` — opt-in via `--run-tests`: `npx vitest run` (full suite)
+     * - `"skipped"` — opt-in via `--skip-tests` (stage not executed)
+     * - `"overridden"` — full mode + `--allow-pre-existing-failures` and the run failed;
+     *   stage downgraded to `skipped` with the pre-existing-failure reason
+     */
+    unitTestsRunMode: 'changed' | 'full' | 'skipped' | 'overridden';
     /** True iff every stage passed (or was skipped) and the boundary is OK to hand off. */
     boundaryReady: boolean;
     /** Total wall-clock duration in ms. */
@@ -54,17 +73,32 @@ export type SliceCheckOptions = {
      */
     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).
+     * When true, run the **full** `npx vitest run` suite at the boundary.
+     * When false (the default), run the **changed-only** suite
+     * (`npx vitest run --changed`) which only exercises tests related to
+     * git-changed files. The changed-only mode is the new default as of
+     * run 017 — full suite costs 30s+ on this repo; the changed-only
+     * mode costs ~1-3s in steady state and is what catches the
+     * regressions that actually matter. The service treats `undefined`
+     * the same as `false`.
+     */
+    runTests?: boolean;
+    /**
+     * When true, skip the unit-test stage entirely. Useful when a slice
+     * has no test surface (e.g. a docs-only or config-only slice), or
+     * when the user wants a "typecheck + review + gate" boundary check
+     * without any test execution.
      */
     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`.
+     * test failures documented in dogfood-2-f1-f4.md F17. Only meaningful
+     * when the unit-test stage actually runs (i.e. not when `skipTests`
+     * is true). 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

@@ -7,12 +7,22 @@
  * off to peaks-qa:
  *
  *   1. typecheck (`npx tsc --noEmit`)
- *   2. unit tests (`npx vitest run`)
+ *   2. unit tests — by default the **changed-only** suite
+ *      (`npx vitest run --changed`). Pass `--run-tests` to opt in to the
+ *      full suite (`npx vitest run`); pass `--skip-tests` to skip
+ *      entirely (e.g. docs-only or config-only slices).
  *   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.
+ *
+ * The unit-test stage emits a `unitTestsRunMode` field on the result
+ * envelope so downstream tooling and the QA test-report can record
+ * which mode actually ran: `"changed"` (default), `"full"` (with
+ * `--run-tests`), `"skipped"` (with `--skip-tests`), or `"overridden"`
+ * (with `--allow-pre-existing-failures` when the run failed and the
+ * stage was downgraded to `skipped` with a reason).
  */
 export {};

package/dist/src/shared/version.d.ts

@@ -1 +1 @@
-export declare const CLI_VERSION = "1.3.6";
+export declare const CLI_VERSION = "1.3.7";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "1.3.6";
+export const CLI_VERSION = "1.3.7";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "1.3.6",
+  "version": "1.3.7",
   "description": "Cross-AI-IDE workflow-gating CLI + skill family (Claude Code shipped, Trae in progress; Codex / Cursor / Qoder / Tongyi Lingma on the roadmap).",
   "author": "SquabbyZ",
   "license": "MIT",

package/skills/peaks-qa/SKILL.md

@@ -356,7 +356,10 @@ ls .peaks/<changeId>/qa/test-cases/<rid>.md
 ```bash
 # Run the project's test command. Do NOT skip this. Writing test cases is not enough.
 # Example (adapt to project):
-npx vitest run --reporter=verbose 2>&1 | tail -30
+# QA validation defaults to the CHANGED-ONLY suite (matches `peaks slice check` default as of run 017).
+# Use the full suite only when the slice is structurally significant or when the user explicitly asks
+# for it (e.g. via /peaks-solo-test or `peaks slice check --run-tests`).
+npx vitest run --changed --reporter=verbose 2>&1 | tail -30
 # Expected: exit code 0, actual test output with pass/fail counts
 # "0 tests executed" or "no test files found" → BLOCKED. Tests were written but not run.
 # Record the raw test output and link it in the test report.
@@ -504,7 +507,7 @@ QA must generate test cases, not merely inspect existing ones. Every QA invocati
 
 **Acceptance linkage (MANDATORY)** — every test case MUST have an `**Acceptance:**` field that references one or more acceptance items from the PRD by their position-based IDs (A1 = first bullet, A2 = second, …). The `peaks scan acceptance-coverage --rid <rid> --project <repo>` command parses both the PRD and this file, builds the coverage map, and fails the QA `verdict-issued` gate if any acceptance item has zero linked test cases. Test cases that genuinely have no acceptance owner (e.g. defense-in-depth regressions) should still include `- **Acceptance:** —` and explain in the **Evidence** field; the coverage report flags these as `unlinkedTestCases` for review without auto-blocking.
 
-**Test-case execution**: Run the project's test command and record results against each generated test case. If the project uses Jest, run `npx jest --coverage` and link the coverage report. If the project uses Vitest, run `npx vitest run --coverage`. Record the coverage percentage for changed files in the test report.
+**Test-case execution**: Run the project's test command and record results against each generated test case. If the project uses Jest, run `npx jest --coverage` and link the coverage report. If the project uses Vitest, run `npx vitest run --changed --coverage` by default (matches the new `peaks slice check` default as of run 017); use the full suite `npx vitest run --coverage` only when the slice warrants a deeper regression check, or when invoked via /peaks-solo-test or `peaks slice check --run-tests`. Record the coverage percentage for changed files in the test report.
 
 ## Mandatory test-report output
 

package/skills/peaks-rd/SKILL.md

@@ -266,7 +266,7 @@ peaks codegraph affected --project <repo> <changed-files...> --json
 #     Without project rules, security review and code review triggers won't fire.
 
 # 7. AFTER implementation, BEFORE QA handoff — RUN THESE GATES:
-#    Peaks-Cli Gate B2: unit tests exist and pass → npx vitest run (or project equivalent)
+#    Peaks-Cli Gate B2: unit tests exist and pass for the changed surface → npx vitest run --changed (or project equivalent; the changed-only mode is the peaks slice check default as of run 017; use --run-tests for the full suite, or invoke /peaks-solo-test to run the full suite standalone)
 #    Peaks-Cli Gate B3: code review evidence → .peaks/<changeId>/rd/code-review.md
 #    Peaks-Cli Gate B4: security review evidence → .peaks/<changeId>/rd/security-review.md
 #    Peaks-Cli Gate B5 (NEW): RD artifact body has no unfilled placeholders.
@@ -341,13 +341,18 @@ ls .peaks/<changeId>/rd/requests/<rid>.md \
 # Both must exist. Missing either → BLOCKED, do not hand off to QA
 ```
 
-**Peaks-Cli Gate B2 — Before QA handoff: unit tests exist and pass:**
+**Peaks-Cli Gate B2 — Before QA handoff: unit tests exist and pass for the changed surface:**
 ```bash
 # Run the project's test command against changed files. Record the output.
 # Example (adapt to project test runner):
-npx vitest run --reporter=verbose 2>&1 | tail -20
-# Expected: exit code 0, all tests passing, coverage for new/changed code recorded
+npx vitest run --changed --reporter=verbose 2>&1 | tail -20
+# Expected: exit code 0, all changed-surface tests passing, coverage for new/changed code recorded
 # Any failing test or zero tests for new code → BLOCKED. Write tests, then re-run.
+#
+# To run the FULL suite (slower; not the default for `peaks slice check`),
+# drop `--changed` or use `npx vitest run --reporter=verbose`. The peaks-solo-test
+# skill is the user-facing wrapper for the full suite; the slice check's
+# `--run-tests` flag is the CLI opt-in.
 ```
 
 **Peaks-Cli Gate B3 — Before QA handoff: code review evidence exists:**

package/skills/peaks-solo/references/micro-cycle.md

@@ -89,12 +89,14 @@ peaks slice check [--rid <rid>] [--project <path>] [--json]
 
 这个命令编排：
 1. `npx tsc --noEmit`（typecheck）
-2. `npx vitest run`（全 suite）
+2. `npx vitest run --changed`（默认；changed-only suite，只跑 git 改动相关的 test，~1-3s）。要全量请加 `--run-tests`；要彻底跳过请加 `--skip-tests`。
 3. 3-way fan-out（code-review + security-review + perf-baseline）
 4. `peaks workflow verify-pipeline --rid <rid> --project <path>`
 
 4 个 check 全绿 + verify-pipeline pass → 才进 `peaks request transition --state qa-handoff`，让 peaks-qa 接管。
 
+> **新增 run 017（2026-06-09）**：边界默认走 changed-only suite，原来的全 suite 行为移到 `--run-tests` opt-in。`peaks-solo-test` skill 仍然是手动跑全量的入口。rationale: 全量 30s+ 严重拖慢 workflow；changed-only 命中 99% 真正回归。详见 PRD `.peaks/_runtime/2026-06-07-session-84feb7/prd/requests/002-017-2026-06-09-remove-auto-full-vitest-from-slice-check.md`。
+
 ## Micro-cycle → 边界 check → QA 的串联
 
 ```
@@ -139,7 +141,7 @@ verdict=return-to-rd → RD 修 (new slice 内部走 micro-cycle)
 ## 为什么这套比当前 peaks-solo 的设计合理
 
 - **快**：micro-cycle ~100ms（vs 30s 全 suite），改 10 个 bug 从 5 分钟降到 30 秒
-- **稳**：边界 check 不省，4 项检查（tsc + vitest + 3-way + verify-pipeline）一次全跑
+- **稳**：边界 check 不省，4 项检查（tsc + vitest run --changed + 3-way + verify-pipeline）一次全跑；changed-only 模式 1-3s 内出结果，全量用 `--run-tests` opt-in
 - **清晰**：LLM 看到一个 explicit "禁止" 列表 + 强制 sequence，比"建议"更不容易越界
 - **可观测**：micro-cycle 走单测 → 边界跑 verify-pipeline，每步都有 JSON envelope 验证