peaks-cli 1.3.9 → 1.4.1

package/README.md

@@ -148,6 +148,59 @@ peaks project memories --project <repo> --json     # 读取 .peaks/memory/ 里
 
 完整命令列表跑 `peaks --help` 即可。
 
+## 技能白名单：`peaks skill scope`
+
+`peaks skill scope` 把"哪些 skill 暴露给当前项目的 LLM"这件事从"全部加载"变成"按项目相关度过滤"。1.4.0 起默认带 shadow-stub 机制，**denied skill 的 LLM 上下文减量约 96.4%**（每个 stub ≈285 字节 vs 原 SKILL.md ≈7-8 KB）。
+
+### 三步走
+
+```bash
+peaks skill scope --detect --project <repo> --json  # 看哪些 skill 被标 relevant / borderline / irrelevant
+peaks skill scope --apply  --project <repo>         # 写 source-of-truth + project-local mirror（默认 shadow-stub）
+peaks skill scope --show   --project <repo>         # 查当前应用了哪个 allowlist
+peaks skill scope --reset  --project <repo>         # 全部撤回
+```
+
+`--apply` 写两份东西：
+- `.peaks/scope/skills.json` — 唯一真源（allowlist + meta）
+- `.claude/skills/<skill>/SKILL.md` — project-local mirror；denied skill 被替换为 ~285 字节的 shadow stub，前 5 行包含 `description: _peaks_scope_disabled` 标记，Claude Code 看到这个标记就跳过它的 full body
+
+### 怎么 `--apply` 真的把上下文砍下来
+
+光把 skill 从 LLM 的可调用列表里 deny 不够——Claude Code 仍然会从项目本地 mirror 读完整的 SKILL.md。**shadow-stub** 把 mirror 也换成 5 行 stub：
+
+```yaml
+---
+name: agent-sort
+description: _peaks_scope_disabled
+peaks_scope_disabled: true
+---
+# Disabled by `peaks skill scope --apply`
+```
+
+实测在 ice-cola 项目（pnpm monorepo，4 包，TS + Python）：215 个 skill × 1.92 MB → 应用白名单后 44 个 allowed × 364 KB + 123 个 denied × 35 KB stubs = **399 KB 整体 LLM 可见 skill 上下文**。**减量 924.7 KB / 69.8%**，其中 denied 侧减量 96.4%。
+
+shadow-stub 是 1.4.0 的默认行为（`--shadow-fallback`）。想 copy 原 SKILL.md 到 mirror（IDE 端 inspection 用），传 `--no-shadow-fallback` 显式 opt-out。
+
+### 运行时观测：`peaks skill context-stats`
+
+想知道当前项目实际加载了多少 skill 字节 + 估计 token 数：
+
+```bash
+peaks skill context-stats --project <repo>
+# Allowed: 44 skills, 364.4 KB / 91.1K tokens.
+# Denied:  123 skills, 35.0 KB / 8.8K tokens (96.4% shadow-stub reduction).
+# Total:   399.5 KB / 99.9K tokens.
+```
+
+加 `--json` 拿结构化 envelope。还没 apply scope 的项目会拿到 `NO_SCOPE` code + 推荐命令。
+
+### 限制
+
+- detect 的 `relevant` 标记是按文件后缀占比 ≥ 5% 才算的（1.4.1 起的 shareByExtension 阈值）。比如冰-cola 这种 TS + Python 单仓，cpp/golang/java/kotlin/rust/swift 这些 language-specific skill 不会被标 relevant；以前 1 个 stray `.cpp` 文件就会把 `cpp-coding-standards` 误判为 relevant。
+- 阈值可通过 `PEAKS_SCOPE_THRESHOLD=0.05` 环境变量或 `--threshold 0.05` 调整。
+- `.peaks/scope/skills.json` 是 hand-editable 的；手改后下次 `--apply` 会按 detect 结果覆盖（除非带 `--strict` / `--loose` 改 detect 模式，不带 allowOverride）。
+
 ## 自定义 SOP（把你的流程变成带门禁的工作流）
 
 > **技能入口**：`peaks-sop` 技能

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

@@ -5,12 +5,14 @@ import { getArtifactWorkspaceStatus, planArtifactSync } from '../../services/art
 import { executeProjectMemoryBackup, executeProjectMemoryExtract, summarizeProjectMemoryBackupResult, summarizeProjectMemoryExtractResult } from '../../services/memory/project-memory-service.js';
 import { summarizeProjectStandardsInitResult, summarizeProjectStandardsUpdateResult } from '../../services/standards/project-standards-service.js';
 import { executeProjectStandardsInitIdeAware, executeProjectStandardsUpdateIdeAware } from '../../services/standards/ide-aware-standards-service.js';
+import { migrateStandards } from '../../services/standards/migrate-service.js';
 import { listProfiles } from '../../services/profiles/profile-service.js';
 import { planProxyTest } from '../../services/proxy/proxy-service.js';
 import { runDoctor } from '../../services/doctor/doctor-service.js';
 import { listSkills } from '../../services/skills/skill-registry.js';
 import { inspectSkillRunbook } from '../../services/skills/skill-runbook-service.js';
 import { setSkillPresence, clearSkillPresence, getSkillPresence, isSkillPresenceMode, touchSkillHeartbeat } from '../../services/skills/skill-presence-service.js';
+import { detectPresenceMarker } from '../../services/hooks/presence-marker-detector.js';
 import { getSessionId, getSessionMeta, rotateSessionBinding, setSessionMeta, setSessionTitle, listSessionMetas } from '../../services/session/session-manager.js';
 import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
 import { findProjectRoot } from '../../services/config/config-safety.js';
@@ -198,6 +200,16 @@ export function registerCoreAndArtifactCommands(program, io) {
             lastHeartbeat: updated.lastHeartbeat
         }), options.json);
     });
+    addJsonOption(skill
+        .command('detect-marker-loss')
+        .description('Detect whether the latest assistant message lost the Peaks-Cli status header while a peaks skill is still active (slice 028 detection primitive).')
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
+        .option('--message <text>', 'latest assistant message text to scan (defaults to reading the most recent LLM response from the stdin pipe, or empty string when no pipe is attached)')).action((options) => {
+        const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const message = options.message ?? '';
+        const result = detectPresenceMarker({ project: projectRoot, latestAssistantMessage: message });
+        printResult(io, ok('skill.detect-marker-loss', result), options.json);
+    });
     const session = program.command('session').description('Manage Peaks session directories');
     addJsonOption(session
         .command('list')
@@ -449,6 +461,21 @@ export function registerCoreAndArtifactCommands(program, io) {
             process.exitCode = 1;
         }
     });
+    addJsonOption(standards
+        .command('migrate')
+        .description('Rewrite a consumer project CLAUDE.md to drop the legacy heartbeat block (slice 028). Dry-run by default; pass --apply to write.')
+        .option('--project <path>', 'target project root')
+        .option('--apply', 'rewrite the legacy block in place; default is dry-run')).action((options) => {
+        const projectRoot = options.project ?? process.cwd();
+        try {
+            const result = migrateStandards({ project: projectRoot, apply: options.apply === true });
+            printResult(io, ok('standards.migrate', result.data, [], result.data.nextActions), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('standards.migrate', 'STANDARDS_MIGRATE_FAILED', getErrorMessage(error), { file: null, foundOldBlock: false, wouldChange: false, applied: false, before: null, after: null, nextActions: [] }, [getErrorMessage(error)]), options.json);
+            process.exitCode = 1;
+        }
+    });
     const memory = program.command('memory').description('Manage project-local Peaks memory');
     addJsonOption(memory
         .command('extract')

package/dist/src/cli/commands/migrate-1-4-1-command.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `peaks workspace migrate-1-4-1` — R004 subcommand.
+ *
+ * Cleanup helper for projects upgraded from 1.4.1 → 1.4.2. Moves per-session
+ * files from the legacy `.peaks/<sid>/<role>/<file>.md` path into the canonical
+ * `.peaks/_runtime/<sid>/<role>/<file>.md` path. Default is dry-run; pass
+ * `--apply` to actually `rename` the files and remove emptied legacy dirs.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerMigrate1_4_1Command(workspace: Command, io: ProgramIO): void;

package/dist/src/cli/commands/migrate-1-4-1-command.js

@@ -0,0 +1,34 @@
+/**
+ * `peaks workspace migrate-1-4-1` — R004 subcommand.
+ *
+ * Cleanup helper for projects upgraded from 1.4.1 → 1.4.2. Moves per-session
+ * files from the legacy `.peaks/<sid>/<role>/<file>.md` path into the canonical
+ * `.peaks/_runtime/<sid>/<role>/<file>.md` path. Default is dry-run; pass
+ * `--apply` to actually `rename` the files and remove emptied legacy dirs.
+ */
+import { ok, fail } from '../../shared/result.js';
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { addJsonOption } from '../cli-helpers.js';
+import { planMigrate1_4_1, applyMigrate1_4_1 } from '../../services/workspace/migrate-1-4-1-service.js';
+export function registerMigrate1_4_1Command(workspace, io) {
+    addJsonOption(workspace
+        .command('migrate-1-4-1')
+        .description('R004: Move per-session files from the legacy `.peaks/<sid>/<role>/<file>.md` path into the canonical `.peaks/_runtime/<sid>/<role>/<file>.md` path. ' +
+        'Default: dry-run. Pass --apply to actually `rename` the files and remove emptied legacy dirs. ' +
+        'Reads each file once, computes sha256, compares to canonical. Identical-content duplicates are removed from legacy. Content-mismatch files are reported and NOT deleted (manual review).')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--apply', 'actually rename the files and remove empty legacy dirs (destructive); without it, dry-run only', false)).action(async (options) => {
+        try {
+            const projectRoot = resolveCanonicalProjectRoot(options.project);
+            const apply = options.apply === true;
+            const result = apply ? applyMigrate1_4_1(projectRoot) : planMigrate1_4_1(projectRoot);
+            const envelope = ok('workspace.migrate-1-4-1', result);
+            io.stdout(`${JSON.stringify(envelope, null, 2)}\n`);
+        }
+        catch (err) {
+            const envelope = fail('workspace.migrate-1-4-1', 'MIGRATE_FAILED', err.message, null, ['Run with --apply to attempt the move (default is dry-run only)']);
+            io.stdout(`${JSON.stringify(envelope, null, 2)}\n`);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/src/cli/commands/skill-context-stats-command.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `peaks skill context-stats` — R003.2
+ *
+ * Reports the per-project skill context footprint for the LLM:
+ *   - Total bytes of allowed skills (full SKILL.md)
+ *   - Total bytes of denied skills (shadow stubs in the project-local mirror)
+ *   - Estimated token counts (chars/4 for full skills, bytes*0.25 for stubs)
+ *   - Shadow-stub reduction percentage vs. the original full SKILL.md bytes
+ *
+ * If no scope is applied (no `.peaks/scope/skills.json`), returns the
+ * "no-scope" branch with a recommended command.
+ */
+import { type ResultEnvelope } from '../../shared/result.js';
+export interface RunContextStatsInput {
+    readonly projectRoot: string;
+    readonly json: boolean;
+    /** Average bytes-per-skill estimate for denied skills without a real SKILL.md (default 7000). */
+    readonly estimatedDeniedOriginalBytes?: number;
+}
+export interface ContextStatsData {
+    readonly scope: unknown;
+    readonly totals: {
+        readonly allowedCount: number;
+        readonly deniedCount: number;
+        readonly allowedBytes: number;
+        readonly stubBytes: number;
+        readonly originalDeniedBytes: number;
+        readonly shadowReductionPct: number;
+        readonly totalBytes: number;
+    };
+    readonly estimatedTokens: {
+        readonly allowed: number;
+        readonly denied: number;
+        readonly total: number;
+    };
+    readonly message?: string;
+    readonly recommendedCommand?: string;
+    readonly human?: string;
+}
+export declare function runContextStats(input: RunContextStatsInput): Promise<ResultEnvelope<ContextStatsData>>;

package/dist/src/cli/commands/skill-context-stats-command.js

@@ -0,0 +1,96 @@
+/**
+ * `peaks skill context-stats` — R003.2
+ *
+ * Reports the per-project skill context footprint for the LLM:
+ *   - Total bytes of allowed skills (full SKILL.md)
+ *   - Total bytes of denied skills (shadow stubs in the project-local mirror)
+ *   - Estimated token counts (chars/4 for full skills, bytes*0.25 for stubs)
+ *   - Shadow-stub reduction percentage vs. the original full SKILL.md bytes
+ *
+ * If no scope is applied (no `.peaks/scope/skills.json`), returns the
+ * "no-scope" branch with a recommended command.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { ok, fail } from '../../shared/result.js';
+export async function runContextStats(input) {
+    const projectRoot = input.projectRoot;
+    const scopePath = join(projectRoot, '.peaks', 'scope', 'skills.json');
+    if (!existsSync(scopePath)) {
+        const noScopeData = {
+            scope: null,
+            totals: {
+                allowedCount: 0,
+                deniedCount: 0,
+                allowedBytes: 0,
+                stubBytes: 0,
+                originalDeniedBytes: 0,
+                shadowReductionPct: 0,
+                totalBytes: 0,
+            },
+            estimatedTokens: { allowed: 0, denied: 0, total: 0 },
+            message: 'No scope applied. Run `peaks skill scope --apply --loose` to enable the skill whitelist for this project.',
+            recommendedCommand: 'peaks skill scope --apply --loose',
+        };
+        return fail('skill.context-stats', 'NO_SCOPE', 'No scope applied to this project.', noScopeData);
+    }
+    const raw = JSON.parse(readFileSync(scopePath, 'utf8'));
+    const allowlist = raw.allowlist;
+    const denied = [];
+    // Walk .claude/skills/ to find shadow stubs (denied skills not in allowlist).
+    const skillsMirror = join(projectRoot, '.claude', 'skills');
+    let stubBytes = 0;
+    let originalDeniedBytes = 0;
+    const estimatedDeniedOriginalBytes = input.estimatedDeniedOriginalBytes ?? 7000;
+    if (existsSync(skillsMirror)) {
+        for (const entry of readdirSync(skillsMirror)) {
+            const skillMd = join(skillsMirror, entry, 'SKILL.md');
+            if (!existsSync(skillMd))
+                continue;
+            if (allowlist.includes(entry))
+                continue; // allowed skills are NOT in the mirror
+            denied.push(entry);
+            const stat = statSync(skillMd);
+            stubBytes += stat.size;
+            // Heuristic: a denied skill would have loaded its full body (~7000 bytes) without shadow-fallback.
+            // We use this as the "original" to compute the reduction.
+            originalDeniedBytes += estimatedDeniedOriginalBytes;
+        }
+    }
+    // For allowed skills, compute the sum of their original SKILL.md bytes from the global catalog.
+    // We don't know the global catalog path here; estimate at 364 KB / 44 = 8272 bytes per allowed skill.
+    const allowedBytes = allowlist.length * 8272; // matches the R002 measurement
+    const totalBytes = allowedBytes + stubBytes;
+    const shadowReductionPct = originalDeniedBytes > 0 ? 1 - stubBytes / originalDeniedBytes : 0;
+    // Token estimation: chars / 4 for full skills; bytes * 0.25 for stubs (YAML is denser).
+    const allowedTokens = Math.round(allowedBytes / 4);
+    const deniedTokens = Math.round(stubBytes * 0.25);
+    const totalTokens = allowedTokens + deniedTokens;
+    const totals = {
+        allowedCount: allowlist.length,
+        deniedCount: denied.length,
+        allowedBytes,
+        stubBytes,
+        originalDeniedBytes,
+        shadowReductionPct,
+        totalBytes,
+    };
+    const estimatedTokens = {
+        allowed: allowedTokens,
+        denied: deniedTokens,
+        total: totalTokens,
+    };
+    const data = {
+        scope: raw,
+        totals,
+        estimatedTokens,
+    };
+    if (!input.json) {
+        data.human = [
+            `Allowed: ${allowlist.length} skills, ${(allowedBytes / 1024).toFixed(1)} KB / ${(allowedTokens / 1000).toFixed(1)}K tokens.`,
+            `Denied: ${denied.length} skills, ${(stubBytes / 1024).toFixed(1)} KB / ${(deniedTokens / 1000).toFixed(1)}K tokens (${(shadowReductionPct * 100).toFixed(1)}% shadow-stub reduction).`,
+            `Total: ${(totalBytes / 1024).toFixed(1)} KB / ${(totalTokens / 1000).toFixed(1)}K tokens.`,
+        ].join('\n');
+    }
+    return ok('skill.context-stats', data);
+}

package/dist/src/cli/commands/skill-scope-commands.d.ts

@@ -0,0 +1,51 @@
+/**
+ * `peaks skill scope` CLI surface (slice 025.1).
+ *
+ * Four subcommands (mutually exclusive):
+ * - `--detect` — dry-run; prints the relevance matrix, never touches files.
+ * - `--apply`  — writes the source-of-truth + IDE-native config.
+ * - `--show`   — reads the source-of-truth + native config back.
+ * - `--reset`  — removes the source-of-truth + IDE-native config.
+ *
+ * Exit code matrix (tech-doc §6.3):
+ *   0  success
+ *   1  uncaught error
+ *   2  invalid usage (missing/incompatible flags)
+ *   3  source-of-truth written but adapter returned NOT_SUPPORTED
+ *   4  adapter failure other than NOT_SUPPORTED
+ */
+import { Command } from 'commander';
+import { type ResultEnvelope } from '../../shared/result.js';
+import { type ProgramIO } from '../cli-helpers.js';
+export type SkillScopeAction = 'detect' | 'apply' | 'show' | 'reset';
+export interface RunSkillScopeInput {
+    readonly subcommand: SkillScopeAction;
+    readonly project: string;
+    readonly strict?: boolean;
+    readonly loose?: boolean;
+    readonly ide?: string;
+    readonly shadowFallback?: boolean;
+    readonly json?: boolean;
+    /** Test seam: override the detected allowlist (CLI re-adds peaks-* per G6). */
+    readonly overrideAllowlist?: readonly string[];
+    /** Test seam: force the source-of-truth write to fail (simulates atomicity test). */
+    readonly simulateSourceOfTruthWriteFailure?: boolean;
+}
+export interface RunSkillScopeResult {
+    readonly exitCode: number;
+    readonly envelope: ResultEnvelope<unknown> | null;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/** Run the --apply subcommand. R003.3: `runApply` is exported for direct testing. */
+export declare function runApply(input: RunSkillScopeInput): Promise<RunSkillScopeResult>;
+/**
+ * Programmatic entry point for `peaks skill scope`. Used by the CLI shim
+ * AND by the unit tests.
+ */
+export declare function runSkillScopeCommand(input: RunSkillScopeInput): Promise<RunSkillScopeResult>;
+/**
+ * Register the `peaks skill scope` subcommand on the `skill` command group.
+ * Mutually-exclusive flags: exactly one of --detect / --apply / --show / --reset.
+ */
+export declare function registerSkillScopeCommands(program: Command, io: ProgramIO): void;

package/dist/src/cli/commands/skill-scope-commands.js

@@ -0,0 +1,310 @@
+/**
+ * `peaks skill scope` CLI surface (slice 025.1).
+ *
+ * Four subcommands (mutually exclusive):
+ * - `--detect` — dry-run; prints the relevance matrix, never touches files.
+ * - `--apply`  — writes the source-of-truth + IDE-native config.
+ * - `--show`   — reads the source-of-truth + native config back.
+ * - `--reset`  — removes the source-of-truth + IDE-native config.
+ *
+ * Exit code matrix (tech-doc §6.3):
+ *   0  success
+ *   1  uncaught error
+ *   2  invalid usage (missing/incompatible flags)
+ *   3  source-of-truth written but adapter returned NOT_SUPPORTED
+ *   4  adapter failure other than NOT_SUPPORTED
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { detectSkillScope, } from '../../services/skill-scope/detect.js';
+import { resolveActiveAdapter, getScopeAdapter } from '../../services/skill-scope/registry.js';
+import { ideCompanionFilePath, readIdeCompanion, readSourceOfTruth, removeIfExists, scopeFilePath, writeSourceOfTruth, } from '../../services/skill-scope/source-of-truth.js';
+import { ALWAYS_RELEVANT_SKILLS } from '../../services/skill-scope/types.js';
+import { fail, getErrorMessage, ok } from '../../shared/result.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+const VALID_ACTIONS = ['detect', 'apply', 'show', 'reset'];
+const VALID_IDES = ['claude-code', 'trae', 'codex', 'cursor', 'qoder', 'tongyi-lingma'];
+function isValidIde(value) {
+    return VALID_IDES.includes(value);
+}
+/**
+ * G6: enforce the peaks-* allowlist. Re-adds any peak-* skill that is
+ * missing from the allowlist, and removes any peak-* skill from the
+ * denylist. The list is the same one declared in `types.ts`.
+ */
+function enforcePeaksAllowlist(allowlist) {
+    const set = new Set(allowlist);
+    for (const name of ALWAYS_RELEVANT_SKILLS) {
+        if (name.startsWith('peaks-'))
+            set.add(name);
+    }
+    return [...set];
+}
+function stripPeaksFromDenylist(denylist) {
+    return denylist.filter((name) => !name.startsWith('peaks-'));
+}
+/**
+ * Determine the IDE. Caller-supplied `--ide` wins; otherwise the registry
+ * probes the project root.
+ */
+async function resolveIde(projectRoot, override) {
+    if (override !== undefined) {
+        if (!isValidIde(override)) {
+            throw new Error(`Unknown IDE: ${override}. Valid: ${VALID_IDES.join(', ')}`);
+        }
+        return { ide: override, isFallback: false };
+    }
+    const resolved = await resolveActiveAdapter(projectRoot);
+    return { ide: resolved.adapter.ide, isFallback: resolved.isFallback };
+}
+/**
+ * Stable timestamp (no millisecond jitter) for the `generatedAt` field.
+ * `Date.now()` would still be deterministic per-run; we keep the natural
+ * one to ensure `generatedAt` matches what the user sees on disk.
+ */
+function nowIso() {
+    return new Date().toISOString();
+}
+/** Run the --detect subcommand. */
+async function runDetect(input) {
+    try {
+        const result = await detectSkillScope({ projectRoot: input.project });
+        const envelope = ok('skill.scope.detect', result);
+        const stdout = input.json === true ? JSON.stringify(envelope, null, 2) : JSON.stringify(result, null, 2);
+        return { exitCode: 0, envelope, stdout, stderr: '' };
+    }
+    catch (error) {
+        const envelope = fail('skill.scope.detect', 'DETECT_FAILED', getErrorMessage(error), null);
+        return { exitCode: 1, envelope, stdout: '', stderr: envelope.message ?? 'detect failed' };
+    }
+}
+/** Build the final ScopeConfig (applies G6 enforcement + override). */
+function buildScopeConfig(args) {
+    const strict = args.strict;
+    const detected = args.detected;
+    // Build allowlist from detected.relevant + (in loose) borderline.
+    const allowFromDetect = detected.skills
+        .filter((s) => s.relevance === 'relevant' || (!strict && s.relevance === 'borderline'))
+        .map((s) => s.name);
+    const merged = args.allowOverride !== undefined ? [...args.allowOverride, ...allowFromDetect] : allowFromDetect;
+    const enforced = enforcePeaksAllowlist(merged);
+    // Denylist: irrelevant skills (strict + loose both), minus anything in allowlist.
+    const denyFromDetect = detected.skills
+        .filter((s) => s.relevance === 'irrelevant' && !enforced.includes(s.name))
+        .map((s) => s.name);
+    const finalDeny = stripPeaksFromDenylist(denyFromDetect);
+    return {
+        generatedAt: nowIso(),
+        ide: args.ide,
+        strict,
+        allowlist: enforced,
+        denylist: finalDeny,
+        skills: detected.skills,
+        signals: detected.projectSignals,
+    };
+}
+/** Run the --apply subcommand. R003.3: `runApply` is exported for direct testing. */
+export async function runApply(input) {
+    // 1. Detect the scope.
+    const detected = await detectSkillScope({ projectRoot: input.project });
+    // --strict wins when both flags are passed. Default is --loose per PRD.
+    const isStrict = input.strict === true && input.loose !== true;
+    const loose = !isStrict;
+    const { ide, isFallback } = await resolveIde(input.project, input.ide);
+    const adapter = getScopeAdapter(ide);
+    const config = buildScopeConfig({
+        ide,
+        strict: isStrict,
+        detected,
+        ...(input.overrideAllowlist !== undefined ? { allowOverride: input.overrideAllowlist } : {}),
+    });
+    // 2. Write the source-of-truth first (atomic). Test seam: simulate failure.
+    let writtenFiles = [];
+    let sourceWritten = false;
+    try {
+        if (input.simulateSourceOfTruthWriteFailure) {
+            throw new Error('simulated source-of-truth write failure');
+        }
+        const file = await writeSourceOfTruth(input.project, config);
+        writtenFiles.push(file);
+        sourceWritten = true;
+    }
+    catch (error) {
+        const envelope = fail('skill.scope.apply', 'WRITE_FAILED', getErrorMessage(error), { ide, sourceWritten: false }, ['Fix filesystem permissions on the project root and retry']);
+        return { exitCode: 4, envelope, stdout: '', stderr: envelope.message ?? 'write failed' };
+    }
+    // 3. Call the adapter. Stub adapters return notSupported=true; we surface it.
+    const adapterInput = {
+        allowlist: config.allowlist,
+        denylist: config.denylist,
+        strict: config.strict,
+        projectRoot: input.project,
+        sourceConfig: config,
+        // R003.3: default to shadow-fallback=true. Pass `shadowFallback: false` (or the
+        // new --no-shadow-fallback CLI flag) to opt out and copy the full SKILL.md.
+        shadowFallback: input.shadowFallback !== false,
+    };
+    let result;
+    try {
+        result = await adapter.applyScope(adapterInput);
+    }
+    catch (error) {
+        // Roll back the source-of-truth on adapter failure.
+        await removeIfExists(scopeFilePath(input.project));
+        const envelope = fail('skill.scope.apply', 'ADAPTER_FAILED', getErrorMessage(error), { ide, sourceWritten: false, writtenFiles: [] }, ['Inspect the adapter error and retry']);
+        return { exitCode: 4, envelope, stdout: '', stderr: envelope.message ?? 'adapter failed' };
+    }
+    // The stub adapter also writes the canonical skills.json — that's
+    // already on disk from step 2, so its second write is a no-op update.
+    const finalWrittenFiles = [...writtenFiles, ...result.writtenFiles];
+    const envelope = ok('skill.scope.apply', {
+        ide,
+        isFallback,
+        strict: isStrict,
+        loose,
+        allowlist: config.allowlist,
+        denylist: config.denylist,
+        signals: config.signals,
+        writtenFiles: finalWrittenFiles,
+        usedShadowStub: result.usedShadowStub,
+        notSupported: result.notSupported,
+        strippedFromDenylist: result.strippedFromDenylist ?? [],
+        error: result.error,
+    });
+    const stdout = input.json === true ? JSON.stringify(envelope, null, 2) : JSON.stringify(envelope.data, null, 2);
+    if (result.notSupported) {
+        // Stub adapter: NOT_SUPPORTED → exit 3, write error to stderr.
+        const stderr = `${result.error?.code ?? 'NOT_SUPPORTED'}: ${result.error?.message ?? 'not supported'}`;
+        return { exitCode: 3, envelope, stdout, stderr };
+    }
+    return { exitCode: 0, envelope, stdout, stderr: '' };
+}
+/** Run the --show subcommand. */
+async function runShow(input) {
+    const source = await readSourceOfTruth(input.project);
+    const { ide } = await resolveIde(input.project, input.ide);
+    const companionPath = ideCompanionFilePath(input.project, ide);
+    const companion = await readIdeCompanion(input.project, ide);
+    // For Claude Code, the native config is `.claude/settings.local.json`.
+    const nativeSettingsPath = join(input.project, '.claude', 'settings.local.json');
+    const nativeExists = existsSync(nativeSettingsPath);
+    let native = companion;
+    if (nativeExists) {
+        try {
+            const { readFile } = await import('node:fs/promises');
+            native = JSON.parse(await readFile(nativeSettingsPath, 'utf8'));
+        }
+        catch {
+            native = null;
+        }
+    }
+    const data = {
+        ide,
+        source,
+        native,
+        nativeSettingsPath: nativeExists ? '.claude/settings.local.json' : null,
+        companionPath: existsSync(companionPath) ? companionPath : null,
+    };
+    const envelope = ok('skill.scope.show', data);
+    const stdout = input.json === true ? JSON.stringify(envelope, null, 2) : JSON.stringify(data, null, 2);
+    return { exitCode: 0, envelope, stdout, stderr: '' };
+}
+/** Run the --reset subcommand. */
+async function runReset(input) {
+    const { ide } = await resolveIde(input.project, input.ide);
+    const adapter = getScopeAdapter(ide);
+    const resetResult = await adapter.resetScope({ projectRoot: input.project });
+    const sourceFile = scopeFilePath(input.project);
+    const sourceRemoved = await removeIfExists(sourceFile);
+    const allRemoved = [...resetResult.removedFiles, ...(sourceRemoved ? [sourceFile] : [])];
+    const envelope = ok('skill.scope.reset', {
+        ide,
+        removedFiles: allRemoved,
+    });
+    // Always include the canonical source-of-truth path in the human-readable
+    // summary, even if it didn't exist (so the user knows what was targeted).
+    const displayFiles = allRemoved.length > 0 ? allRemoved : [sourceFile, join(input.project, '.claude', 'settings.local.json')];
+    const summary = `removed: ${displayFiles.join(', ')}`;
+    const stdout = input.json === true ? JSON.stringify(envelope, null, 2) : summary;
+    return { exitCode: 0, envelope, stdout, stderr: '' };
+}
+/**
+ * Programmatic entry point for `peaks skill scope`. Used by the CLI shim
+ * AND by the unit tests.
+ */
+export async function runSkillScopeCommand(input) {
+    if (!VALID_ACTIONS.includes(input.subcommand)) {
+        const envelope = fail('skill.scope', 'INVALID_USAGE', `Unknown action: ${input.subcommand}`, null);
+        return { exitCode: 2, envelope, stdout: '', stderr: envelope.message ?? 'invalid usage' };
+    }
+    switch (input.subcommand) {
+        case 'detect': return runDetect(input);
+        case 'apply': return runApply(input);
+        case 'show': return runShow(input);
+        case 'reset': return runReset(input);
+    }
+}
+/**
+ * Register the `peaks skill scope` subcommand on the `skill` command group.
+ * Mutually-exclusive flags: exactly one of --detect / --apply / --show / --reset.
+ */
+export function registerSkillScopeCommands(program, io) {
+    // Find the existing 'skill' subcommand if any.
+    let skillCmd = program.commands.find((c) => c.name() === 'skill');
+    if (skillCmd === undefined) {
+        skillCmd = program.command('skill').description('Manage Peaks skills');
+    }
+    const scope = skillCmd
+        .command('scope')
+        .description('Per-project skill scoping: detect, apply, show, reset');
+    addJsonOption(scope
+        .option('--detect', 'dry-run: print the relevance matrix')
+        .option('--apply', 'apply the scope (writes source-of-truth + IDE config)')
+        .option('--show', 'show the currently applied scope')
+        .option('--reset', 'remove the scope config')
+        .option('--project <path>', 'target project root (defaults to cwd)', process.cwd())
+        .option('--strict', '--apply: only `relevant` skills in the allowlist')
+        .option('--loose', '--apply: `relevant` + `borderline` in the allowlist (default)')
+        .option('--ide <name>', 'force a specific IDE adapter (overrides auto-detect)')
+        // R003.3: --shadow-fallback is the new default. Pass --no-shadow-fallback
+        // to opt out (copy the full SKILL.md to .claude/skills/ for IDE-side inspection).
+        .option('--shadow-fallback', '--apply: Claude Code uses shadow stubs for the denylist (default)')
+        .option('--no-shadow-fallback', '--apply: copy the full SKILL.md for the denylist (opt out of shadowing)')).action(async (options) => {
+        const flags = [options.detect, options.apply, options.show, options.reset].filter(Boolean).length;
+        if (flags !== 1) {
+            const envelope = fail('skill.scope', 'INVALID_USAGE', 'Exactly one of --detect / --apply / --show / --reset is required', null, ['Pass exactly one action flag']);
+            printResult(io, envelope, options.json === true);
+            process.exitCode = 2;
+            return;
+        }
+        const subcommand = options.detect
+            ? 'detect'
+            : options.apply
+                ? 'apply'
+                : options.show
+                    ? 'show'
+                    : 'reset';
+        const result = await runSkillScopeCommand({
+            subcommand,
+            project: options.project ?? process.cwd(),
+            ...(options.strict !== undefined ? { strict: options.strict } : {}),
+            ...(options.loose !== undefined ? { loose: options.loose } : {}),
+            ...(options.ide !== undefined ? { ide: options.ide } : {}),
+            ...(options.shadowFallback !== undefined ? { shadowFallback: options.shadowFallback } : {}),
+            ...(options.json !== undefined ? { json: options.json } : {}),
+        });
+        if (options.json === true) {
+            if (result.envelope !== null)
+                printResult(io, result.envelope, true);
+        }
+        else {
+            if (result.stdout.length > 0)
+                io.stdout(result.stdout);
+            if (result.stderr.length > 0)
+                io.stderr(result.stderr);
+        }
+        if (result.exitCode !== 0) {
+            process.exitCode = result.exitCode;
+        }
+    });
+}