peaks-loop 4.0.0-beta.9 → 4.0.1

package/dist/cli/commands/prd-blocks-commands.js

@@ -15,7 +15,7 @@
  */
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { checkPrdBlocks } from '../../services/prd/prd-blocks-checker.js';
-import { ok } from '../../shared/result.js';
+import { ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 export function registerPrdBlocksCommands(program, io) {
     // Find existing `prd` top-level command (registered by prd-commands.ts).

package/dist/cli/commands/prd-commands.js

@@ -15,7 +15,7 @@
  */
 import { readFile } from 'node:fs/promises';
 import { initHandoff, readHandoff, showHandoff, verifyHandoff, writeHandoff } from '../../services/prd/handoff-service.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 /** Split a comma-separated string into a trimmed, non-empty list.
  *  Empty / undefined input → empty array. */
@@ -37,7 +37,9 @@ async function resolveBody(bodyArg) {
     return bodyArg;
 }
 export function registerPrdCommands(program, io) {
-    const prd = program.command('prd').description('peaks-prd role: artifact + handoff primitives');
+    const prd = program
+        .command('prd', { hidden: true })
+        .description('peaks-prd role: artifact + handoff primitives');
     const handoff = prd.command('handoff').description('Write / verify / show the immutable PRD handoff (sha256-locked, schemaVersion: 2)');
     // peaks prd handoff init
     addJsonOption(handoff

package/dist/cli/commands/preferences-commands.js

@@ -12,6 +12,26 @@ const ALLOWED_KEYS = new Set([
     'swarmSpeculative',
     'loopAutonomousEnabled',
 ]);
+/**
+ * Stable, sorted list of allowed preference keys. Used in error messages
+ * so a PREFERENCES_KEY_UNKNOWN throw is self-documenting (the operator
+ * sees exactly which keys are valid without reading the source).
+ */
+const ALLOWED_KEYS_LIST = Array.from(ALLOWED_KEYS).sort();
+/**
+ * Build a PREFERENCES_KEY_UNKNOWN error with the allowed-keys list baked
+ * in. Throwing a plain Error here is the legacy path that the CLI
+ * surfaces verbatim on stderr; the helper exists so all three sites
+ * (`get` / `set` / `reset`) emit the same operator-facing message.
+ *
+ * Stage-3 follow-up (ice-cola surface check 2026-07-22, follow-on to
+ * report item 5.3): previously the message was just `PREFERENCES_KEY_UNKNOWN:
+ * <key>` which forced the operator to look up valid keys elsewhere. The
+ * new message lists the valid keys inline so the response is actionable.
+ */
+function unknownKeyError(key) {
+    return new Error(`PREFERENCES_KEY_UNKNOWN: ${key}. Allowed keys: ${ALLOWED_KEYS_LIST.join(', ')}.`);
+}
 export function registerPreferencesCommands(program) {
     const prefs = program
         .command('preferences')
@@ -25,7 +45,7 @@ export function registerPreferencesCommands(program) {
         .action((opts) => {
         try {
             if (!ALLOWED_KEYS.has(opts.key)) {
-                throw new Error(`PREFERENCES_KEY_UNKNOWN: ${opts.key}`);
+                throw unknownKeyError(opts.key);
             }
             const all = loadPreferences(opts.project);
             const value = all[opts.key];
@@ -71,7 +91,7 @@ export function registerPreferencesCommands(program) {
         .action((opts) => {
         try {
             if (!ALLOWED_KEYS.has(opts.key)) {
-                throw new Error(`PREFERENCES_KEY_UNKNOWN: ${opts.key}`);
+                throw unknownKeyError(opts.key);
             }
             let parsed = opts.value;
             try {
@@ -106,7 +126,7 @@ export function registerPreferencesCommands(program) {
         .action((opts) => {
         try {
             if (!ALLOWED_KEYS.has(opts.key)) {
-                throw new Error(`PREFERENCES_KEY_UNKNOWN: ${opts.key}`);
+                throw unknownKeyError(opts.key);
             }
             const filePath = preferencesPath(opts.project);
             // Read raw on-disk state (not the merged view) so removing a key

package/dist/cli/commands/project-commands.js

@@ -4,7 +4,7 @@ import { extractSessionMemories, readMemoryIndex, readProjectMemories, readProje
 import { readBusinessKnowledge } from '../../services/prd/project-scan-reader.js';
 import { applyStalePolicy, DEFAULT_STALE_DAYS } from '../../shared/stale-policy.js';
 import { formatMdCompact } from '../../shared/format-md-compact.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 export function registerProjectCommands(program, io) {
     const project = program.command('project').description('Aggregate Peaks state for a target project (read-only)');

package/dist/cli/commands/qa-business-review-commands.js

@@ -15,7 +15,7 @@
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
 import { acceptQaReview, buildEmptyQaReview, deriveQaDecision, QA_BUSINESS_ITEMS, readQaReview, rejectQaReview, scoreQaItem, writeQaReview } from '../../services/qa/qa-business-review-state.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 export function registerQaBusinessReviewCommands(program, io) {
     // G5 commands registered as TOP-LEVEL commands prefixed with `qa-business-`

package/dist/cli/commands/qa-commands.d.ts

@@ -28,7 +28,7 @@
 import { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
 import { type BrowserEvent } from '../../services/qa/browser-restart-detector.js';
-import type { MutReportJson } from '../../services/mut/types.js';
+import { type MutReportJson } from 'peaks-loop-mut';
 export type QaRunOptions = {
     project: string;
     browser?: boolean;

package/dist/cli/commands/qa-commands.js

@@ -26,8 +26,11 @@
  * backend-only or already-covered-by-unit-tests work.
  */
 import { join } from 'node:path';
+import { resolve } from 'node:path';
 import { addJsonOption, printResult } from '../cli-helpers.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { archiveScreenshots } from '../../services/qa/screenshot-archive-service.js';
+import { getSessionId } from '../../services/session/session-manager.js';
 import { BrowserRestartDetector } from '../../services/qa/browser-restart-detector.js';
 import { BrowserEventLogger } from '../../services/qa/browser-event-logger.js';
 import { BROWSER_REUSE_HINT } from '../../services/qa/browser-reuse-hint.js';
@@ -36,7 +39,7 @@ import { buildContext } from '../../services/context/context-builder.js';
 // Plan 1 / Task 10 — production fetcher (replaces mockFetcher).
 import { createHeadroomFetcher } from '../../services/context/headroom-fetcher.js';
 // Plan 2 / Task 8 — consume MUT.sig from peaks-mut into verdict envelope.
-import { loadMutReport, mutReportPath } from '../../services/mut/index.js';
+import { loadMutReport, mutReportPath } from 'peaks-loop-mut';
 function buildHeadroomFetcher(sid) {
     return createHeadroomFetcher({
         cacheDir: `.peaks/_runtime/${sid}/doc-cache`,
@@ -200,7 +203,7 @@ export function readQaRunOptions(options) {
 }
 export function registerQaCommands(program, io) {
     const qa = program
-        .command('qa')
+        .command('qa', { hidden: true })
         .description('peaks-qa slice: run QA gates (functional / security / browser E2E / mutation) for the active project');
     addJsonOption(qa
         .command('run')
@@ -268,4 +271,37 @@ export function registerQaCommands(program, io) {
             process.exitCode = 1;
         }
     });
+    // rid-012 (2026-07-27) — screenshot archive.
+    // Enforces peaks-qa SKILL.md "Hard contracts for browser validation"
+    // Contract 1: every Playwright `browser_take_screenshot` MUST land under
+    // `.peaks/_runtime/<sessionId>/qa/screenshots/`, not at the project root.
+    // When the LLM forgets to pass `filename`, Playwright MCP scatters
+    // `.png` files at the repo top level. This subcommand is the
+    // remediation: scan `--source` (default: project root) and move stray
+    // screenshots into `.peaks/_runtime/<session-id>/qa/screenshots/`.
+    addJsonOption(qa
+        .command('archive-screenshots')
+        .description('Move stray Playwright screenshots (.png/.jpg/.jpeg) from the ' +
+        'project root into .peaks/_runtime/<session-id>/qa/screenshots/. ' +
+        'Enforces peaks-qa SKILL.md Contract 1.')
+        .option('--source <dir>', 'directory to scan for stray screenshots (default: project root)', '.')
+        .option('--project <path>', 'project root (default: cwd)', '.')
+        .option('--session-id <sid>', 'target session id; defaults to the active session', '')).action((options) => {
+        try {
+            const projectRoot = resolve(options.project);
+            const sid = options.sessionId?.trim() || getSessionId(projectRoot) || 'ad-hoc';
+            const targetDir = join(projectRoot, '.peaks', '_runtime', sid, 'qa', 'screenshots');
+            const envelope = archiveScreenshots({ sourceDir: options.source, targetDir });
+            printResult(io, ok('qa.archive-screenshots', envelope, [], envelope.moved.length === 0
+                ? ['No stray screenshots found in ' + envelope.scannedSource]
+                : [
+                    `Moved ${envelope.moved.length} file(s) to ${envelope.targetDir}`,
+                    'Re-run peaks qa run to verify the gate passes'
+                ]), options.json);
+        }
+        catch (error) {
+            process.exitCode = 1;
+            printResult(io, fail('qa.archive-screenshots', 'ARCHIVE_FAILED', error instanceof Error ? error.message : 'Unknown error', { project: options.project, source: options.source }, ['Verify the source dir exists and is readable']), options.json);
+        }
+    });
 }

package/dist/cli/commands/release-commands.d.ts

@@ -19,6 +19,21 @@
  */
 import type { Command } from 'commander';
 import { isReleaseStage } from '../../services/release/release-state.js';
+import { type LayerResult } from '../../services/release/version-precheck-service.js';
 import { type ProgramIO } from '../cli-helpers.js';
+export declare function executeCanaryAction(opts: {
+    percent: string;
+    note?: string;
+    project?: string;
+    json?: boolean;
+}, io: ProgramIO, projectRoot: string): {
+    ok: boolean;
+    payload: Readonly<Record<string, unknown>>;
+    status: 'PRECHECK_BLOCKER' | 'INVALID_PERCENT' | 'INVALID_TRANSITION' | 'OK';
+    blockerLayer?: {
+        name: string;
+        result: LayerResult;
+    };
+};
 export declare function registerReleaseCommands(program: Command, io: ProgramIO): void;
 export { isReleaseStage };

package/dist/cli/commands/release-commands.js

@@ -19,12 +19,74 @@
  */
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { hotfixRelease, isReleaseStage, planRelease, readReleaseState, rollbackRelease, transitionRelease, watchWindow, writeReleaseState } from '../../services/release/release-state.js';
-import { fail, ok } from '../../shared/result.js';
+import { runAllLayers } from '../../services/release/version-precheck-service.js';
+import { runChangesetHardGate } from '../../services/changeset/changeset-check-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 const CANARY_PERCENTS = {
     10: 'canary-10',
     50: 'canary-50'
 };
+// rid-010 — extracted canary action handler so AC-8 can drive the canary
+// precheck-guard via direct function call (not via program.parseAsync with a
+// mocked service). Returns the result envelope for the caller to print.
+export function executeCanaryAction(opts, io, projectRoot) {
+    // rid-010 — precheck guard (Layer A or Layer B blocker refuses canary).
+    // rid-011 — changeset hard gate runs inline in the canary closure BEFORE
+    // this function is called (step 0 short-circuits with CHANGESET_BLOCKED).
+    // Layers C/D default warning → do not block canary; --strict upgrade would
+    // be a separate flag (out of scope for rid-011).
+    // Layers C/D default warning → do not block canary; --strict upgrade would
+    // be a separate flag (out of scope for rid-010).
+    const precheck = runAllLayers({ projectRoot, strict: false });
+    const blockerEntry = Object.entries(precheck.layers).find(([, l]) => l.status === 'blocker');
+    if (blockerEntry !== undefined) {
+        const [name, result] = blockerEntry;
+        return {
+            ok: false,
+            status: 'PRECHECK_BLOCKER',
+            blockerLayer: { name, result },
+            payload: {
+                projectRoot,
+                precheckSnapshotAt: precheck.snapshotAt,
+                layer: name,
+                message: result.message,
+                remediation: result.remediation
+            }
+        };
+    }
+    const percent = Number.parseInt(opts.percent, 10);
+    if (percent !== 10 && percent !== 50) {
+        return {
+            ok: false,
+            status: 'INVALID_PERCENT',
+            payload: { projectRoot, got: opts.percent }
+        };
+    }
+    const state = readReleaseState(projectRoot);
+    const targetStage = CANARY_PERCENTS[percent];
+    const result = transitionRelease(state, targetStage, opts.note);
+    if ('error' in result) {
+        return {
+            ok: false,
+            status: 'INVALID_TRANSITION',
+            payload: { projectRoot, error: result.error }
+        };
+    }
+    writeReleaseState(projectRoot, result.state);
+    return {
+        ok: true,
+        status: 'OK',
+        payload: {
+            projectRoot,
+            percent,
+            currentStage: targetStage,
+            nextAction: percent === 10
+                ? 'peaks release canary --percent 50'
+                : 'peaks release promote'
+        }
+    };
+}
 export function registerReleaseCommands(program, io) {
     const release = program
         .command('release')
@@ -53,37 +115,43 @@ export function registerReleaseCommands(program, io) {
             'Run `peaks release canary --percent 10` to begin the canary phase.'
         ]), opts.json ?? false);
     });
-    // 2. canary
+    // 2. canary — rid-010 wires precheck as the first step via executeCanaryAction
     addJsonOption(release
         .command('canary')
         .description('Advance the active release to a canary stage. Two percent values supported: ' +
         '10 (first canary, requires stage=planned) and 50 (second canary, requires ' +
-        'stage=canary-10). Use `peaks release promote` to complete.')
+        'stage=canary-10). Runs `peaks release precheck` first and refuses with ' +
+        'PRECHECK_BLOCKER if any blocker layer (rootVsShared or tagCollision) fails.')
         .requiredOption('--percent <10|50>', 'canary percent (10 or 50)')
         .option('--note <text>', 'optional note for the stage transition')
         .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
-        const percent = Number.parseInt(opts.percent, 10);
-        if (percent !== 10 && percent !== 50) {
-            printResult(io, fail('release.canary', 'INVALID_PERCENT', `--percent must be 10 or 50 (got "${opts.percent}")`, {}, []), opts.json ?? false);
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        // rid-011 — changeset hard gate (step 0).
+        const gate = runChangesetHardGate(projectRoot);
+        if (gate.state === 'staged-present') {
+            process.exitCode = 1;
+            printResult(io, fail('release.canary', 'CHANGESET_BLOCKED', `${gate.stagedFiles.length} staged .changeset/*.md file(s) — refusing canary`, { projectRoot, state: gate.state, stagedFiles: [...gate.stagedFiles], snapshotAt: gate.snapshotAt }, [`Drain pending changesets (coordinating LLM: drain via the standard changeset consumption path), then re-run \`peaks changeset check --project ${projectRoot}\` to confirm clean state.`]), opts.json ?? false);
             return;
         }
-        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
-        const state = readReleaseState(projectRoot);
-        const targetStage = CANARY_PERCENTS[percent];
-        const result = transitionRelease(state, targetStage, opts.note);
-        if ('error' in result) {
-            printResult(io, fail('release.canary', 'INVALID_TRANSITION', result.error, { projectRoot }, []), opts.json ?? false);
+        const result = executeCanaryAction(opts, io, projectRoot);
+        if (result.status === 'PRECHECK_BLOCKER') {
+            const layer = result.blockerLayer;
+            printResult(io, fail('release.canary', 'PRECHECK_BLOCKER', `precheck blocker on layer '${layer?.name ?? 'unknown'}': ${layer?.result.message ?? ''}`, result.payload, [
+                `Run 'peaks release precheck --project ${projectRoot}' for the full 4-layer envelope.`,
+                `Run 'peaks release precheck --strict' to also surface warning-layer issues.`,
+                `Remediation: ${layer?.result.remediation ?? ''}`
+            ]), opts.json ?? false);
             return;
         }
-        writeReleaseState(projectRoot, result.state);
-        printResult(io, ok('release.canary', {
-            projectRoot,
-            percent,
-            currentStage: targetStage,
-            nextAction: percent === 10
-                ? 'peaks release canary --percent 50'
-                : 'peaks release promote'
-        }, [], []), opts.json ?? false);
+        if (result.status === 'INVALID_PERCENT') {
+            printResult(io, fail('release.canary', 'INVALID_PERCENT', `--percent must be 10 or 50 (got "${opts.percent}")`, result.payload, []), opts.json ?? false);
+            return;
+        }
+        if (result.status === 'INVALID_TRANSITION') {
+            printResult(io, fail('release.canary', 'INVALID_TRANSITION', String(result.payload['error'] ?? ''), result.payload, []), opts.json ?? false);
+            return;
+        }
+        printResult(io, ok('release.canary', result.payload, [], []), opts.json ?? false);
     });
     // 3. promote
     addJsonOption(release
@@ -211,6 +279,13 @@ export function registerReleaseCommands(program, io) {
         .option('--note <text>', 'optional hotfix note')
         .option('--project <path>', 'project root (default: cwd)')).action((version, opts) => {
         const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        // rid-011 — changeset hard gate (step 0). No --skip-changeset-check override.
+        const changesetGate = runChangesetHardGate(projectRoot);
+        if (changesetGate.state === 'staged-present') {
+            process.exitCode = 1;
+            printResult(io, fail('release.hotfix', 'CHANGESET_BLOCKED', `${changesetGate.stagedFiles.length} staged .changeset/*.md file(s) — refusing to start hotfix`, { projectRoot, stagedFiles: [...changesetGate.stagedFiles], snapshotAt: changesetGate.snapshotAt }, [`Drain pending changesets (coordinating LLM: drain via the standard changeset consumption path), then re-run \`peaks changeset check --project ${projectRoot}\` to confirm clean state.`]), opts.json ?? false);
+            return;
+        }
         const state = readReleaseState(projectRoot);
         const result = hotfixRelease(state, version, opts.note);
         if ('error' in result) {
@@ -226,6 +301,23 @@ export function registerReleaseCommands(program, io) {
             'Hotfix started at canary-10. Run `peaks release canary --percent 50` to advance.'
         ]), opts.json ?? false);
     });
+    // 8. precheck — rid-010 (Phase 4 slice 1) — 4-layer version precheck.
+    addJsonOption(release
+        .command('precheck')
+        .description('Run the 4-layer version precheck (rootVsShared / tagCollision / ' +
+        'changesetStaged / workspaceLockstep). Layer A+B are blockers by default; ' +
+        'Layer C+D are warnings unless --strict is passed (CI parity mode). ' +
+        'Shared with publish.yml gate-cli-version step §(A).')
+        .option('--strict', 'treat warnings as blockers (CI parity mode)')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const envelope = runAllLayers({ projectRoot, strict: opts.strict === true });
+        process.exitCode = envelope.ok ? 0 : 1;
+        const warningLines = envelope.overall === 'warning'
+            ? ['Warning layers reported but did not block. Re-run with --strict to upgrade.']
+            : [];
+        printResult(io, ok('release.precheck', envelope, [], warningLines), opts.json ?? false);
+    });
 }
 // Re-export for tests / external consumers.
 export { isReleaseStage };

package/dist/cli/commands/request-commands.js

@@ -4,7 +4,7 @@ import { ConfirmationRequiredError } from '../../services/mode/mode-enforcement.
 import { recordBypass, isBypassLimitReached, MAX_BYPASSES_PER_SESSION } from '../../services/mode/bypass-tracker.js';
 import { lintRequestArtifact } from '../../services/artifacts/artifact-lint-service.js';
 import { getRepairCycleStatus } from '../../services/artifacts/repair-cycle-service.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { formatMdCompact } from '../../shared/format-md-compact.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 /**

package/dist/cli/commands/retrospective-commands.js

@@ -5,7 +5,7 @@ import { loadRetrospectiveIndex } from '../../services/retrospective/retrospecti
 import { showRetrospective } from '../../services/retrospective/retrospective-show.js';
 import { searchRetrospective } from '../../services/retrospective/retrospective-search-service.js';
 import { pickFromList } from '../../services/fuzzy-matching/fzf-pick-service.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 const VALID_RETRO_TYPES = ['refactor', 'feature', 'bugfix', 'config', 'docs', 'chore'];
 const VALID_RETRO_OUTCOMES = ['shipped', 'blocked', 'in-flight', 'cancelled'];

package/dist/cli/commands/reviewer-commands.js

@@ -2,7 +2,7 @@ import { runReviewer, REVIEWER_ID } from '../../services/reviewer/reviewer-servi
 import { loadReviewerConfig } from '../../services/reviewer/reviewer-config.js';
 import { deriveModelFamily } from '../../services/reviewer/model-family.js';
 import { addJsonOption, printResult } from '../cli-helpers.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 export function registerReviewerCommands(program, io) {
     const reviewer = program
         .command('reviewer')

package/dist/cli/commands/role-commands.js

@@ -10,7 +10,7 @@
  */
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { DEFAULT_SENIOR_FE_ROLE, grantPermission, readRoleRegistry, roleHasPermission, upsertRole, writeRoleRegistry } from '../../services/role/role-registry.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 export function registerRoleCommands(program, io) {
     const role = program

package/dist/cli/commands/runtime-commands-helpers.d.ts

@@ -0,0 +1,7 @@
+/** Internal helper exposed for tests + future programmatic callers:
+ *  resolve the registry file location, ensuring the parent dir
+ *  exists. Idempotent. */
+export declare function ensureRegistryDir(registryFile: string): void;
+/** Internal helper for tests: locate the registry file under the
+ *  given project root. Thin wrapper so tests can stub the resolution. */
+export declare function registryFileFor(projectRoot: string): string;

package/dist/cli/commands/runtime-commands-helpers.js

@@ -0,0 +1,24 @@
+/**
+ * Internal helpers for the adapter-registry path used by
+ * `peaks adapter register|list`. Extracted from runtime-commands.ts
+ * after Task 1.7 (design §13.1) retired the `peaks runtime compact`
+ * dispatch — the registry plumbing is still used by the
+ * adapter-registration CLI, so it lives here as a stand-alone module
+ * rather than re-attaching to the retired dispatch surface.
+ */
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { AdapterRegistry } from '../../services/adapter/adapter-registry.js';
+/** Internal helper exposed for tests + future programmatic callers:
+ *  resolve the registry file location, ensuring the parent dir
+ *  exists. Idempotent. */
+export function ensureRegistryDir(registryFile) {
+    mkdirSync(dirname(registryFile), { recursive: true });
+}
+/** Internal helper for tests: locate the registry file under the
+ *  given project root. Thin wrapper so tests can stub the resolution. */
+export function registryFileFor(projectRoot) {
+    const f = AdapterRegistry.defaultFile(projectRoot);
+    ensureRegistryDir(f);
+    return f;
+}

package/dist/cli/commands/runtime-commands.js

@@ -1,8 +1,7 @@
 import { existsSync, mkdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { addJsonOption, printResult } from '../cli-helpers.js';
-import { fail, ok } from '../../shared/result.js';
-import { getErrorMessage } from '../../shared/result.js';
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
 import { detectRuntime } from '../../services/runtime/runtime-detector.js';
 import { RuntimeService } from '../../services/runtime/runtime-service.js';
 import { AdapterRegistry } from '../../services/adapter/adapter-registry.js';

package/dist/cli/commands/sc-commands.js

@@ -1,8 +1,10 @@
 import { createArtifactRetentionReport, createChangeImpact, getChangeTraceabilityStatus, getScHelpText, recordCommitBoundary, validateArtifactRetention } from '../../services/sc/sc-service.js';
-import { ok } from '../../shared/result.js';
+import { ok } from 'peaks-loop-shared/result';
 import { addJsonOption, multipleOption, printResult } from '../cli-helpers.js';
 export function registerSCCommands(program, io) {
-    const sc = program.command('sc').description('Source control and change traceability (peaks-sc integration)');
+    const sc = program
+        .command('sc', { hidden: true })
+        .description('Source control and change traceability (peaks-sc integration)');
     registerSCStatusCommands(sc, io);
     registerSCArtifactCommands(sc, io);
 }

package/dist/cli/commands/scan-commands.js

@@ -10,7 +10,7 @@ import { scanApiSurface, formatApiSurfaceMarkdown } from '../../services/scan/ap
 import { scanOrphans, formatOrphanMarkdown } from '../../services/scan/orphan-service.js';
 import { scanKarpathy, formatKarpathyMarkdown } from '../../services/scan/karpathy-service.js';
 import { isRequestType, VALID_REQUEST_TYPES } from '../../services/artifacts/artifact-prerequisites.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 function parsePositiveInt(value, fallback) {
     if (value === undefined)

package/dist/cli/commands/security-audit-commands.js

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs';
-import { detectSecurityAudit, isSecurityAuditEnvelope, runSecurityAudit, } from '../../services/audit-independent/security-audit-service.js';
+import { detectSecurityAudit, isSecurityAuditEnvelope, runSecurityAudit, } from '../../services/audit-independent/index.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 function resolveEnvelope(envelopePath) {
     if (envelopePath === undefined || envelopePath === '-') {
         // Read from stdin
@@ -36,7 +36,7 @@ function readStdinSync() {
 }
 export function registerSecurityAuditCommands(program, io) {
     const securityAudit = program
-        .command('security-audit')
+        .command('security-audit', { hidden: true })
         .description('Independent security audit skill driver. Reads the immutable peaks-prd handoff (sha256-locked) + the project-level security-template.md, then writes a structured security-<rid>.md artifact. Decoupled from peaks-rd 5-way fan-out per slice v2.12.0 (Group A, Tier 2). See skills/bee/peaks-security-audit/SKILL.md for the full workflow.');
     addJsonOption(securityAudit
         .command('detect')

package/dist/cli/commands/sediment-commands.js

@@ -27,6 +27,7 @@
 import { writeFileSync, mkdirSync, readFileSync, existsSync, readdirSync, rmSync } from "node:fs";
 import { join, basename } from "node:path";
 import { SYSTEM_PATH_FORBIDDEN, assertNotSystemPath, resolveSegmentsDir, resolveStateDbPath, resolveBlobsDir, resolveUserBeesDir, resolveUserBeeDir, } from "../../services/sediment/pool-paths.js";
+import { peaksHome } from "../../services/sop/sop-paths.js";
 import { writeBeeManifest } from "../../services/sediment/pool-write.js";
 import { readPool } from "../../services/sediment/pool-read.js";
 import { rebuildIndexFromFs } from "../../services/sediment/pool-rebuild-index.js";
@@ -636,7 +637,15 @@ export function registerSedimentCommands(program, io) {
         .command("sediment <args...>")
         .description("Sediment pool operations (LLM-coordinated; see peaks-maker skill)")
         .action(async (args) => {
-        const home = process.env.HOME ?? process.env.USERPROFILE ?? process.cwd();
+        // D-018: peaks-loop's `state.db` (loop engineering + bee sediment pool)
+        // lives at PEAKS_HOME-based path, NOT under the project root. The
+        // original `process.env.HOME ?? USERPROFILE ?? process.cwd()` would
+        // resolve `home` to cwd when invoked from a project (e.g.
+        // `peaks skill sediment list` from peaks-loop/), producing
+        // `<project>/.peaks/state.db` — wrong. Per design contract
+        // (peaks-maker SKILL.md §22 + sop-paths.ts §29), the canonical
+        // home is `~/.peaks` (or PEAKS_HOME override for test isolation).
+        const home = peaksHome();
         const r = await runSediment(args, { home });
         // Delegate the JSON rendering AND the process.exitCode side-effect
         // to the shared CLI shim helper (Critical #1 fix). The library

package/dist/cli/commands/session-24h-mode.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `peaks session 24h-mode` — state-only CLI for the 24h mode backbone.
+ *
+ * Rid-020a (state-only slice). Exposes four sub-actions so the LLM
+ * orchestrator can introspect, transition, audit retry attempts, and
+ * reset the 24h state machine without touching the JSON file
+ * directly. The LLM is the decision-maker; the CLI is the muscle
+ * (same contract as `peaks session checkpoint`).
+ *
+ * Sub-actions (all accept --json for machine-readable envelopes):
+ *   - `peaks session 24h-mode state`        — read snapshot
+ *   - `peaks session 24h-mode transition`   — move to a new state
+ *   - `peaks session 24h-mode attempts`     — read attempts map
+ *   - `peaks session 24h-mode reset`        — wipe the snapshot
+ *
+ * peaks-code is the skill that should drive this CLI; we do not
+ * add a new top-level verb (peaks-loop is enhancement, not a new
+ * CLI surface — see `.peaks/memory/peaks-loop-is-enhancement-not-new-cli.md`).
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerSession24hModeCommand(session: Command, io: ProgramIO): void;
+export declare const SESSION_24H_MODE_CONSTANTS: {
+    readonly STATES: readonly ["IDLE", "BRAINSTORM", "USER_CONFIRM", "24H_ACTIVE", "WAITING_USER", "HANDOFF"];
+    readonly HANDOFF_EXIT_CONDITIONS: readonly ["user_abort", "all_triggers_resolved", "b3_unresolvable"];
+};