peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

package/dist/services/migrate-skill-name/migrate.d.ts

@@ -0,0 +1,17 @@
+import type { MigrateResult } from './schema.js';
+export interface MigrateOpts {
+    projectRoot: string;
+    from: string;
+    to: string;
+    /** false = dry-run (default); true = write through. */
+    apply: boolean;
+}
+/** True iff `absPath` falls under any skip-path (substring match). */
+export declare function shouldSkip(projectRoot: string, absPath: string): boolean;
+/**
+ * Recursively walk a directory and return every `.json` / `.md`
+ * path. Missing root → empty list (the CLI reports scannedFiles:0,
+ * which is the truthful "nothing to look at" signal).
+ */
+export declare function walkRuntimeFiles(root: string): string[];
+export declare function migrateSkillName(opts: MigrateOpts): MigrateResult;

package/dist/services/migrate-skill-name/migrate.js

@@ -0,0 +1,152 @@
+/**
+ * `peaks session migrate-skill-name` core service (slice 2 of the
+ * peaks-code → peaks-code rename plan).
+ *
+ * Walks `.peaks/_runtime/**` and rewrites two patterns:
+ *   1. Key-value:   `"skill": "<old>"`  →  `"skill": "<new>"`
+ *   2. Slash-trig:  `/<old>`            →  `/<new>`
+ *
+ * Files under known skip-paths (`.peaks/memory/**`,
+ * `.peaks/skills/.system/bees/<old>/manifest.json`) are recorded in
+ * `skipped` but never opened. The operation is idempotent: re-running
+ * with the same `--from` on a tree already migrated reports 0
+ * modifications.
+ *
+ * Dry-run (`apply: false`) counts what WOULD change without writing;
+ * apply (`apply: true`) validates each `.json` payload with
+ * `JSON.parse` before writing so a broken mid-edit never lands on
+ * disk. Errors are pushed into `result.errors` (never swallowed).
+ */
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+/**
+ * Skip-paths are matched against the path relative to `projectRoot`,
+ * forward-slashed (Windows-friendly). Each entry is a SUBSTRING —
+ * the brief pins two specific exclusions: the memory dir, and the
+ * .system bee manifest for the old skill (which the renamer must
+ * leave alone until the bee itself is moved in a later slice).
+ */
+const SKIP_DIRS = ['.peaks/memory', '.peaks/skills/.system/bees'];
+const TARGET_ROOT = '.peaks/_runtime';
+const KEY_VALUE_PATTERN = (from, to) => new RegExp(`"skill"\\s*:\\s*"${escapeRe(from)}"`, 'g');
+const STRING_PATTERN = (from, to) => new RegExp(`/${escapeRe(from)}`, 'g');
+/**
+ * Escape regex metachars so an aggressive `--from` value (e.g.
+ * `peaks.code`) doesn't blow up the regex compiler. The two regexes
+ * above use `from` inside both body and character-class territory,
+ * so escaping is the safe path regardless of input.
+ */
+function escapeRe(input) {
+    return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** True iff `absPath` falls under any skip-path (substring match). */
+export function shouldSkip(projectRoot, absPath) {
+    const rel = relative(projectRoot, absPath).replace(/\\/g, '/');
+    return SKIP_DIRS.some((skip) => rel.includes(skip));
+}
+/**
+ * Recursively walk a directory and return every `.json` / `.md`
+ * path. Missing root → empty list (the CLI reports scannedFiles:0,
+ * which is the truthful "nothing to look at" signal).
+ */
+export function walkRuntimeFiles(root) {
+    const out = [];
+    if (!existsSync(root))
+        return out;
+    const visit = (dir) => {
+        for (const entry of readdirSync(dir)) {
+            const full = join(dir, entry);
+            const stat = statSync(full);
+            if (stat.isDirectory()) {
+                visit(full);
+            }
+            else if (entry.endsWith('.json') || entry.endsWith('.md')) {
+                out.push(full);
+            }
+        }
+    };
+    visit(root);
+    return out;
+}
+export function migrateSkillName(opts) {
+    const runtimeRoot = join(opts.projectRoot, TARGET_ROOT);
+    const files = walkRuntimeFiles(runtimeRoot);
+    const result = {
+        ok: true,
+        scannedFiles: files.length,
+        modifiedFiles: 0,
+        keyValueReplacements: 0,
+        stringReplacements: 0,
+        skipped: [...SKIP_DIRS],
+        errors: [],
+    };
+    for (const file of files) {
+        if (shouldSkip(opts.projectRoot, file))
+            continue;
+        let original;
+        try {
+            original = readFileSync(file, 'utf-8');
+        }
+        catch (e) {
+            // Unreadable file: surface the error and keep going (other
+            // files may be fine). `ok` flips to false; reporting stops
+            // hiding the failure from the operator.
+            result.errors.push(`${file}: read failed: ${e.message}`);
+            result.ok = false;
+            continue;
+        }
+        // Pin the broken-JSON test: any .json runtime file that fails
+        // to parse MUST be surfaced as an error, EVEN when it does not
+        // contain the from-name (the operator still needs to know the
+        // file is unparseable so they can fix it before re-running).
+        // Per Karpathy §4 honesty, silent skip is the worst kind of
+        // fake-green.
+        if (file.endsWith('.json')) {
+            try {
+                JSON.parse(original);
+            }
+            catch (e) {
+                result.errors.push(`${file}: invalid JSON: ${e.message}`);
+                result.ok = false;
+                continue;
+            }
+        }
+        let mutated = original;
+        const kvPattern = KEY_VALUE_PATTERN(opts.from, opts.to);
+        const kvMatches = mutated.match(kvPattern);
+        if (kvMatches) {
+            mutated = mutated.replace(kvPattern, `"skill": "${opts.to}"`);
+            result.keyValueReplacements += kvMatches.length;
+        }
+        const strPattern = STRING_PATTERN(opts.from, opts.to);
+        const strMatches = mutated.match(strPattern);
+        if (strMatches) {
+            mutated = mutated.replace(strPattern, `/${opts.to}`);
+            result.stringReplacements += strMatches.length;
+        }
+        if (mutated === original)
+            continue;
+        if (opts.apply) {
+            try {
+                if (file.endsWith('.json')) {
+                    // Validate the post-edit JSON before touching the disk —
+                    // catches accidents (e.g., stray quotes in the renamed
+                    // from/to values) without leaving a corrupted runtime file
+                    // behind.
+                    JSON.parse(mutated);
+                }
+                writeFileSync(file, mutated, 'utf-8');
+                result.modifiedFiles += 1;
+            }
+            catch (e) {
+                result.errors.push(`${file}: ${e.message}`);
+                result.ok = false;
+            }
+        }
+        // Dry-run path intentionally does not bump `modifiedFiles` —
+        // pin: `expect(result.modifiedFiles).toBe(0)` in the dry-run
+        // test. The would-be count lives implicitly in the *Replacement
+        // counters, which both dry-run and apply share.
+    }
+    return result;
+}

package/dist/services/migrate-skill-name/schema.d.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+/**
+ * Result shape for `peaks session migrate-skill-name`.
+ *
+ * Counters:
+ *   - `scannedFiles` — every .json / .md under `.peaks/_runtime/**` (excluding
+ *     skip dirs below).
+ *   - `modifiedFiles` — files whose contents would change (dry-run reports
+ *     the predicted count; --apply reports the actually-written count).
+ *   - `keyValueReplacements` — `"skill": "<old>"` → `"skill": "<new>"`.
+ *   - `stringReplacements` — `/<old>` → `/<new>` slash-trigger mentions.
+ *
+ * Errors are surfaced per-file with `errors: [ "<absPath>: <message>", … ]`;
+ * the tool never silently skips a broken JSON file (Karpathy §4 honesty:
+ * silence on bad data is the worst kind of fake-green).
+ */
+export declare const MigrateResultSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    scannedFiles: z.ZodNumber;
+    modifiedFiles: z.ZodNumber;
+    keyValueReplacements: z.ZodNumber;
+    stringReplacements: z.ZodNumber;
+    skipped: z.ZodArray<z.ZodString, "many">;
+    errors: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    ok: boolean;
+    skipped: string[];
+    scannedFiles: number;
+    modifiedFiles: number;
+    keyValueReplacements: number;
+    stringReplacements: number;
+    errors: string[];
+}, {
+    ok: boolean;
+    skipped: string[];
+    scannedFiles: number;
+    modifiedFiles: number;
+    keyValueReplacements: number;
+    stringReplacements: number;
+    errors: string[];
+}>;
+export type MigrateResult = z.infer<typeof MigrateResultSchema>;

package/dist/services/migrate-skill-name/schema.js

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+/**
+ * Result shape for `peaks session migrate-skill-name`.
+ *
+ * Counters:
+ *   - `scannedFiles` — every .json / .md under `.peaks/_runtime/**` (excluding
+ *     skip dirs below).
+ *   - `modifiedFiles` — files whose contents would change (dry-run reports
+ *     the predicted count; --apply reports the actually-written count).
+ *   - `keyValueReplacements` — `"skill": "<old>"` → `"skill": "<new>"`.
+ *   - `stringReplacements` — `/<old>` → `/<new>` slash-trigger mentions.
+ *
+ * Errors are surfaced per-file with `errors: [ "<absPath>: <message>", … ]`;
+ * the tool never silently skips a broken JSON file (Karpathy §4 honesty:
+ * silence on bad data is the worst kind of fake-green).
+ */
+export const MigrateResultSchema = z.object({
+    ok: z.boolean(),
+    scannedFiles: z.number().int().nonnegative(),
+    modifiedFiles: z.number().int().nonnegative(),
+    keyValueReplacements: z.number().int().nonnegative(),
+    stringReplacements: z.number().int().nonnegative(),
+    skipped: z.array(z.string()),
+    errors: z.array(z.string()),
+});

package/dist/services/migration/v2-10-to-v2-11-service.d.ts

@@ -0,0 +1,44 @@
+/**
+ * v2.11.0 — Group E (Tier 8) migration service.
+ *
+ * Scans pre-v2.11.0 sessions for `rd/tech-doc.md` files and tags each
+ * with a deprecation banner (Karpathy §3 surgical: text-only, no file
+ * moves). Idempotent: re-running produces no diff on a previously-
+ * migrated repo.
+ *
+ * === Why text-only (no move / no prune) ===
+ *
+ * v2.11.0 introduces the immutable peaks-prd handoff at
+ * `.peaks/_runtime/<sid>/prd/handoff.md` as the source of truth. The
+ * old `rd/tech-doc.md` is no longer required by any CLI gate, but the
+ * historical content still has audit value. Removing it silently would
+ * lose the diff; renaming would orphan any external reference (e.g.,
+ * commit messages, blog posts). The least-risky path is: tag in place
+ * with a banner; let the user decide when/whether to prune in a future
+ * slice.
+ *
+ * === Banner shape (locked) ===
+ *
+ * The banner is prepended (NOT wrapped) — keeps existing body intact,
+ * Git blame still works for the original content lines.
+ *
+ * === Source: peaks-rd/references/writing-handoff-frontmatter.md §"v2.11.0" ===
+ */
+import { type MigrationEntry, type MigrationPlan, type MigrationResult, type MigrationReason } from './v2-10-to-v2-11-types.js';
+export declare function enumerateTechDocs(projectRoot: string): ReadonlyArray<{
+    readonly sessionId: string;
+    readonly filePath: string;
+}>;
+export declare function planV2ToV11Migration(projectRoot: string): MigrationPlan;
+export declare function applyV2ToV11Migration(plan: MigrationPlan): MigrationResult;
+export interface DryRunResult {
+    readonly plan: MigrationPlan;
+    readonly applied: false;
+    readonly writtenCount: 0;
+    readonly errors: ReadonlyArray<{
+        readonly path: string;
+        readonly message: string;
+    }>;
+}
+export declare function dryRunV2ToV11Migration(projectRoot: string): DryRunResult;
+export type { MigrationEntry, MigrationPlan, MigrationReason, MigrationResult };

package/dist/services/migration/v2-10-to-v2-11-service.js

@@ -0,0 +1,190 @@
+/**
+ * v2.11.0 — Group E (Tier 8) migration service.
+ *
+ * Scans pre-v2.11.0 sessions for `rd/tech-doc.md` files and tags each
+ * with a deprecation banner (Karpathy §3 surgical: text-only, no file
+ * moves). Idempotent: re-running produces no diff on a previously-
+ * migrated repo.
+ *
+ * === Why text-only (no move / no prune) ===
+ *
+ * v2.11.0 introduces the immutable peaks-prd handoff at
+ * `.peaks/_runtime/<sid>/prd/handoff.md` as the source of truth. The
+ * old `rd/tech-doc.md` is no longer required by any CLI gate, but the
+ * historical content still has audit value. Removing it silently would
+ * lose the diff; renaming would orphan any external reference (e.g.,
+ * commit messages, blog posts). The least-risky path is: tag in place
+ * with a banner; let the user decide when/whether to prune in a future
+ * slice.
+ *
+ * === Banner shape (locked) ===
+ *
+ * The banner is prepended (NOT wrapped) — keeps existing body intact,
+ * Git blame still works for the original content lines.
+ *
+ * === Source: peaks-rd/references/writing-handoff-frontmatter.md §"v2.11.0" ===
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DEPRECATION_BANNER } from './v2-10-to-v2-11-types.js';
+const SKIP_DIRS = new Set([
+    'memory',
+    'PROJECT.md',
+    'retrospective',
+    'scope',
+    '.peaks-init-hooks-decision.json',
+    'session.json',
+    '.session.json',
+    '_runtime',
+    '_sub_agents',
+    'change',
+    'caller',
+    'callers',
+    'sop-state',
+    'system',
+    'active-skill.json',
+    '.active-skill.json'
+]);
+const SESSION_DIR_RE = /^\d{4}-\d{2}-\d{2}-session-/;
+const TECH_DOC_MARKERS = ['## Architecture', '## Component', '## API', '## Dependencies'];
+function sha256(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+function hasExistingFrontmatter(body) {
+    const lines = body.split(/\r?\n/).slice(0, 10);
+    return lines.some((line) => line.trim() === '---');
+}
+function looksLikeTechDoc(body) {
+    return TECH_DOC_MARKERS.some((marker) => body.includes(marker));
+}
+function isAlreadyDeprecated(body) {
+    return body.startsWith(DEPRECATION_BANNER);
+}
+function enumerateSessionDirs(projectRoot) {
+    const peaksRoot = join(projectRoot, '.peaks');
+    if (!existsSync(peaksRoot))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(peaksRoot)) {
+        if (SKIP_DIRS.has(entry))
+            continue;
+        if (entry.startsWith('.'))
+            continue;
+        if (SESSION_DIR_RE.test(entry))
+            out.push(entry);
+    }
+    return out;
+}
+function buildEntryForFile(sessionId, filePath) {
+    if (!existsSync(filePath))
+        return null;
+    const body = readFileSync(filePath, 'utf8');
+    const fromHash = sha256(body);
+    if (isAlreadyDeprecated(body)) {
+        return {
+            sessionId,
+            filePath,
+            fromHash,
+            toHash: fromHash,
+            reason: 'already-deprecated',
+            skippedBytes: 0
+        };
+    }
+    if (hasExistingFrontmatter(body)) {
+        return {
+            sessionId,
+            filePath,
+            fromHash,
+            toHash: fromHash,
+            reason: 'not-a-tech-doc',
+            skippedBytes: 0
+        };
+    }
+    if (!looksLikeTechDoc(body)) {
+        return {
+            sessionId,
+            filePath,
+            fromHash,
+            toHash: fromHash,
+            reason: 'not-a-tech-doc',
+            skippedBytes: 0
+        };
+    }
+    const newBody = DEPRECATION_BANNER + body;
+    return {
+        sessionId,
+        filePath,
+        fromHash,
+        toHash: sha256(newBody),
+        reason: 'will-deprecate',
+        skippedBytes: 0
+    };
+}
+export function enumerateTechDocs(projectRoot) {
+    const out = [];
+    for (const sid of enumerateSessionDirs(projectRoot)) {
+        const filePath = join(projectRoot, '.peaks', sid, 'rd', 'tech-doc.md');
+        if (existsSync(filePath))
+            out.push({ sessionId: sid, filePath });
+    }
+    return out;
+}
+export function planV2ToV11Migration(projectRoot) {
+    const entries = [];
+    let willDeprecateCount = 0;
+    let alreadyDeprecatedCount = 0;
+    let notTechDocCount = 0;
+    for (const { sessionId, filePath } of enumerateTechDocs(projectRoot)) {
+        const entry = buildEntryForFile(sessionId, filePath);
+        if (entry === null)
+            continue;
+        entries.push(entry);
+        if (entry.reason === 'will-deprecate')
+            willDeprecateCount++;
+        else if (entry.reason === 'already-deprecated')
+            alreadyDeprecatedCount++;
+        else
+            notTechDocCount++;
+    }
+    return {
+        projectRoot,
+        entries,
+        willDeprecateCount,
+        alreadyDeprecatedCount,
+        notTechDocCount
+    };
+}
+export function applyV2ToV11Migration(plan) {
+    const errors = [];
+    let writtenCount = 0;
+    for (const entry of plan.entries) {
+        if (entry.reason !== 'will-deprecate')
+            continue;
+        try {
+            const body = readFileSync(entry.filePath, 'utf8');
+            const newBody = DEPRECATION_BANNER + body;
+            writeFileSync(entry.filePath, newBody, 'utf8');
+            writtenCount++;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            errors.push({ path: entry.filePath, message });
+        }
+    }
+    return {
+        plan,
+        applied: true,
+        writtenCount,
+        errors
+    };
+}
+export function dryRunV2ToV11Migration(projectRoot) {
+    const plan = planV2ToV11Migration(projectRoot);
+    return {
+        plan,
+        applied: false,
+        writtenCount: 0,
+        errors: []
+    };
+}

package/dist/services/migration/v2-10-to-v2-11-types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * v2.11.0 — Group E (Tier 8) migration types.
+ *
+ * The migration codemod scans pre-v2.11.0 sessions for `rd/tech-doc.md`
+ * files and prepends a YAML banner marking them as deprecated. Files
+ * move (physically) is out of scope per Karpathy §3 surgical changes;
+ * the immutable peaks-prd handoff at `prd/handoff.md` is the new
+ * source of truth, but old files coexist.
+ *
+ * === Source: peaks-rd/references/writing-handoff-frontmatter.md §"v2.11.0" ===
+ *
+ * The banner shape is fixed; if a file already carries a `---` frontmatter,
+ * the migration skips it (set `reason: 'not-a-tech-doc'`) to avoid clobbering
+ * user-authored content.
+ */
+export type MigrationReason = 'will-deprecate' | 'already-deprecated' | 'not-a-tech-doc';
+export interface MigrationEntry {
+    readonly sessionId: string;
+    readonly filePath: string;
+    readonly fromHash: string;
+    readonly toHash: string;
+    readonly reason: MigrationReason;
+    readonly skippedBytes: number;
+}
+export interface MigrationPlan {
+    readonly projectRoot: string;
+    readonly entries: ReadonlyArray<MigrationEntry>;
+    readonly willDeprecateCount: number;
+    readonly alreadyDeprecatedCount: number;
+    readonly notTechDocCount: number;
+}
+export interface MigrationResult {
+    readonly plan: MigrationPlan;
+    readonly applied: boolean;
+    readonly writtenCount: number;
+    readonly errors: ReadonlyArray<{
+        readonly path: string;
+        readonly message: string;
+    }>;
+}
+export declare const DEPRECATION_BANNER: string;

package/dist/services/migration/v2-10-to-v2-11-types.js

@@ -0,0 +1,23 @@
+/**
+ * v2.11.0 — Group E (Tier 8) migration types.
+ *
+ * The migration codemod scans pre-v2.11.0 sessions for `rd/tech-doc.md`
+ * files and prepends a YAML banner marking them as deprecated. Files
+ * move (physically) is out of scope per Karpathy §3 surgical changes;
+ * the immutable peaks-prd handoff at `prd/handoff.md` is the new
+ * source of truth, but old files coexist.
+ *
+ * === Source: peaks-rd/references/writing-handoff-frontmatter.md §"v2.11.0" ===
+ *
+ * The banner shape is fixed; if a file already carries a `---` frontmatter,
+ * the migration skips it (set `reason: 'not-a-tech-doc'`) to avoid clobbering
+ * user-authored content.
+ */
+export const DEPRECATION_BANNER = [
+    '---',
+    'deprecated: historical',
+    'deprecatedBy: v2.11.0',
+    'replacedBy: peaks-prd handoff at .peaks/_runtime/<sessionId>/prd/handoff.md',
+    '---',
+    ''
+].join('\n');

package/dist/services/mode/bypass-tracker.d.ts

@@ -0,0 +1,4 @@
+export declare const MAX_BYPASSES_PER_SESSION = 3;
+export declare function getBypassCount(sessionRoot: string): number;
+export declare function recordBypass(sessionRoot: string): number;
+export declare function isBypassLimitReached(sessionRoot: string): boolean;

package/dist/services/mode/bypass-tracker.js

@@ -0,0 +1,31 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const MAX_BYPASSES_PER_SESSION = 3;
+const BYPASS_FILE = '.bypass-count.json';
+function bypassFilePath(sessionRoot) {
+    return join(sessionRoot, BYPASS_FILE);
+}
+export function getBypassCount(sessionRoot) {
+    const filePath = bypassFilePath(sessionRoot);
+    if (!existsSync(filePath)) {
+        return 0;
+    }
+    try {
+        const raw = readFileSync(filePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        return typeof parsed.count === 'number' ? parsed.count : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+export function recordBypass(sessionRoot) {
+    const current = getBypassCount(sessionRoot);
+    const next = current + 1;
+    const filePath = bypassFilePath(sessionRoot);
+    writeFileSync(filePath, JSON.stringify({ count: next }, null, 2), 'utf8');
+    return next;
+}
+export function isBypassLimitReached(sessionRoot) {
+    return getBypassCount(sessionRoot) >= MAX_BYPASSES_PER_SESSION;
+}

package/dist/services/mode/mode-enforcement.d.ts

@@ -0,0 +1,14 @@
+import { type SkillPresenceMode } from '../skills/skill-presence-service.js';
+type TransitionKey = `${string}:${string}`;
+export declare function requiresConfirmation(mode: SkillPresenceMode, transitionKey: TransitionKey): boolean;
+export type ConfirmationOptions = {
+    projectRoot: string;
+    transitionKey: TransitionKey;
+    confirmed?: boolean | undefined;
+    forceConfirm?: boolean | undefined;
+};
+export declare class ConfirmationRequiredError extends Error {
+    constructor(transitionKey: TransitionKey);
+}
+export declare function requireUserConfirmation(options: ConfirmationOptions): Promise<void>;
+export {};

package/dist/services/mode/mode-enforcement.js

@@ -0,0 +1,84 @@
+import * as readline from 'node:readline';
+import { getSkillPresence } from '../skills/skill-presence-service.js';
+const ASSISTED_CONFIRM_TRANSITIONS = new Set([
+    'prd:confirmed-by-user',
+    'rd:qa-handoff',
+    'qa:verdict-issued'
+]);
+export function requiresConfirmation(mode, transitionKey) {
+    if (mode === 'full-auto' || mode === 'swarm') {
+        return false;
+    }
+    if (mode === 'strict') {
+        return true;
+    }
+    // assisted: only specific transitions
+    return ASSISTED_CONFIRM_TRANSITIONS.has(transitionKey);
+}
+function describeTransition(transitionKey) {
+    const parts = transitionKey.split(':');
+    const role = parts[0] ?? 'unknown';
+    const state = parts[1] ?? 'unknown';
+    return `Transition ${role.toUpperCase()} → ${state}`;
+}
+export class ConfirmationRequiredError extends Error {
+    constructor(transitionKey) {
+        const description = describeTransition(transitionKey);
+        super(`Confirmation required for: ${description}\n` +
+            'Add --confirm to proceed non-interactively, or run in an interactive terminal.\n' +
+            'In assisted/strict mode, major workflow boundaries require explicit user approval.');
+        this.name = 'ConfirmationRequiredError';
+    }
+}
+export async function requireUserConfirmation(options) {
+    // Resolve presence from the project being operated on, not the process cwd.
+    const presence = getSkillPresence(options.projectRoot);
+    if (!presence?.mode) {
+        return;
+    }
+    const mode = presence.mode;
+    if (!requiresConfirmation(mode, options.transitionKey)) {
+        return;
+    }
+    // --confirm flag bypasses interactive prompt
+    if (options.confirmed) {
+        return;
+    }
+    // PEAKS_AUTO_CONFIRM=1 only works for full-auto/swarm (already returned above)
+    // For assisted/strict, env var is ignored unless --force-confirm is also set
+    if (process.env.PEAKS_AUTO_CONFIRM === '1') {
+        if (options.forceConfirm) {
+            console.error(// TODO(g2): legacy console.error without envelope — grace: 1 minor release (v2.14.0)
+            `[WARNING] --force-confirm used in ${mode} mode. ` +
+                'This bypasses user confirmation. Use with caution.');
+            return;
+        }
+        throw new ConfirmationRequiredError(options.transitionKey);
+    }
+    // --force-confirm without env var
+    if (options.forceConfirm) {
+        console.error(// TODO(g2): legacy console.error without envelope — grace: 1 minor release (v2.14.0)
+        `[WARNING] --force-confirm used in ${mode} mode. ` +
+            'This bypasses user confirmation. Use with caution.');
+        return;
+    }
+    // Interactive prompt
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stderr
+    });
+    return new Promise((resolve, reject) => {
+        const description = describeTransition(options.transitionKey);
+        const prompt = `\n[CONFIRM] ${description}\nProceed? (y/N) `;
+        rl.question(prompt, (answer) => {
+            rl.close();
+            const normalized = answer.trim().toLowerCase();
+            if (normalized === 'y' || normalized === 'yes') {
+                resolve();
+            }
+            else {
+                reject(new ConfirmationRequiredError(options.transitionKey));
+            }
+        });
+    });
+}

package/dist/services/mut/assert-scanner.d.ts

@@ -0,0 +1,6 @@
+import type { AssertionsReport } from './types.js';
+export interface ScanInput {
+    readonly project: string;
+    readonly testFiles: ReadonlyArray<string>;
+}
+export declare function scanAssertions(input: ScanInput): Promise<AssertionsReport>;