peaks-cli 1.4.1 → 2.0.0

package/skills/peaks-solo/references/step-0-55-1x-detection.md

@@ -0,0 +1,82 @@
+# Step 0.55 — 1.x → 2.0 detection reference
+
+> Body of `### Peaks-Cli Step 0.55`. Slice: 2026-06-12-solo-step-0-55-1x-detection.
+
+## Why this step exists
+
+The peaks-cli 1.x → 2.0 closeout ships:
+
+1. A postinstall that auto-detects 1.x state and dispatches the upgrade (slice 1, commit `b6e34e6`).
+2. A standards-migrate path that thins `.claude/rules/**/*.md` and scaffolds `.peaks/standards/` (slice 2, commit `33dd392`).
+3. **THIS STEP** — a peaks-solo startup sequence probe that detects 1.x state when the user invokes `/peaks-solo` directly in a 1.x consumer project, and prompts the user to upgrade.
+
+The 1.x user experience is: "I just typed /peaks-solo. Why is it not working in 2.0 mode?" Step 0.55 catches this case and surfaces an `AskUserQuestion` with a one-click upgrade.
+
+## Detection algorithm
+
+```bash
+# 1. Read-only probe via the umbrella CLI
+peaks upgrade --detect-1x --project <root> --json
+```
+
+The CLI returns:
+```json
+{
+  "ok": true,
+  "command": "upgrade.detect-1x",
+  "data": {
+    "isOneX": true,
+    "signals": [
+      "<path> has schema_version 1.0.0, expected '2.0.0'",
+      "..."
+    ],
+    "projectRoot": "/path/to/project",
+    "configPath": null
+  },
+  "warnings": [],
+  "nextActions": [
+    "Detected 1.x state. peaks-solo Step 0.55 should present an AskUserQuestion to invoke `peaks upgrade --to 2.0 --auto --project /path/to/project`."
+  ]
+}
+```
+
+The detection logic mirrors `scripts/install-skills.mjs:detect1xProjectState` (canonical implementation) — it walks up to find `.peaks/_runtime/`, then sniffs:
+
+1. `~/.peaks/config.json` for `version: 1.x`
+2. `<projectRoot>/.claude/rules/common/dev-preference.md` for "peaks progress"
+3. `<projectRoot>/.peaks/preferences.json` for missing or non-`2.0.0` `schema_version`
+
+The TS mirror in `src/services/upgrade/1x-detector-service.ts` is the canonical entrypoint for the skill; the postinstall `.mjs` version is the canonical entrypoint for the npm-install flow. The two implementations MUST stay in parity (a parity test is in the slice's test suite).
+
+## AskUserQuestion (only when `isOneX: true`)
+
+| Option | What it does |
+|---|---|
+| Run `peaks upgrade --to 2.0 --auto --project <root>` (Recommended) | Invokes the umbrella. The user sees the 6 sub-step results in the terminal. After the upgrade, re-run peaks-solo with the standing 2.0 layout. Persist `autoUpgradePrompt: opt-in` to `.peaks/preferences.json`. |
+| Skip for this session | Continue with the standing 1.x layout. Persist `autoUpgradePrompt: skip-this-session` to `.peaks/preferences.json`. The next time the user invokes peaks-solo in this project, the question re-asks. |
+| Never ask again for this project | Persist `autoUpgradePrompt: skip-forever` to `.peaks/preferences.json`. Step 0.55 becomes a no-op for this project from now on. The user can re-enable later by removing the `autoUpgradePrompt` key from preferences.json. |
+
+## Persistence contract
+
+The decision is persisted via `peaks preferences set --project <root> --key autoUpgradePrompt --value <opt-in|skip-this-session|skip-forever> --apply`. Subsequent Step 0.55 invocations read the value first:
+
+- If `opt-in` (and Step 0.55 is the first invocation in the session), the user has already opted in; auto-run the umbrella without re-asking.
+- If `skip-this-session`, the user already said no this session; skip without re-asking (but re-ask next session).
+- If `skip-forever`, the user said no permanently; skip without re-asking.
+- If the key is absent, present the AskUserQuestion.
+
+## What is NOT in this step
+
+- The auto-upgrade execution itself: the umbrella is invoked via the AskUserQuestion's recommended option. The umbrella's behavior (6 sub-commands + write-upgrade-record) is documented in the umbrella's own help text.
+- The postinstall auto-dispatch: that's `scripts/install-skills.mjs:autoUpgrade1xProjectIfPresent`, which fires fire-and-forget on `npm i -g peaks-cli@2.0`. Step 0.55 is the user-invoked path.
+- Re-authoring the 1.x detector heuristics: the implementation is a 1:1 mirror of the canonical `.mjs` version. Drift is prevented by the parity test.
+
+## How this integrates with the rest of the workflow
+
+- Step 0.5 (OpenSpec opt-in) — runs first if `openspec/` is missing.
+- Step 0 (anchor) — runs always.
+- Step 0.7 (resume detection) — runs after Step 0.
+- **Step 0.55 (1.x detection) — runs after Step 0.7, only when the project is not on a 2.0 layout.**
+- Step 1 (mode selection) — runs after Step 0.55.
+
+The 1.x detection is intentionally placed AFTER Step 0.7 because the user might already have a 1.x-converted in-flight slice; the resume flow takes precedence over the upgrade prompt.

package/skills/peaks-solo/references/workflow-gates-and-types.md

@@ -102,6 +102,15 @@ ls .peaks/<id>/ui/design-draft.md 2>&1
 
 The CLI gate (`peaks request transition --state qa-handoff`) is the authoritative check; running this `ls` first lets you produce missing files before the CLI rejects the transition.
 
+| Request type | Required RD evidence (under `.peaks/<id>/`) |
+|---|---|
+| `feature` / `refactor` | `rd/tech-doc.md` + `rd/code-review.md` + `rd/security-review.md` + `rd/perf-baseline.md` + `qa/test-cases/<rid>.md` (qa/test-cases pre-drafted by the 4th sub-agent in peaks-rd's parallel fan-out — slice 004) |
+| `bugfix` | `rd/bug-analysis.md` + `rd/code-review.md` + `rd/security-review.md` + `qa/test-cases/<rid>.md` (rd/perf-baseline.md only when the bug is performance-shaped) |
+| `config` | `rd/security-review.md` |
+| `docs` / `chore` | (no extra evidence required) |
+
+Always required (in addition to the type-specific row): `ls .peaks/<id>/rd/requests/<rid>.md`. Missing any required file → DO NOT attempt the qa-handoff transition; CLI will reject with PREREQUISITES_MISSING.
+
 ```bash
 # Always required
 ls .peaks/<id>/rd/requests/<rid>.md

package/dist/src/cli/commands/shadcn-commands.d.ts

@@ -1,3 +0,0 @@
-import { Command } from 'commander';
-import { type ProgramIO } from '../cli-helpers.js';
-export declare function registerShadcnCommands(program: Command, io: ProgramIO): void;

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

@@ -1,35 +0,0 @@
-import { createShadcnInvocation, executeShadcnInvocation } from '../../services/shadcn/shadcn-service.js';
-import { fail } from '../../shared/result.js';
-import { getErrorMessage, printResult, redactSensitiveErrorMessage } from '../cli-helpers.js';
-function printShadcnFailure(io, error, exitCode = 1) {
-    printResult(io, fail('shadcn', 'SHADCN_COMMAND_FAILED', redactSensitiveErrorMessage(getErrorMessage(error)), {}, ['Check the shadcn command arguments before retrying']), false);
-    process.exitCode = exitCode;
-}
-async function runShadcnCommand(io, args) {
-    try {
-        const invocation = createShadcnInvocation({ args });
-        const result = await executeShadcnInvocation(invocation);
-        const didFail = result.exitCode !== null && result.exitCode !== 0;
-        if (result.stdout.length > 0) {
-            io.stdout((didFail ? redactSensitiveErrorMessage(result.stdout) : result.stdout).trimEnd());
-        }
-        if (result.stderr.length > 0) {
-            io.stderr((didFail ? redactSensitiveErrorMessage(result.stderr) : result.stderr).trimEnd());
-        }
-        if (didFail) {
-            process.exitCode = result.exitCode;
-        }
-    }
-    catch (error) {
-        printShadcnFailure(io, error);
-    }
-}
-export function registerShadcnCommands(program, io) {
-    program
-        .command('shadcn')
-        .description('Run the pinned shadcn CLI bundled with Peaks')
-        .allowUnknownOption(true)
-        .helpOption(false)
-        .argument('<args...>', 'arguments forwarded to shadcn')
-        .action((args) => runShadcnCommand(io, args));
-}

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

@@ -1,40 +0,0 @@
-/**
- * `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

@@ -1,96 +0,0 @@
-/**
- * `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

@@ -1,51 +0,0 @@
-/**
- * `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

@@ -1,310 +0,0 @@
-/**
- * `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;
-        }
-    });
-}

package/dist/src/services/shadcn/shadcn-service.d.ts

@@ -1,27 +0,0 @@
-declare const SHADCN_PACKAGE_NAME = "shadcn";
-declare const SHADCN_PACKAGE_VERSION = "4.7.0";
-declare const SHADCN_EXECUTABLE: string;
-export type ShadcnInvocationOptions = {
-    args: string[];
-    cwd?: string;
-};
-export type ShadcnInvocation = {
-    executable: typeof SHADCN_EXECUTABLE;
-    args: string[];
-    cwd: string;
-    packageName: typeof SHADCN_PACKAGE_NAME;
-    packageVersion: typeof SHADCN_PACKAGE_VERSION;
-};
-export type ShadcnExecutionResult = {
-    exitCode: number | null;
-    stdout: string;
-    stderr: string;
-};
-export type ShadcnProcessRunner = (invocation: ShadcnInvocation) => Promise<ShadcnExecutionResult>;
-declare function createShadcnEnvironment(sourceEnv?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
-export declare function createShadcnInvocation(options: ShadcnInvocationOptions): ShadcnInvocation;
-export declare function executeShadcnInvocation(invocation: ShadcnInvocation, runner?: ShadcnProcessRunner): Promise<ShadcnExecutionResult>;
-export declare const testInternals: {
-    createShadcnEnvironment: typeof createShadcnEnvironment;
-};
-export {};