peaks-cli 1.3.9 → 1.4.1

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

@@ -329,7 +329,7 @@ export function registerWorkflowCommands(program, io) {
             process.exitCode = exitOk;
         }
         catch (error) {
-            printResult(io, fail('workflow.verify-pipeline', 'VERIFY_FAILED', getErrorMessage(error), {}, ['Check that --project and --rid are correct; --change-id is optional (resolved from the artifact otherwise)']), options.json);
+            printResult(io, fail('workflow.verify-pipeline', 'VERIFY_FAILED', getErrorMessage(error), { acceptedForm: 'none', gateC: 'fail' }, ['Check that --project and --rid are correct; --change-id is optional (resolved from the artifact otherwise)']), options.json);
             process.exitCode = 1;
         }
     });

package/dist/src/cli/commands/workflow-plan-commands.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `peaks workflow plan <read|refresh|detect-trigger>` — slice 025 CLI.
+ *
+ * Three subcommands under the existing `peaks workflow` verb:
+ * - `read <security|perf> --project <repo> --json`
+ * - `refresh <security|perf> --project <repo> [--apply] --json`
+ * - `detect-trigger --project <repo> --rid <rid> [--refresh] --json`
+ *
+ * CLI justification (per dev-preference rules):
+ * - `read`           (2) JSON-gated — slice workflow reads plan hash.
+ * - `refresh`        (3) destructive write needs explicit `--apply`.
+ * - `detect-trigger` (2) JSON-gated — slice workflow needs the verdict.
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+declare function runPlanRead(io: ProgramIO, options: {
+    type: string;
+    project?: string;
+    sessionId?: string;
+    json?: boolean;
+}): void;
+declare function runPlanRefresh(io: ProgramIO, options: {
+    type: string;
+    project?: string;
+    sessionId?: string;
+    apply?: boolean;
+    json?: boolean;
+}): void;
+declare function runPlanDetectTrigger(io: ProgramIO, options: {
+    project?: string;
+    rid?: string;
+    sessionId?: string;
+    refresh?: boolean;
+    json?: boolean;
+}): void;
+export declare function registerWorkflowPlanCommands(program: Command, io: ProgramIO): void;
+export { runPlanRead as _runPlanRead };
+export { runPlanRefresh as _runPlanRefresh };
+export { runPlanDetectTrigger as _runPlanDetectTrigger };

package/dist/src/cli/commands/workflow-plan-commands.js

@@ -0,0 +1,163 @@
+import { fail, getErrorMessage } from '../../shared/result.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { readPlan } from '../../services/workflow/plan-reader.js';
+import { refreshPlan } from '../../services/workflow/plan-refresher.js';
+import { detectTrigger } from '../../services/workflow/plan-trigger-detector.js';
+import { getSessionId } from '../../services/session/session-manager.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+const VALID_TYPES = ['security', 'perf'];
+// F-1 (slice 025 security): reject session ids that look like path
+// traversal payloads. Canonical pattern is YYYY-MM-DD-<slug>.
+const SESSION_ID_PATTERN = /^\d{4}-\d{2}-\d{2}-[a-z][a-z0-9-]*[a-z0-9]$/;
+// F-1 (slice 025 security): reject rids that contain path separators,
+// null bytes, or traversal sequences.
+const REQUEST_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function isPlanType(value) {
+    return VALID_TYPES.includes(value);
+}
+function isValidSessionId(value) {
+    return SESSION_ID_PATTERN.test(value);
+}
+function isValidRequestId(value) {
+    return REQUEST_ID_PATTERN.test(value);
+}
+function resolveSessionId(io, command, projectRoot, explicit, asJson) {
+    if (explicit !== undefined && explicit.length > 0) {
+        if (!isValidSessionId(explicit)) {
+            printResult(io, fail(command, 'INVALID_SESSION_ID', 'session id must match YYYY-MM-DD-slug pattern', { sessionId: explicit }, ['Use --session-id <YYYY-MM-DD-slug>']), asJson === true);
+            process.exitCode = 1;
+            return null;
+        }
+        return explicit;
+    }
+    const sid = getSessionId(projectRoot);
+    if (sid === null || sid === undefined) {
+        printResult(io, fail(command, 'NO_ACTIVE_SESSION', 'No active session — pass --session-id explicitly or run peaks workspace init', { projectRoot }, ['Run peaks workspace init or pass --session-id <YYYY-MM-DD-slug>']), asJson === true);
+        process.exitCode = 1;
+        return null;
+    }
+    // Defensive: even active-session resolution must satisfy the pattern.
+    if (!isValidSessionId(sid)) {
+        printResult(io, fail(command, 'INVALID_SESSION_ID', 'session id must match YYYY-MM-DD-slug pattern', { sessionId: sid }, ['Use --session-id <YYYY-MM-DD-slug>']), asJson === true);
+        process.exitCode = 1;
+        return null;
+    }
+    return sid;
+}
+function resolveProjectRoot(projectArg) {
+    if (projectArg === undefined || projectArg === '') {
+        return findProjectRoot(process.cwd()) ?? process.cwd();
+    }
+    return projectArg;
+}
+function runPlanRead(io, options) {
+    if (!isPlanType(options.type)) {
+        printResult(io, fail('workflow.plan.read', 'INVALID_TYPE', `Unsupported plan type: ${options.type}`, { supportedTypes: VALID_TYPES }, ['Use --type security or --type perf']), options.json === true);
+        process.exitCode = 1;
+        return;
+    }
+    const projectRoot = resolveProjectRoot(options.project);
+    const sessionId = resolveSessionId(io, 'workflow.plan.read', projectRoot, options.sessionId, options.json);
+    if (sessionId === null)
+        return;
+    try {
+        const result = readPlan({ type: options.type, project: projectRoot, sessionId });
+        printResult(io, result, options.json === true);
+    }
+    catch (error) {
+        printResult(io, fail('workflow.plan.read', 'READ_FAILED', getErrorMessage(error), null, ['Check that --project is a valid repo root with a peaks session']), options.json === true);
+        process.exitCode = 1;
+    }
+}
+function runPlanRefresh(io, options) {
+    if (!isPlanType(options.type)) {
+        printResult(io, fail('workflow.plan.refresh', 'INVALID_TYPE', `Unsupported plan type: ${options.type}`, { supportedTypes: VALID_TYPES }, ['Use --type security or --type perf']), options.json === true);
+        process.exitCode = 1;
+        return;
+    }
+    const projectRoot = resolveProjectRoot(options.project);
+    const sessionId = resolveSessionId(io, 'workflow.plan.refresh', projectRoot, options.sessionId, options.json);
+    if (sessionId === null)
+        return;
+    try {
+        const result = refreshPlan({
+            type: options.type,
+            project: projectRoot,
+            sessionId,
+            apply: options.apply === true
+        });
+        printResult(io, result, options.json === true);
+    }
+    catch (error) {
+        printResult(io, fail('workflow.plan.refresh', 'REFRESH_FAILED', getErrorMessage(error), null, ['Check that --project is a valid repo root and the session exists']), options.json === true);
+        process.exitCode = 1;
+    }
+}
+function runPlanDetectTrigger(io, options) {
+    if (options.rid === undefined || options.rid === '') {
+        printResult(io, fail('workflow.plan.detect-trigger', 'MISSING_RID', 'Missing --rid', null, ['Pass --rid <request-id>']), options.json === true);
+        process.exitCode = 1;
+        return;
+    }
+    if (!isValidRequestId(options.rid)) {
+        printResult(io, fail('workflow.plan.detect-trigger', 'INVALID_RID', 'request id must match [A-Za-z0-9][A-Za-z0-9._-]*', { rid: options.rid }, ['Pass --rid <alphanumeric.request-id>']), options.json === true);
+        process.exitCode = 1;
+        return;
+    }
+    const projectRoot = resolveProjectRoot(options.project);
+    const sessionId = resolveSessionId(io, 'workflow.plan.detect-trigger', projectRoot, options.sessionId, options.json);
+    if (sessionId === null)
+        return;
+    try {
+        const result = detectTrigger({
+            project: projectRoot,
+            rid: options.rid,
+            sessionId,
+            ...(options.refresh === true ? { manualOverride: true } : {})
+        });
+        printResult(io, result, options.json === true);
+    }
+    catch (error) {
+        printResult(io, fail('workflow.plan.detect-trigger', 'DETECT_FAILED', getErrorMessage(error), null, ['Check that --project is a valid repo root and --rid is set']), options.json === true);
+        process.exitCode = 1;
+    }
+}
+export function registerWorkflowPlanCommands(program, io) {
+    let workflowCmd = program.commands.find((c) => c.name() === 'workflow');
+    if (workflowCmd === undefined) {
+        workflowCmd = program.command('workflow').description('Plan workflow routing dry-run graphs');
+    }
+    const plan = workflowCmd
+        .command('plan')
+        .description('Read, refresh, or detect-trigger for security / perf plans (slice 025)');
+    addJsonOption(plan
+        .command('read')
+        .description('Read the project-level plan envelope (exists, path, hash, refreshedAt)')
+        .requiredOption('--type <type>', 'plan type: security or perf')
+        .option('--project <path>', 'project root', process.cwd())
+        .option('--session-id <sid>', 'session id (defaults to the active session)')).action((options) => {
+        runPlanRead(io, options);
+    });
+    addJsonOption(plan
+        .command('refresh')
+        .description('Regenerate the plan (deterministic, idempotent; --apply to write)')
+        .requiredOption('--type <type>', 'plan type: security or perf')
+        .option('--project <path>', 'project root', process.cwd())
+        .option('--session-id <sid>', 'session id (defaults to the active session)')
+        .option('--apply', 'write the plan to disk (default is dry-run preview)')).action((options) => {
+        runPlanRefresh(io, options);
+    });
+    addJsonOption(plan
+        .command('detect-trigger')
+        .description('Detect whether a plan refresh is warranted for the slice diff')
+        .requiredOption('--rid <rid>', 'request identifier')
+        .option('--project <path>', 'project root', process.cwd())
+        .option('--session-id <sid>', 'session id (defaults to the active session)')
+        .option('--refresh', 'force triggered=true (manual override)')).action((options) => {
+        runPlanDetectTrigger(io, options);
+    });
+}
+// Re-export for tests that need a programmatic entry point.
+export { runPlanRead as _runPlanRead };
+export { runPlanRefresh as _runPlanRefresh };
+export { runPlanDetectTrigger as _runPlanDetectTrigger };

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/cli/program.js

@@ -27,6 +27,8 @@ import { registerHooksCommands } from './commands/hooks-commands.js';
 import { registerStatusLineCommands } from './commands/statusline-commands.js';
 import { registerUnderstandCommands } from './commands/understand-commands.js';
 import { registerWorkspaceCommands } from './commands/workspace-commands.js';
+import { registerSkillScopeCommands } from './commands/skill-scope-commands.js';
+import { registerWorkflowPlanCommands } from './commands/workflow-plan-commands.js';
 export { printResult } from './cli-helpers.js';
 export function createProgram(io = { stdout: (text) => console.log(text), stderr: (text) => console.error(text) }) {
     const program = new Command();
@@ -107,5 +109,9 @@ Run peaks (no arguments) for a quickstart. You likely want one of:
     registerStatusLineCommands(program, io);
     registerUnderstandCommands(program, io);
     registerWorkspaceCommands(program, io);
+    // Slice 025: peaks skill scope — per-project multi-IDE skill scoping.
+    registerSkillScopeCommands(program, io);
+    // Slice 025: peaks workflow plan — security/perf plan/result split CLI.
+    registerWorkflowPlanCommands(program, io);
     return program;
 }

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

@@ -44,6 +44,43 @@ export type WorkspaceLayoutInspection = {
     perChangeIdDirs?: string[];
 };
 export type WorkspaceLayoutProbe = () => WorkspaceLayoutInspection;
+/**
+ * 2026-06-10 — `gateguard-fact-force` (a third-party PreToolUse hook,
+ * NOT peaks-cli) fires on Edit / Write and demands a 4-fact questionnaire
+ * before allowing the edit. When the LLM is in a peaks-qa flow and tries
+ * to update `.peaks/_runtime/<sid>/qa/requests/*.md` via the Edit/Write
+ * tool, the hook demands facts that are inapplicable to QA envelope
+ * templates (no importers, no public API, no data files, user
+ * instruction already in the conversation context). The check detects
+ * this hook in the user's global and project `.claude/settings.json` and
+ * warns when no `.peaks/**` skip is configured. The probe is injected so
+ * tests do not depend on the real `~/.claude/settings.json` state.
+ */
+export type GateguardHookLocation = {
+    /** Source file the hook was discovered in (`global` or `project .claude/settings.json`). */
+    source: 'global' | 'project';
+    /** Resolved absolute path to the source file (for the message). */
+    sourcePath: string;
+    /** The PreToolUse entry that contains a gateguard hook command. */
+    entry: {
+        matcher?: string;
+        hooks: ReadonlyArray<{
+            type?: string;
+            command?: string;
+        }>;
+    };
+};
+export type GateguardProbeResult = {
+    /** Absolute path to `~/.claude/settings.json` (or null when the probe could not resolve it). */
+    globalSettingsPath: string | null;
+    /** Parsed global settings payload (or null when missing / unreadable / malformed). */
+    globalSettings: unknown;
+    /** Absolute path to the project `.claude/settings.json` (or null when the project root is not in a peaks project). */
+    projectSettingsPath: string | null;
+    /** Parsed project settings payload (or null when missing / unreadable / malformed). */
+    projectSettings: unknown;
+};
+export type GateguardProbe = () => GateguardProbeResult;
 export type DoctorOptions = {
     schemasBaseDir?: string;
     skillsBaseDir?: string;
@@ -59,6 +96,8 @@ export type DoctorOptions = {
     distVersionProbe?: DistVersionProbe;
     /** Injected for the build:workspace-layout-canonical check (defaults to inspectWorkspaceLayout on disk). */
     workspaceLayoutProbe?: WorkspaceLayoutProbe;
+    /** Injected for the integration:gateguard-peaks-conflict check (defaults to defaultGateguardProbe on disk). */
+    gateguardProbe?: GateguardProbe;
 };
 /**
  * Pure helper extracted from `defaultWorkspaceInitializedProbe` so tests can
@@ -99,4 +138,5 @@ export declare function inspectWorkspaceLayout(opts: {
     dotfileScanner?: (root: string) => string[];
     perChangeIdScanner?: (root: string) => string[];
 }): WorkspaceLayoutInspection;
+export declare function collectGateguardEntries(probe: GateguardProbeResult): GateguardHookLocation[];
 export declare function runDoctor(options?: DoctorOptions): Promise<DoctorReport>;

package/dist/src/services/doctor/doctor-service.js

@@ -270,6 +270,121 @@ function findDestructiveApplyLines(section) {
     const lines = section.split(/\r?\n/);
     return lines.filter((line) => DESTRUCTIVE_APPLY_PATTERNS.some((pattern) => pattern.test(line)));
 }
+// ---------------------------------------------------------------------------
+// 2026-06-10 — gateguard-fact-force integration check (NOT a peaks-cli hook).
+//
+// The `gateguard-fact-force` hook is a third-party PreToolUse hook that
+// fires on Edit / Write / MultiEdit and demands a 4-fact questionnaire
+// before allowing the edit. It is unrelated to peaks-cli, but when the
+// LLM is in a peaks-qa flow and edits `.peaks/_runtime/<sid>/qa/requests/
+// *.md`, the questionnaire demands facts that do not apply (no
+// importers, no public API, no data files, user instruction already
+// in the conversation context). The check below detects the hook in
+// `~/.claude/settings.json` and the project `.claude/settings.json`,
+// and warns when no `.peaks/**` skip is configured.
+//
+// Probing is split out of the check so the check itself stays a pure
+// mapping over `GateguardProbeResult`. Tests inject the probe to keep
+// `~/.claude/settings.json` from leaking into test fixtures.
+// ---------------------------------------------------------------------------
+/** Hook command fragments that identify the gateguard-fact-force hook. */
+const GATEGUARD_HOOK_NEEDLES = ['gateguard', 'fact-force', 'fact_force'];
+/** Token the gateguard hook exposes for "skip these paths" — the check
+ *  treats any match against `.peaks` (path or globs) as a routed
+ *  configuration. We accept a few common spellings because the third-
+ *  party hook's CLI surface is not part of peaks-cli's contract. */
+const GATEGUARD_PEAKS_SKIP_NEEDLES = [
+    '.peaks',
+    'peaks-skip',
+    'skip-glob',
+    '--skip',
+    'skip_paths'
+];
+function commandMentionsGateguard(command) {
+    if (typeof command !== 'string' || command.length === 0)
+        return false;
+    const lower = command.toLowerCase();
+    return GATEGUARD_HOOK_NEEDLES.some((needle) => lower.includes(needle));
+}
+function entrySkipsPeaks(entry) {
+    const matcher = typeof entry.matcher === 'string' ? entry.matcher : '';
+    const matcherMentionsPeaks = matcher.toLowerCase().includes('.peaks');
+    if (matcherMentionsPeaks)
+        return true;
+    for (const hook of entry.hooks) {
+        const command = typeof hook.command === 'string' ? hook.command : '';
+        const lower = command.toLowerCase();
+        if (GATEGUARD_PEAKS_SKIP_NEEDLES.some((needle) => lower.includes(needle))) {
+            return true;
+        }
+    }
+    return false;
+}
+function extractGateguardEntries(source, sourcePath, settings) {
+    if (settings === null || typeof settings !== 'object')
+        return [];
+    const hooks = settings.hooks;
+    if (hooks === null || typeof hooks !== 'object')
+        return [];
+    const preToolUse = hooks.PreToolUse;
+    if (!Array.isArray(preToolUse))
+        return [];
+    const out = [];
+    for (const rawEntry of preToolUse) {
+        if (rawEntry === null || typeof rawEntry !== 'object')
+            continue;
+        const entry = rawEntry;
+        if (!Array.isArray(entry.hooks))
+            continue;
+        const hooks = [];
+        for (const rawHook of entry.hooks) {
+            if (rawHook === null || typeof rawHook !== 'object')
+                continue;
+            const h = rawHook;
+            const hookEntry = {};
+            if (typeof h.type === 'string')
+                hookEntry.type = h.type;
+            if (typeof h.command === 'string')
+                hookEntry.command = h.command;
+            hooks.push(hookEntry);
+        }
+        if (!hooks.some((h) => commandMentionsGateguard(h.command)))
+            continue;
+        const outEntry = { hooks };
+        if (typeof entry.matcher === 'string')
+            outEntry.matcher = entry.matcher;
+        out.push({ source, sourcePath, entry: outEntry });
+    }
+    return out;
+}
+function readSettingsJson(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function defaultGateguardProbe() {
+    const projectRoot = findProjectRoot(process.cwd());
+    const globalPath = join(homedir(), '.claude', 'settings.json');
+    const projectPath = projectRoot === null ? null : join(projectRoot, '.claude', 'settings.json');
+    return {
+        globalSettingsPath: globalPath,
+        globalSettings: readSettingsJson(globalPath),
+        projectSettingsPath: projectPath,
+        projectSettings: projectPath === null ? null : readSettingsJson(projectPath)
+    };
+}
+export function collectGateguardEntries(probe) {
+    const fromGlobal = extractGateguardEntries('global', probe.globalSettingsPath ?? '~/.claude/settings.json', probe.globalSettings);
+    const fromProject = probe.projectSettingsPath === null
+        ? []
+        : extractGateguardEntries('project', probe.projectSettingsPath, probe.projectSettings);
+    return [...fromGlobal, ...fromProject];
+}
 export async function runDoctor(options = {}) {
     const checks = [];
     const registry = await loadSkillRegistry(options.skillsBaseDir);
@@ -619,6 +734,51 @@ export async function runDoctor(options = {}) {
             message: `Workspace layout check failed: ${getErrorMessage(error)}`
         });
     }
+    // 2026-06-10 — gateguard-fact-force integration check. The hook is a
+    // third-party PreToolUse that fires on Edit / Write and demands a
+    // 4-fact questionnaire; when the LLM is in a peaks-qa flow updating
+    // `.peaks/_runtime/<sid>/qa/requests/*.md` the facts do not apply.
+    // We warn when the hook is installed and no `.peaks/**` skip is
+    // configured. The check stays a pure mapping over the probe result
+    // so tests can drive it without touching the real `~/.claude/`.
+    const gateguardProbe = options.gateguardProbe ?? defaultGateguardProbe;
+    try {
+        const probe = gateguardProbe();
+        const offending = collectGateguardEntries(probe);
+        if (offending.length === 0) {
+            checks.push({
+                id: 'integration:gateguard-peaks-conflict',
+                ok: true,
+                message: 'No gateguard-fact-force PreToolUse hook detected in ~/.claude/settings.json or project .claude/settings.json; the Edit/Write fact-forcing flow will not interfere with peaks-qa .peaks/ artifact writes'
+            });
+        }
+        else {
+            const unrouted = offending.filter((location) => !entrySkipsPeaks(location.entry));
+            if (unrouted.length === 0) {
+                checks.push({
+                    id: 'integration:gateguard-peaks-conflict',
+                    ok: true,
+                    message: `gateguard-fact-force hook is installed in ${offending.map((l) => l.source).join(' + ')} but a .peaks/** skip pattern is configured; peaks-qa .peaks/ artifact writes are not blocked`
+                });
+            }
+            else {
+                const sources = Array.from(new Set(unrouted.map((u) => u.sourcePath))).join(' + ');
+                const matchers = unrouted.map((u) => u.entry.matcher ?? '*').join(', ');
+                checks.push({
+                    id: 'integration:gateguard-peaks-conflict',
+                    ok: false,
+                    message: `gateguard-fact-force PreToolUse hook is installed (${sources}, matcher: ${matchers}) with no .peaks/** skip pattern; every Edit/Write of a peaks-qa envelope (.peaks/_runtime/<sid>/qa/requests/*.md) will be intercepted and demand a 4-fact questionnaire that does not apply to QA templates. Workaround: set \`ECC_DISABLED_HOOKS=pre:edit-write:gateguard-fact-force\` for the session, OR add a paired PreToolUse entry whose matcher restricts the hook to non-.peaks paths. peaks-cli is NOT the source of this hook.`
+                });
+            }
+        }
+    }
+    catch (error) {
+        checks.push({
+            id: 'integration:gateguard-peaks-conflict',
+            ok: true,
+            message: `gateguard probe failed (${getErrorMessage(error)}); skipping check`
+        });
+    }
     try {
         const schemaText = await readText(join(schemaRoot, 'doctor-report.schema.json'));
         const schema = JSON.parse(schemaText);

package/dist/src/services/hooks/presence-marker-detector.d.ts

@@ -0,0 +1,16 @@
+export type DetectPresenceMarkerInput = {
+    project: string;
+    latestAssistantMessage: string;
+};
+export type DetectPresenceMarkerResult = {
+    active: boolean;
+    skill?: string;
+    markerFound: boolean;
+    warning?: string;
+};
+export type PresenceMarkerWarning = (typeof PRESENCE_MARKER_WARNING)[number];
+export declare const PRESENCE_MARKER_WARNING: readonly ["Peaks skill context may have been lost from this conversation; please re-invoke /peaks-<skill>."];
+/**
+ * Pure read-only presence-marker detection. No I/O side effects.
+ */
+export declare function detectPresenceMarker(input: DetectPresenceMarkerInput): DetectPresenceMarkerResult;

package/dist/src/services/hooks/presence-marker-detector.js

@@ -0,0 +1,105 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+/**
+ * Slice 028 (Q1=A): hook-based skill-presence marker detection.
+ *
+ * Background: the consumer-facing CLAUDE.md template (rendered by
+ * `peaks standards init` / `peaks standards update`) instructs the LLM
+ * to display a compact status header
+ *   `Peaks-Cli Skill: <skill> | Peaks-Cli Gate: <gate> | Next: <one short action>`
+ * on every turn while a peaks skill is active. If the LLM forgets (e.g.
+ * because of context compaction or a fresh session), the user is left
+ * without an at-a-glance signal that peaks is orchestrating the work.
+ *
+ * This service is the read-only side of the slice-028 detection
+ * mechanism. The PostToolUse hook (or any other consumer, e.g.
+ * `peaks skill detect-marker-loss`) calls
+ * `detectPresenceMarker({ project, latestAssistantMessage })`
+ * and gets back:
+ *
+ *   - `active`:      whether an active-skill marker was found on disk.
+ *   - `skill?`:      the active skill name, if any.
+ *   - `markerFound`: whether the latest assistant message carries the
+ *                    expected `Peaks-Cli Skill:` / `Peaks-Cli Gate:`
+ *                    marker. Always `false` when `active` is `false`.
+ *   - `warning?`:    a human-readable warning emitted when the marker
+ *                    is missing while the presence is active.
+ *
+ * The function is pure: it does not write to disk, does not clear the
+ * presence file, and does not depend on `process.cwd()`. The caller is
+ * expected to provide the absolute project root (peaks-cli convention
+ * from the standards-commands family — see dev-preference rule
+ * `project-option-is-canonical-project-root-source`).
+ */
+const PRESENCE_CANONICAL_PATH = '.peaks/_runtime/active-skill.json';
+const PRESENCE_LEGACY_PATH = '.peaks/.active-skill.json';
+const MARKER_PRIMARY = 'Peaks-Cli Skill:';
+const MARKER_SECONDARY = 'Peaks-Cli Gate:';
+const SKILL_NAME_RE = /"skill"\s*:\s*"([^"\\]*(?:\\.[^"\\]*)*)"/;
+export const PRESENCE_MARKER_WARNING = [
+    'Peaks skill context may have been lost from this conversation; please re-invoke /peaks-<skill>.'
+];
+function readPresenceFile(absolutePath) {
+    if (!existsSync(absolutePath))
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(absolutePath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== 'object')
+        return null;
+    const skillMatch = SKILL_NAME_RE.exec(JSON.stringify(parsed));
+    if (skillMatch === null)
+        return null;
+    if (typeof skillMatch[1] !== 'string' || skillMatch[1].length === 0)
+        return null;
+    return { skill: skillMatch[1] };
+}
+function readPresenceBackCompat(project) {
+    const projectRoot = resolve(project);
+    const canonicalPath = resolve(projectRoot, PRESENCE_CANONICAL_PATH);
+    const legacyPath = resolve(projectRoot, PRESENCE_LEGACY_PATH);
+    for (const candidate of [canonicalPath, legacyPath]) {
+        const parsed = readPresenceFile(candidate);
+        if (parsed === null)
+            continue;
+        return { skill: parsed.skill, path: candidate };
+    }
+    return null;
+}
+function messageHasMarker(message) {
+    if (message.length === 0)
+        return false;
+    return message.includes(MARKER_PRIMARY) || message.includes(MARKER_SECONDARY);
+}
+/**
+ * Pure read-only presence-marker detection. No I/O side effects.
+ */
+export function detectPresenceMarker(input) {
+    const project = input.project;
+    const message = input.latestAssistantMessage ?? '';
+    const presence = readPresenceBackCompat(project);
+    if (presence === null) {
+        return { active: false, markerFound: false };
+    }
+    const markerFound = messageHasMarker(message);
+    if (markerFound) {
+        return { active: true, skill: presence.skill, markerFound: true };
+    }
+    return {
+        active: true,
+        skill: presence.skill,
+        markerFound: false,
+        warning: PRESENCE_MARKER_WARNING[0]
+    };
+}

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;