peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/handoff/handoff-types.js

@@ -0,0 +1,19 @@
+/**
+ * Handoff frontmatter schema — types.
+ *
+ * Spec: docs/superpowers/plans/2026-06-25-slice-topology-multipass.md
+ *       Phase 1, Task 4 (Handoff frontmatter types + parser + writer).
+ *
+ * A handoff artifact is a markdown file with a YAML frontmatter block
+ * carrying structured fields (rid, slice_id, status, ...) followed by a
+ * prose body. The frontmatter is the source of truth for downstream
+ * automation (peaks-rd, peaks-qa); the body is human/agent prose.
+ *
+ * Two schema versions exist:
+ *   - "0" — legacy handoff (no frontmatter block). Fields default to
+ *           `rid='unknown'`, `slice_id='unknown'`, `agent_id='unknown'`,
+ *           `status='unknown'`, `created_at=epoch`.
+ *   - "1" — current schema. All required fields must be present; the
+ *           parser throws `IncompleteHandoffError` if any are missing.
+ */
+export {};

package/dist/services/handoff/handoff-writer.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Handoff frontmatter — writer.
+ *
+ * Spec: docs/superpowers/plans/2026-06-25-slice-topology-multipass.md
+ *       Phase 1, Task 4.
+ *
+ * Serializes a `HandoffFrontmatter` plus a body string into a single
+ * markdown file with the canonical layout:
+ *
+ *   ---
+ *   rid: "..."
+ *   slice_id: "..."
+ *   ...
+ *   ---
+ *
+ *   <body verbatim>
+ *
+ * The output of `writeHandoff` is round-trip compatible with
+ * `parseHandoff` — writing then parsing recovers the same frontmatter
+ * fields and body.
+ */
+import type { HandoffFrontmatter } from './handoff-types.js';
+export declare function writeHandoff(filePath: string, frontmatter: HandoffFrontmatter, body: string): void;

package/dist/services/handoff/handoff-writer.js

@@ -0,0 +1,30 @@
+/**
+ * Handoff frontmatter — writer.
+ *
+ * Spec: docs/superpowers/plans/2026-06-25-slice-topology-multipass.md
+ *       Phase 1, Task 4.
+ *
+ * Serializes a `HandoffFrontmatter` plus a body string into a single
+ * markdown file with the canonical layout:
+ *
+ *   ---
+ *   rid: "..."
+ *   slice_id: "..."
+ *   ...
+ *   ---
+ *
+ *   <body verbatim>
+ *
+ * The output of `writeHandoff` is round-trip compatible with
+ * `parseHandoff` — writing then parsing recovers the same frontmatter
+ * fields and body.
+ */
+import { writeFileSync } from 'node:fs';
+import { stringify as stringifyYaml } from 'yaml';
+const FRONTMATTER_OPEN = '---\n';
+const FRONTMATTER_CLOSE = '\n---\n\n';
+export function writeHandoff(filePath, frontmatter, body) {
+    const yamlStr = stringifyYaml(frontmatter).trimEnd();
+    const content = `${FRONTMATTER_OPEN}${yamlStr}${FRONTMATTER_CLOSE}${body}`;
+    writeFileSync(filePath, content, 'utf8');
+}

package/dist/services/hooks/auto-compact-hook-install.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Slice 2026-07-02-auto-compact-zero-pause — `ide-native` pathway
+ * hook install/remove service.
+ *
+ * Writes the auto-compact PreToolUse hook into the consumer
+ * project's `.claude/settings.local.json` so the next Bash or Task
+ * tool call from the running Claude Code session reads
+ * `CLAUDE_CONTEXT_USAGE_PERCENT` and, at ratio ≥ 0.95, in-band fires
+ * `claude --compact` against the current runner (not a child process).
+ *
+ * Idempotency contract:
+ *   - install is idempotent — calling `installAutoCompactHook`
+ *     twice produces a byte-identical file (after stripping the
+ *     magic comment). The on-disk matcher entry is the single
+ *     source of truth.
+ *   - remove is idempotent — calling `removeAutoCompactHook` when
+ *     the hook is absent is a no-op.
+ *   - other PreToolUse entries are untouched on install AND remove.
+ *
+ * Magic comment marker: `peaks:auto-compact-hook-do-not-edit`. The
+ * comment sits next to the matcher entry so a human reading the file
+ * sees the boundary; an automated diff/remove op keys off the marker
+ * + the `matcher` regex.
+ *
+ * Pure data + minimal IO: `installAutoCompactHook` and
+ * `removeAutoCompactHook` accept `settingsPath` so callers can pick
+ * `.claude/settings.local.json` (default) or pass an explicit path
+ * for tests. The functions write to disk via `fs.writeFileSync` so
+ * the on-disk file matches the in-memory template byte-for-byte
+ * (modulo the magic comment which is excluded from the data
+ * structure; see `AUTO_COMPACT_HOOK_MATCHER`).
+ */
+/**
+ * Stable matcher for the auto-compact hook. Single source of truth
+ * — `install` and `remove` both key off this constant so the
+ * invariants can't drift between the two paths.
+ */
+export declare const AUTO_COMPACT_HOOK_MATCHER = "Bash|Task";
+/**
+ * Stable command the hook fires. Wraps `peaks compact auto` so the
+ * heavy lifting (ratio probe + in-band `claude --compact` spawn)
+ * lives in the CLI surface, not inlined into the hook.
+ *
+ * `npx peaks` is deliberately omitted: the project-local install
+ * puts `peaks` on PATH inside the consumer repo (postinstall step),
+ * so the unqualified command works in the same shell the runner
+ * is using.
+ */
+export declare const AUTO_COMPACT_HOOK_COMMAND = "peaks compact auto";
+/**
+ * Magic comment marker that fences the auto-compatchook block.
+ * Both install (writes the marker) and remove (matches on it) use
+ * this string so the comment is the only place the boundary lives.
+ */
+export declare const AUTO_COMPACT_HOOK_MARKER = "peaks:auto-compact-hook-do-not-edit";
+/**
+ * Default on-disk location — kept here (not in claude-settings-template)
+ * because the auto-compact hook is a separate install surface from
+ * the fact-forcing gate bypass template.
+ */
+export declare const AUTO_COMPACT_HOOK_SETTINGS_PATH = ".claude/settings.local.json";
+/**
+ * Result envelope for `installAutoCompactHook`.
+ */
+export type AutoCompactHookInstallResult = {
+    readonly action: 'installed';
+    readonly settingsPath: string;
+} | {
+    readonly action: 'already-installed';
+    readonly settingsPath: string;
+};
+/**
+ * Result envelope for `removeAutoCompactHook`.
+ */
+export type AutoCompactHookRemoveResult = {
+    readonly action: 'removed';
+    readonly settingsPath: string;
+} | {
+    readonly action: 'absent';
+    readonly settingsPath: string;
+};
+/**
+ * Install the auto-compact PreToolUse hook. Idempotent: a re-run
+ * returns `action: 'already-installed'` and does NOT re-write the
+ * file (preserves any unrelated edits the user has made to other
+ * entries).
+ */
+export declare function installAutoCompactHook(input: {
+    readonly projectRoot: string;
+    readonly settingsPath?: string;
+}): AutoCompactHookInstallResult;
+/**
+ * Remove the auto-compact PreToolUse hook. Idempotent: missing hook
+ * returns `action: 'absent'` without re-writing the file.
+ *
+ * Other PreToolUse entries are left untouched. The settings file
+ * structure is preserved (top-level keys like `permissions` are not
+ * deleted).
+ */
+export declare function removeAutoCompactHook(input: {
+    readonly projectRoot: string;
+    readonly settingsPath?: string;
+}): AutoCompactHookRemoveResult;

package/dist/services/hooks/auto-compact-hook-install.js

@@ -0,0 +1,156 @@
+/**
+ * Slice 2026-07-02-auto-compact-zero-pause — `ide-native` pathway
+ * hook install/remove service.
+ *
+ * Writes the auto-compact PreToolUse hook into the consumer
+ * project's `.claude/settings.local.json` so the next Bash or Task
+ * tool call from the running Claude Code session reads
+ * `CLAUDE_CONTEXT_USAGE_PERCENT` and, at ratio ≥ 0.95, in-band fires
+ * `claude --compact` against the current runner (not a child process).
+ *
+ * Idempotency contract:
+ *   - install is idempotent — calling `installAutoCompactHook`
+ *     twice produces a byte-identical file (after stripping the
+ *     magic comment). The on-disk matcher entry is the single
+ *     source of truth.
+ *   - remove is idempotent — calling `removeAutoCompactHook` when
+ *     the hook is absent is a no-op.
+ *   - other PreToolUse entries are untouched on install AND remove.
+ *
+ * Magic comment marker: `peaks:auto-compact-hook-do-not-edit`. The
+ * comment sits next to the matcher entry so a human reading the file
+ * sees the boundary; an automated diff/remove op keys off the marker
+ * + the `matcher` regex.
+ *
+ * Pure data + minimal IO: `installAutoCompactHook` and
+ * `removeAutoCompactHook` accept `settingsPath` so callers can pick
+ * `.claude/settings.local.json` (default) or pass an explicit path
+ * for tests. The functions write to disk via `fs.writeFileSync` so
+ * the on-disk file matches the in-memory template byte-for-byte
+ * (modulo the magic comment which is excluded from the data
+ * structure; see `AUTO_COMPACT_HOOK_MATCHER`).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+/**
+ * Stable matcher for the auto-compact hook. Single source of truth
+ * — `install` and `remove` both key off this constant so the
+ * invariants can't drift between the two paths.
+ */
+export const AUTO_COMPACT_HOOK_MATCHER = 'Bash|Task';
+/**
+ * Stable command the hook fires. Wraps `peaks compact auto` so the
+ * heavy lifting (ratio probe + in-band `claude --compact` spawn)
+ * lives in the CLI surface, not inlined into the hook.
+ *
+ * `npx peaks` is deliberately omitted: the project-local install
+ * puts `peaks` on PATH inside the consumer repo (postinstall step),
+ * so the unqualified command works in the same shell the runner
+ * is using.
+ */
+export const AUTO_COMPACT_HOOK_COMMAND = 'peaks compact auto';
+/**
+ * Magic comment marker that fences the auto-compatchook block.
+ * Both install (writes the marker) and remove (matches on it) use
+ * this string so the comment is the only place the boundary lives.
+ */
+export const AUTO_COMPACT_HOOK_MARKER = 'peaks:auto-compact-hook-do-not-edit';
+/**
+ * Default on-disk location — kept here (not in claude-settings-template)
+ * because the auto-compact hook is a separate install surface from
+ * the fact-forcing gate bypass template.
+ */
+export const AUTO_COMPACT_HOOK_SETTINGS_PATH = '.claude/settings.local.json';
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function readSettings(settingsPath) {
+    if (!existsSync(settingsPath))
+        return {};
+    try {
+        const raw = readFileSync(settingsPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        return isObject(parsed) ? parsed : {};
+    }
+    catch {
+        // Malformed JSON → start fresh so install doesn't error. The
+        // caller is the human / CLI, not an LLM (idempotency matters
+        // more than preserve-on-corruption here).
+        return {};
+    }
+}
+function writeSettings(settingsPath, settings) {
+    const dir = dirname(settingsPath);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    // 2-space JSON matches the existing template writer's style so
+    // `diff` against pre-install files is minimal.
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+}
+function isAutoCompactEntry(entry) {
+    return entry.matcher === AUTO_COMPACT_HOOK_MATCHER;
+}
+/**
+ * Install the auto-compact PreToolUse hook. Idempotent: a re-run
+ * returns `action: 'already-installed'` and does NOT re-write the
+ * file (preserves any unrelated edits the user has made to other
+ * entries).
+ */
+export function installAutoCompactHook(input) {
+    const settingsPath = input.settingsPath ?? join(input.projectRoot, AUTO_COMPACT_HOOK_SETTINGS_PATH);
+    const settings = readSettings(settingsPath);
+    const hooks = settings.hooks ?? {};
+    const preToolUse = hooks.PreToolUse ?? [];
+    const alreadyInstalled = preToolUse.some(isAutoCompactEntry);
+    if (alreadyInstalled) {
+        return { action: 'already-installed', settingsPath };
+    }
+    const nextPreToolUse = [
+        ...preToolUse,
+        {
+            matcher: AUTO_COMPACT_HOOK_MATCHER,
+            hooks: [
+                {
+                    type: 'command',
+                    command: AUTO_COMPACT_HOOK_COMMAND
+                }
+            ]
+        }
+    ];
+    writeSettings(settingsPath, {
+        ...settings,
+        hooks: {
+            ...hooks,
+            PreToolUse: nextPreToolUse
+        }
+    });
+    return { action: 'installed', settingsPath };
+}
+/**
+ * Remove the auto-compact PreToolUse hook. Idempotent: missing hook
+ * returns `action: 'absent'` without re-writing the file.
+ *
+ * Other PreToolUse entries are left untouched. The settings file
+ * structure is preserved (top-level keys like `permissions` are not
+ * deleted).
+ */
+export function removeAutoCompactHook(input) {
+    const settingsPath = input.settingsPath ?? join(input.projectRoot, AUTO_COMPACT_HOOK_SETTINGS_PATH);
+    if (!existsSync(settingsPath))
+        return { action: 'absent', settingsPath };
+    const settings = readSettings(settingsPath);
+    const hooks = settings.hooks ?? {};
+    const preToolUse = hooks.PreToolUse ?? [];
+    const nextPreToolUse = preToolUse.filter((entry) => !isAutoCompactEntry(entry));
+    if (nextPreToolUse.length === preToolUse.length) {
+        return { action: 'absent', settingsPath };
+    }
+    writeSettings(settingsPath, {
+        ...settings,
+        hooks: {
+            ...hooks,
+            PreToolUse: nextPreToolUse
+        }
+    });
+    return { action: 'removed', settingsPath };
+}

package/dist/services/hooks/output.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Slice 003-2026-06-16-hook-governance — single source of truth for the
+ * peaks hook output contract. See `.claude/HOOKS.md` for the canonical doc.
+ *
+ * Three helpers, one job: enforce the stdout/stderr/exit-code discipline
+ * that every peaks-managed hook command MUST follow. Centralising the
+ * contract here lets us:
+ *   1. Pin the contract in cross-platform tests (tests/unit/hooks/contract.test.ts).
+ *   2. Add a new helper (e.g. emitAsk) without changing every call site.
+ *   3. Stop hand-rolling the deny JSON in gate-commands.ts / hook-handle.ts,
+ *      which historically drifted into "PreToolUse:Bash hook error" noise.
+ *
+ * The contract (intentionally redundant with the doc; the doc is for humans,
+ * this is for the type checker):
+ *
+ *   emitHint(io, text)
+ *     - Writes `text` to io.stderr with a trailing newline.
+ *     - Does NOT write to io.stdout (the host reads stdout as the decision
+ *       signal; a hint on stdout is interpreted as a malformed decision).
+ *     - Does NOT set a non-zero process.exitCode. A hint is diagnostic only;
+ *       it must not change the host's permission decision.
+ *     - Empty `text` is a no-op (skips both the write and the trailing
+ *       newline so we never pollute stderr with blank lines).
+ *
+ *   emitBlock(io, reason)
+ *     - Builds the Claude-Code-shaped deny JSON:
+ *         { "hookSpecificOutput": { "hookEventName": "PreToolUse",
+ *                                   "permissionDecision": "deny",
+ *                                   "permissionDecisionReason": <reason> } }
+ *       JSON.stringify is the canonical escape for the reason; quotes,
+ *       backslashes, and newlines inside the reason are preserved.
+ *     - Writes the serialized JSON to io.stdout with a trailing newline.
+ *     - Sets process.exitCode = 2. Claude Code treats exit-2 as the
+ *       "block" signal (see [Fact-Forcing Gate] note in .claude/HOOKS.md);
+ *       the JSON on stdout is the human-readable reason for the LLM.
+ *     - Surfaces the reason to io.stderr so an operator running the
+ *       hook command directly (or the LLM inspecting logs) can see
+ *       WHY the tool was blocked, not just THAT it was blocked.
+ *
+ *   emitDecision(io, decision)
+ *     - Writes the caller-provided decision JSON to io.stdout with a
+ *       trailing newline and returns the serialized string. Used by
+ *       IDE adapters that produce a different shape (e.g. Trae uses
+ *       hookEventName='beforeToolCall' instead of 'PreToolUse'). The
+ *       helper is intentionally shape-agnostic: the caller is the
+ *       adapter's `formatDecisionResponse`, which already knows the
+ *       IDE-specific shape.
+ *     - Does NOT set a non-zero process.exitCode. The decision is
+ *       communicated entirely via the stdout JSON; the host reads
+ *       permissionDecision='deny' to block. Setting exit=2 on top
+ *       of the JSON would be double-signaling.
+ *
+ * Platform notes:
+ *   - The contract is platform-independent. The helpers write to ProgramIO
+ *     (stdout / stderr) only; no path separators, no shell escaping, no
+ *     line-ending variants. The cross-platform contract test pins this.
+ *   - On win32, Node's process.stdout and process.stderr are binary-safe
+ *     and UTF-8; do not introduce \r\n anywhere. The contract is LF.
+ */
+import type { ProgramIO } from '../../cli/cli-helpers.js';
+/** Exit code the host treats as a hard block (Claude Code convention). */
+export declare const HOOK_BLOCK_EXIT_CODE = 2;
+/** Canonical Claude-Code hook event name. */
+export declare const CLAUDE_CODE_HOOK_EVENT = "PreToolUse";
+/** Permissive decision shape — anything JSON-serialisable. */
+export type DecisionShape = Record<string, unknown>;
+/**
+ * Hint — diagnostic, stderr-only, never affects the host decision.
+ * Returns the bytes written to stderr (or '' for an empty hint).
+ */
+export declare function emitHint(io: ProgramIO, text: string): string;
+/** Result of a block emission — the bytes written to stdout and the original reason. */
+export type EmitBlockResult = {
+    readonly stdout: string;
+    readonly reason: string;
+};
+/**
+ * Block — deny a tool call. Writes the Claude-Code-shaped deny JSON to
+ * stdout, sets process.exitCode = 2, and surfaces the reason to stderr.
+ */
+export declare function emitBlock(io: ProgramIO, reason: string): EmitBlockResult;
+/**
+ * Decision — write a caller-built decision object to stdout. Returns the
+ * serialized bytes so callers can log / assert on the exact string.
+ *
+ * Accepts either a plain object (canonical path; the helper does the
+ * JSON.stringify) or a pre-serialized string (used by adapter dispatch
+ * where `formatDecisionResponse` already serialized the IDE-shaped
+ * envelope). The string form is the legacy escape hatch and should not
+ * be used for new code.
+ */
+export declare function emitDecision(io: ProgramIO, decision: DecisionShape | string): string;

package/dist/services/hooks/output.js

@@ -0,0 +1,111 @@
+/**
+ * Slice 003-2026-06-16-hook-governance — single source of truth for the
+ * peaks hook output contract. See `.claude/HOOKS.md` for the canonical doc.
+ *
+ * Three helpers, one job: enforce the stdout/stderr/exit-code discipline
+ * that every peaks-managed hook command MUST follow. Centralising the
+ * contract here lets us:
+ *   1. Pin the contract in cross-platform tests (tests/unit/hooks/contract.test.ts).
+ *   2. Add a new helper (e.g. emitAsk) without changing every call site.
+ *   3. Stop hand-rolling the deny JSON in gate-commands.ts / hook-handle.ts,
+ *      which historically drifted into "PreToolUse:Bash hook error" noise.
+ *
+ * The contract (intentionally redundant with the doc; the doc is for humans,
+ * this is for the type checker):
+ *
+ *   emitHint(io, text)
+ *     - Writes `text` to io.stderr with a trailing newline.
+ *     - Does NOT write to io.stdout (the host reads stdout as the decision
+ *       signal; a hint on stdout is interpreted as a malformed decision).
+ *     - Does NOT set a non-zero process.exitCode. A hint is diagnostic only;
+ *       it must not change the host's permission decision.
+ *     - Empty `text` is a no-op (skips both the write and the trailing
+ *       newline so we never pollute stderr with blank lines).
+ *
+ *   emitBlock(io, reason)
+ *     - Builds the Claude-Code-shaped deny JSON:
+ *         { "hookSpecificOutput": { "hookEventName": "PreToolUse",
+ *                                   "permissionDecision": "deny",
+ *                                   "permissionDecisionReason": <reason> } }
+ *       JSON.stringify is the canonical escape for the reason; quotes,
+ *       backslashes, and newlines inside the reason are preserved.
+ *     - Writes the serialized JSON to io.stdout with a trailing newline.
+ *     - Sets process.exitCode = 2. Claude Code treats exit-2 as the
+ *       "block" signal (see [Fact-Forcing Gate] note in .claude/HOOKS.md);
+ *       the JSON on stdout is the human-readable reason for the LLM.
+ *     - Surfaces the reason to io.stderr so an operator running the
+ *       hook command directly (or the LLM inspecting logs) can see
+ *       WHY the tool was blocked, not just THAT it was blocked.
+ *
+ *   emitDecision(io, decision)
+ *     - Writes the caller-provided decision JSON to io.stdout with a
+ *       trailing newline and returns the serialized string. Used by
+ *       IDE adapters that produce a different shape (e.g. Trae uses
+ *       hookEventName='beforeToolCall' instead of 'PreToolUse'). The
+ *       helper is intentionally shape-agnostic: the caller is the
+ *       adapter's `formatDecisionResponse`, which already knows the
+ *       IDE-specific shape.
+ *     - Does NOT set a non-zero process.exitCode. The decision is
+ *       communicated entirely via the stdout JSON; the host reads
+ *       permissionDecision='deny' to block. Setting exit=2 on top
+ *       of the JSON would be double-signaling.
+ *
+ * Platform notes:
+ *   - The contract is platform-independent. The helpers write to ProgramIO
+ *     (stdout / stderr) only; no path separators, no shell escaping, no
+ *     line-ending variants. The cross-platform contract test pins this.
+ *   - On win32, Node's process.stdout and process.stderr are binary-safe
+ *     and UTF-8; do not introduce \r\n anywhere. The contract is LF.
+ */
+/** Exit code the host treats as a hard block (Claude Code convention). */
+export const HOOK_BLOCK_EXIT_CODE = 2;
+/** Canonical Claude-Code hook event name. */
+export const CLAUDE_CODE_HOOK_EVENT = 'PreToolUse';
+/**
+ * Hint — diagnostic, stderr-only, never affects the host decision.
+ * Returns the bytes written to stderr (or '' for an empty hint).
+ */
+export function emitHint(io, text) {
+    if (text.length === 0) {
+        return '';
+    }
+    const line = text.endsWith('\n') ? text : `${text}\n`;
+    io.stderr(line);
+    return line;
+}
+/**
+ * Block — deny a tool call. Writes the Claude-Code-shaped deny JSON to
+ * stdout, sets process.exitCode = 2, and surfaces the reason to stderr.
+ */
+export function emitBlock(io, reason) {
+    const safeReason = reason.length > 0 ? reason : 'denied by peaks';
+    const payload = {
+        hookSpecificOutput: {
+            hookEventName: CLAUDE_CODE_HOOK_EVENT,
+            permissionDecision: 'deny',
+            permissionDecisionReason: safeReason
+        }
+    };
+    const serialized = JSON.stringify(payload);
+    io.stdout(serialized);
+    io.stdout('\n');
+    io.stderr(`peaks: ${safeReason}\n`);
+    process.exitCode = HOOK_BLOCK_EXIT_CODE;
+    return { stdout: serialized, reason: safeReason };
+}
+/**
+ * Decision — write a caller-built decision object to stdout. Returns the
+ * serialized bytes so callers can log / assert on the exact string.
+ *
+ * Accepts either a plain object (canonical path; the helper does the
+ * JSON.stringify) or a pre-serialized string (used by adapter dispatch
+ * where `formatDecisionResponse` already serialized the IDE-shaped
+ * envelope). The string form is the legacy escape hatch and should not
+ * be used for new code.
+ */
+export function emitDecision(io, decision) {
+    const serialized = typeof decision === 'string' ? decision : JSON.stringify(decision);
+    io.stdout(serialized);
+    io.stdout('\n');
+    return serialized;
+}

package/dist/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/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-Loop Skill: <skill> | Peaks-Loop 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-Loop Skill:` / `Peaks-Loop 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-loop 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-Loop Skill:';
+const MARKER_SECONDARY = 'Peaks-Loop 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 { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        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]
+    };
+}