peaks-cli 1.2.9 → 1.3.1

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

@@ -1,16 +1,110 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+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 { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { applyHookInstall, readHookStatus } from '../../services/skills/hooks-settings-service.js';
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+/** Sticky decision marker for the first-time "install hooks" prompt. */
+const HOOKS_DECISION_REL_PATH = '.peaks/.peaks-init-hooks-decision.json';
+function readDecisionMarker(projectRoot) {
+    const path = join(projectRoot, HOOKS_DECISION_REL_PATH);
+    if (!existsSync(path))
+        return null;
+    try {
+        const data = JSON.parse(readFileSync(path, 'utf8'));
+        if (data.version !== 1)
+            return null;
+        if (data.decision !== 'installed' && data.decision !== 'skipped')
+            return null;
+        if (typeof data.decidedAt !== 'string')
+            return null;
+        if (data.scope !== 'project' && data.scope !== 'global')
+            return null;
+        return {
+            version: 1,
+            decision: data.decision,
+            decidedAt: data.decidedAt,
+            scope: data.scope
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function writeDecisionMarker(projectRoot, decision) {
+    const path = join(projectRoot, HOOKS_DECISION_REL_PATH);
+    const dir = join(projectRoot, '.peaks');
+    mkdirSync(dir, { recursive: true });
+    const marker = {
+        version: 1,
+        decision,
+        decidedAt: new Date().toISOString(),
+        scope: 'project'
+    };
+    writeFileSync(path, JSON.stringify(marker, null, 2) + '\n', 'utf8');
+}
+/**
+ * Read a yes/no answer from stdin. Returns `true` for empty / Y / y,
+ * `false` for N / n, or `null` when stdin is not a TTY (the caller falls
+ * back to the no-prompt path). Times out after 30s so a piped-but-blocked
+ * stdin never hangs the CLI.
+ */
+function promptYesNo(question) {
+    return new Promise((resolve) => {
+        if (process.stdin.isTTY !== true) {
+            resolve(null);
+            return;
+        }
+        const rl = createInterface({ input: process.stdin, output: process.stderr, terminal: true });
+        const timer = setTimeout(() => {
+            rl.close();
+            resolve(null);
+        }, 30_000);
+        rl.question(question, (answer) => {
+            clearTimeout(timer);
+            rl.close();
+            const trimmed = answer.trim().toLowerCase();
+            if (trimmed === '' || trimmed === 'y' || trimmed === 'yes') {
+                resolve(true);
+                return;
+            }
+            if (trimmed === 'n' || trimmed === 'no') {
+                resolve(false);
+                return;
+            }
+            // Treat anything else as "no" — the user can re-run with --install-hooks
+            // if they want a different answer. We never throw from this prompt.
+            resolve(false);
+        });
+    });
+}
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+const DEFAULT_RECONCILE_AGE_DAYS = 7;
 export function registerWorkspaceCommands(program, io) {
     const workspace = program.command('workspace').description('Manage the Peaks per-session artifact workspace (.peaks/<session-id>/)');
     addJsonOption(workspace
         .command('init')
-        .description('Create the .peaks/<session-id>/ directory structure (prd, ui, rd, qa, sc, txt, system) and bind the session as the project current one. Pass --session-id to use a specific id, or omit it to auto-generate one (and adopt an existing binding if present).')
+        .description('Create the .peaks/<session-id>/ directory structure (prd, ui, rd, qa, sc, txt, system) and bind the session as the project current one. Pass --session-id to use a specific id, or omit it to auto-generate one (and adopt an existing binding if present). On the first call for a project, also handles the one-time "install peaks hooks" decision (sticky-marker stored in .peaks/.peaks-init-hooks-decision.json).')
         .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)).action(async (options) => {
+        .option('--allow-session-rebind', 'overwrite an existing session binding when the requested session id differs from the project current one', false)
+        .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');
+        }
+        return value;
+    })
+        .option('--install-hooks <mode>', 'first-time hooks install behaviour: ask (default in TTY, prompt once + sticky-marker), auto (default in --json / non-TTY, install silently + sticky-marker), skip (sticky-marker skipped, do not install)', (value) => {
+        if (value !== 'ask' && value !== 'auto' && value !== 'skip') {
+            throw new Error(`--install-hooks must be one of: ask, auto, skip (got "${value}")`);
+        }
+        return value;
+    })).action(async (options) => {
         try {
             // Resolve the session id. Two paths:
             //   - explicit --session-id: use it as the requested binding target
@@ -18,7 +112,7 @@ export function registerWorkspaceCommands(program, io) {
             //     session, unless --allow-session-rebind is set)
             //   - omitted: defer to ensureSession(), which reuses an existing
             //     binding or auto-generates a fresh one. The init then writes
-            //     .session.json so the binding sticks.
+            //     .peaks/_runtime/session.json so the binding sticks.
             //
             // Before that: canonicalise the project root. If the user (or the
             // LLM via "$(pwd)") passed a sub-directory of a real git repo
@@ -40,7 +134,8 @@ export function registerWorkspaceCommands(program, io) {
             const report = await initWorkspace({
                 projectRoot,
                 sessionId,
-                allowSessionRebind: options.allowSessionRebind === true
+                allowSessionRebind: options.allowSessionRebind === true,
+                ...(options.changeId !== undefined ? { changeId: options.changeId } : {})
             });
             const nextActions = [];
             if (report.previousSessionId !== null && report.bound) {
@@ -52,7 +147,34 @@ export function registerWorkspaceCommands(program, io) {
             else {
                 nextActions.push('Run `peaks scan archetype --project <path> --json` next to populate rd/project-scan.md.');
             }
-            printResult(io, ok('workspace.init', report, [], nextActions), options.json);
+            // First-time hooks install decision. Sticky-marker at
+            // .peaks/.peaks-init-hooks-decision.json records the user's answer
+            // (or the auto-decision) so subsequent inits for new sessions in the
+            // same project do not re-prompt. The marker is the only state that
+            // survives across sessions — without it, every new session would
+            // re-trigger the question.
+            const hooksOutcome = await resolveFirstTimeHooksInstall({
+                projectRoot,
+                ...(options.installHooks !== undefined ? { explicitMode: options.installHooks } : {}),
+                jsonMode: options.json === true
+            });
+            if (hooksOutcome.decision === 'installed') {
+                nextActions.push(hooksOutcome.action === 'reinstalled'
+                    ? 'Re-installed the peaks-managed PreToolUse hooks (Bash→gate enforce, Task→progress start) — the marker said installed but the hooks were missing.'
+                    : 'Installed the peaks-managed PreToolUse hooks (Bash→gate enforce, Task→progress start). Restart Claude Code so the hooks take effect.');
+            }
+            else if (hooksOutcome.action === 'first-decision' && hooksOutcome.decision === 'skipped') {
+                nextActions.push('Skipped peaks-managed hook install for this project. Re-run with --install-hooks=auto (or peaks hooks install) to install later.');
+            }
+            printResult(io, ok('workspace.init', {
+                ...report,
+                hooksInstall: {
+                    decision: hooksOutcome.decision,
+                    action: hooksOutcome.action,
+                    scope: hooksOutcome.scope,
+                    ...(hooksOutcome.reason !== undefined ? { reason: hooksOutcome.reason } : {})
+                }
+            }, [], nextActions), options.json);
         }
         catch (error) {
             if (error instanceof InvalidSessionIdError) {
@@ -75,4 +197,224 @@ export function registerWorkspaceCommands(program, io) {
             process.exitCode = 1;
         }
     });
+    addJsonOption(workspace
+        .command('reconcile')
+        .description('Scan .peaks/2026-MM-DD-session-*/ directories and re-point .peaks/_runtime/session.json ' +
+        'to the canonical session (4-tier heuristic: active-skill binding -> latest session.json mtime -> ' +
+        'latest any-file mtime -> dir-name sort). Also migrates any legacy .peaks/.session.json / ' +
+        '.peaks/.active-skill.json / .peaks/sop-state/ into .peaks/_runtime/ (idempotent; no-op on a ' +
+        'tree that is already on the new layout). By default the command is a dry-run: it reports empty / abandoned ' +
+        `session dirs older than ${DEFAULT_RECONCILE_AGE_DAYS} days as deletion candidates but does not delete them. ` +
+        'Pass --apply to actually remove the listed candidate dirs (destructive). ' +
+        'Override the age threshold with --older-than <days>.')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--apply', 'actually delete the deletion candidates (destructive); without it, dry-run only', false)
+        .option('--older-than <days>', `age threshold in days for deletion candidates (default: ${DEFAULT_RECONCILE_AGE_DAYS})`, (value) => Number.parseFloat(value))).action((options) => {
+        try {
+            const projectRoot = resolveCanonicalProjectRoot(options.project);
+            const olderThanDays = options.olderThan ?? DEFAULT_RECONCILE_AGE_DAYS;
+            if (typeof olderThanDays !== 'number' || !Number.isFinite(olderThanDays) || olderThanDays <= 0) {
+                printResult(io, fail('workspace.reconcile', 'INVALID_AGE_THRESHOLD', `--older-than must be a positive number of days`, { provided: options.olderThan }, ['Use --older-than 7 (or omit it to accept the 7-day default)']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const olderThanMs = olderThanDays * MS_PER_DAY;
+            const apply = options.apply === true;
+            const result = reconcileWorkspace({
+                projectRoot,
+                apply,
+                olderThanMs
+            });
+            const warnings = [];
+            if (result.sessions.length === 0) {
+                warnings.push('No session directories found under .peaks/. Run peaks workspace init first.');
+            }
+            if (apply && result.deleted.length > 0) {
+                warnings.push(`Deleted ${result.deleted.length} session dir(s) older than ${olderThanDays} day(s).`);
+            }
+            const nextActions = [];
+            if (result.migratedFiles.length > 0) {
+                nextActions.push(`Migrated ${result.migratedFiles.length} legacy runtime file(s) into .peaks/_runtime/: ${result.migratedFiles.join(', ')}.`);
+            }
+            if (result.repointed) {
+                nextActions.push(`Re-pointed .peaks/_runtime/session.json from ${result.repointedFrom ?? '<unbound>'} to ${result.repointedTo}.`);
+            }
+            if (!apply && result.wouldDelete.length > 0) {
+                nextActions.push(`Re-run with --apply to delete ${result.wouldDelete.length} candidate dir(s).`);
+            }
+            printResult(io, ok('workspace.reconcile', result, warnings, nextActions), options.json);
+            if (result.errors.length > 0) {
+                process.exitCode = 1;
+            }
+        }
+        catch (error) {
+            printResult(io, fail('workspace.reconcile', 'WORKSPACE_RECONCILE_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path exists and is writable']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(workspace
+        .command('migrate')
+        .description('Migrate legacy `.peaks/<session-id>/<role>/<file>` content into the new layout: ' +
+        '`.peaks/retrospective/<change-id>/<role>/<file>`. Each file is routed by a 4-tier ' +
+        'change-id resolver (filename regex → content H1 → body frontmatter → per-session fallback ' +
+        'to the most recent rd/requests entry). Cross-cutting files (project-scan, perf-baseline) ' +
+        'and transient runtime files (session.json, system/) are skipped with reasons in the ' +
+        'response. By default the command is a dry-run: it reports the planned moves + conflicts ' +
+        'and the session dirs that WOULD be deleted. Pass --apply to actually `git mv` the files ' +
+        'and `rm -rf` the emptied session dirs. Idempotent: re-running on an already-migrated tree ' +
+        'is a no-op (all files report conflicts with identical content).')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--apply', 'actually `git mv` the files and delete the emptied session dirs (destructive); without it, dry-run only', false)).action(async (options) => {
+        try {
+            const projectRoot = resolveCanonicalProjectRoot(options.project);
+            const apply = options.apply === true;
+            const result = await migrateWorkspace({ projectRoot, apply });
+            const warnings = [];
+            if (result.sessions.length === 0) {
+                warnings.push('No legacy session directories found under .peaks/. Nothing to migrate.');
+            }
+            else if (result.wouldMove.length === 0) {
+                warnings.push('Legacy session dirs found but no reviewable content to migrate (all files were cross-cutting or transient).');
+            }
+            const nextActions = [];
+            if (!apply && result.wouldMove.length > 0) {
+                nextActions.push(`Re-run with --apply to perform ${result.wouldMove.length} move(s) and delete ${result.wouldDeleteSessions.length} session dir(s).`);
+            }
+            if (result.conflicts.length > 0) {
+                nextActions.push(`${result.conflicts.length} file(s) already exist at the target path; review before --apply (or re-run after a partial migrate).`);
+            }
+            if (apply) {
+                if (result.moved.length > 0) {
+                    nextActions.push(`Migrated ${result.moved.length} file(s) into .peaks/retrospective/.`);
+                }
+                if (result.deletedSessions.length > 0) {
+                    nextActions.push(`Deleted ${result.deletedSessions.length} emptied session dir(s).`);
+                }
+            }
+            printResult(io, ok('workspace.migrate', result, warnings, nextActions), options.json ?? false);
+        }
+        catch (error) {
+            printResult(io, fail('workspace.migrate', 'WORKSPACE_MIGRATE_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path exists and is writable']), options.json ?? false);
+            process.exitCode = 1;
+        }
+    });
+}
+/**
+ * Resolve the first-time "install peaks hooks" decision for this project.
+ * Decision tree:
+ *
+ *   1. Read the sticky marker.
+ *      - Marker present:
+ *        - marker.decision === 'installed' AND hooks are present → action: marker-honored, no side effects
+ *        - marker.decision === 'installed' AND hooks are MISSING   → re-install, action: reinstalled
+ *        - marker.decision === 'skipped'                            → action: marker-honored, no install
+ *      - Marker absent:
+ *        - hooks already present → write a fresh 'installed' marker, action: already-installed
+ *        - otherwise:
+ *          - explicit --install-hooks=auto  → install + marker, action: first-decision
+ *          - explicit --install-hooks=skip  → marker only, action: first-decision
+ *          - explicit --install-hooks=ask OR default in TTY:
+ *              - jsonMode → silently auto-install (LLM cannot answer), action: first-decision
+ *              - TTY      → prompt; on yes install + marker, on no marker-only
+ *          - default in non-TTY → auto-install, action: first-decision
+ *
+ * Project scope is the only supported scope here; global scope is reserved
+ * for explicit `peaks hooks install --global` invocations.
+ */
+export async function resolveFirstTimeHooksInstall(options) {
+    const { projectRoot, jsonMode } = options;
+    const existingMarker = readDecisionMarker(projectRoot);
+    // readHookStatus can throw (e.g. .claude is a symlink → safety check rejects).
+    // Treat any throw as "hooks status unknown → treat as not-installed" so the
+    // function still reaches the install path; the install will surface the same
+    // error in a more specific reason field.
+    let hookStatus;
+    try {
+        hookStatus = readHookStatus('project', projectRoot);
+    }
+    catch (error) {
+        hookStatus = { installed: false };
+        // Fall through to the install path; the failure will be captured below.
+        void error;
+    }
+    if (existingMarker !== null) {
+        if (existingMarker.decision === 'installed' && !hookStatus.installed) {
+            try {
+                applyHookInstall('project', projectRoot);
+                return { decision: 'installed', action: 'reinstalled', scope: 'project', reason: 'marker-said-installed-hooks-missing' };
+            }
+            catch (error) {
+                return { decision: existingMarker.decision, action: 'marker-honored', scope: 'project', reason: `reinstall-failed: ${getErrorMessage(error)}` };
+            }
+        }
+        return { decision: existingMarker.decision, action: 'marker-honored', scope: existingMarker.scope };
+    }
+    // No marker yet — first decision.
+    if (hookStatus.installed) {
+        writeDecisionMarker(projectRoot, 'installed');
+        return { decision: 'installed', action: 'already-installed', scope: 'project' };
+    }
+    // Determine effective mode (explicit flag wins; default depends on TTY + jsonMode).
+    const explicitMode = options.explicitMode;
+    const effectiveMode = explicitMode ??
+        (jsonMode ? 'auto' : (process.stdin.isTTY === true ? 'ask' : 'auto'));
+    if (effectiveMode === 'skip') {
+        writeDecisionMarker(projectRoot, 'skipped');
+        return { decision: 'skipped', action: 'first-decision', scope: 'project', reason: 'explicit-skip' };
+    }
+    if (effectiveMode === 'auto' || jsonMode) {
+        // The reason code distinguishes the path the user took to reach auto-install:
+        //   - explicit-auto:  user passed --install-hooks=auto
+        //   - json-mode:      no --install-hooks flag, but --json was set
+        //   - non-tty-default: no flag, no --json, stdin is not a TTY
+        let autoReason;
+        if (explicitMode === 'auto') {
+            autoReason = 'explicit-auto';
+        }
+        else if (jsonMode) {
+            autoReason = 'json-mode';
+        }
+        else {
+            autoReason = 'non-tty-default';
+        }
+        try {
+            applyHookInstall('project', projectRoot);
+            writeDecisionMarker(projectRoot, 'installed');
+            return { decision: 'installed', action: 'first-decision', scope: 'project', reason: autoReason };
+        }
+        catch (error) {
+            // Auto-install failed: still record the decision so we do not keep retrying
+            // every workspace init. The user can fix the underlying problem and run
+            // `peaks hooks install` manually.
+            writeDecisionMarker(projectRoot, 'installed');
+            return { decision: 'installed', action: 'first-decision', scope: 'project', reason: `install-failed: ${getErrorMessage(error)}` };
+        }
+    }
+    // effectiveMode === 'ask' AND TTY: prompt once.
+    process.stderr.write('\nPeaks-Cli: install the PreToolUse hooks for this project now?\n' +
+        '  → Bash matcher: `peaks gate enforce` (SOP gate enforcement)\n' +
+        '  → Task matcher: `peaks progress start` (auto-spawn sub-agent progress terminal)\n' +
+        'Both run on every Claude Code tool call without further prompting. The decision is sticky\n' +
+        '(recorded in .peaks/.peaks-init-hooks-decision.json) and re-runs of `workspace init` will\n' +
+        'honour it. Re-run with --install-hooks=skip or --install-hooks=auto to override.\n\n' +
+        'Install now? [Y/n]: ');
+    const answer = await promptYesNo('');
+    if (answer === null) {
+        // TTY disappeared mid-prompt (rare): treat as skip + write marker.
+        writeDecisionMarker(projectRoot, 'skipped');
+        return { decision: 'skipped', action: 'first-decision', scope: 'project', reason: 'tty-prompt-aborted' };
+    }
+    if (!answer) {
+        writeDecisionMarker(projectRoot, 'skipped');
+        return { decision: 'skipped', action: 'first-decision', scope: 'project', reason: 'user-answered-no' };
+    }
+    try {
+        applyHookInstall('project', projectRoot);
+        writeDecisionMarker(projectRoot, 'installed');
+        return { decision: 'installed', action: 'first-decision', scope: 'project', reason: 'user-answered-yes' };
+    }
+    catch (error) {
+        writeDecisionMarker(projectRoot, 'installed');
+        return { decision: 'installed', action: 'first-decision', scope: 'project', reason: `install-failed: ${getErrorMessage(error)}` };
+    }
 }

package/dist/src/cli/program.js

@@ -15,6 +15,7 @@ import { registerProjectCommands } from './commands/project-commands.js';
 import { registerRequestCommands } from './commands/request-commands.js';
 import { registerScanCommands } from './commands/scan-commands.js';
 import { registerShadcnCommands } from './commands/shadcn-commands.js';
+import { registerSliceCommands } from './commands/slice-commands.js';
 import { registerSopCommands } from './commands/sop-commands.js';
 import { registerGateCommands } from './commands/gate-commands.js';
 import { registerHooksCommands } from './commands/hooks-commands.js';
@@ -31,6 +32,8 @@ export function createProgram(io = { stdout: (text) => console.log(text), stderr
 Run peaks (no arguments) for a quickstart. You likely want one of:
   peaks doctor     check your environment
   peaks skill      list or manage skills
+  peaks slice      boundary check (tsc + vitest + 3-way + verify-pipeline)
+  peaks workflow   plan workflow routing dry-run graphs
   peaks sop        author your own workflow gates
   peaks hooks      install the un-bypassable gate-enforcement hook
   peaks gate       enforce/bypass SOP gates on Bash commands`)
@@ -87,6 +90,7 @@ Run peaks (no arguments) for a quickstart. You likely want one of:
     registerRequestCommands(program, io);
     registerScanCommands(program, io);
     registerShadcnCommands(program, io);
+    registerSliceCommands(program, io);
     registerSopCommands(program, io);
     registerGateCommands(program, io);
     registerHooksCommands(program, io);

package/dist/src/services/artifacts/artifact-prerequisites.d.ts

@@ -10,6 +10,15 @@ export type ArtifactPrerequisite = {
     description: string;
     /** Optional content markers — when set, the file must contain ALL of these (case-insensitive substring). */
     mustContain?: ReadonlyArray<string>;
+    /**
+     * Optional content markers — when set, the file must contain AT LEAST ONE of
+     * these (case-insensitive substring). Use this for escape-hatch patterns
+     * (e.g. perf-baseline's "Results table" OR "N/A — no perf surface" stub).
+     * `mustContain` and `mustContainAny` are independent: when both are set,
+     * `mustContain` markers must all be present AND at least one `mustContainAny`
+     * marker must be present.
+     */
+    mustContainAny?: ReadonlyArray<string>;
 };
 export type PrerequisiteCheckResult = {
     ok: boolean;
@@ -20,7 +29,14 @@ export type PrerequisiteCheckResult = {
 };
 export type CheckPrerequisitesOptions = {
     projectRoot: string;
-    sessionId: string;
+    /**
+     * Durable scope of the artifact (the `.peaks/<changeId>/` directory
+     * the file lives in). The gate scans under `.peaks/<changeId>/<role>/`
+     * for prerequisite artifacts. As of slice 2026-06-05-change-id-as-unit-of-work,
+     * this replaces the legacy `sessionId` field — the file body and the
+     * on-disk path now agree on the same top-level dir.
+     */
+    changeId: string;
     role: RequestArtifactRole;
     newState: RequestArtifactState;
     requestId: string;

package/dist/src/services/artifacts/artifact-prerequisites.js

@@ -30,6 +30,19 @@ const CODE_REVIEW = {
     mustContain: ['## Findings', 'CRITICAL']
 };
 const SECURITY_REVIEW = { relativePath: 'rd/security-review.md', description: 'Security review evidence for the changed surface' };
+// Gate B9 — RD-side perf baseline (peaks-rd SKILL "Parallel review fan-out").
+// The file must exist; the body must either carry a Results table marker
+// (per peaks-rd SKILL "Mandatory perf-baseline output") or the explicit
+// "N/A — no perf surface" escape hatch. A slice without a perf surface
+// still has to write the stub; an RD that omits perf-baseline entirely is
+// blocked here, matching peaks-rd's BLOCKING Gate B9 claim.
+const PERF_BASELINE = {
+    relativePath: 'rd/perf-baseline.md',
+    description: 'RD-side perf baseline (peaks-rd Gate B9) — must include a Results table with measurements OR the literal "N/A — no perf surface" escape hatch in the Notes section. QA Gate A4 diffs against this file.',
+    // Either a real Results table is present, OR the explicit no-perf-surface
+    // stub marker. Both paths satisfy Gate B9; absence of both is BLOCKED.
+    mustContainAny: ['## Results', 'N/A — no perf surface']
+};
 const TEST_CASES = {
     relativePath: 'qa/test-cases/<rid>.md',
     description: 'Generated test cases (unit / integration / UI regression)',
@@ -70,16 +83,19 @@ const QA_INITIATED = {
 const FEATURE_TABLE = {
     'prd:handed-off': [PRD_CONTENT],
     'rd:implemented': [TECH_DOC],
-    'rd:qa-handoff': [TECH_DOC, CODE_REVIEW, SECURITY_REVIEW, UNIT_TESTS, QA_INITIATED],
+    'rd:qa-handoff': [TECH_DOC, CODE_REVIEW, SECURITY_REVIEW, PERF_BASELINE, UNIT_TESTS, QA_INITIATED],
     'qa:running': [TEST_CASES],
     'qa:verdict-issued': [TEST_CASES, TEST_REPORT, SECURITY_FINDINGS, PERFORMANCE_FINDINGS]
 };
 // Bugfix: lighter planning artifact (bug-analysis instead of tech-doc), still requires code review + security review + regression test.
-// Performance findings not mandatory for non-perf bugs (use --allow-incomplete --reason if a perf bug requires it).
+// Performance baseline: required for perf-shaped bugfixes (where the bug IS a
+// perf regression). For non-perf bugfixes, RD writes the perf-baseline stub
+// with "N/A — no perf surface" — Gate B9 still passes (mustContainAny hit),
+// and the stub tells QA Gate A4 to skip the perf diff.
 const BUGFIX_TABLE = {
     'prd:handed-off': [PRD_CONTENT],
     'rd:implemented': [BUG_ANALYSIS],
-    'rd:qa-handoff': [BUG_ANALYSIS, CODE_REVIEW, SECURITY_REVIEW, UNIT_TESTS, QA_INITIATED],
+    'rd:qa-handoff': [BUG_ANALYSIS, CODE_REVIEW, SECURITY_REVIEW, PERF_BASELINE, UNIT_TESTS, QA_INITIATED],
     'qa:running': [TEST_CASES],
     'qa:verdict-issued': [TEST_CASES, TEST_REPORT, SECURITY_FINDINGS]
 };
@@ -146,11 +162,17 @@ export async function checkPrerequisites(options) {
     if (requirements.length === 0) {
         return { ok: true, missing: [] };
     }
-    const sessionRoot = join(options.projectRoot, '.peaks', options.sessionId);
+    // As of slice 2026-06-05-change-id-as-unit-of-work, the prerequisite
+    // gate resolves paths under `.peaks/<changeId>/<role>/...` where the
+    // changeId is the file's durable scope (the top-level dir the file
+    // lives in), NOT the body's `- session:` line. The body and the path
+    // can now disagree (e.g. a request written in one session but read
+    // across sessions), and the gate follows the on-disk location.
+    const changeRoot = join(options.projectRoot, '.peaks', options.changeId);
     const missing = [];
     for (const prerequisite of requirements) {
         const relative = resolvePrerequisitePath(prerequisite, options.requestId);
-        const absolute = await resolvePrerequisiteAbsolutePath(sessionRoot, prerequisite, options.requestId);
+        const absolute = await resolvePrerequisiteAbsolutePath(changeRoot, prerequisite, options.requestId);
         if (absolute === null) {
             missing.push({ path: relative, description: prerequisite.description });
             continue;
@@ -166,6 +188,17 @@ export async function checkPrerequisites(options) {
                 });
             }
         }
+        if (prerequisite.mustContainAny && prerequisite.mustContainAny.length > 0) {
+            const body = await readFile(absolute, 'utf8');
+            const lowered = body.toLowerCase();
+            const hitAny = prerequisite.mustContainAny.some((marker) => lowered.includes(marker.toLowerCase()));
+            if (!hitAny) {
+                missing.push({
+                    path: relative,
+                    description: `${prerequisite.description} — none of the escape-hatch markers present: ${prerequisite.mustContainAny.join(', ')}`
+                });
+            }
+        }
     }
     return { ok: missing.length === 0, missing };
 }

package/dist/src/services/artifacts/request-artifact-service.d.ts

@@ -6,6 +6,14 @@ export type CreateRequestArtifactOptions = {
     requestId: string;
     projectRoot: string;
     sessionId?: string;
+    /**
+     * Optional explicit change-id. When set, the artifact file lands at
+     * `.peaks/<changeId>/<role>/requests/...` regardless of any
+     * `current-change` binding. When unset, falls back to the binding, then
+     * to the requestId. The CLI's `--session-id <scope>` flag uses this to
+     * preserve the legacy "session-id as scope dir name" behavior.
+     */
+    changeId?: string;
     apply?: boolean;
     requestType?: RequestType;
     clock?: () => string;
@@ -21,6 +29,20 @@ export type CreateRequestArtifactResult = {
 export declare function createRequestArtifact(options: CreateRequestArtifactOptions): Promise<CreateRequestArtifactResult>;
 export type RequestArtifactSummary = {
     role: RequestArtifactRole;
+    /**
+     * Durable scope of the artifact: the top-level `.peaks/<changeId>/`
+     * directory the file lives in. As of slice 2026-06-05-change-id-as-unit-of-work,
+     * the prerequisite gate resolves paths under this dir (not the body
+     * `- session:` line), so the file body and the on-disk path agree.
+     */
+    changeId: string;
+    /**
+     * Session binding (which developer's local session wrote the file).
+     * Read from the file body's `- session:` line. Falls back to `changeId`
+     * when the body is missing the line. For back-compat with legacy
+     * session-id dirs, this may equal the dir name; for new change-id
+     * dirs, it is the metadata session that produced the file.
+     */
     sessionId: string;
     requestId: string;
     path: string;