peaks-cli 1.3.8 → 1.4.0

package/dist/src/services/retrospective/retrospective-show.d.ts

@@ -0,0 +1,40 @@
+/**
+ * retrospective-show — load one retrospective entry by id, synthesize the
+ * body on-demand from `artifactPaths` (concatenate with `---` separator),
+ * apply `formatMdCompact` by default, return the JSON envelope.
+ *
+ * Slice 023 (R3). The on-disk MD form is gone after the G9 migration; the
+ * body is re-hydrated from the source PRD / RD / QA / TXT artifacts. If
+ * a referenced artifact is missing on disk, `show` returns a
+ * `ARTIFACT_MISSING` envelope (PRD R3) and does not crash.
+ *
+ * Stale policy is **not** applied to retrospective in this slice
+ * (per PRD G7 / R3 scope). The helper exists for a future slice.
+ */
+import { loadRetrospectiveIndex, type RetrospectiveEntry, type RetrospectiveIndexResult } from './retrospective-index.js';
+export type RetrospectiveFormat = 'compact' | 'pretty';
+export interface RetrospectiveShowOptions {
+    projectRoot: string;
+    id: string;
+    format?: RetrospectiveFormat;
+}
+export interface RetrospectiveShowSuccess {
+    ok: true;
+    projectRoot: string;
+    format: RetrospectiveFormat;
+    entry: RetrospectiveEntry;
+    body: string;
+    warnings: string[];
+}
+export interface RetrospectiveShowError {
+    ok: false;
+    code: 'NOT_FOUND' | 'INDEX_MISSING' | 'ARTIFACT_MISSING' | 'INVALID_REQUEST';
+    message: string;
+    hint?: string;
+    projectRoot: string;
+    missingArtifacts?: string[];
+}
+export type RetrospectiveShowResult = RetrospectiveShowSuccess | RetrospectiveShowError;
+export declare function showRetrospective(options: RetrospectiveShowOptions): RetrospectiveShowResult;
+export { loadRetrospectiveIndex };
+export type { RetrospectiveEntry, RetrospectiveIndexResult };

package/dist/src/services/retrospective/retrospective-show.js

@@ -0,0 +1,109 @@
+/**
+ * retrospective-show — load one retrospective entry by id, synthesize the
+ * body on-demand from `artifactPaths` (concatenate with `---` separator),
+ * apply `formatMdCompact` by default, return the JSON envelope.
+ *
+ * Slice 023 (R3). The on-disk MD form is gone after the G9 migration; the
+ * body is re-hydrated from the source PRD / RD / QA / TXT artifacts. If
+ * a referenced artifact is missing on disk, `show` returns a
+ * `ARTIFACT_MISSING` envelope (PRD R3) and does not crash.
+ *
+ * Stale policy is **not** applied to retrospective in this slice
+ * (per PRD G7 / R3 scope). The helper exists for a future slice.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { formatMdCompact } from '../../shared/format-md-compact.js';
+import { loadRetrospectiveIndex } from './retrospective-index.js';
+export function showRetrospective(options) {
+    if (typeof options.id !== 'string' || options.id.trim().length === 0) {
+        return {
+            ok: false,
+            code: 'INVALID_REQUEST',
+            message: 'retrospective show requires a non-empty <id> argument',
+            projectRoot: resolve(options.projectRoot)
+        };
+    }
+    const resolvedRoot = resolve(options.projectRoot);
+    const index = loadRetrospectiveIndex(resolvedRoot);
+    if (index.source === null) {
+        return {
+            ok: false,
+            code: 'INDEX_MISSING',
+            message: index.warning ?? `retrospective index not found at ${index.indexPath}`,
+            hint: 'run `peaks retrospective migrate --apply` to build the index',
+            projectRoot: resolvedRoot
+        };
+    }
+    const entry = index.entries.find((e) => e.id === options.id);
+    if (entry === undefined) {
+        return {
+            ok: false,
+            code: 'NOT_FOUND',
+            message: `retrospective entry not found: ${options.id}`,
+            hint: 'run `peaks retrospective index --json` to see available ids',
+            projectRoot: resolvedRoot
+        };
+    }
+    const format = options.format ?? 'compact';
+    const synthesis = synthesizeBody(entry, resolvedRoot);
+    const body = format === 'pretty' ? synthesis.body : formatMdCompact(synthesis.body);
+    const warnings = synthesis.warnings;
+    return {
+        ok: true,
+        projectRoot: resolvedRoot,
+        format,
+        entry,
+        body,
+        warnings
+    };
+}
+function synthesizeBody(entry, projectRoot) {
+    if (entry.artifactPaths.length === 0) {
+        return { body: renderEntryHeader(entry), warnings: ['entry has no artifactPaths; body is the index summary only'] };
+    }
+    const sections = [];
+    const warnings = [];
+    for (const relativePath of entry.artifactPaths) {
+        const absolutePath = join(projectRoot, relativePath);
+        if (!existsSync(absolutePath)) {
+            warnings.push(`artifact missing on disk: ${relativePath}`);
+            continue;
+        }
+        try {
+            const content = readFileSync(absolutePath, 'utf8');
+            sections.push(`## ${relativePath}\n\n${content}`);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            warnings.push(`failed to read ${relativePath}: ${message}`);
+        }
+    }
+    const header = renderEntryHeader(entry);
+    const body = sections.length === 0
+        ? `${header}\n\n_No artifacts available; only the index summary is shown._`
+        : `${header}\n\n${sections.join('\n\n---\n\n')}`;
+    return { body, warnings };
+}
+function renderEntryHeader(entry) {
+    const lines = [
+        `# ${entry.title}`,
+        '',
+        `- id: ${entry.id}`,
+        `- session: ${entry.sessionId}`,
+        ...(entry.sliceId !== undefined ? [`- slice: ${entry.sliceId}`] : []),
+        `- type: ${entry.type}`,
+        `- outcome: ${entry.outcome}`,
+        `- updatedAt: ${entry.updatedAt}`,
+        `- lessonsLearned: ${entry.lessonsLearned}`,
+        ''
+    ];
+    if (entry.keyDecisions.length > 0) {
+        lines.push('## Key Decisions', '', ...entry.keyDecisions.map((decision) => `- ${decision}`), '');
+    }
+    if (entry.summary.length > 0) {
+        lines.push('## Summary', '', entry.summary, '');
+    }
+    return lines.join('\n');
+}
+export { loadRetrospectiveIndex };

package/dist/src/services/skill-scope/adapters/_stub-helper.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared `makeStubAdapter` helper for the 5 non-shipped IDEs (Trae, Cursor,
+ * Codex, Qoder, Tongyi Lingma).
+ *
+ * Each stub adapter:
+ * 1. Implements `SkillScopeAdapter` with `supported: false`.
+ * 2. In `applyScope`, ALWAYS writes the companion source-of-truth
+ *    `.peaks/scope/<ide>-skills.json` first, then returns a NOT_SUPPORTED
+ *    ApplyResult (the test contract asserts the source-of-truth is on disk
+ *    even when the adapter can't apply it natively).
+ * 3. In `showScope`, reads from the companion source-of-truth file.
+ * 4. In `resetScope`, removes the companion source-of-truth file.
+ * 5. In `detect`, returns 0.0 (the stub does not actually probe).
+ *
+ * The TODO comment in each stub file points at the follow-up slice (025.2+).
+ */
+import type { SkillScopeAdapter } from '../types.js';
+/**
+ * IDE-id -> companion source-of-truth shape. The companion file is a
+ * parallel record so the user can see "this is what would have applied"
+ * even when the IDE doesn't support a real implementation.
+ */
+export interface StubSourceOfTruth {
+    readonly ide: string;
+    readonly generatedAt: string;
+    readonly strict: boolean;
+    readonly allowlist: readonly string[];
+    readonly denylist: readonly string[];
+    readonly todoRef: string;
+    readonly notes: string;
+}
+/**
+ * The factory: every stub is a thin wrapper around this function. The
+ * `applyScope` implementation ALWAYS writes the source-of-truth, then
+ * returns a NOT_SUPPORTED ApplyResult (NOT a thrown error — the contract
+ * for stub adapters is "return ok:false, notSupported:true" so the CLI
+ * can keep going and surface the error to the user).
+ */
+export declare function makeStubAdapter(ide: SkillScopeAdapter['ide'], todoRef: string, displayName: string): SkillScopeAdapter;

package/dist/src/services/skill-scope/adapters/_stub-helper.js

@@ -0,0 +1,98 @@
+/**
+ * Shared `makeStubAdapter` helper for the 5 non-shipped IDEs (Trae, Cursor,
+ * Codex, Qoder, Tongyi Lingma).
+ *
+ * Each stub adapter:
+ * 1. Implements `SkillScopeAdapter` with `supported: false`.
+ * 2. In `applyScope`, ALWAYS writes the companion source-of-truth
+ *    `.peaks/scope/<ide>-skills.json` first, then returns a NOT_SUPPORTED
+ *    ApplyResult (the test contract asserts the source-of-truth is on disk
+ *    even when the adapter can't apply it natively).
+ * 3. In `showScope`, reads from the companion source-of-truth file.
+ * 4. In `resetScope`, removes the companion source-of-truth file.
+ * 5. In `detect`, returns 0.0 (the stub does not actually probe).
+ *
+ * The TODO comment in each stub file points at the follow-up slice (025.2+).
+ */
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { ideCompanionFilePath, removeIfExists, scopeFilePath, writeJsonAtomic } from '../source-of-truth.js';
+async function writeStubCompanion(ide, input, todoRef) {
+    const file = ideCompanionFilePath(input.projectRoot, ide);
+    const data = {
+        ide,
+        generatedAt: input.sourceConfig.generatedAt,
+        strict: input.strict,
+        allowlist: input.allowlist,
+        denylist: input.denylist,
+        todoRef,
+        notes: `Stub source-of-truth for ${ide}. The real config format has not yet been researched. ` +
+            `This file is written so the user's intent is captured and can be ported when ` +
+            `the follow-up slice (${todoRef}) lands.`,
+    };
+    await writeJsonAtomic(file, data);
+    return file;
+}
+async function readStubCompanion(ide, projectRoot) {
+    const file = ideCompanionFilePath(projectRoot, ide);
+    if (!existsSync(file))
+        return null;
+    try {
+        return JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The factory: every stub is a thin wrapper around this function. The
+ * `applyScope` implementation ALWAYS writes the source-of-truth, then
+ * returns a NOT_SUPPORTED ApplyResult (NOT a thrown error — the contract
+ * for stub adapters is "return ok:false, notSupported:true" so the CLI
+ * can keep going and surface the error to the user).
+ */
+export function makeStubAdapter(ide, todoRef, displayName) {
+    const ideStr = String(ide);
+    return {
+        ide,
+        supported: false,
+        async detect() {
+            // Stubs never "win" detection; they return 0.0 so the registry falls
+            // back to the shipped adapter (Claude Code).
+            return 0.0;
+        },
+        async applyScope(input) {
+            // 1. Always write the source-of-truth first.
+            const companion = await writeStubCompanion(ideStr, input, todoRef);
+            // 2. Always write the canonical .peaks/scope/skills.json too.
+            const canonical = scopeFilePath(input.projectRoot);
+            await writeJsonAtomic(canonical, input.sourceConfig);
+            // 3. Surface NOT_SUPPORTED with a clear, IDE-named message.
+            const message = `${displayName} (${ideStr}) config format not yet researched — ${todoRef} follow-up. ` +
+                `Source-of-truth written to ${companion}.`;
+            return {
+                ide,
+                ok: false,
+                writtenFiles: [companion, canonical],
+                usedShadowStub: false,
+                notSupported: true,
+                error: { code: 'NOT_SUPPORTED', message },
+            };
+        },
+        async showScope(projectRoot) {
+            const native = await readStubCompanion(ideStr, projectRoot);
+            return { source: null, native, ide };
+        },
+        async resetScope(input) {
+            const removed = [];
+            const companion = ideCompanionFilePath(input.projectRoot, ideStr);
+            if (await removeIfExists(companion))
+                removed.push(companion);
+            // Also remove the canonical source-of-truth on reset.
+            const canonical = scopeFilePath(input.projectRoot);
+            if (await removeIfExists(canonical))
+                removed.push(canonical);
+            return { ide, removedFiles: removed };
+        },
+    };
+}

package/dist/src/services/skill-scope/adapters/claude-code.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `peaks skill scope` — Claude Code adapter (full impl, slice 025.1).
+ *
+ * Strategy (tech-doc-025 §3):
+ * 1. PRIMARY: write `.claude/settings.local.json` with
+ *    `permissions.allow: ["Skill(name)", ...]` + `permissions.deny: [...]`.
+ * 2. FALLBACK (R1, `--shadow-fallback`): when the runtime probe determines
+ *    Claude Code rejects `Skill(name)` in `permissions.deny`, write a
+ *    shadow stub at `.claude/skills/<name>/SKILL.md` for each denylisted
+ *    skill. Tagged with `_peaks_scope_disabled: true` (R6).
+ *
+ * Idempotency: dedupe the allow/deny arrays; shadow-stub writes skip
+ * when the marker is already present. AC11.
+ */
+import type { ApplyResult, ApplyScopeInput, ResetScopeInput, ResetScopeResult, ShowScopeResult, SkillScopeAdapter } from '../types.js';
+/** Format the `Skill(name)` string Claude Code's permission system uses. */
+export declare function skillRef(name: string): string;
+interface ClaudePermissions {
+    readonly allow: string[];
+    readonly deny: string[];
+}
+interface ClaudeSettings {
+    readonly permissions: ClaudePermissions;
+    readonly [key: string]: unknown;
+}
+/**
+ * Map allowlist/denylist → permissions.allow/permissions.deny. Never sorts;
+ * preserves input order. Always dedupes.
+ */
+export declare function toPermissions(allowlist: readonly string[], denylist: readonly string[]): ClaudeSettings;
+/**
+ * Strip any peaks-* name from the denylist (G6 hard constraint). Returns
+ * the cleaned denylist + the list of stripped names for the audit log.
+ */
+export declare function stripPeaksFromDenylist(denylist: readonly string[]): {
+    readonly cleaned: readonly string[];
+    readonly stripped: readonly string[];
+};
+/**
+ * Runtime probe for whether Claude Code supports `Skill(name)` syntax in
+ * `permissions.deny` (R1). For slice 025.1 we return `unknown` and let
+ * the caller decide. Replace this with a real check when Claude Code's
+ * `permissions.deny` schema is documented.
+ */
+export declare function probeSkillDenySupport(): Promise<'support-allow-and-deny' | 'support-allow-only' | 'unknown'>;
+export declare class ClaudeCodeSkillScope implements SkillScopeAdapter {
+    readonly ide: "claude-code";
+    readonly supported = true;
+    constructor(_opts?: {
+        readonly projectRoot?: string;
+    });
+    /** detect(): returns 1.0 when the project root has a .claude/ dir. */
+    detect(projectRoot: string): Promise<number>;
+    applyScope(input: ApplyScopeInput): Promise<ApplyResult>;
+    showScope(projectRoot: string): Promise<ShowScopeResult>;
+    resetScope(input: ResetScopeInput): Promise<ResetScopeResult>;
+}
+export declare const CLAUDE_CODE_SKILL_SCOPE: SkillScopeAdapter;
+export {};

package/dist/src/services/skill-scope/adapters/claude-code.js

@@ -0,0 +1,304 @@
+/**
+ * `peaks skill scope` — Claude Code adapter (full impl, slice 025.1).
+ *
+ * Strategy (tech-doc-025 §3):
+ * 1. PRIMARY: write `.claude/settings.local.json` with
+ *    `permissions.allow: ["Skill(name)", ...]` + `permissions.deny: [...]`.
+ * 2. FALLBACK (R1, `--shadow-fallback`): when the runtime probe determines
+ *    Claude Code rejects `Skill(name)` in `permissions.deny`, write a
+ *    shadow stub at `.claude/skills/<name>/SKILL.md` for each denylisted
+ *    skill. Tagged with `_peaks_scope_disabled: true` (R6).
+ *
+ * Idempotency: dedupe the allow/deny arrays; shadow-stub writes skip
+ * when the marker is already present. AC11.
+ */
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+/** Adapter id. */
+const IDE_ID = 'claude-code';
+/** Format the `Skill(name)` string Claude Code's permission system uses. */
+export function skillRef(name) {
+    return `Skill(${name})`;
+}
+/** Dedupe a list preserving the first-seen order. */
+function dedupe(list) {
+    const seen = new Set();
+    const out = [];
+    for (const item of list) {
+        if (!seen.has(item)) {
+            seen.add(item);
+            out.push(item);
+        }
+    }
+    return out;
+}
+const EMPTY_SETTINGS = { permissions: { allow: [], deny: [] } };
+/**
+ * Read the existing `.claude/settings.local.json` (returns empty settings
+ * if the file does not exist). On parse failure returns empty settings
+ * and a warning rather than throwing — the user can still write fresh
+ * settings.
+ */
+async function readSettingsLocal(projectRoot) {
+    const file = join(projectRoot, '.claude', 'settings.local.json');
+    if (!existsSync(file))
+        return { settings: EMPTY_SETTINGS, existed: false, malformed: false };
+    try {
+        const raw = await readFile(file, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== 'object') {
+            return { settings: EMPTY_SETTINGS, existed: true, malformed: true };
+        }
+        const obj = parsed;
+        const permsRaw = obj.permissions;
+        const perms = permsRaw !== null && typeof permsRaw === 'object'
+            ? {
+                allow: Array.isArray(permsRaw.allow)
+                    ? permsRaw.allow
+                    : [],
+                deny: Array.isArray(permsRaw.deny)
+                    ? permsRaw.deny
+                    : [],
+            }
+            : { allow: [], deny: [] };
+        return { settings: { ...obj, permissions: perms }, existed: true, malformed: false };
+    }
+    catch {
+        return { settings: EMPTY_SETTINGS, existed: true, malformed: true };
+    }
+}
+/**
+ * Write the JSON file atomically via `.peaks-tmp` + `rename`. Removes the
+ * temp file on partial failure.
+ */
+async function writeJsonAtomic(file, data) {
+    await mkdir(dirname(file), { recursive: true });
+    const tmp = `${file}.peaks-tmp`;
+    try {
+        await writeFile(tmp, JSON.stringify(data, null, 2) + '\n', 'utf8');
+        await rename(tmp, file);
+    }
+    catch (error) {
+        if (existsSync(tmp)) {
+            try {
+                await rm(tmp, { force: true });
+            }
+            catch { /* best-effort */ }
+        }
+        throw error;
+    }
+}
+/**
+ * Map allowlist/denylist → permissions.allow/permissions.deny. Never sorts;
+ * preserves input order. Always dedupes.
+ */
+export function toPermissions(allowlist, denylist) {
+    return {
+        permissions: {
+            allow: dedupe(allowlist.map(skillRef)),
+            deny: dedupe(denylist.map(skillRef)),
+        },
+    };
+}
+/**
+ * Strip any peaks-* name from the denylist (G6 hard constraint). Returns
+ * the cleaned denylist + the list of stripped names for the audit log.
+ */
+export function stripPeaksFromDenylist(denylist) {
+    const cleaned = [];
+    const stripped = [];
+    for (const name of denylist) {
+        if (name.startsWith('peaks-')) {
+            stripped.push(name);
+        }
+        else {
+            cleaned.push(name);
+        }
+    }
+    return { cleaned, stripped };
+}
+/** Render the shadow-stub SKILL.md body (R6 marker). */
+function shadowStubBody(name) {
+    return `---
+name: ${name}
+description: _peaks_scope_disabled
+_peaks_scope_disabled: true
+---
+# Disabled by \`peaks skill scope --apply\`
+
+This skill is shadowed because the project has marked it as out of scope.
+To restore, run \`peaks skill scope --reset\` or edit \`.peaks/scope/skills.json\`.
+`;
+}
+async function writeShadowStub(projectRoot, name) {
+    const file = join(projectRoot, '.claude', 'skills', name, 'SKILL.md');
+    await mkdir(dirname(file), { recursive: true });
+    // Skip if already has the marker
+    if (existsSync(file)) {
+        try {
+            const existing = await readFile(file, 'utf8');
+            if (existing.includes('_peaks_scope_disabled: true')) {
+                return file;
+            }
+        }
+        catch { /* fall through and overwrite */ }
+    }
+    await writeFile(file, shadowStubBody(name), 'utf8');
+    return file;
+}
+/**
+ * Runtime probe for whether Claude Code supports `Skill(name)` syntax in
+ * `permissions.deny` (R1). For slice 025.1 we return `unknown` and let
+ * the caller decide. Replace this with a real check when Claude Code's
+ * `permissions.deny` schema is documented.
+ */
+export async function probeSkillDenySupport() {
+    return 'unknown';
+}
+/**
+ * Decision: should the denylist use shadow stubs instead of `permissions.deny`?
+ * Returns true when:
+ * - The caller passes `shadowFallback: true`, OR
+ * - The runtime probe returns `support-allow-only` / `unknown`.
+ */
+async function shouldUseShadowStubs(input) {
+    if (input.shadowFallback)
+        return true;
+    const probe = await probeSkillDenySupport();
+    return probe !== 'support-allow-and-deny';
+}
+/** Strip the peaks-* shadow stubs written by a previous apply. */
+function shadowStubDir(projectRoot, name) {
+    return join(projectRoot, '.claude', 'skills', name, 'SKILL.md');
+}
+async function removeShadowStubIfPresent(projectRoot, name) {
+    const file = shadowStubDir(projectRoot, name);
+    if (!existsSync(file))
+        return false;
+    try {
+        const raw = await readFile(file, 'utf8');
+        if (!raw.includes('_peaks_scope_disabled: true'))
+            return false;
+        await rm(file, { force: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export class ClaudeCodeSkillScope {
+    ide = IDE_ID;
+    supported = true;
+    constructor(_opts) {
+        // projectRoot is supplied on every method call; the class is stateless.
+        void _opts;
+    }
+    /** detect(): returns 1.0 when the project root has a .claude/ dir. */
+    async detect(projectRoot) {
+        return existsSync(join(projectRoot, '.claude')) ? 1.0 : 0.5;
+    }
+    async applyScope(input) {
+        const written = [];
+        const removed = [];
+        // G6: strip peaks-* from the denylist.
+        const { cleaned: cleanedDeny, stripped } = stripPeaksFromDenylist(input.denylist);
+        if (stripped.length > 0) {
+            removed.push(...stripped);
+        }
+        const useShadows = await shouldUseShadowStubs(input);
+        // 1. Write (or skip) settings.local.json
+        const { settings: existing } = await readSettingsLocal(input.projectRoot);
+        const next = toPermissions(input.allowlist, cleanedDeny);
+        // Preserve existing non-permissions fields (theme, env, etc.).
+        const preserved = { ...existing };
+        delete preserved.permissions;
+        // Merge with the user's pre-existing allow/deny entries (deduped).
+        const existingAllow = (existing.permissions.allow ?? []);
+        const existingDeny = (existing.permissions.deny ?? []);
+        const merged = {
+            ...preserved,
+            permissions: {
+                allow: dedupe([...existingAllow, ...next.permissions.allow]),
+                deny: dedupe([...existingDeny, ...next.permissions.deny]),
+            },
+        };
+        if (input.simulateWriteFailure) {
+            throw new Error('simulated write failure (settings.local.json)');
+        }
+        const settingsFile = join(input.projectRoot, '.claude', 'settings.local.json');
+        await writeJsonAtomic(settingsFile, merged);
+        written.push(settingsFile);
+        // 2. Optionally write shadow stubs for the (stripped, cleaned) denylist
+        let usedShadowStub = false;
+        if (useShadows) {
+            usedShadowStub = true;
+            for (const name of cleanedDeny) {
+                const stub = await writeShadowStub(input.projectRoot, name);
+                written.push(stub);
+            }
+        }
+        return {
+            ide: this.ide,
+            ok: true,
+            writtenFiles: written,
+            usedShadowStub,
+            notSupported: false,
+            strippedFromDenylist: stripped,
+        };
+    }
+    async showScope(projectRoot) {
+        const settingsFile = join(projectRoot, '.claude', 'settings.local.json');
+        let native = null;
+        if (existsSync(settingsFile)) {
+            try {
+                native = JSON.parse(await readFile(settingsFile, 'utf8'));
+            }
+            catch {
+                native = null;
+            }
+        }
+        return { source: null, native, ide: this.ide };
+    }
+    async resetScope(input) {
+        const removed = [];
+        const settingsFile = join(input.projectRoot, '.claude', 'settings.local.json');
+        if (existsSync(settingsFile)) {
+            // Only remove if it has a permissions.allow/deny field shaped by us,
+            // otherwise leave the user's hand-curated file alone.
+            try {
+                const raw = await readFile(settingsFile, 'utf8');
+                const parsed = JSON.parse(raw);
+                if (parsed !== null &&
+                    typeof parsed === 'object' &&
+                    parsed.permissions !== undefined) {
+                    await rm(settingsFile, { force: true });
+                    removed.push(settingsFile);
+                }
+            }
+            catch {
+                // best-effort
+            }
+        }
+        // Also remove shadow stubs (we don't know which skills are stubbed, so
+        // we don't blindly walk .claude/skills; the caller can re-run detect +
+        // reset if they need a full sweep). For the explicit case we know
+        // about, we strip any stub whose marker is present.
+        const skillsDir = join(input.projectRoot, '.claude', 'skills');
+        if (existsSync(skillsDir)) {
+            // Best-effort scan: only act when the file is unmistakably a stub.
+            const { readdirSync } = await import('node:fs');
+            const entries = readdirSync(skillsDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                const removedStub = await removeShadowStubIfPresent(input.projectRoot, entry.name);
+                if (removedStub) {
+                    removed.push(join(input.projectRoot, '.claude', 'skills', entry.name, 'SKILL.md'));
+                }
+            }
+        }
+        return { ide: this.ide, removedFiles: removed };
+    }
+}
+export const CLAUDE_CODE_SKILL_SCOPE = new ClaudeCodeSkillScope();

package/dist/src/services/skill-scope/adapters/codex.d.ts

@@ -0,0 +1,2 @@
+import type { SkillScopeAdapter } from '../types.js';
+export declare const CODEX_SKILL_SCOPE: SkillScopeAdapter;

package/dist/src/services/skill-scope/adapters/codex.js

@@ -0,0 +1,12 @@
+// TODO(slice-025.4-codex): research Codex's per-project skill scoping
+// config format. Codex uses `.codex/` for project-local config.
+//
+// Until the real format is known, this stub:
+// 1. Writes `.peaks/scope/codex-skills.json` (source-of-truth) on every
+//    `applyScope` so the user's intent is captured on disk.
+// 2. Returns NOT_SUPPORTED with a clear message pointing at this slice.
+//
+// When implementing, replace the makeStubAdapter call with the real
+// CodexSkillScope class.
+import { makeStubAdapter } from './_stub-helper.js';
+export const CODEX_SKILL_SCOPE = makeStubAdapter('codex', 'slice-025.4-codex', 'Codex');

package/dist/src/services/skill-scope/adapters/cursor.d.ts

@@ -0,0 +1,2 @@
+import type { SkillScopeAdapter } from '../types.js';
+export declare const CURSOR_SKILL_SCOPE: SkillScopeAdapter;