peaks-cli 1.4.2 → 2.0.0

package/dist/src/services/slice/slice-check-service.js

@@ -1,17 +1,55 @@
 import { execFileSync } from 'node:child_process';
-import { existsSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { isDirectory } from '../../shared/fs.js';
 import { getCurrentChangeId } from '../../shared/change-id.js';
 import { verifyPipeline } from '../workflow/pipeline-verify-service.js';
-function runCommand(command, args, cwd, timeoutMs) {
+import { findMockViolations } from '../audit/enforcers/mock-placement.js';
+import { runRedLinesAudit } from '../audit/red-lines-service.js';
+/**
+ * Resolve a CLI binary to a project-local path, falling back to
+ * the system `npx`. pnpm (and npm/yarn) all create
+ * `node_modules/.bin/<name>`:
+ *
+ *   - On Unix, this is a symlink to the package's executable.
+ *   - On Windows, this is a `.cmd` shim; `execFileSync` only
+ *     resolves `.cmd` through the shell (PATHEXT), so we pass
+ *     `shell: true` when invoking one. Without this, the
+ *     Windows `npx ENOENT` false-positive from
+ *     observations 2317 + 2792 reproduces for every local
+ *     binary.
+ *
+ * Returns the command + args + a `shell` flag that the
+ * `runCommand` helper threads into `execFileSync`.
+ */
+function resolveLocalBinary(projectRoot, name) {
+    // pnpm creates `node_modules/.bin/<name>` (symlink on Unix,
+    // `.cmd` shim on Windows). We probe both shapes; the
+    // `process.platform === 'win32'` extension probe is the most
+    // portable approach.
+    const isWin = process.platform === 'win32';
+    const candidateNames = isWin ? [`${name}.cmd`, `${name}.ps1`, `${name}`] : [name];
+    for (const candidate of candidateNames) {
+        const cmdPath = join(projectRoot, 'node_modules', '.bin', candidate);
+        if (existsSync(cmdPath)) {
+            return { command: cmdPath, args: [], shell: isWin };
+        }
+    }
+    // Fallback: system npx. On Windows this still has the ENOENT
+    // issue, but the fallback is at least informative when it
+    // fires (the user can see "npx not found" instead of a
+    // silent exit 1).
+    return { command: 'npx', args: [name], shell: false };
+}
+function runCommand(command, args, cwd, timeoutMs, shell = false) {
     const start = Date.now();
     try {
         const stdout = execFileSync(command, args, {
             cwd,
             stdio: ['ignore', 'pipe', 'pipe'],
             timeout: timeoutMs,
-            maxBuffer: 32 * 1024 * 1024
+            maxBuffer: 32 * 1024 * 1024,
+            shell
         }).toString('utf8');
         return {
             status: 'pass',
@@ -41,11 +79,17 @@ function tailLines(text, max) {
 }
 async function runTypecheck(projectRoot) {
     const start = Date.now();
-    const result = runCommand('npx', ['tsc', '--noEmit'], projectRoot, 180_000);
+    // Per Windows npx ENOENT (observations 2317+2792 from
+    // 2026-06-09), prefer the project-local `node_modules/.bin/tsc`
+    // (symlink on Unix, .cmd on Windows). The local binary is
+    // installed by pnpm at workspace-install time and avoids the
+    // npx PATH-lookup issue.
+    const tsc = resolveLocalBinary(projectRoot, 'tsc');
+    const result = runCommand(tsc.command, [...tsc.args, '--noEmit'], projectRoot, 180_000, tsc.shell);
     const testFiles = result.stdout.match(/(tests?\/.*\.test\.ts)/g) ?? [];
     return {
         name: 'typecheck',
-        description: 'npx tsc --noEmit (no JS emit, type-only check)',
+        description: `${tsc.command} --noEmit (no JS emit, type-only check)`,
         status: result.status,
         durationMs: result.durationMs,
         detail: result.status === 'pass'
@@ -76,13 +120,17 @@ async function runUnitTests(projectRoot, runTests) {
     // state. Opt-in to the full suite via `runTests: true` (CLI flag
     // `--run-tests`). See `references/runbook.md` for the rationale and
     // `tests/unit/slice-check-service.test.ts` for the regression net.
-    const args = runTests
-        ? ['vitest', 'run', '--reporter=default', '--coverage=false']
-        : ['vitest', 'run', '--changed', '--reporter=default', '--coverage=false'];
+    // Per Windows npx ENOENT (observations 2317+2792), resolve
+    // the project-local vitest binary instead of shelling out
+    // through npx.
+    const vitest = resolveLocalBinary(projectRoot, 'vitest');
+    const vitestArgs = runTests
+        ? ['run', '--reporter=default', '--coverage=false']
+        : ['run', '--changed', '--reporter=default', '--coverage=false'];
     const description = runTests
-        ? 'npx vitest run (full test suite, coverage off)'
-        : 'npx vitest run --changed (tests for git-changed files only, coverage off)';
-    const result = runCommand('npx', args, projectRoot, 600_000);
+        ? `${vitest.command} run (full test suite, coverage off)`
+        : `${vitest.command} run --changed (tests for git-changed files only, coverage off)`;
+    const result = runCommand(vitest.command, [...vitest.args, ...vitestArgs], projectRoot, 600_000, vitest.shell);
     const summary = parseVitestSummary(result.stdout, result.durationMs);
     // Vitest doesn't always print the per-bucket counts cleanly; infer "passed"
     // as total - failed - skipped when failed/skipped buckets are present.
@@ -225,7 +273,7 @@ export async function sliceCheck(options) {
     if (options.skipTests) {
         stages.push({
             name: 'unit-tests',
-            description: 'npx vitest run (skipped per --skip-tests)',
+            description: 'vitest run (skipped per --skip-tests)',
             status: 'skipped',
             durationMs: 0,
             detail: 'Skipped: --skip-tests was set. Use the peaks-solo-test skill to run the full suite manually.'
@@ -244,7 +292,7 @@ export async function sliceCheck(options) {
             const failureCount = unitTests.data?.failed ?? 0;
             stages.push({
                 name: 'unit-tests',
-                description: `npx vitest run ${options.runTests === true ? '' : '--changed '} (overridden via --allow-pre-existing-failures)`.trim(),
+                description: `vitest run ${options.runTests === true ? '' : '--changed '} (overridden via --allow-pre-existing-failures)`.trim(),
                 status: 'skipped',
                 durationMs: unitTests.durationMs,
                 detail: `pre-existing failures: ${failureCount} failing test(s) under coverage.exclude or unrelated to this slice; user opted in via --allow-pre-existing-failures. For the long-term fix, mark these tests .skip or move to coverage.exclude (see dogfood-2-f1-f4.md F17c).`,
@@ -261,6 +309,17 @@ export async function sliceCheck(options) {
     stages.push(await runReviewFanout(options.projectRoot, rid, options.refreshFanout));
     // Stage 4: gate verify-pipeline
     stages.push(await runGateVerifyPipeline(options.projectRoot, rid, rid));
+    // Stage 5: mock-placement (L2.1 P0 #5) — refuse inline mock data in src/ or skills/.
+    // Lifts changed files via `git diff --name-only HEAD`; falls back to a
+    // warning when the diff is empty (e.g. a fresh tree). Lighter than the
+    // full `peaks scan diff-vs-scope` and keeps the slice check self-contained.
+    stages.push(await runMockPlacement(options.projectRoot));
+    // Stage 6 (Slice #7 L2.4 P2-b): audit-regression — assert
+    // catalog integrity (no orphan enforcers, no orphan catalog
+    // entries), catalog size lower bound, and runtime budget.
+    // The stage runs `peaks audit red-lines` in-process (no
+    // subprocess) and is gating: failure exits non-zero.
+    stages.push(await runAuditRegression(options.projectRoot));
     const boundaryReady = stages.every((s) => s.status === 'pass' || s.status === 'skipped');
     const nextActions = [];
     if (!boundaryReady) {
@@ -283,3 +342,97 @@ export async function sliceCheck(options) {
         nextActions
     };
 }
+async function runAuditRegression(projectRoot) {
+    const start = Date.now();
+    try {
+        const result = runRedLinesAudit({ projectRoot });
+        const durationMs = Date.now() - start;
+        // Slice #7 L2.4 P2-b acceptance A3 + A4:
+        //   - totalRedLines >= 60 (catalog grew to 66; pins the lower bound)
+        //   - enforcerFindings has no rl-audit-no-orphan-enforcer / rl-audit-no-orphan-catalog hits
+        const issues = [];
+        if (result.audit.totalRedLines < 60) {
+            issues.push(`totalRedLines ${result.audit.totalRedLines} < 60`);
+        }
+        const orphanFindings = result.audit.enforcerFindings.filter((f) => f.enforcerId === 'rl-audit-no-orphan-enforcer-001' ||
+            f.enforcerId === 'rl-audit-no-orphan-catalog-001');
+        if (orphanFindings.length > 0) {
+            issues.push(`${orphanFindings.length} orphan-enforcer / orphan-catalog finding(s)`);
+        }
+        if (issues.length > 0) {
+            return {
+                name: 'audit-regression',
+                description: 'audit-regression: catalog integrity + runtime budget (L2.4 P2-b stage 6)',
+                status: 'fail',
+                durationMs,
+                detail: issues.join('; '),
+            };
+        }
+        return {
+            name: 'audit-regression',
+            description: 'audit-regression: catalog integrity + runtime budget (L2.4 P2-b stage 6)',
+            status: 'pass',
+            durationMs,
+            detail: `catalog: ${result.audit.totalRedLines} entries (${result.audit.cliBacked} cli-backed, ${result.audit.proseOnly} prose-only); audit ran in ${durationMs}ms`,
+        };
+    }
+    catch (error) {
+        return {
+            name: 'audit-regression',
+            description: 'audit-regression: catalog integrity + runtime budget (L2.4 P2-b stage 6)',
+            status: 'fail',
+            durationMs: Date.now() - start,
+            detail: 'audit-regression failed: ' + (error?.message ?? String(error)),
+        };
+    }
+}
+async function runMockPlacement(projectRoot) {
+    const start = Date.now();
+    // List changed files via git. `--name-only` produces one path per line;
+    // we filter to text files in scope and read each.
+    const diffResult = runCommand('git', ['diff', '--name-only', '--diff-filter=ACMR', 'HEAD'], projectRoot, 30_000);
+    if (diffResult.status !== 'pass') {
+        return {
+            name: 'mock-placement',
+            description: 'mock-placement: no inline mock data in src/ or skills/ (L2.1 P0 #5)',
+            status: 'skipped',
+            durationMs: Date.now() - start,
+            detail: 'git diff failed or returned no changed files; mock-placement scan skipped.'
+        };
+    }
+    const changed = diffResult.stdout
+        .split('\n')
+        .map((l) => l.trim())
+        .filter(Boolean);
+    if (changed.length === 0) {
+        return {
+            name: 'mock-placement',
+            description: 'mock-placement: no inline mock data in src/ or skills/ (L2.1 P0 #5)',
+            status: 'skipped',
+            durationMs: Date.now() - start,
+            detail: 'no changed files in HEAD diff; mock-placement scan skipped.'
+        };
+    }
+    const files = changed
+        .filter((p) => p.startsWith('src/') || p.startsWith('skills/'))
+        .filter((p) => p.endsWith('.ts') || p.endsWith('.tsx') || p.endsWith('.js') || p.endsWith('.mjs'))
+        .map((filePath) => {
+        const abs = join(projectRoot, filePath);
+        if (!existsSync(abs))
+            return null;
+        const content = readFileSync(abs, 'utf-8');
+        return { filePath, content };
+    })
+        .filter((f) => f !== null);
+    const violations = findMockViolations(files);
+    return {
+        name: 'mock-placement',
+        description: 'mock-placement: no inline mock data in src/ or skills/ (L2.1 P0 #5)',
+        status: violations.length === 0 ? 'pass' : 'fail',
+        durationMs: Date.now() - start,
+        detail: violations.length === 0
+            ? `Scanned ${files.length} changed file(s); no inline mock data found.`
+            : `${violations.length} violation(s): ${violations.map((v) => `${v.filePath} (${v.snippet})`).join('; ')}`,
+        data: { scannedFiles: files.length, violations: violations.map((v) => ({ filePath: v.filePath, pattern: v.pattern, snippet: v.snippet })) }
+    };
+}

package/dist/src/services/slice/slice-check-types.d.ts

@@ -28,7 +28,7 @@
 export type SliceCheckStageStatus = 'pass' | 'fail' | 'skipped';
 export type SliceCheckStage = {
     /** Stable id for the stage (matches the runbook's check list). */
-    name: 'typecheck' | 'unit-tests' | 'review-fanout' | 'gate-verify-pipeline';
+    name: 'typecheck' | 'unit-tests' | 'review-fanout' | 'gate-verify-pipeline' | 'mock-placement' | 'audit-regression';
     /** Human-readable description. */
     description: string;
     status: SliceCheckStageStatus;

package/dist/src/services/standards/migrate-claude-rules-service.d.ts

@@ -0,0 +1,19 @@
+export interface MigrateClaudeRulesInput {
+    readonly projectRoot: string;
+    readonly apply?: boolean;
+}
+export interface MigrateClaudeRulesData {
+    readonly backupPath: string | null;
+    readonly thinnedFiles: readonly string[];
+    readonly scaffoldedFiles: readonly string[];
+    readonly preservedFiles: readonly string[];
+    readonly wouldChange: boolean;
+    readonly applied: boolean;
+    readonly nextActions: readonly string[];
+}
+export interface MigrateClaudeRulesResult {
+    readonly ok: true;
+    readonly data: MigrateClaudeRulesData;
+    readonly warnings: readonly string[];
+}
+export declare function migrateClaudeRules(input: MigrateClaudeRulesInput): MigrateClaudeRulesResult;

package/dist/src/services/standards/migrate-claude-rules-service.js

@@ -0,0 +1,193 @@
+/**
+ * peaks standards migrate — .claude/rules/ tree thinning.
+ * Slice: 2026-06-12-standards-migrate-claude-rules.
+ *
+ * The 1.x peaks-cli install copied a thick .claude/rules
+ * tree (skill-first / CLI-auxiliary / dogfood / commit-trailer
+ * rules) into consumer projects. In 2.0, the canonical rules
+ * live at .peaks/standards/ and every markdown file under
+ * .claude/rules becomes a 2-line pointer to the canonical path.
+ *
+ * The service:
+ *   1. Backs up the existing `.claude/rules/` tree to
+ *      `.claude/rules/.peaks-2.0-backup-<ts>/` (timestamped;
+ *      safe to run multiple times).
+ *   2. Replaces each .md file under .claude/rules (recursive)
+ *      with a 2-line pointer.
+ *   3. Scaffolds the 2.0 canonical rules at
+ *      `.peaks/standards/{common,typescript}/`, but
+ *      never overwrites existing files in `.peaks/standards/`.
+ *
+ * All operations are gated by `apply: true`. Dry-run mode
+ * returns the would-change diff without writing.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const POINTER_TEXT = (canonicalPath) => `# Canonical peaks-cli 2.0 rules live at: ${canonicalPath}\n# This file is a 2-line pointer. Edit the canonical file instead.\n`;
+function timestampSlug() {
+    return new Date().toISOString().replace(/[:.]/g, '-');
+}
+function readMarkdownFilesRecursive(root) {
+    if (!existsSync(root))
+        return [];
+    const out = [];
+    const stat = statSync(root);
+    if (stat.isFile()) {
+        return root.endsWith('.md') ? [root] : [];
+    }
+    if (!stat.isDirectory())
+        return [];
+    for (const entry of readdirSync(root)) {
+        out.push(...readMarkdownFilesRecursive(join(root, entry)));
+    }
+    return out;
+}
+function isAlreadyPointer(filePath) {
+    if (!existsSync(filePath))
+        return false;
+    try {
+        const body = readFileSync(filePath, 'utf8');
+        return body.includes('Canonical peaks-cli 2.0 rules live at:');
+    }
+    catch {
+        return false;
+    }
+}
+const CANONICAL_2_0_DEV_PREFERENCE = `# Peaks-Cli dev preference (2.0 canonical)
+
+> Project-local preference, captured from the 1.x install + re-rendered with the 2.0 vocabulary.
+> Scope: applies to every iteration, adjustment, fix, or tweak on this project.
+> Reading: read this **before** opening a new CLI command or routing a new feature through a CLI surface.
+
+## Rule 1 — Skill-first, CLI-auxiliary
+
+When designing or modifying a peaks-cli feature, default to the **skill-first** design. CLI commands are **invoked by the skill prompt** when they are the right primitive: a side effect that must be atomic, a gate that must be machine-enforced, a probe that needs structured JSON, or a backstop that prevents the LLM from skipping a step. Behaviour only an LLM in a skill prompt would use lives **in the relevant skill's SKILL.md**, not as a new CLI command. See \`.claude/rules/common/dev-preference.md\` for the decision template.
+
+## Rule 2 — Dogfood on every adjustment
+
+**Every adjustment, iteration, or fix-problem operation must be dogfood-tested in the current project before the work is declared complete.** No exceptions for "it's a small change", "just a comment update", or "just a SKILL.md line". The unit test suite is a subset of "current effect"; the dogfood is the full set. If a change passes unit tests but breaks a CLI command, the change is a regression.
+
+## Rule 3 — Commits belong to the human
+
+**No AI co-author trailer.** The commit is the human's. **Identity is global gitconfig only** (\`~/.gitconfig\`). Do not set, override, or shadow \`user.name\` / \`user.email\` at the repo level, via env vars, or via \`git -c user.*=...\`. The commit's recorded author and committer must both equal the global identity.
+`;
+const CANONICAL_2_0_CODING_STYLE_TS = `# TypeScript Coding Standards (2.0 canonical)
+
+> Project-local standards, derived from the 1.x install + re-rendered with the 2.0 vocabulary.
+
+- Apply project-local conventions before generic typescript guidance.
+- Keep public APIs typed or documented according to typescript ecosystem norms.
+- Do not add new \`any\` types; use explicit domain types, generics, or \`unknown\` with narrowing.
+- Prefer standard tooling and existing project scripts for formatting, linting, tests, and coverage.
+- peaks-rd must check this file before planning code changes in typescript projects.
+`;
+const CANONICAL_2_0_COMMON_FILES = [
+    { relPath: 'common/dev-preference.md', content: CANONICAL_2_0_DEV_PREFERENCE },
+    {
+        relPath: 'common/coding-style.md',
+        content: '# Coding Standards (2.0 canonical)\n\n- Prefer simple, readable code over clever abstractions.\n- Keep functions focused and files cohesive.\n- Use immutable updates unless a language-specific convention explicitly favors mutation.\n- Validate user input, external data, file paths, and configuration at system boundaries.\n- Preserve existing project conventions when they are stricter than this baseline.\n',
+    },
+    {
+        relPath: 'common/code-review.md',
+        content: '# Code Review Standards (2.0 canonical)\n\n- Review diffs for correctness, maintainability, test coverage, and regression risk.\n- Treat missing tests for changed behavior as a blocker unless the change is documentation-only.\n- Verify code paths that handle filesystem, external APIs, credentials, user input, or generated artifacts.\n',
+    },
+    {
+        relPath: 'common/security.md',
+        content: '# Security Review Standards (2.0 canonical)\n\n- Never hardcode secrets, API keys, passwords, tokens, or credentials.\n- Do not send private code or secrets to external services without explicit user authorization.\n- Guard filesystem writes against path traversal, symlink, and junction escapes.\n- Require explicit confirmation for destructive actions, external state changes, and credential use.\n',
+    },
+    { relPath: 'typescript/coding-style.md', content: CANONICAL_2_0_CODING_STYLE_TS },
+];
+export function migrateClaudeRules(input) {
+    const projectRoot = input.projectRoot;
+    const apply = input.apply === true;
+    const warnings = [];
+    const nextActions = [];
+    const claudeRulesDir = join(projectRoot, '.claude', 'rules');
+    const peaksStandardsDir = join(projectRoot, '.peaks', 'standards');
+    const canonicalRelPath = '.peaks/standards/';
+    const existingRulesFiles = readMarkdownFilesRecursive(claudeRulesDir);
+    const thickFiles = existingRulesFiles.filter((f) => !isAlreadyPointer(f));
+    const hasThickFiles = thickFiles.length > 0;
+    // The backup path is computed eagerly (so dry-run can preview
+    // the would-create location) but only created on disk in
+    // apply mode. In dry-run mode we still return the path so
+    // the user can see where the backup will land.
+    const computedBackupPath = hasThickFiles ? join(claudeRulesDir, `.peaks-2.0-backup-${timestampSlug()}`) : null;
+    const backupPath = apply ? computedBackupPath : null;
+    const thinnedFiles = [];
+    const scaffoldedFiles = [];
+    const preservedFiles = [];
+    // wouldChange is true iff there is at least one thick file to
+    // thin. An empty .claude/rules/ is NOT a wouldChange (no-op).
+    const wouldChange = hasThickFiles;
+    if (apply && hasThickFiles) {
+        // Step 1: backup
+        if (backupPath !== null) {
+            try {
+                mkdirSync(backupPath, { recursive: true });
+                for (const file of thickFiles) {
+                    const body = readFileSync(file, 'utf8');
+                    const rel = file.slice(claudeRulesDir.length + 1);
+                    writeFileSync(join(backupPath, rel), body, 'utf8');
+                }
+            }
+            catch (err) {
+                warnings.push(`Backup step failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        // Step 2: replace each .md with a 2-line pointer
+        for (const file of thickFiles) {
+            try {
+                writeFileSync(file, POINTER_TEXT(canonicalRelPath), 'utf8');
+                thinnedFiles.push(file);
+            }
+            catch (err) {
+                warnings.push(`Thin step failed for ${file}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        // Step 3: scaffold .peaks/standards/ — never overwrite existing
+        for (const file of CANONICAL_2_0_COMMON_FILES) {
+            const dest = join(peaksStandardsDir, file.relPath);
+            if (existsSync(dest)) {
+                preservedFiles.push(dest);
+                continue;
+            }
+            try {
+                mkdirSync(join(dest, '..'), { recursive: true });
+                writeFileSync(dest, file.content, 'utf8');
+                scaffoldedFiles.push(dest);
+            }
+            catch (err) {
+                warnings.push(`Scaffold step failed for ${file.relPath}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    if (thinnedFiles.length > 0) {
+        nextActions.push(`Thinned ${thinnedFiles.length} .md file(s) under .claude/rules (recursive) → 2-line pointer.`);
+    }
+    if (scaffoldedFiles.length > 0) {
+        nextActions.push(`Scaffolded ${scaffoldedFiles.length} 2.0 canonical rule(s) at .peaks/standards/.`);
+    }
+    if (preservedFiles.length > 0) {
+        nextActions.push(`Preserved ${preservedFiles.length} existing .peaks/standards/ file(s) (no overwrite).`);
+    }
+    if (backupPath !== null) {
+        nextActions.push(`Backup at ${backupPath} (git-ignored).`);
+    }
+    if (!apply && wouldChange) {
+        nextActions.push('Re-run with --apply to perform the migration.');
+    }
+    return {
+        ok: true,
+        data: {
+            backupPath,
+            thinnedFiles,
+            scaffoldedFiles,
+            preservedFiles,
+            wouldChange,
+            applied: apply && hasThickFiles,
+            nextActions,
+        },
+        warnings,
+    };
+}

package/dist/src/services/understand/understand-scan-service.js

@@ -2,6 +2,7 @@ import { stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { isDirectory, pathExists, readText } from '../../shared/fs.js';
 import { getErrorMessage } from '../../shared/result.js';
+import { loadPreferences } from '../preferences/preferences-service.js';
 function defaultArtifactDir(projectRoot) {
     return join(projectRoot, '.understand-anything');
 }
@@ -54,19 +55,31 @@ async function readGraph(graphPath) {
 export async function scanUnderstandAnything(options) {
     const artifactDir = options.artifactDir ?? defaultArtifactDir(options.projectRoot);
     const exists = await isDirectory(artifactDir);
+    // L3.1: read uaPrompt from preferences.json (graceful — returns 'unset' if missing/broken)
+    const uaPrompt = await readUaPrompt(options.projectRoot);
     if (!exists) {
         return {
             exists: false,
             artifactDir,
             graph: { exists: false, path: join(artifactDir, 'knowledge-graph.json') },
             intermediate: { exists: false, path: join(artifactDir, 'intermediate') },
-            diffOverlay: { exists: false, path: join(artifactDir, 'diff-overlay.json') }
+            diffOverlay: { exists: false, path: join(artifactDir, 'diff-overlay.json') },
+            uaPrompt
         };
     }
     const graph = await readGraph(join(artifactDir, 'knowledge-graph.json'));
     const intermediate = await readFlag(join(artifactDir, 'intermediate'));
     const diffOverlay = await readFlag(join(artifactDir, 'diff-overlay.json'));
-    return { exists: true, artifactDir, graph, intermediate, diffOverlay };
+    return { exists: true, artifactDir, graph, intermediate, diffOverlay, uaPrompt };
+}
+async function readUaPrompt(projectRoot) {
+    try {
+        const prefs = await loadPreferences(projectRoot);
+        return prefs.uaPrompt;
+    }
+    catch {
+        return 'unset';
+    }
 }
 function pickStringId(value) {
     if (value === null || typeof value !== 'object' || Array.isArray(value)) {

package/dist/src/services/understand/understand-types.d.ts

@@ -15,10 +15,36 @@ export type UnderstandFlagReport = {
     exists: boolean;
     path: string;
 };
+/**
+ * Slice L3.1 — UA opt-in UX state. 'unset' triggers an opt-in prompt on
+ * first scan; 'skip-this-session' suppresses the prompt for the current
+ * session; 'skip-forever' writes to .peaks/preferences.json to suppress
+ * all future prompts. Mirrors preferences.json:uaPrompt.
+ */
+export type UaPromptDecision = 'unset' | 'skip-this-session' | 'skip-forever';
 export type UnderstandScanReport = {
     exists: boolean;
     artifactDir: string;
     graph: UnderstandGraphReport;
     intermediate: UnderstandFlagReport;
     diffOverlay: UnderstandFlagReport;
+    /** Slice L3.1: opt-in UX state from preferences.json:uaPrompt. */
+    readonly uaPrompt?: UaPromptDecision;
 };
+/**
+ * Slice L3.1 — opt-in prompt payload. When uaPrompt === 'unset' and UA is
+ * absent, the peaks-solo / peaks-ide layer surfaces this to the user via
+ * AskUserQuestion. The CLI does not prompt directly; it returns this
+ * payload so the LLM-side UX layer can decide.
+ */
+export interface UaOptInPrompt {
+    readonly version: 1;
+    readonly tool: 'ua-opt-in';
+    readonly artifactDir: string;
+    readonly reason: 'ua-artifact-missing';
+    readonly options: readonly {
+        readonly id: 'install' | 'fallback-this-session' | 'fallback-forever';
+        readonly label: string;
+        readonly description: string;
+    }[];
+}

package/dist/src/services/upgrade/1x-detector-service.d.ts

@@ -0,0 +1,7 @@
+export interface OneXState {
+    readonly isOneX: boolean;
+    readonly signals: readonly string[];
+    readonly projectRoot: string | null;
+    readonly configPath: string | null;
+}
+export declare function detect1xProjectState(cwd?: string): OneXState;

package/dist/src/services/upgrade/1x-detector-service.js

@@ -0,0 +1,94 @@
+/**
+ * 1.x → 2.0 detection service — TypeScript mirror of
+ * `scripts/install-skills.mjs:detect1xProjectState`.
+ *
+ * Slice: 2026-06-12-solo-step-0-55-1x-detection.
+ *
+ * The canonical implementation lives in the .mjs postinstall
+ * (because the postinstall runs before any TS compile step).
+ * This TS mirror exists so the peaks-solo skill can call
+ * `peaks upgrade --detect-1x --project <root> --json` and
+ * read a structured JSON envelope to gate the
+ * AskUserQuestion that prompts the 1.x → 2.0 upgrade.
+ *
+ * The two implementations MUST stay in parity. The
+ * `tests/integration/upgrade/1x-detector-parity.test.ts`
+ * test exercises both on the same fixture and asserts
+ * their outputs match.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+const MAX_WALK_UP = 8;
+export function detect1xProjectState(cwd = process.cwd()) {
+    const home = homedir();
+    const signals = [];
+    let projectRoot = null;
+    let configPath = null;
+    // Walk up from cwd looking for .peaks/_runtime (signals
+    // we're inside a peaks project).
+    let dir = cwd;
+    for (let i = 0; i < MAX_WALK_UP; i += 1) {
+        const peaksRuntime = join(dir, '.peaks', '_runtime');
+        if (existsSync(peaksRuntime)) {
+            projectRoot = dir;
+            break;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    // Signal 1: ~/.peaks/config.json with 1.x version
+    const globalConfig = join(home, '.peaks', 'config.json');
+    if (existsSync(globalConfig)) {
+        try {
+            const raw = JSON.parse(readFileSync(globalConfig, 'utf8'));
+            if (typeof raw['version'] === 'string' && /^1\./.test(raw['version'])) {
+                signals.push(`global config at ${globalConfig} is 1.x (${raw['version']})`);
+                if (configPath === null)
+                    configPath = globalConfig;
+            }
+        }
+        catch {
+            // ignore parse error — the 1.x detection is best-effort
+        }
+    }
+    // Signal 2: .claude/rules/common/dev-preference.md with peaks progress
+    if (projectRoot !== null) {
+        const devPref = join(projectRoot, '.claude', 'rules', 'common', 'dev-preference.md');
+        if (existsSync(devPref)) {
+            try {
+                const body = readFileSync(devPref, 'utf8');
+                if (/peaks progress/i.test(body)) {
+                    signals.push(`${devPref} references "peaks progress" (1.x CLI surface, removed in slice #014)`);
+                }
+            }
+            catch {
+                // ignore
+            }
+        }
+        // Signal 3: project preferences.json missing or 1.x
+        const prefs = join(projectRoot, '.peaks', 'preferences.json');
+        if (!existsSync(prefs)) {
+            signals.push(`${prefs} does not exist (1.x project never migrated)`);
+        }
+        else {
+            try {
+                const raw = JSON.parse(readFileSync(prefs, 'utf8'));
+                if (raw['schema_version'] !== '2.0.0') {
+                    signals.push(`${prefs} has schema_version ${JSON.stringify(raw['schema_version'])}, expected '2.0.0'`);
+                }
+            }
+            catch {
+                signals.push(`${prefs} exists but is not valid JSON`);
+            }
+        }
+    }
+    return {
+        isOneX: signals.length > 0,
+        signals,
+        projectRoot,
+        configPath,
+    };
+}