peaks-cli 1.3.1 → 1.3.2

package/dist/src/cli/commands/core-artifact-commands.js

@@ -8,7 +8,7 @@ import { runDoctor } from '../../services/doctor/doctor-service.js';
 import { listSkills } from '../../services/skills/skill-registry.js';
 import { inspectSkillRunbook } from '../../services/skills/skill-runbook-service.js';
 import { setSkillPresence, clearSkillPresence, getSkillPresence, isSkillPresenceMode, touchSkillHeartbeat } from '../../services/skills/skill-presence-service.js';
-import { ensureSession, getSessionMeta, rotateSessionBinding, setSessionMeta, setSessionTitle, listSessionMetas } from '../../services/session/session-manager.js';
+import { getSessionId, getSessionMeta, rotateSessionBinding, setSessionMeta, setSessionTitle, listSessionMetas } from '../../services/session/session-manager.js';
 import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { generateProjectContext } from '../../services/memory/project-context-service.js';
@@ -120,7 +120,7 @@ export function registerCoreAndArtifactCommands(program, io) {
         .description('Set the currently active Peaks skill for session-wide visibility')
         .option('--mode <mode>', 'execution mode')
         .option('--gate <gate>', 'current gate')
-        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')).action(async (name, options) => {
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')).action((name, options) => {
         const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
         if (options.mode !== undefined && !isSkillPresenceMode(options.mode)) {
             printResult(io, fail('skill.presence:set', 'INVALID_MODE', `Invalid mode: ${options.mode} (expected one of: full-auto, assisted, swarm, strict)`, { name, mode: options.mode }, ['Use a valid mode: full-auto, assisted, swarm, or strict']), options.json);
@@ -128,13 +128,26 @@ export function registerCoreAndArtifactCommands(program, io) {
             return;
         }
         const presence = setSkillPresence(name, options.mode, options.gate, options.project);
-        // Also update session metadata so session dirs self-document
-        const sessionId = await ensureSession(projectRoot);
-        setSessionMeta(projectRoot, sessionId, {
-            skill: name,
-            ...(options.mode ? { mode: options.mode } : {}),
-            ...(options.gate ? { gate: options.gate } : {})
-        });
+        // As of slice 003-2026-06-06-session-layout-canonicalize we do NOT
+        // call `ensureSession` here. The CLI wrapper previously spawned a
+        // new session on every presence call, which made the canonical
+        // session binding drift (the LLM saw the session id change every
+        // turn). The presence now reuses the session bound at
+        // `.peaks/_runtime/session.json` (or the legacy `.peaks/.session.json`
+        // during the back-compat window). If no session is bound, the
+        // presence still writes the active-skill marker — downstream code
+        // can `peaks workspace init` separately to create the session.
+        //
+        // Session metadata is updated when a session is bound (read-only
+        // path: `getSessionId`). We do not auto-spawn a session.
+        const boundSessionId = getSessionId(projectRoot);
+        if (boundSessionId !== null) {
+            setSessionMeta(projectRoot, boundSessionId, {
+                skill: name,
+                ...(options.mode ? { mode: options.mode } : {}),
+                ...(options.gate ? { gate: options.gate } : {})
+            });
+        }
         printResult(io, ok('skill.presence:set', { active: true, ...presence }), options.json);
     });
     addJsonOption(skill
@@ -191,9 +204,34 @@ export function registerCoreAndArtifactCommands(program, io) {
         printResult(io, ok('session.list', { sessions: metas, total: metas.length }), options.json);
     });
     addJsonOption(session
-        .command('info <sessionId>')
-        .description('Show full metadata for a session directory')).action((sessionId, options) => {
+        .command('info [sessionId]')
+        .description('Show full metadata for a session directory. Pass --active to resolve the canonical binding from .peaks/_runtime/session.json (the "one command a sub-agent runs to find the parent\'s sid" primitive).')
+        .option('--active', 'resolve the canonical session id from .peaks/_runtime/session.json (ignores [sessionId] when set)')).action(async (sessionId, options) => {
         const projectRoot = findProjectRoot(process.cwd()) ?? process.cwd();
+        // Slice 007 — sub-agent session sharing. A sub-agent that does
+        // not know the parent's sid reads it from the binding via
+        // `peaks session info --active`. The call uses the
+        // canonicalize-on-read path so a stored "projectRoot: '.'" and a
+        // caller-passed absolute realpath both resolve to the same
+        // binding. Without this primitive the sub-agent has no way to
+        // discover the parent sid short of scanning the filesystem.
+        if (options.active === true) {
+            // Import lazily to avoid a cycle with workspace-commands.
+            const { getSessionIdCanonical } = await import('../../services/session/session-manager.js');
+            const activeSid = getSessionIdCanonical(projectRoot);
+            if (activeSid === null) {
+                printResult(io, fail('session.info', 'NO_ACTIVE_BINDING', 'No canonical session binding at .peaks/_runtime/session.json', { projectRoot }, ['Run `peaks workspace init` or `peaks skill presence:set` to anchor a session']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('session.info', { active: true, sessionId: activeSid, source: '.peaks/_runtime/session.json' }), options.json);
+            return;
+        }
+        if (sessionId === undefined) {
+            printResult(io, fail('session.info', 'SESSION_ID_REQUIRED', 'session.info requires a <sessionId> or --active', {}, ['Pass a <sessionId> argument, or use --active to resolve the canonical binding']), options.json);
+            process.exitCode = 1;
+            return;
+        }
         const meta = getSessionMeta(projectRoot, sessionId);
         if (meta === null) {
             printResult(io, fail('session.info', 'SESSION_NOT_FOUND', `Session "${sessionId}" not found or has no metadata`, { sessionId }, ['Use `peaks session list` to see available sessions']), options.json);

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

@@ -16,14 +16,16 @@ export function registerSliceCommands(program, io) {
         .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)).action(async (options) => {
+        .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) => {
         try {
             const projectRoot = resolveCanonicalProjectRoot(options.project);
             const result = await sliceCheck({
                 projectRoot,
                 ...(options.rid ? { rid: options.rid } : {}),
                 refreshFanout: options.refreshFanout === true,
-                skipTests: options.skipTests === true
+                skipTests: options.skipTests === true,
+                allowPreExistingFailures: options.allowPreExistingFailures === true
             });
             const warnings = [];
             if (result.stages.some((s) => s.status === 'fail')) {

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

@@ -89,7 +89,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). 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).')
+        .description('Create the .peaks/_runtime/<session-id>/ directory with ONLY the session.json metadata file (slice 006: role subdirs prd/ui/rd/qa/sc/txt and the system/ subdir are created lazily by writers, not pre-created at init). When --change-id is given, also creates the .peaks/<change-id>/ dir. 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)
@@ -199,14 +199,24 @@ export function registerWorkspaceCommands(program, io) {
     });
     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>.')
+        .description('Scan .peaks/2026-MM-DD-session-*/ directories and consolidate the runtime state. ' +
+        'By default (no --apply) the command performs four actions:\n' +
+        '  1. Migrates legacy runtime files into .peaks/_runtime/: ' +
+        '.peaks/.session.json -> .peaks/_runtime/session.json, ' +
+        '.peaks/.active-skill.json -> .peaks/_runtime/active-skill.json, ' +
+        '.peaks/sop-state/ -> .peaks/_runtime/sop-state/ ' +
+        '(idempotent; no-op if already on the new layout).\n' +
+        '  2. Re-points .peaks/_runtime/session.json to the canonical session ' +
+        'using a 4-tier heuristic: active-skill binding -> latest session.json mtime -> ' +
+        'latest any-file mtime -> dir-name sort.\n' +
+        '  3. (slice 006) Syncs the single change/<sid>/ live marker under ' +
+        '.peaks/_runtime/change/. The marker is an empty directory; every other ' +
+        'entry under change/ is removed. Also cleans up the F3-introduced ' +
+        '.peaks/_runtime/<sid>/system/ subdir (no-op if already absent).\n' +
+        '  4. REPORTS (but does not delete) session dirs older than --older-than <days> ' +
+        `(default ${DEFAULT_RECONCILE_AGE_DAYS}) as deletion candidates; this is the only step that is dry-run by default.\n` +
+        'Pass --apply to additionally REMOVE the listed candidate dirs (destructive). ' +
+        'Migration (1), repoint (2), and marker sync (3) always run regardless of --apply.')
         .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) => {
@@ -242,6 +252,18 @@ export function registerWorkspaceCommands(program, io) {
             if (!apply && result.wouldDelete.length > 0) {
                 nextActions.push(`Re-run with --apply to delete ${result.wouldDelete.length} candidate dir(s).`);
             }
+            if (result.changeMarker.created !== null) {
+                nextActions.push(`Synced change/<${result.changeMarker.created}>/ live marker.`);
+            }
+            else if (result.canonicalSessionId !== null) {
+                nextActions.push(`change/<${result.canonicalSessionId}>/ live marker already in place.`);
+            }
+            if (result.changeMarker.removed.length > 0) {
+                nextActions.push(`Removed ${result.changeMarker.removed.length} stale change/<oldSid>/ marker(s).`);
+            }
+            if (result.systemCleaned.length > 0) {
+                nextActions.push(`Removed ${result.systemCleaned.length} F3 system/ subdir(s).`);
+            }
             printResult(io, ok('workspace.reconcile', result, warnings, nextActions), options.json);
             if (result.errors.length > 0) {
                 process.exitCode = 1;
@@ -262,18 +284,24 @@ export function registerWorkspaceCommands(program, io) {
         '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).')
+        'is a no-op (all files report conflicts with identical content).' +
+        '\n\nSlice 003 (--to-runtime): moves every top-level `.peaks/<sid>/` to `.peaks/_runtime/<sid>/` ' +
+        'for projects still on the pre-runtime-layer layout. Idempotent: re-running on a tree ' +
+        'that is already canonical is a no-op. F15 carve-out: top-level `rd/project-scan.md` is ' +
+        'never overwritten when the runtime copy already exists with different 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) => {
+        .option('--apply', 'actually `git mv` the files and delete the emptied session dirs (destructive); without it, dry-run only', false)
+        .option('--to-runtime', 'slice 003: also consolidate every top-level .peaks/<sid>/ dir into .peaks/_runtime/<sid>/. Idempotent; conflicts are logged but never overwrite.', false)).action(async (options) => {
         try {
             const projectRoot = resolveCanonicalProjectRoot(options.project);
             const apply = options.apply === true;
-            const result = await migrateWorkspace({ projectRoot, apply });
+            const toRuntime = options.toRuntime === true;
+            const result = await migrateWorkspace({ projectRoot, apply, toRuntime });
             const warnings = [];
-            if (result.sessions.length === 0) {
+            if (result.sessions.length === 0 && (result.toRuntimePlans?.length ?? 0) === 0) {
                 warnings.push('No legacy session directories found under .peaks/. Nothing to migrate.');
             }
-            else if (result.wouldMove.length === 0) {
+            else if (result.wouldMove.length === 0 && (result.toRuntimePlans?.length ?? 0) === 0) {
                 warnings.push('Legacy session dirs found but no reviewable content to migrate (all files were cross-cutting or transient).');
             }
             const nextActions = [];
@@ -283,6 +311,31 @@ export function registerWorkspaceCommands(program, io) {
             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 (toRuntime) {
+                const plans = result.toRuntimePlans ?? [];
+                if (apply) {
+                    if ((result.toRuntimeMoved?.length ?? 0) > 0) {
+                        nextActions.push(`Moved ${result.toRuntimeMoved?.length} top-level session dir(s) to .peaks/_runtime/ (slice 003 --to-runtime).`);
+                    }
+                    if ((result.toRuntimeConflicts?.length ?? 0) > 0) {
+                        nextActions.push(`${result.toRuntimeConflicts?.length} --to-runtime conflict(s) — see response. ${plans.filter((p) => p.action === 'f15-conflict-project-scan').length} are F15 carve-outs (deferred to a separate slice).`);
+                    }
+                }
+                else {
+                    const wouldMoveCount = plans.filter((p) => p.action === 'moved').length;
+                    const wouldSkipCount = plans.filter((p) => p.action === 'skipped-already-canonical').length;
+                    if (wouldMoveCount > 0) {
+                        nextActions.push(`Re-run with --apply to move ${wouldMoveCount} top-level session dir(s) to .peaks/_runtime/; ${wouldSkipCount} already canonical.`);
+                    }
+                    else if (wouldSkipCount > 0) {
+                        nextActions.push(`All ${wouldSkipCount} top-level session dir(s) are already canonical — no moves needed.`);
+                    }
+                    const f15Count = plans.filter((p) => p.action === 'f15-conflict-project-scan').length;
+                    if (f15Count > 0) {
+                        nextActions.push(`${f15Count} F15 carve-out conflict(s) (rd/project-scan.md differs from runtime copy) — see response.`);
+                    }
+                }
+            }
             if (apply) {
                 if (result.moved.length > 0) {
                     nextActions.push(`Migrated ${result.moved.length} file(s) into .peaks/retrospective/.`);

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

@@ -37,6 +37,18 @@ export type CheckPrerequisitesOptions = {
      * on-disk path now agree on the same top-level dir.
      */
     changeId: string;
+    /**
+     * Session binding (the developer's local session that wrote the
+     * request artifact). Read from the file body's `- session:` line.
+     * Optional, but when present the gate falls back to
+     * `.peaks/_runtime/<sid>/<role>/` and then `.peaks/<sid>/<role>/`
+     * for prerequisite artifacts that don't exist at the per-change-id
+     * path. This mirrors the F1/F2 back-compat pattern (read new path
+     * first, then legacy) and keeps the gate working for users whose
+     * QA / tech-doc / initiated artifacts still live under the session
+     * dir rather than under the change-id dir.
+     */
+    sessionId?: string;
     role: RequestArtifactRole;
     newState: RequestArtifactState;
     requestId: string;

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

@@ -162,17 +162,25 @@ export async function checkPrerequisites(options) {
     if (requirements.length === 0) {
         return { ok: true, missing: [] };
     }
-    // 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);
+    // Slice 006 simplifies the resolution to a 2-tier fallback. The
+    // per-change-id scope (`.peaks/<changeId>/<role>/`) is gone — new
+    // artifacts go to the session dir directly. The 2 tiers are:
+    //   1. `.peaks/_runtime/<sid>/<role>/...` (post-F3 canonical
+    //      session home; primary).
+    //   2. `.peaks/<sid>/<role>/...` (pre-F3 legacy session home;
+    //      back-compat).
+    // The changeId is preserved in the artifact body's frontmatter for
+    // human navigation; it is no longer a filesystem path key.
+    const canonicalSessionRoot = options.sessionId !== undefined
+        ? join(options.projectRoot, '.peaks', '_runtime', options.sessionId)
+        : null;
+    const legacySessionRoot = options.sessionId !== undefined
+        ? join(options.projectRoot, '.peaks', options.sessionId)
+        : null;
     const missing = [];
     for (const prerequisite of requirements) {
         const relative = resolvePrerequisitePath(prerequisite, options.requestId);
-        const absolute = await resolvePrerequisiteAbsolutePath(changeRoot, prerequisite, options.requestId);
+        const absolute = await resolvePrerequisiteAbsolutePathWithFallback(canonicalSessionRoot, legacySessionRoot, prerequisite, options.requestId);
         if (absolute === null) {
             missing.push({ path: relative, description: prerequisite.description });
             continue;
@@ -202,3 +210,26 @@ export async function checkPrerequisites(options) {
     }
     return { ok: missing.length === 0, missing };
 }
+/**
+ * Resolve a prerequisite to an on-disk path, with a 2-tier fallback
+ * (slice 006 — the per-change-id tier was dropped because per-change-id
+ * dirs are no longer created):
+ *   1. `<canonicalSessionRoot>/<relative>` (post-F3 canonical session
+ *      home, when `canonicalSessionRoot` is provided).
+ *   2. `<legacySessionRoot>/<relative>` (pre-F3 legacy session home,
+ *      when `legacySessionRoot` is provided).
+ * Tolerates the numbered filename prefix that `request init` writes
+ * (e.g. `001-<rid>.md`) at every tier. Returns the matched absolute
+ * path, or null when nothing matches.
+ */
+async function resolvePrerequisiteAbsolutePathWithFallback(canonicalSessionRoot, legacySessionRoot, prerequisite, requestId) {
+    const roots = [canonicalSessionRoot, legacySessionRoot];
+    for (const root of roots) {
+        if (root === null)
+            continue;
+        const found = await resolvePrerequisiteAbsolutePath(root, prerequisite, requestId);
+        if (found !== null)
+            return found;
+    }
+    return null;
+}

package/dist/src/services/artifacts/request-artifact-service.js

@@ -3,8 +3,8 @@ import { existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { isDirectory, listDirectories } from '../../shared/fs.js';
 import { checkPrerequisites, DEFAULT_REQUEST_TYPE, isRequestType, VALID_REQUEST_TYPES } from './artifact-prerequisites.js';
-import { ensureSession } from '../session/session-manager.js';
-import { getCurrentChangeId, getChangeArtifactRoot } from '../../shared/change-id.js';
+import { ensureSession, getSessionIdCanonical } from '../session/session-manager.js';
+import { getCurrentChangeId } from '../../shared/change-id.js';
 import { getNextNumber, buildNumberedFilename } from '../../shared/incrementing-number.js';
 import { lintRequestArtifact } from './artifact-lint-service.js';
 import { checkTypeSanity } from '../scan/type-sanity-service.js';
@@ -313,25 +313,48 @@ export async function createRequestArtifact(options) {
     const clock = options.clock ?? defaultClock;
     const timestamp = clock();
     // Use provided session ID or get/create current session. The session
-    // id is kept as the in-memory binding (so the artifact body can record
-    // which session wrote it), but the artifact file is now written
-    // under the change-id dir, NOT the session dir.
+    // id is the binding for the artifact file's location.
     //
-    // The change-id is the file's durable scope. As of slice
-    // 2026-06-05-change-id-as-unit-of-work, the requestId IS the
-    // change-id (per the legacy `001-<change-id>.md` filename convention);
-    // a request that lives in a session dir under a different change-id
-    // is no longer the model. We honor a `current-change` binding if
-    // one is set, and otherwise fall back to the requestId itself.
+    // Slice 006 collapses the per-change-id top-level dirs. The artifact
+    // file is now written under the SESSION dir
+    // (`.peaks/_runtime/<sid>/<role>/requests/`) instead of the
+    // change-id dir. The 2-tier fallback (canonical session → legacy
+    // session) replaces the F3 3-tier fallback (per-change-id →
+    // canonical session → legacy session). The change-id is preserved
+    // in the artifact body's frontmatter (under `- change-id:`) for
+    // human navigation; it is no longer a filesystem path key.
     const sessionId = options.sessionId ?? await ensureSession(options.projectRoot);
     const boundChangeId = getCurrentChangeId(options.projectRoot);
-    // Resolution order for the change-id (file path key):
-    //   1. Explicit `options.changeId` (CLI `--session-id` pre-1.3.0 set this).
+    // Resolution order for the change-id (file body metadata):
+    //   1. Explicit `options.changeId` (CLI `--change-id`).
     //   2. `current-change` binding (live developer working context).
     //   3. The requestId itself (every request is its own scope by default).
     const changeId = options.changeId ?? boundChangeId ?? options.requestId;
-    // Build numbered path under the change-id dir
-    const requestsDir = getChangeArtifactRoot(options.projectRoot, changeId) + '/' + options.role + '/requests';
+    // Slice 008 (F21 fix): fail fast when the resolved session id
+    // looks like a real session id (matches the date+session prefix)
+    // but does NOT correspond to an actual session dir under
+    // `.peaks/_runtime/`. Pre-F21 a sub-agent with a typo or stale
+    // binding (e.g. `2025-01-01-session-deadbe`) silently planned
+    // to write to a non-existent path. The check is intentionally
+    // scoped to "looks like a real session id" — a sid like
+    // `test-session` or `s` (no date prefix) is allowed through so
+    // the existing F3 / slice-007 back-compat flows (e.g. the
+    // `peaks request init --session-id <arbitrary-scope>` tests)
+    // can still create the dir on demand via the writer's
+    // `mkdir(..., { recursive: true })`.
+    const LOOKS_LIKE_SESSION_ID = /^\d{4}-\d{2}-\d{2}-session-/;
+    if (LOOKS_LIKE_SESSION_ID.test(sessionId)) {
+        const sessionDir = join(options.projectRoot, '.peaks', '_runtime', sessionId);
+        if (!(await isDirectory(sessionDir))) {
+            const canonicalSid = getSessionIdCanonical(options.projectRoot);
+            const hint = canonicalSid !== null
+                ? `Use --session-id ${canonicalSid} or run 'peaks workspace init' to create a new session.`
+                : `Run 'peaks workspace init' to create a new session.`;
+            throw new Error(`session id '${sessionId}' does not exist in _runtime/. Current canonical binding is '${canonicalSid ?? '<none>'}'. ${hint}`);
+        }
+    }
+    // Build numbered path under the session dir (canonical post-F3 home).
+    const requestsDir = join(options.projectRoot, '.peaks', '_runtime', sessionId, options.role, 'requests');
     // Check if a file with this requestId already exists (regardless of number prefix)
     if (await isDirectory(requestsDir)) {
         const existingFiles = await listMarkdownFiles(requestsDir);
@@ -356,11 +379,11 @@ export async function createRequestArtifact(options) {
     await mkdir(dirname(path), { recursive: true });
     await writeFile(path, content, 'utf8');
     // Create QA initiated marker so rd:qa-handoff gate can verify QA was invoked.
-    // As of slice 2026-06-05-change-id-as-unit-of-work, the marker lives under
-    // the change-id dir (not the session dir), so the gate's prereq scan
-    // (which reads from `.peaks/<change-id>/<role>/...`) finds it.
+    // Slice 006: the marker lives under the SESSION dir (canonical post-F3
+    // home), not the change-id dir. The gate's prereq scan finds it at
+    // `.peaks/_runtime/<sid>/qa/.initiated`.
     if (options.role === 'qa') {
-        const qaDir = getChangeArtifactRoot(options.projectRoot, changeId) + '/qa';
+        const qaDir = join(options.projectRoot, '.peaks', '_runtime', sessionId, 'qa');
         const initiatedPath = join(qaDir, '.initiated');
         if (!existsSync(initiatedPath)) {
             await mkdir(qaDir, { recursive: true });
@@ -448,45 +471,45 @@ export async function listRequestArtifacts(options) {
     if (!(await isDirectory(peaksRoot))) {
         return [];
     }
-    // As of slice 2026-06-05-change-id-as-unit-of-work, artifact files live
-    // in `.peaks/<change-id>/<role>/requests/`. The top-level `.peaks/<dir>/`
-    // entries we scan here are change-id dirs (new layout) AND legacy
-    // session-id dirs (pre-1.3.0 layout). Both have the same
-    // `<role>/requests/<file>.md` shape, so we read them uniformly.
+    // Slice 006 collapsed the per-change-id top-level dirs. The 2-tier
+    // resolution model is:
+    //   1. `.peaks/_runtime/<sid>/<role>/requests/` (post-F3 canonical
+    //      session home; slice 006's primary home for request artifacts).
+    //   2. `.peaks/<sid>/<role>/requests/` (pre-F3 legacy home; back-compat
+    //      for users who have not yet migrated).
     //
-    // Additionally, shipped slices are archived under
-    // `.peaks/retrospective/<change-id>/<role>/requests/` and dogfood
-    // evidence lives under `.peaks/_dogfood/<change-id>/<role>/requests/`.
-    // When `sessionId` is NOT pinned, we scan ALL three umbrella dirs
-    // (`<top>`, `retrospective/`, `_dogfood/`) so a `peaks request show
-    // <rid>` resolves shipped slices too — which is what the slice check's
-    // gate-verify-pipeline stage needs to find evidence for the retrospective
-    // slice being verified.
-    //
-    // Skip well-known non-artifact dirs: `_runtime/` holds ephemeral state
-    // (no `requests/` subdirs anyway, but skip explicitly to avoid noise).
-    const allDirs = await listDirectories(peaksRoot);
-    const candidateDirs = allDirs.filter((dir) => dir !== '_runtime');
-    // Expand scopes to include the nested umbrellas that host change-id dirs
-    // (retrospective/, _dogfood/). For each, list its sub-dirs and treat
-    // them as additional scopes. This makes the lookup span the entire
-    // .peaks tree.
-    const expandedScopes = [];
+    // When `sessionId` is pinned, the function scans that one session's
+    // two tiers (canonical + legacy). When `sessionId` is NOT pinned,
+    // the function scans every session dir under `.peaks/_runtime/`
+    // (canonical) AND every legacy session dir under `.peaks/`
+    // (top-level). Per-change-id dirs (the old `.peaks/<changeId>/<role>/`
+    // layout) are NOT scanned — slice 008 will migrate the 5
+    // already-shipped slices' artifacts to the new layout; new request
+    // artifacts are written to the session dir directly.
+    const scopes = [];
     if (options.sessionId !== undefined) {
-        expandedScopes.push(options.sessionId);
+        scopes.push(join('_runtime', options.sessionId));
+        scopes.push(options.sessionId);
     }
     else {
-        for (const dir of candidateDirs) {
-            expandedScopes.push(dir);
-            if (dir === 'retrospective' || dir === '_dogfood') {
-                const nested = await listDirectories(join(peaksRoot, dir));
-                for (const n of nested) {
-                    expandedScopes.push(join(dir, n));
-                }
+        const runtimeRoot = join(peaksRoot, '_runtime');
+        if (await isDirectory(runtimeRoot)) {
+            for (const sid of await listDirectories(runtimeRoot)) {
+                scopes.push(join('_runtime', sid));
             }
         }
+        // Legacy top-level session dirs: scan every non-`._peaks` top-level
+        // dir as a potential legacy scope. Slice 006 dropped per-change-id
+        // dirs, so any top-level dir name under `.peaks/` that is NOT
+        // `_runtime` (and not a well-known umbrella like retrospective,
+        // _dogfood, memory, etc. — those have no `<role>/requests/` tree)
+        // is treated as a candidate legacy session dir.
+        for (const dir of await listDirectories(peaksRoot)) {
+            if (dir === '_runtime')
+                continue;
+            scopes.push(dir);
+        }
     }
-    const scopes = expandedScopes;
     const roles = options.role !== undefined ? [options.role] : Array.from(VALID_ROLES);
     const summaries = [];
     for (const scope of scopes) {
@@ -525,45 +548,56 @@ export async function showRequestArtifact(options) {
     // As of slice 2026-06-05-change-id-as-unit-of-work, the dir key is the
     // change-id (not the session-id). When the caller pins `sessionId` we
     // use it as the scope anyway (legacy callers, and tests that pass
-    // `STABLE_SESSION` as a stand-in). The directory layout is identical
-    // for both old session dirs and new change-id dirs, so a single
-    // read path works for both.
+    // `STABLE_SESSION` as a stand-in).
+    //
+    // As of slice 2026-06-06-session-layout-canonicalize (F3), the
+    // canonical home for session dirs is `.peaks/_runtime/<sid>/`.
+    // The pre-F3 layout `.peaks/<sid>/` is preserved as a one-minor
+    // back-compat fallback (the new path wins when both exist). We
+    // resolve the dir to use UP FRONT (not lazily after a miss) so the
+    // prerequisite gate's "request artifact present" check observes
+    // the same path the rest of the canonical layout uses.
     if (options.sessionId !== undefined) {
-        const dir = join(options.projectRoot, '.peaks', options.sessionId, options.role, 'requests');
+        const canonicalDir = join(options.projectRoot, '.peaks', '_runtime', options.sessionId, options.role, 'requests');
+        const legacyDir = join(options.projectRoot, '.peaks', options.sessionId, options.role, 'requests');
+        // Try the canonical (post-F3) path first; fall back to the legacy
+        // path only if the canonical path is absent. The legacy path is
+        // expected to be empty after a `peaks workspace migrate --to-runtime`
+        // run; this fallback exists for users who have not yet migrated.
+        const dir = (await isDirectory(canonicalDir)) ? canonicalDir : legacyDir;
+        const scope = dir === canonicalDir
+            ? join('_runtime', options.sessionId)
+            : options.sessionId;
         const found = await findFileInDir(dir);
         if (found === null) {
             return null;
         }
-        return await readRequestArtifact(options.projectRoot, options.sessionId, options.role, found);
+        return await readRequestArtifact(options.projectRoot, scope, options.role, found);
     }
     const peaksRoot = join(options.projectRoot, '.peaks');
     if (!(await isDirectory(peaksRoot))) {
         return null;
     }
-    // Scan all top-level dirs in `.peaks/` AND nested change-id dirs
-    // under `retrospective/` and `_dogfood/`. The expanded scope list
-    // lets us find request artifacts that live one or two levels deep
-    // (shipped slices, dogfood evidence). Without this expansion,
-    // verify-pipeline can't find the RD/QA request files for any
-    // retrospective slice.
-    const allDirs = await listDirectories(peaksRoot);
-    const scopes = [];
-    for (const dir of allDirs) {
-        if (dir === '_runtime')
-            continue;
-        scopes.push(dir);
-        if (dir === 'retrospective' || dir === '_dogfood') {
-            const nested = await listDirectories(join(peaksRoot, dir));
-            for (const n of nested) {
-                scopes.push(join(dir, n));
+    // Slice 006: scan only session-scoped dirs (canonical + legacy)
+    // for the artifact. The per-change-id top-level dirs are no longer
+    // scanned — they are frozen until slice 008 migrates them.
+    const runtimeRoot = join(peaksRoot, '_runtime');
+    if (await isDirectory(runtimeRoot)) {
+        for (const sid of await listDirectories(runtimeRoot)) {
+            const dir = join(runtimeRoot, sid, options.role, 'requests');
+            const found = await findFileInDir(dir);
+            if (found !== null) {
+                return await readRequestArtifact(options.projectRoot, join('_runtime', sid), options.role, found);
             }
         }
     }
-    for (const scope of scopes) {
-        const dir = join(peaksRoot, scope, options.role, 'requests');
-        const found = await findFileInDir(dir);
+    for (const dir of await listDirectories(peaksRoot)) {
+        if (dir === '_runtime')
+            continue;
+        const target = join(peaksRoot, dir, options.role, 'requests');
+        const found = await findFileInDir(target);
         if (found !== null) {
-            return await readRequestArtifact(options.projectRoot, scope, options.role, found);
+            return await readRequestArtifact(options.projectRoot, dir, options.role, found);
         }
     }
     return null;
@@ -719,6 +753,12 @@ export async function transitionRequestArtifact(options) {
     const prerequisiteResult = await checkPrerequisites({
         projectRoot: options.projectRoot,
         changeId: existing.changeId,
+        // F3 repair cycle 1: pass the session binding so the gate can fall
+        // back to `.peaks/_runtime/<sid>/<role>/` (and the legacy
+        // `.peaks/<sid>/<role>/`) for prerequisite artifacts that still
+        // live under the session dir rather than the change-id dir. This
+        // mirrors the F1/F2 back-compat pattern.
+        sessionId: existing.sessionId,
         role: options.role,
         newState: options.newState,
         requestId: options.requestId,