peaks-cli 1.3.0 → 1.3.2

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

@@ -3,7 +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 { 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';
@@ -21,10 +22,11 @@ function dateSlugFromIso(iso) {
 function defaultSessionId(iso) {
     return `${dateSlugFromIso(iso)}-session`;
 }
-function renderPrdTemplate(requestId, sessionId, timestamp, requestType) {
+function renderPrdTemplate(requestId, changeId, sessionId, timestamp, requestType) {
     return `# PRD Request ${requestId}
 
 - session: ${sessionId}
+- change-id: ${changeId}
 - type: ${requestType}
 - source: <ticket, message URL, or "verbal" with a short sanitized quote>
 - raw input (sanitized): <one-paragraph restatement of what the user actually asked for>
@@ -57,9 +59,9 @@ function renderPrdTemplate(requestId, sessionId, timestamp, requestType) {
 
 ## Handoff
 
-- to peaks-rd: .peaks/${sessionId}/rd/requests/${requestId}.md
-- to peaks-qa: .peaks/${sessionId}/qa/requests/${requestId}.md
-- to peaks-ui: .peaks/${sessionId}/ui/requests/${requestId}.md  (when UI involved)
+- to peaks-rd: .peaks/${changeId}/rd/requests/${requestId}.md
+- to peaks-qa: .peaks/${changeId}/qa/requests/${requestId}.md
+- to peaks-ui: .peaks/${changeId}/ui/requests/${requestId}.md  (when UI involved)
 
 ## Status
 
@@ -68,11 +70,12 @@ function renderPrdTemplate(requestId, sessionId, timestamp, requestType) {
 - state: draft
 `;
 }
-function renderUiTemplate(requestId, sessionId, timestamp, requestType) {
+function renderUiTemplate(requestId, changeId, sessionId, timestamp, requestType) {
     return `# UI Request ${requestId}
 
 - session: ${sessionId}
-- linked-prd: .peaks/${sessionId}/prd/requests/${requestId}.md
+- change-id: ${changeId}
+- linked-prd: .peaks/${changeId}/prd/requests/${requestId}.md
 - type: ${requestType}
 - scope: full new surface | iteration on existing surface | regression fix | visual refresh
 - design direction: editorial | bento | Swiss | luxury | retro-futurist | glass | product-system | other-explicit-name
@@ -108,8 +111,8 @@ function renderUiTemplate(requestId, sessionId, timestamp, requestType) {
 
 ## Handoff
 
-- to peaks-rd: .peaks/${sessionId}/rd/requests/${requestId}.md
-- to peaks-qa: .peaks/${sessionId}/qa/requests/${requestId}.md
+- to peaks-rd: .peaks/${changeId}/rd/requests/${requestId}.md
+- to peaks-qa: .peaks/${changeId}/qa/requests/${requestId}.md
 
 ## Status
 
@@ -118,12 +121,13 @@ function renderUiTemplate(requestId, sessionId, timestamp, requestType) {
 - state: draft
 `;
 }
-function renderRdTemplate(requestId, sessionId, timestamp, requestType) {
+function renderRdTemplate(requestId, changeId, sessionId, timestamp, requestType) {
     return `# RD Request ${requestId}
 
 - session: ${sessionId}
-- linked-prd: .peaks/${sessionId}/prd/requests/${requestId}.md
-- linked-ui:  .peaks/${sessionId}/ui/requests/${requestId}.md  (when UI involved)
+- change-id: ${changeId}
+- linked-prd: .peaks/${changeId}/prd/requests/${requestId}.md
+- linked-ui:  .peaks/${changeId}/ui/requests/${requestId}.md  (when UI involved)
 - type: ${requestType}
 
 ## Red-line scope
@@ -165,8 +169,8 @@ function renderRdTemplate(requestId, sessionId, timestamp, requestType) {
 
 ## Handoff
 
-- to peaks-qa: .peaks/${sessionId}/qa/requests/${requestId}.md
-- to peaks-sc: .peaks/${sessionId}/sc/commit-boundaries/${requestId}.md
+- to peaks-qa: .peaks/${changeId}/qa/requests/${requestId}.md
+- to peaks-sc: .peaks/${changeId}/sc/commit-boundaries/${requestId}.md
 
 ## Status
 
@@ -175,13 +179,14 @@ function renderRdTemplate(requestId, sessionId, timestamp, requestType) {
 - state: draft
 `;
 }
-function renderQaTemplate(requestId, sessionId, timestamp, requestType) {
+function renderQaTemplate(requestId, changeId, sessionId, timestamp, requestType) {
     return `# QA Request ${requestId}
 
 - session: ${sessionId}
-- linked-prd: .peaks/${sessionId}/prd/requests/${requestId}.md
-- linked-rd:  .peaks/${sessionId}/rd/requests/${requestId}.md
-- linked-ui:  .peaks/${sessionId}/ui/requests/${requestId}.md  (when UI involved)
+- change-id: ${changeId}
+- linked-prd: .peaks/${changeId}/prd/requests/${requestId}.md
+- linked-rd:  .peaks/${changeId}/rd/requests/${requestId}.md
+- linked-ui:  .peaks/${changeId}/ui/requests/${requestId}.md  (when UI involved)
 - type: ${requestType}
 
 ## Red-line boundary check
@@ -230,14 +235,15 @@ function renderQaTemplate(requestId, sessionId, timestamp, requestType) {
 - state: draft
 `;
 }
-function renderScTemplate(requestId, sessionId, timestamp, requestType) {
+function renderScTemplate(requestId, changeId, sessionId, timestamp, requestType) {
     return `# SC Request ${requestId}
 
 - session: ${sessionId}
-- linked-prd: .peaks/${sessionId}/prd/requests/${requestId}.md
-- linked-rd:  .peaks/${sessionId}/rd/requests/${requestId}.md
-- linked-qa:  .peaks/${sessionId}/qa/requests/${requestId}.md
-- linked-ui:  .peaks/${sessionId}/ui/requests/${requestId}.md  (when UI involved)
+- change-id: ${changeId}
+- linked-prd: .peaks/${changeId}/prd/requests/${requestId}.md
+- linked-rd:  .peaks/${changeId}/rd/requests/${requestId}.md
+- linked-qa:  .peaks/${changeId}/qa/requests/${requestId}.md
+- linked-ui:  .peaks/${changeId}/ui/requests/${requestId}.md  (when UI involved)
 - type: ${requestType}
 
 ## Change impact
@@ -262,7 +268,7 @@ function renderScTemplate(requestId, sessionId, timestamp, requestType) {
 
 ## Sync / authorization
 
-- artifact workspace path: .peaks/${sessionId}/
+- artifact workspace path: .peaks/${changeId}/
 - memory sync authorized: yes | no
 - artifact sync authorized: yes | no
 - rationale if not authorized: keep local
@@ -273,7 +279,7 @@ function renderScTemplate(requestId, sessionId, timestamp, requestType) {
 
 ## Handoff
 
-- to peaks-txt: .peaks/${sessionId}/txt/skill-usage-lessons.md (when reusable lesson exists)
+- to peaks-txt: .peaks/${changeId}/txt/skill-usage-lessons.md (when reusable lesson exists)
 
 ## Status
 
@@ -282,18 +288,18 @@ function renderScTemplate(requestId, sessionId, timestamp, requestType) {
 - state: draft
 `;
 }
-function renderTemplate(role, requestId, sessionId, timestamp, requestType) {
+function renderTemplate(role, requestId, changeId, sessionId, timestamp, requestType) {
     switch (role) {
         case 'prd':
-            return renderPrdTemplate(requestId, sessionId, timestamp, requestType);
+            return renderPrdTemplate(requestId, changeId, sessionId, timestamp, requestType);
         case 'ui':
-            return renderUiTemplate(requestId, sessionId, timestamp, requestType);
+            return renderUiTemplate(requestId, changeId, sessionId, timestamp, requestType);
         case 'rd':
-            return renderRdTemplate(requestId, sessionId, timestamp, requestType);
+            return renderRdTemplate(requestId, changeId, sessionId, timestamp, requestType);
         case 'qa':
-            return renderQaTemplate(requestId, sessionId, timestamp, requestType);
+            return renderQaTemplate(requestId, changeId, sessionId, timestamp, requestType);
         case 'sc':
-            return renderScTemplate(requestId, sessionId, timestamp, requestType);
+            return renderScTemplate(requestId, changeId, sessionId, timestamp, requestType);
     }
 }
 export async function createRequestArtifact(options) {
@@ -306,10 +312,49 @@ export async function createRequestArtifact(options) {
     const requestType = options.requestType ?? DEFAULT_REQUEST_TYPE;
     const clock = options.clock ?? defaultClock;
     const timestamp = clock();
-    // Use provided session ID or get/create current session
+    // Use provided session ID or get/create current session. The session
+    // id is the binding for the artifact file's location.
+    //
+    // 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);
-    // Build numbered path in session directory
-    const requestsDir = join(options.projectRoot, '.peaks', sessionId, options.role, 'requests');
+    const boundChangeId = getCurrentChangeId(options.projectRoot);
+    // 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;
+    // 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);
@@ -327,15 +372,18 @@ export async function createRequestArtifact(options) {
     const number = getNextNumber(requestsDir);
     const filename = buildNumberedFilename(number, options.requestId);
     const path = join(requestsDir, filename);
-    const content = renderTemplate(options.role, options.requestId, sessionId, timestamp, requestType);
+    const content = renderTemplate(options.role, options.requestId, changeId, sessionId, timestamp, requestType);
     if (options.apply !== true) {
         return { role: options.role, requestId: options.requestId, sessionId, path, content, applied: false };
     }
     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
+    // Create QA initiated marker so rd:qa-handoff gate can verify QA was invoked.
+    // 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 = join(options.projectRoot, '.peaks', sessionId, 'qa');
+        const qaDir = join(options.projectRoot, '.peaks', '_runtime', sessionId, 'qa');
         const initiatedPath = join(qaDir, '.initiated');
         if (!existsSync(initiatedPath)) {
             await mkdir(qaDir, { recursive: true });
@@ -348,6 +396,7 @@ function extractMetadata(markdown) {
     let state = 'unknown';
     let createdAt;
     let requestType = DEFAULT_REQUEST_TYPE;
+    let sessionId;
     for (const rawLine of markdown.split(/\r?\n/)) {
         const line = rawLine.trim();
         const stateMatch = /^-\s*state:\s*(.+?)\s*$/.exec(line);
@@ -367,21 +416,41 @@ function extractMetadata(markdown) {
                 requestType = candidate;
             }
             // Placeholder values (e.g. "feature | bug | refactor | clarification") fall back to default.
+            continue;
+        }
+        const sessionMatch = /^-\s*session:\s*(.+?)\s*$/.exec(line);
+        if (sessionMatch !== null && sessionMatch[1] !== undefined) {
+            sessionId = sessionMatch[1];
+            continue;
         }
     }
     const base = { state, requestType };
     if (createdAt !== undefined)
         base.createdAt = createdAt;
+    if (sessionId !== undefined)
+        base.sessionId = sessionId;
     return base;
 }
-async function readSummary(projectRoot, sessionId, role, fileName) {
-    const path = join(projectRoot, '.peaks', sessionId, role, 'requests', fileName);
+async function readSummary(projectRoot, changeId, role, fileName) {
+    const path = join(projectRoot, '.peaks', changeId, role, 'requests', fileName);
     const body = await readFile(path, 'utf8');
-    const { state, createdAt, requestType } = extractMetadata(body);
+    const { state, createdAt, requestType, sessionId: bodySessionId } = extractMetadata(body);
     // Strip numbered prefix (e.g., "001-requestId.md" -> "requestId")
     // Only strip 3-digit zero-padded prefixes (our incrementing number format)
     const requestId = fileName.replace(/^0\d{2}-/, '').replace(/\.md$/, '');
-    const summary = { role, sessionId, requestId, path, state, requestType };
+    // `changeId` is the durable scope (the directory the file lives in).
+    // `sessionId` is metadata (the session that wrote the file, parsed from
+    // the `- session:` body line). They may differ when a request is read
+    // across sessions (back-compat) or after a session re-bind.
+    const summary = {
+        role,
+        changeId,
+        sessionId: bodySessionId ?? changeId,
+        requestId,
+        path,
+        state,
+        requestType
+    };
     if (createdAt !== undefined) {
         summary.createdAt = createdAt;
     }
@@ -402,15 +471,53 @@ export async function listRequestArtifacts(options) {
     if (!(await isDirectory(peaksRoot))) {
         return [];
     }
-    const sessions = options.sessionId !== undefined ? [options.sessionId] : await listDirectories(peaksRoot);
+    // 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).
+    //
+    // 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) {
+        scopes.push(join('_runtime', options.sessionId));
+        scopes.push(options.sessionId);
+    }
+    else {
+        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 roles = options.role !== undefined ? [options.role] : Array.from(VALID_ROLES);
     const summaries = [];
-    for (const sessionId of sessions) {
+    for (const scope of scopes) {
         for (const role of roles) {
-            const dir = join(peaksRoot, sessionId, role, 'requests');
+            const dir = join(peaksRoot, scope, role, 'requests');
             const fileNames = await listMarkdownFiles(dir);
             for (const fileName of fileNames) {
-                summaries.push(await readSummary(options.projectRoot, sessionId, role, fileName));
+                summaries.push(await readSummary(options.projectRoot, scope, role, fileName));
             }
         }
     }
@@ -438,32 +545,76 @@ export async function showRequestArtifact(options) {
         }
         return null;
     };
+    // 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).
+    //
+    // 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;
         }
-        const summary = await readSummary(options.projectRoot, options.sessionId, options.role, found.fileName);
-        const content = await readFile(found.path, 'utf8');
-        return { ...summary, content };
+        return await readRequestArtifact(options.projectRoot, scope, options.role, found);
     }
     const peaksRoot = join(options.projectRoot, '.peaks');
     if (!(await isDirectory(peaksRoot))) {
         return null;
     }
-    const sessions = await listDirectories(peaksRoot);
-    for (const sessionId of sessions) {
-        const dir = join(peaksRoot, sessionId, options.role, 'requests');
-        const found = await findFileInDir(dir);
+    // 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 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) {
-            const summary = await readSummary(options.projectRoot, sessionId, options.role, found.fileName);
-            const content = await readFile(found.path, 'utf8');
-            return { ...summary, content };
+            return await readRequestArtifact(options.projectRoot, dir, options.role, found);
         }
     }
     return null;
 }
+/** Read the summary + content for a found request file; treat a read
+ * error on the content as "not found" so the caller can fall through
+ * to the next candidate (the on-disk file may be partially written). */
+async function readRequestArtifact(projectRoot, scope, role, found) {
+    const summary = await readSummary(projectRoot, scope, role, found.fileName);
+    try {
+        const content = await readFile(found.path, 'utf8');
+        return { ...summary, content };
+    }
+    catch {
+        return null;
+    }
+}
 const ALLOWED_STATES_PER_ROLE = {
     prd: ['draft', 'confirmed-by-user', 'handed-off', 'blocked'],
     ui: ['draft', 'direction-locked', 'handed-off', 'blocked'],
@@ -601,6 +752,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,
@@ -653,6 +810,7 @@ export async function transitionRequestArtifact(options) {
     await writeFile(existing.path, updated, 'utf8');
     const result = {
         role: options.role,
+        changeId: existing.changeId,
         sessionId: existing.sessionId,
         requestId: options.requestId,
         path: existing.path,

package/dist/src/services/doctor/doctor-service.d.ts

@@ -18,6 +18,32 @@ export type CodegraphCapabilityProbe = {
     binaryPath: string;
     binaryExists: boolean;
 };
+export type DistVersionComparison = {
+    dist: string | null;
+    source: string;
+    match: boolean;
+    distReadable: boolean;
+};
+export type DistVersionProbe = () => DistVersionComparison;
+export type WorkspaceLayoutInspection = {
+    topLevelSessionDirs: string[];
+    legacyDotfiles: string[];
+    /**
+     * Slice 007 — per-change-id top-level dirs (e.g. `.peaks/001-2026-06-06-.../`).
+     * The pre-F3 canonical layout put reviewable artifacts under a
+     * per-change-id top-level dir; the post-F3 canonical layout
+     * consolidates them under `.peaks/_runtime/<sid>/<role>/`. Any
+     * leftover per-change-id top-level dir is a regression to flag.
+     * Slice 008's migration will consolidate these; until then, the
+     * check reports them as `ok: false`.
+     *
+     * Optional in the type for back-compat with test probes that
+     * pre-date the slice 007 broadening; the check itself falls back
+     * to an empty array when the field is missing.
+     */
+    perChangeIdDirs?: string[];
+};
+export type WorkspaceLayoutProbe = () => WorkspaceLayoutInspection;
 export type DoctorOptions = {
     schemasBaseDir?: string;
     skillsBaseDir?: string;
@@ -29,5 +55,48 @@ export type DoctorOptions = {
     workspaceInitializedProbe?: () => boolean;
     /** Platform string (defaults to process.platform); injectable for tests. */
     platform?: NodeJS.Platform;
+    /** Injected for the build:dist-version-matches-source check (defaults to compareDistVersion on disk). */
+    distVersionProbe?: DistVersionProbe;
+    /** Injected for the build:workspace-layout-canonical check (defaults to inspectWorkspaceLayout on disk). */
+    workspaceLayoutProbe?: WorkspaceLayoutProbe;
 };
+/**
+ * Pure helper extracted from `defaultWorkspaceInitializedProbe` so tests can
+ * drive the filesystem check without monkey-patching `process.cwd()` or
+ * `findProjectRoot`. Returns `true` when EITHER the canonical
+ * `.peaks/_runtime/session.json` OR the legacy `.peaks/.session.json` exists.
+ */
+export declare function isWorkspaceInitializedAt(projectRoot: string): boolean;
+/**
+ * Pure helper that compares the published dist `CLI_VERSION` against the
+ * source-of-truth `package.json#version`. Default readers fail-soft to `null`
+ * on missing/unreadable/malformed input. Exported so tests can drive the
+ * filesystem reads without monkey-patching `process.cwd()`.
+ */
+export declare function compareDistVersion(opts: {
+    projectRoot: string;
+    distVersionReader?: (root: string) => string | null;
+    sourceVersionReader?: (root: string) => string | null;
+}): DistVersionComparison;
+/**
+ * Pure helper that inspects the on-disk workspace layout for
+ * post-F3-canonical violations. The post-F3 canonical layout puts
+ * session dirs under `.peaks/_runtime/<sid>/` and the runtime
+ * binding at `.peaks/_runtime/session.json`; the legacy paths
+ * (top-level `<YYYY-MM-DD-session-<hex>>/` dirs and the legacy
+ * top-level `.peaks/.session.json` / `.peaks/.active-skill.json`
+ * dotfiles) must be absent. This helper is exported so tests can
+ * drive the filesystem walk without monkey-patching `process.cwd()`
+ * or `findProjectRoot`.
+ *
+ * Both scanners fail-soft (return `[]` on read errors) so a flaky
+ * filesystem read on a non-fatal probe path never escalates into a
+ * doctor failure.
+ */
+export declare function inspectWorkspaceLayout(opts: {
+    projectRoot: string;
+    topLevelScanner?: (root: string) => string[];
+    dotfileScanner?: (root: string) => string[];
+    perChangeIdScanner?: (root: string) => string[];
+}): WorkspaceLayoutInspection;
 export declare function runDoctor(options?: DoctorOptions): Promise<DoctorReport>;