peaks-cli 1.3.5 → 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/cli/program.js

@@ -7,7 +7,6 @@ import { registerCoreAndArtifactCommands } from './commands/core-artifact-comman
 import { registerWorkflowCommands } from './commands/workflow-commands.js';
 import { registerCapabilityWorkerConfigAndSCCommands } from './commands/capability-worker-config-sc-commands.js';
 import { registerCodegraphCommands } from './commands/codegraph-commands.js';
-import { registerMcpCommands } from './commands/mcp-commands.js';
 import { registerOpenSpecCommands } from './commands/openspec-commands.js';
 import { registerPerfCommands } from './commands/perf-commands.js';
 // Slice #014: peaks progress * CLI surface deleted (replaced by sub-agent
@@ -87,7 +86,6 @@ Run peaks (no arguments) for a quickstart. You likely want one of:
     registerWorkflowCommands(program, io);
     registerCapabilityWorkerConfigAndSCCommands(program, io);
     registerCodegraphCommands(program, io);
-    registerMcpCommands(program, io);
     registerOpenSpecCommands(program, io);
     registerPerfCommands(program, io);
     registerProjectCommands(program, io);

package/dist/src/services/dashboard/project-dashboard-service.d.ts

@@ -1,6 +1,5 @@
 import { type RequestArtifactRole, type RequestArtifactSummary } from '../artifacts/request-artifact-service.js';
 import type { OpenSpecChangeSummary } from '../openspec/openspec-types.js';
-import type { McpScanReport } from '../mcp/mcp-types.js';
 import type { CapabilityItem } from '../recommendations/recommendation-types.js';
 import { type SkillPresence } from '../skills/skill-presence-service.js';
 export type ProjectDashboardRequests = {
@@ -19,10 +18,6 @@ export type ProjectDashboardUnderstand = {
     graphPath: string;
     parseError?: string;
 };
-export type ProjectDashboardMcp = {
-    servers: McpScanReport['servers'];
-    scopes: McpScanReport['scopes'];
-};
 export type ProjectDashboardDoctor = {
     ok: boolean;
     passed: number;
@@ -57,7 +52,6 @@ export type ProjectDashboardRunbookHealth = {
 };
 export type ProjectDashboardCapabilities = {
     count: number;
-    mcpCount: number;
     sample: Array<Pick<CapabilityItem, 'capabilityId' | 'name' | 'itemType' | 'category'>>;
 };
 export type ProjectDashboardSkillPresence = {
@@ -76,7 +70,6 @@ export type ProjectDashboard = {
     requests: ProjectDashboardRequests;
     openspec: ProjectDashboardOpenSpec;
     understand: ProjectDashboardUnderstand;
-    mcp: ProjectDashboardMcp;
     doctor: ProjectDashboardDoctor;
     runbookHealth: ProjectDashboardRunbookHealth;
     capabilities: ProjectDashboardCapabilities;

package/dist/src/services/dashboard/project-dashboard-service.js

@@ -1,6 +1,5 @@
 import { listRequestArtifacts } from '../artifacts/request-artifact-service.js';
 import { scanOpenSpec } from '../openspec/openspec-scan-service.js';
-import { scanMcpServers } from '../mcp/mcp-scan-service.js';
 import { scanUnderstandAnything } from '../understand/understand-scan-service.js';
 import { seedCapabilityItems } from '../recommendations/capability-seed-items.js';
 import { requiredSkillNames } from '../../shared/paths.js';
@@ -78,7 +77,6 @@ function buildCapabilitiesSummary(sampleSize) {
     const items = seedCapabilityItems;
     return {
         count: items.length,
-        mcpCount: items.filter((item) => item.itemType === 'mcp').length,
         sample: items.slice(0, sampleSize).map((item) => ({
             capabilityId: item.capabilityId,
             name: item.name,
@@ -109,10 +107,9 @@ export async function loadProjectDashboard(options) {
     const clock = options.clock ?? defaultClock;
     const sampleSize = options.sampleCapabilities ?? 8;
     const okPolicy = options.okPolicy ?? 'workspace-only';
-    const [items, openspecReport, mcpReport, understandReport, doctorAndRunbook] = await Promise.all([
+    const [items, openspecReport, understandReport, doctorAndRunbook] = await Promise.all([
         listRequestArtifacts({ projectRoot: options.projectRoot }),
         scanOpenSpec({ openspecRoot: `${options.projectRoot}/openspec` }),
-        scanMcpServers({ projectRoot: options.projectRoot }),
         scanUnderstandAnything({ projectRoot: options.projectRoot }),
         loadDoctorAndRunbookHealth(options.doctorReport, options.runbookHealth)
     ]);
@@ -142,10 +139,6 @@ export async function loadProjectDashboard(options) {
             graphPath: understandReport.graph.path,
             ...(understandReport.graph.parseError !== undefined ? { parseError: understandReport.graph.parseError } : {})
         },
-        mcp: {
-            servers: mcpReport.servers,
-            scopes: mcpReport.scopes
-        },
         doctor: doctorAndRunbook.doctor,
         runbookHealth: doctorAndRunbook.runbookHealth,
         capabilities: buildCapabilitiesSummary(sampleSize),

package/dist/src/services/ide/adapters/claude-code-adapter.js

@@ -46,7 +46,6 @@ export const CLAUDE_CODE_ADAPTER = {
     capabilities: {
         gateEnforce: true,
         statusline: true,
-        mcpInstall: true,
     },
     // Slice #011: standards profile. Claude Code reads its constitution at
     // CLAUDE.md + module-level rules under .claude/rules/**. The values mirror

package/dist/src/services/ide/adapters/trae-adapter.js

@@ -71,19 +71,6 @@ export const TRAE_ADAPTER = {
     capabilities: {
         gateEnforce: true,
         statusline: true,
-        // Slice #007-007-2026-06-07-mcp-decouple: mcpInstall is LOAD-BEARING.
-        // The 4 MCP capabilities (playwright, chrome-devtools, figma, context7)
-        // are installed via `peaks mcp plan/apply` which writes to the global
-        // `~/.claude/settings.json` file. Trae 1.x's MCP integration is
-        // UNVERIFIED (the Trae fixture did not dogfood the MCP install path),
-        // so the 6 SKILL.md files must surface a Trae-specific path (manual
-        // install + manual tool invocation) rather than promising `peaks mcp
-        // apply` will work on Trae. Skill bodies consume this flag through
-        // the IDE adapter's `capabilities.mcpInstall`; setting it to true
-        // without a real Trae MCP install dogfood would be a regression.
-        // Cross-reference: .peaks/memory/trae-adapter-sets-mcpinstall-false-trae-mcp-integration-is-unverified.md
-        // and the 4 per-capability memos under .peaks/memory/mcp-decouple-*.md.
-        mcpInstall: false
     }
     // Standards: UNVERIFIED — see slice #012+ (Trae real-install dogfood for
     // the `standardsProfile` and `skillInstall` fields). The slice #011

package/dist/src/services/ide/ide-types.d.ts

@@ -18,8 +18,6 @@ export interface IdeCapabilities {
     readonly gateEnforce: true;
     /** peaks statusline 状态栏是否适用 */
     readonly statusline: boolean;
-    /** peaks mcp install 是否适用 */
-    readonly mcpInstall: boolean;
 }
 export interface IdeSettingsLocation {
     /** 项目根下的 settings 目录名,例如 '.claude' / '.trae' / '.cursor' */

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;
 };