peaks-cli 1.4.0 → 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/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

@@ -37,6 +37,8 @@ export interface RunSkillScopeResult {
     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.

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

@@ -103,8 +103,8 @@ function buildScopeConfig(args) {
         signals: detected.projectSignals,
     };
 }
-/** Run the --apply subcommand. */
-async function runApply(input) {
+/** 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.
@@ -140,7 +140,9 @@ async function runApply(input) {
         strict: config.strict,
         projectRoot: input.project,
         sourceConfig: config,
-        shadowFallback: input.shadowFallback === true,
+        // 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 {
@@ -264,7 +266,10 @@ export function registerSkillScopeCommands(program, io) {
         .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)')
-        .option('--shadow-fallback', '--apply: Claude Code uses shadow stubs for the denylist')).action(async (options) => {
+        // 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']);

package/dist/src/cli/commands/workspace-commands.js

@@ -4,6 +4,7 @@ import { createInterface } from 'node:readline';
 import { initWorkspace, InvalidSessionIdError, ConflictingSessionError } from '../../services/workspace/workspace-service.js';
 import { reconcileWorkspace } from '../../services/workspace/reconcile-service.js';
 import { migrateWorkspace } from '../../services/workspace/migrate-service.js';
+import { registerMigrate1_4_1Command } from './migrate-1-4-1-command.js';
 import { ensureSessionWithRotation } from '../../services/session/session-manager.js';
 import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
 import { applyHookInstall, readHookStatus } from '../../services/skills/hooks-settings-service.js';
@@ -398,6 +399,13 @@ export function registerWorkspaceCommands(program, io) {
             process.exitCode = 1;
         }
     });
+    // R004: subcommand to physically move per-session files from the legacy
+    // `.peaks/<sid>/<role>/<file>.md` path to the canonical
+    // `.peaks/_runtime/<sid>/<role>/<file>.md` path. The 2-tier fallback in
+    // artifact-prerequisites.ts accepts either location, so this command is
+    // purely a UX / filesystem-cleanup helper — the functional behavior is
+    // already correct without it.
+    registerMigrate1_4_1Command(workspace, io);
 }
 /**
  * Resolve the first-time "install peaks hooks" decision for this project.

package/dist/src/services/skill-scope/detect.d.ts

@@ -16,9 +16,15 @@
 import type { ProjectSignals, SkillKind, SkillScopeCounts, SkillScopeRecord } from './types.js';
 /**
  * Walk `src/` (recursively) AND the project root, collecting the top-50
- * unique file extensions. Sorted lexicographically.
+ * unique file extensions (sorted lexicographically) AND the per-extension
+ * file count (used by R003.1 to compute fractional share).
  */
-export declare function scanFileTree(projectRoot: string, maxExtensions?: number): string[];
+export interface ScanResult {
+    readonly extensions: readonly string[];
+    readonly counts: Readonly<Record<string, number>>;
+    readonly totalFiles: number;
+}
+export declare function scanFileTree(projectRoot: string, maxExtensions?: number): ScanResult;
 /**
  * Build the `ProjectSignals` object from the project root.
  */

package/dist/src/services/skill-scope/detect.js

@@ -16,7 +16,7 @@
 import { existsSync, readdirSync, statSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { ALWAYS_RELEVANT_SKILLS, NON_TS_SKILL_PREFIXES, TRACKED_EXTENSIONS, } from './types.js';
+import { ALWAYS_RELEVANT_SKILLS, NON_TS_SKILL_PREFIXES, TRACKED_EXTENSIONS, readScopeThreshold, } from './types.js';
 function hasAnyDep(pkg, names) {
     const all = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
     return names.some((name) => Object.prototype.hasOwnProperty.call(all, name));
@@ -52,16 +52,12 @@ function asTsConfig(value) {
         return null;
     return value;
 }
-/**
- * Walk `src/` (recursively) AND the project root, collecting the top-50
- * unique file extensions. Sorted lexicographically.
- */
 export function scanFileTree(projectRoot, maxExtensions = 50) {
     const roots = [];
     if (existsSync(join(projectRoot, 'src')))
         roots.push(join(projectRoot, 'src'));
     roots.push(projectRoot);
-    const exts = new Set();
+    const counts = {};
     // Bound the walk: at most 2000 files, 5 levels deep.
     let visited = 0;
     const MAX_FILES = 2000;
@@ -100,14 +96,13 @@ export function scanFileTree(projectRoot, maxExtensions = 50) {
                     if (dot < 0)
                         continue;
                     const ext = name.slice(dot).toLowerCase();
-                    exts.add(ext);
-                    if (exts.size >= maxExtensions)
-                        break;
+                    counts[ext] = (counts[ext] ?? 0) + 1;
                 }
             }
         }
     }
-    return [...exts].sort().slice(0, maxExtensions);
+    const extensions = Object.keys(counts).sort().slice(0, maxExtensions);
+    return { extensions, counts, totalFiles: visited };
 }
 function hasExt(exts, ext) {
     return exts.includes(ext);
@@ -155,12 +150,20 @@ export async function extractProjectSignals(projectRoot) {
     const isHeadroom = pkg !== null && (hasAnyDep(pkg, ['headroom-ai']) ||
         Object.keys({ ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) }).some((k) => k.startsWith('@headroom/')));
     const nodeEngineMajor = parseNodeEngineMajor(pkg?.engines?.node);
-    const topExtensions = scanFileTree(projectRoot);
-    // Build the per-extension presence flag map.
+    const scan = scanFileTree(projectRoot);
+    const topExtensions = scan.extensions;
+    // Build the per-extension presence flag map (R003.1: kept for backwards-compat).
     const hasFileExtension = {};
     for (const ext of TRACKED_EXTENSIONS) {
         hasFileExtension[ext.slice(1)] = hasExt(topExtensions, ext);
     }
+    // Build the per-extension fractional share map (R003.1).
+    const shareByExtension = {};
+    if (scan.totalFiles > 0) {
+        for (const [ext, count] of Object.entries(scan.counts)) {
+            shareByExtension[ext.slice(1)] = count / scan.totalFiles;
+        }
+    }
     return {
         hasPackageJson,
         isTypeScript,
@@ -185,6 +188,7 @@ export async function extractProjectSignals(projectRoot) {
         nodeEngineMajor,
         topExtensions,
         hasFileExtension,
+        shareByExtension,
     };
 }
 /**
@@ -232,10 +236,24 @@ export function classifySkill(skill, signals, rules) {
     const desc = skill.description.toLowerCase();
     // Special-case: when the project is a non-TS project (Python, etc.),
     // language-specific skills with matching keywords should be relevant.
+    // R003.1: gate this on the language's fractional share >= threshold,
+    // so a 1-file stray `.cpp` does not flip cpp-coding-standards to relevant.
     if (isNonTsProject(signals)) {
         const langMatch = languageKeywordMatch(desc);
         if (langMatch !== null) {
-            reasons.push(`${langMatch} keyword + non-TS project`);
+            const ext = LANGUAGE_TO_EXTENSION[langMatch];
+            const share = ext === undefined ? 1 : (signals.shareByExtension?.[ext] ?? 0);
+            const threshold = readScopeThreshold();
+            if (share < threshold) {
+                reasons.push(`${langMatch} keyword but share ${(share * 100).toFixed(1)}% < threshold ${(threshold * 100).toFixed(0)}%`);
+                return {
+                    name: skill.name,
+                    kind: inferSkillKind(skill.name, rules.alwaysRelevant),
+                    relevance: 'irrelevant',
+                    reasons,
+                };
+            }
+            reasons.push(`${langMatch} keyword + non-TS project (share ${(share * 100).toFixed(1)}%)`);
             return {
                 name: skill.name,
                 kind: inferSkillKind(skill.name, rules.alwaysRelevant),
@@ -354,6 +372,21 @@ function languageKeywordMatch(description) {
         return 'cpp';
     return null;
 }
+/**
+ * R003.1: map a non-TS language keyword to its primary file extension
+ * (used to look up the fractional share from `signals.shareByExtension`).
+ */
+const LANGUAGE_TO_EXTENSION = {
+    python: 'py',
+    kotlin: 'kt',
+    java: 'java',
+    rust: 'rs',
+    go: 'go',
+    ruby: 'rb',
+    swift: 'swift',
+    csharp: 'cs',
+    cpp: 'cpp',
+};
 /**
  * Multi-language project heuristic: if the project's file tree contains
  * extensions matching a non-TS language, OR the project is a Python project,

package/dist/src/services/skill-scope/types.d.ts

@@ -65,7 +65,26 @@ export interface ProjectSignals {
     readonly topExtensions: readonly string[];
     /** Per-extension presence flags derived from topExtensions. */
     readonly hasFileExtension: Readonly<Record<string, boolean>>;
+    /**
+     * Per-extension fractional share (file count / total files, in [0, 1]).
+     * Slice 025 / R003.1: replaces the binary `hasFileExtension` for the
+     * keyword-matching path. A language/framework skill becomes `relevant`
+     * only when its corresponding share is >= the configured threshold
+     * (default 0.05). Extensions with 0 files are absent.
+     */
+    readonly shareByExtension: Readonly<Record<string, number>>;
 }
+/**
+ * Default threshold for the share-based relevance check (R003.1).
+ * Override at runtime with `PEAKS_SCOPE_THRESHOLD=0.05` (env) or
+ * `--threshold 0.05` (CLI).
+ */
+export declare const SCOPE_THRESHOLD_DEFAULT = 0.05;
+/**
+ * Read the threshold from `PEAKS_SCOPE_THRESHOLD` env var, clamped to
+ * [0, 1]. Falls back to SCOPE_THRESHOLD_DEFAULT.
+ */
+export declare function readScopeThreshold(): number;
 /** The shape of the always-written source-of-truth file. */
 export interface ScopeConfig {
     /** ISO-8601 UTC timestamp at which this scope was last applied. */

package/dist/src/services/skill-scope/types.js

@@ -13,6 +13,29 @@
  * - Errors are typed (NotSupportedError / ScopeApplyError), not strings.
  *   The CLI maps `ScopeApplyError.code` to exit codes (see tech-doc §6.3).
  */
+/**
+ * Default threshold for the share-based relevance check (R003.1).
+ * Override at runtime with `PEAKS_SCOPE_THRESHOLD=0.05` (env) or
+ * `--threshold 0.05` (CLI).
+ */
+export const SCOPE_THRESHOLD_DEFAULT = 0.05;
+/**
+ * Read the threshold from `PEAKS_SCOPE_THRESHOLD` env var, clamped to
+ * [0, 1]. Falls back to SCOPE_THRESHOLD_DEFAULT.
+ */
+export function readScopeThreshold() {
+    const raw = process.env['PEAKS_SCOPE_THRESHOLD'];
+    if (raw === undefined || raw === '')
+        return SCOPE_THRESHOLD_DEFAULT;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed))
+        return SCOPE_THRESHOLD_DEFAULT;
+    if (parsed < 0)
+        return 0;
+    if (parsed > 1)
+        return 1;
+    return parsed;
+}
 /** Sentinel error type for stub adapters (G3). */
 export class NotSupportedError extends Error {
     code = 'NOT_SUPPORTED';

package/dist/src/services/workspace/migrate-1-4-1-service.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `peaks workspace migrate-1-4-1` — R004.
+ *
+ * Cleanup command for projects upgraded from peaks-cli 1.4.1 → 1.4.2.
+ *
+ * Slice 006 (1.4.0) moved the canonical per-session root to
+ * `.peaks/_runtime/<sid>/`. Per-request artifacts (PRD, RD, QA, SC requests)
+ * were written to the new root, but per-session artifacts (tech-doc.md,
+ * code-review.md, test-cases/<rid>.md, etc.) were kept at the legacy
+ * `.peaks/<sid>/<role>/<file>.md` path. The 2-tier fallback in
+ * `resolvePrerequisiteAbsolutePathWithFallback` accepts either location, so
+ * the functional behavior is correct, but the user's filesystem has visible
+ * dual-path duplication ("飘逸" — the user's term for the UX).
+ *
+ * R004 ships this command to physically move the legacy per-session files
+ * into the canonical `_runtime/<sid>/<role>/` location. After this runs,
+ * the project has a single canonical tree; the legacy `<sid>/<role>/`
+ * directories are removed (only if empty after the move).
+ *
+ * Default: dry-run. Pass `--apply` to actually move.
+ */
+export declare const PER_SESSION_ARTIFACT_TYPES: readonly ["rd/tech-doc.md", "rd/code-review.md", "rd/security-review.md", "rd/perf-baseline.md", "rd/bug-analysis.md", "qa/security-findings.md", "qa/performance-findings.md"];
+export declare const PER_REQUEST_ARTIFACT_TYPES: readonly ["qa/test-cases/<rid>.md", "qa/test-reports/<rid>.md"];
+export type MigrationPlanEntry = {
+    readonly sessionId: string;
+    readonly relativePath: string;
+    readonly from: string;
+    readonly to: string;
+    readonly sha256: string;
+    readonly reason: 'legacy-only' | 'identical-content-already-canonical' | 'content-mismatch' | 'no-legacy-file';
+};
+export type MigrationResult = {
+    readonly plan: ReadonlyArray<MigrationPlanEntry>;
+    readonly applied: boolean;
+    readonly movedCount: number;
+    readonly conflictCount: number;
+    readonly deletedEmptyDirs: ReadonlyArray<string>;
+    readonly errors: ReadonlyArray<{
+        path: string;
+        message: string;
+    }>;
+};
+export declare function planMigrate1_4_1(projectRoot: string): MigrationResult;
+export declare function applyMigrate1_4_1(projectRoot: string): MigrationResult;

package/dist/src/services/workspace/migrate-1-4-1-service.js

@@ -0,0 +1,195 @@
+/**
+ * `peaks workspace migrate-1-4-1` — R004.
+ *
+ * Cleanup command for projects upgraded from peaks-cli 1.4.1 → 1.4.2.
+ *
+ * Slice 006 (1.4.0) moved the canonical per-session root to
+ * `.peaks/_runtime/<sid>/`. Per-request artifacts (PRD, RD, QA, SC requests)
+ * were written to the new root, but per-session artifacts (tech-doc.md,
+ * code-review.md, test-cases/<rid>.md, etc.) were kept at the legacy
+ * `.peaks/<sid>/<role>/<file>.md` path. The 2-tier fallback in
+ * `resolvePrerequisiteAbsolutePathWithFallback` accepts either location, so
+ * the functional behavior is correct, but the user's filesystem has visible
+ * dual-path duplication ("飘逸" — the user's term for the UX).
+ *
+ * R004 ships this command to physically move the legacy per-session files
+ * into the canonical `_runtime/<sid>/<role>/` location. After this runs,
+ * the project has a single canonical tree; the legacy `<sid>/<role>/`
+ * directories are removed (only if empty after the move).
+ *
+ * Default: dry-run. Pass `--apply` to actually move.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+export const PER_SESSION_ARTIFACT_TYPES = [
+    'rd/tech-doc.md',
+    'rd/code-review.md',
+    'rd/security-review.md',
+    'rd/perf-baseline.md',
+    'rd/bug-analysis.md',
+    'qa/security-findings.md',
+    'qa/performance-findings.md',
+];
+export const PER_REQUEST_ARTIFACT_TYPES = [
+    'qa/test-cases/<rid>.md',
+    'qa/test-reports/<rid>.md',
+];
+import { createHash } from 'node:crypto';
+function sha256(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+function enumerateLegacySessions(projectRoot) {
+    // Legacy per-session dirs: `.peaks/<sid>/` (NOT `.peaks/_runtime/<sid>/`).
+    // We skip well-known non-session entries.
+    const SKIP = new Set(['memory', 'PROJECT.md', 'retrospective', 'scope', 'skill-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 peaksRoot = join(projectRoot, '.peaks');
+    if (!existsSync(peaksRoot))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(peaksRoot)) {
+        if (SKIP.has(entry))
+            continue;
+        if (entry.startsWith('.'))
+            continue;
+        // Treat any directory under .peaks/ that doesn't match a known non-session
+        // directory as a candidate session id. The session id is a dated prefix.
+        if (entry.match(/^\d{4}-\d{2}-\d{2}-session-/))
+            out.push(entry);
+    }
+    return out;
+}
+function listRequestIdsForSession(legacySessionRoot) {
+    // Per-request artifacts use file id like `001-r001.md`. We scan the
+    // requests dir to find existing rids.
+    const ids = new Set();
+    for (const role of ['prd', 'rd', 'qa', 'sc']) {
+        const dir = join(legacySessionRoot, role, 'requests');
+        if (!existsSync(dir))
+            continue;
+        for (const f of readdirSync(dir)) {
+            const m = f.match(/^\d+-(r\d+)\.md$/);
+            if (m && m[1])
+                ids.add(m[1]);
+        }
+    }
+    return [...ids];
+}
+function buildPlan(projectRoot) {
+    const plan = [];
+    for (const sid of enumerateLegacySessions(projectRoot)) {
+        const legacyRoot = join(projectRoot, '.peaks', sid);
+        const canonicalRoot = join(projectRoot, '.peaks', '_runtime', sid);
+        // Per-session files (no <rid> template).
+        for (const rel of PER_SESSION_ARTIFACT_TYPES) {
+            const from = join(legacyRoot, rel);
+            if (!existsSync(from))
+                continue;
+            const content = readFileSync(from, 'utf8');
+            const hash = sha256(content);
+            const to = join(canonicalRoot, rel);
+            if (existsSync(to)) {
+                const existing = readFileSync(to, 'utf8');
+                if (sha256(existing) === hash) {
+                    plan.push({ sessionId: sid, relativePath: rel, from, to, sha256: hash, reason: 'identical-content-already-canonical' });
+                }
+                else {
+                    plan.push({ sessionId: sid, relativePath: rel, from, to, sha256: hash, reason: 'content-mismatch' });
+                }
+            }
+            else {
+                plan.push({ sessionId: sid, relativePath: rel, from, to, sha256: hash, reason: 'legacy-only' });
+            }
+        }
+        // Per-request files (with <rid> template).
+        const rids = listRequestIdsForSession(legacyRoot);
+        for (const rel of PER_REQUEST_ARTIFACT_TYPES) {
+            for (const rid of rids) {
+                const expanded = rel.replace('<rid>', rid);
+                const from = join(legacyRoot, expanded);
+                if (!existsSync(from))
+                    continue;
+                const content = readFileSync(from, 'utf8');
+                const hash = sha256(content);
+                const to = join(canonicalRoot, expanded);
+                if (existsSync(to)) {
+                    const existing = readFileSync(to, 'utf8');
+                    if (sha256(existing) === hash) {
+                        plan.push({ sessionId: sid, relativePath: expanded, from, to, sha256: hash, reason: 'identical-content-already-canonical' });
+                    }
+                    else {
+                        plan.push({ sessionId: sid, relativePath: expanded, from, to, sha256: hash, reason: 'content-mismatch' });
+                    }
+                }
+                else {
+                    plan.push({ sessionId: sid, relativePath: expanded, from, to, sha256: hash, reason: 'legacy-only' });
+                }
+            }
+        }
+    }
+    return plan;
+}
+export function planMigrate1_4_1(projectRoot) {
+    const plan = buildPlan(projectRoot);
+    return {
+        plan,
+        applied: false,
+        movedCount: 0,
+        conflictCount: plan.filter((p) => p.reason === 'content-mismatch').length,
+        deletedEmptyDirs: [],
+        errors: [],
+    };
+}
+export function applyMigrate1_4_1(projectRoot) {
+    const plan = buildPlan(projectRoot);
+    const errors = [];
+    let movedCount = 0;
+    const deletedEmptyDirs = [];
+    const movedFiles = [];
+    for (const entry of plan) {
+        try {
+            if (entry.reason === 'legacy-only') {
+                // Move: ensure target dir exists, then rename.
+                mkdirSync(join(entry.to, '..'), { recursive: true });
+                renameSync(entry.from, entry.to);
+                movedFiles.push(entry.from);
+                movedCount++;
+            }
+            else if (entry.reason === 'identical-content-already-canonical') {
+                // Skip the move but delete the duplicate source.
+                try {
+                    rmSync(entry.from);
+                }
+                catch { /* best-effort */ }
+            }
+            else if (entry.reason === 'content-mismatch') {
+                // Conflict: do NOT delete the source. Mark for manual review.
+                errors.push({ path: entry.from, message: `content mismatch; review manually (target ${entry.to})` });
+            }
+        }
+        catch (err) {
+            errors.push({ path: entry.from, message: err.message });
+        }
+    }
+    // After all moves, clean up legacy session dirs. They're now empty
+    // (all files moved; per-role subdirs are also empty). Force-remove the
+    // entire tree — if any non-empty dir remains it's a pre-existing file
+    // that wasn't part of the migrate plan, which is fine to keep.
+    for (const sid of new Set(plan.map((p) => p.sessionId))) {
+        const legacyRoot = join(projectRoot, '.peaks', sid);
+        try {
+            if (existsSync(legacyRoot)) {
+                rmSync(legacyRoot, { recursive: true, force: true });
+                deletedEmptyDirs.push(legacyRoot);
+            }
+        }
+        catch { /* best-effort */ }
+    }
+    return {
+        plan,
+        applied: true,
+        movedCount,
+        conflictCount: plan.filter((p) => p.reason === 'content-mismatch').length,
+        deletedEmptyDirs,
+        errors,
+    };
+}

package/dist/src/shared/version.d.ts

@@ -1 +1 @@
-export declare const CLI_VERSION = "1.4.0";
+export declare const CLI_VERSION = "1.4.1";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "1.4.0";
+export const CLI_VERSION = "1.4.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "Cross-AI-IDE workflow-gating CLI + skill family (Claude Code shipped, Trae in progress; Codex / Cursor / Qoder / Tongyi Lingma on the roadmap).",
   "author": "SquabbyZ",
   "license": "MIT",