peaks-cli 1.1.0 → 1.1.2

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

@@ -126,6 +126,18 @@ export function registerRequestCommands(program, io) {
         try {
             const role = options.role;
             const newState = parseStateForRole(role, options.state);
+            // Resolve the artifact's real session up front. Falling back to a literal
+            // 'default' (the previous behavior) points the bypass counter at a
+            // non-existent .peaks/default/ dir and crashes with ENOENT, so when
+            // --session-id is omitted we look the artifact up to find its session.
+            let resolvedSessionId = options.sessionId;
+            if (resolvedSessionId === undefined) {
+                const { showRequestArtifact: showForSession } = await import('../../services/artifacts/request-artifact-service.js');
+                const located = await showForSession({ projectRoot: options.project, role, requestId });
+                if (located !== null) {
+                    resolvedSessionId = located.sessionId;
+                }
+            }
             if (options.allowIncomplete === true && (options.reason === undefined || options.reason.trim().length === 0)) {
                 printResult(io, fail('request.transition', 'BYPASS_REASON_REQUIRED', '--allow-incomplete requires --reason explaining why prerequisites are skipped', { role, requestId }, ['Add --reason "<short justification>" or remove --allow-incomplete and produce the missing artifacts']), options.json);
                 process.exitCode = 1;
@@ -142,7 +154,7 @@ export function registerRequestCommands(program, io) {
                         return;
                     }
                     // Check bypass count
-                    const sessionRoot = (await import('node:path')).join(options.project, '.peaks', options.sessionId ?? 'default');
+                    const sessionRoot = (await import('node:path')).join(options.project, '.peaks', resolvedSessionId ?? 'default');
                     if (isBypassLimitReached(sessionRoot)) {
                         printResult(io, fail('request.transition', 'BYPASS_LIMIT_REACHED', `--allow-incomplete limit reached (${MAX_BYPASSES_PER_SESSION} per session)`, { role, requestId, limit: MAX_BYPASSES_PER_SESSION }, ['Produce the missing artifacts instead of bypassing.']), options.json);
                         process.exitCode = 1;

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

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

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

@@ -0,0 +1,111 @@
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, printResult, getErrorMessage } from '../cli-helpers.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { buildStatusLineModel, parseStatusLineStdin } from '../../services/skills/skill-statusline-service.js';
+import { renderStatusLine } from '../../services/skills/skill-statusline-renderer.js';
+import { applyStatusLineInstall, planStatusLineInstall, removeStatusLineInstall } from '../../services/skills/statusline-settings-service.js';
+const STDIN_READ_TIMEOUT_MS = 250;
+/** Read piped stdin if present; resolve quickly with '' when attached to a TTY. */
+function readStdin() {
+    return new Promise((resolve) => {
+        if (process.stdin.isTTY) {
+            resolve('');
+            return;
+        }
+        let data = '';
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(data);
+        };
+        const timer = setTimeout(finish, STDIN_READ_TIMEOUT_MS);
+        timer.unref?.();
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => {
+            data += chunk;
+        });
+        process.stdin.on('end', () => {
+            clearTimeout(timer);
+            finish();
+        });
+        process.stdin.on('error', () => {
+            clearTimeout(timer);
+            finish();
+        });
+    });
+}
+function resolveScope(options) {
+    return options.global ? 'global' : 'project';
+}
+export function registerStatusLineCommands(program, io) {
+    const statusline = program
+        .command('statusline')
+        .description('Render the Peaks skill status line for Claude Code (reads session JSON on stdin)')
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
+        .action(async (options) => {
+        const raw = await readStdin();
+        const stdin = parseStatusLineStdin(raw);
+        // When a project override is passed (or no stdin), seed cwd so detection works.
+        const seeded = options.project
+            ? { ...(stdin ?? {}), workspace: { current_dir: options.project } }
+            : stdin;
+        const model = buildStatusLineModel(seeded, Date.now());
+        io.stdout(renderStatusLine(model));
+    });
+    addJsonOption(statusline
+        .command('install')
+        .description('Install the Peaks status line into .claude/settings.json (project scope by default)')
+        .option('--global', 'install into the user-level ~/.claude/settings.json instead of the project')
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
+        .option('--force', 'overwrite an existing non-Peaks statusLine entry')
+        .option('--dry-run', 'show what would change without writing')).action((options) => {
+        const scope = resolveScope(options);
+        const projectRoot = scope === 'project'
+            ? (options.project ?? findProjectRoot(process.cwd()) ?? process.cwd())
+            : undefined;
+        try {
+            if (options.dryRun) {
+                const plan = planStatusLineInstall(scope, projectRoot);
+                const warnings = plan.conflict
+                    ? [`An existing statusLine command is set: ${plan.conflictCommand}. Rerun with --force to overwrite.`]
+                    : [];
+                printResult(io, ok('statusline.install', { ...plan, applied: false, dryRun: true }, warnings), options.json);
+                return;
+            }
+            const result = applyStatusLineInstall(scope, projectRoot, options.force ? { force: true } : {});
+            const warnings = result.conflict && !result.applied
+                ? [`An existing statusLine command is set: ${result.conflictCommand}. Rerun with --force to overwrite.`]
+                : [];
+            const nextActions = result.applied
+                ? ['Restart Claude Code (or reload the window) so the status line takes effect']
+                : [];
+            printResult(io, ok('statusline.install', { ...result, dryRun: false }, warnings, nextActions), options.json);
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            printResult(io, fail('statusline.install', 'STATUSLINE_INSTALL_FAILED', message, { scope, applied: false }, [message]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(statusline
+        .command('uninstall')
+        .description('Remove the Peaks status line from .claude/settings.json')
+        .option('--global', 'remove from the user-level ~/.claude/settings.json instead of the project')
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')).action((options) => {
+        const scope = resolveScope(options);
+        const projectRoot = scope === 'project'
+            ? (options.project ?? findProjectRoot(process.cwd()) ?? process.cwd())
+            : undefined;
+        try {
+            const result = removeStatusLineInstall(scope, projectRoot);
+            printResult(io, ok('statusline.uninstall', result), options.json);
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            printResult(io, fail('statusline.uninstall', 'STATUSLINE_UNINSTALL_FAILED', message, { scope, removed: false }, [message]), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/src/cli/program.js

@@ -10,6 +10,7 @@ import { registerProjectCommands } from './commands/project-commands.js';
 import { registerRequestCommands } from './commands/request-commands.js';
 import { registerScanCommands } from './commands/scan-commands.js';
 import { registerShadcnCommands } from './commands/shadcn-commands.js';
+import { registerStatusLineCommands } from './commands/statusline-commands.js';
 import { registerUnderstandCommands } from './commands/understand-commands.js';
 import { registerWorkspaceCommands } from './commands/workspace-commands.js';
 export { printResult } from './cli-helpers.js';
@@ -40,6 +41,7 @@ export function createProgram(io = { stdout: (text) => console.log(text), stderr
     registerRequestCommands(program, io);
     registerScanCommands(program, io);
     registerShadcnCommands(program, io);
+    registerStatusLineCommands(program, io);
     registerUnderstandCommands(program, io);
     registerWorkspaceCommands(program, io);
     return program;

package/dist/src/services/artifacts/artifact-lint-service.js

@@ -35,6 +35,15 @@ const ALLOWLIST_PATTERNS = [
 function isAllowlisted(line) {
     return ALLOWLIST_PATTERNS.some((pattern) => pattern.test(line));
 }
+/**
+ * Remove inline code spans (`...`) before applying placeholder rules. Content
+ * inside backticks is literal example text — e.g. a documented command syntax
+ * `peaks sop init <id>` — not an unfilled prose placeholder. Lint checks prose,
+ * not code, so a `<...>` token only counts when it appears outside code spans.
+ */
+function stripInlineCode(line) {
+    return line.replace(/`[^`]*`/g, '');
+}
 export async function lintRequestArtifact(options) {
     const showOptions = {
         projectRoot: options.projectRoot,
@@ -50,14 +59,24 @@ export async function lintRequestArtifact(options) {
     }
     const lines = artifact.content.split(/\r?\n/);
     const findings = [];
+    let insideFence = false;
     for (let index = 0; index < lines.length; index += 1) {
         const rawLine = lines[index];
         if (rawLine === undefined)
             continue;
+        // Fenced code blocks hold literal examples, not prose to fill; skip their
+        // contents entirely (the fence delimiters themselves toggle the state).
+        if (/^\s*```/.test(rawLine)) {
+            insideFence = !insideFence;
+            continue;
+        }
+        if (insideFence)
+            continue;
         if (isAllowlisted(rawLine))
             continue;
+        const testLine = stripInlineCode(rawLine);
         for (const rule of RULES) {
-            if (rule.test(rawLine)) {
+            if (rule.test(testLine)) {
                 findings.push({
                     line: index + 1,
                     text: rawLine.trim(),

package/dist/src/services/artifacts/artifact-prerequisites.js

@@ -1,5 +1,5 @@
-import { join } from 'node:path';
-import { readFile } from 'node:fs/promises';
+import { join, dirname, basename } from 'node:path';
+import { readFile, readdir } from 'node:fs/promises';
 import { pathExists } from '../../shared/fs.js';
 export const VALID_REQUEST_TYPES = [
     'feature',
@@ -111,6 +111,36 @@ export function getPrerequisitesFor(role, newState, requestType = DEFAULT_REQUES
 function resolvePrerequisitePath(prerequisite, requestId) {
     return prerequisite.relativePath.replace('<rid>', requestId);
 }
+/**
+ * Resolve a prerequisite to an on-disk path, tolerating the numbered filename
+ * prefix that `request init` writes (e.g. `001-<rid>.md`). When the prerequisite
+ * path contains `<rid>`, we accept either the legacy bare `<rid>.md` form or any
+ * `NNN-<rid>.md` numbered form — mirroring the matcher in request-artifact-service.
+ * Returns the matched absolute path, or null when nothing matches.
+ */
+async function resolvePrerequisiteAbsolutePath(sessionRoot, prerequisite, requestId) {
+    const relative = resolvePrerequisitePath(prerequisite, requestId);
+    const exact = join(sessionRoot, relative);
+    if (await pathExists(exact)) {
+        return exact;
+    }
+    // Only `<rid>`-templated prerequisites can carry a numbered prefix; fixed paths
+    // (e.g. rd/tech-doc.md) are matched exactly above.
+    if (!prerequisite.relativePath.includes('<rid>')) {
+        return null;
+    }
+    const dir = dirname(exact);
+    const targetSuffix = `-${basename(exact)}`;
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        return null;
+    }
+    const match = entries.find((name) => /^\d+-/.test(name) && name.endsWith(targetSuffix));
+    return match ? join(dir, match) : null;
+}
 export async function checkPrerequisites(options) {
     const requirements = getPrerequisitesFor(options.role, options.newState, options.requestType);
     if (requirements.length === 0) {
@@ -120,8 +150,8 @@ export async function checkPrerequisites(options) {
     const missing = [];
     for (const prerequisite of requirements) {
         const relative = resolvePrerequisitePath(prerequisite, options.requestId);
-        const absolute = join(sessionRoot, relative);
-        if (!(await pathExists(absolute))) {
+        const absolute = await resolvePrerequisiteAbsolutePath(sessionRoot, prerequisite, options.requestId);
+        if (absolute === null) {
             missing.push({ path: relative, description: prerequisite.description });
             continue;
         }

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

@@ -24,5 +24,6 @@ export type DoctorOptions = {
     codegraphProbe?: () => CodegraphCapabilityProbe;
     skillPresenceProbe?: () => SkillPresence | null;
     skillPresenceFreshnessThresholdMs?: number;
+    statusLineInstalledProbe?: () => boolean;
 };
 export declare function runDoctor(options?: DoctorOptions): Promise<DoctorReport>;

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

@@ -8,6 +8,8 @@ import { requiredSchemaFiles, requiredSkillNames, schemasDir } from '../../share
 import { getErrorMessage } from '../../shared/result.js';
 import { loadSkillRegistry } from '../skills/skill-registry.js';
 import { getSkillPresence } from '../skills/skill-presence-service.js';
+import { planStatusLineInstall } from '../skills/statusline-settings-service.js';
+import { findProjectRoot } from '../config/config-safety.js';
 const CODEGRAPH_EXPECTED_VERSION = '0.7.10';
 const SKILL_PRESENCE_FRESHNESS_THRESHOLD_MS = 24 * 60 * 60 * 1000;
 function defaultCodegraphProbe() {
@@ -22,6 +24,17 @@ function defaultCodegraphProbe() {
         binaryExists: existsSync(binaryPath)
     };
 }
+function defaultStatusLineInstalledProbe() {
+    const projectRoot = findProjectRoot(process.cwd());
+    if (projectRoot === null)
+        return false;
+    try {
+        return planStatusLineInstall('project', projectRoot).alreadyInstalled;
+    }
+    catch {
+        return false;
+    }
+}
 const DESTRUCTIVE_APPLY_PATTERNS = [
     /peaks\s+memory\s+sync[^\n]*--apply/,
     /peaks\s+memory\s+extract[^\n]*--apply/,
@@ -190,6 +203,33 @@ export async function runDoctor(options = {}) {
             }
         }
     }
+    // Discoverability nudge: when a skill is actively orchestrating but the
+    // out-of-band statusLine isn't installed, the user has no terminal-level
+    // signal that Peaks is in control. Suggest installing it (non-failing).
+    const statusLineProbe = options.statusLineInstalledProbe ?? defaultStatusLineInstalledProbe;
+    let statusLineInstalled = false;
+    try {
+        statusLineInstalled = statusLineProbe();
+    }
+    catch {
+        statusLineInstalled = false;
+    }
+    if (presence !== null && !statusLineInstalled) {
+        checks.push({
+            id: 'statusline:install',
+            ok: true,
+            message: 'A Peaks skill is active but the statusLine is not installed; run `peaks statusline install` so the active skill shows in the terminal status bar'
+        });
+    }
+    else {
+        checks.push({
+            id: 'statusline:install',
+            ok: true,
+            message: statusLineInstalled
+                ? 'Peaks statusLine is installed'
+                : 'Peaks statusLine not installed (no active skill; install optional)'
+        });
+    }
     const probe = options.codegraphProbe ?? defaultCodegraphProbe;
     try {
         const result = probe();

package/dist/src/services/scan/type-sanity-service.js

@@ -25,6 +25,16 @@ function classifyFile(filePath) {
         return 'source';
     return 'unknown';
 }
+/**
+ * Peaks' own artifact workspace. Changes here (PRD/RD/QA markdown, session
+ * state) are never the "code change" a request type describes, so they must be
+ * excluded from the diff — otherwise a PRD-planning-phase handoff that only
+ * wrote `.peaks/**` markdown would be misclassified as a docs change.
+ */
+function isArtifactWorkspaceFile(filePath) {
+    const normalized = filePath.replace(/\\/g, '/');
+    return normalized === '.peaks' || normalized.startsWith('.peaks/');
+}
 function tryGitDiffFiles(projectRoot, baseRef) {
     try {
         // Combine: tracked changes vs baseRef + untracked files. Use porcelain status for untracked too.
@@ -32,7 +42,7 @@ function tryGitDiffFiles(projectRoot, baseRef) {
         const tracked = trackedRaw.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
         const untrackedRaw = execFileSync('git', ['-C', projectRoot, 'ls-files', '--others', '--exclude-standard'], { encoding: 'utf8' });
         const untracked = untrackedRaw.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
-        const merged = Array.from(new Set([...tracked, ...untracked]));
+        const merged = Array.from(new Set([...tracked, ...untracked])).filter((file) => !isArtifactWorkspaceFile(file));
         return { ok: true, files: merged };
     }
     catch {

package/dist/src/services/skills/skill-statusline-renderer.d.ts

@@ -0,0 +1,6 @@
+import type { StatusLineModel } from './skill-statusline-service.js';
+/**
+ * Render the status line. The output is plain text with simple status glyphs so
+ * it stays readable in any terminal; Claude Code applies its own styling.
+ */
+export declare function renderStatusLine(model: StatusLineModel): string;

package/dist/src/services/skills/skill-statusline-renderer.js

@@ -0,0 +1,55 @@
+import { basename } from 'node:path';
+/**
+ * Pure formatting layer for the Peaks statusLine. Takes the read-only status
+ * model and produces the single line Claude Code paints at the bottom of the
+ * terminal. Kept separate from the reader so formatting can be tested without
+ * touching the filesystem.
+ */
+const BRAND = '⛰ Peaks';
+function formatAge(ageMs) {
+    if (ageMs === null)
+        return '';
+    const hours = Math.round(ageMs / (60 * 60 * 1000));
+    if (hours >= 1)
+        return `stale ${hours}h`;
+    const minutes = Math.max(1, Math.round(ageMs / (60 * 1000)));
+    return `stale ${minutes}m`;
+}
+function rootLabel(projectRoot) {
+    if (!projectRoot)
+        return '';
+    return basename(projectRoot);
+}
+/**
+ * Render the status line. The output is plain text with simple status glyphs so
+ * it stays readable in any terminal; Claude Code applies its own styling.
+ */
+export function renderStatusLine(model) {
+    const root = rootLabel(model.projectRoot);
+    const rootSuffix = root ? ` · ${root}` : '';
+    switch (model.state) {
+        case 'active': {
+            const presence = model.presence;
+            if (!presence)
+                return `${BRAND} ○ idle${rootSuffix}`;
+            const parts = [presence.skill];
+            if (presence.mode)
+                parts.push(presence.mode);
+            if (presence.gate)
+                parts.push(`gate:${presence.gate}`);
+            return `${BRAND} ● ${parts.join(' · ')}${rootSuffix}`;
+        }
+        case 'stale': {
+            const presence = model.presence;
+            const skill = presence?.skill ?? 'unknown';
+            const age = formatAge(model.ageMs);
+            const ageSuffix = age ? ` · ${age}` : '';
+            return `${BRAND} ⚠ ${skill}${ageSuffix}${rootSuffix}`;
+        }
+        case 'invalid-presence':
+            return `${BRAND} ⚠ presence file unreadable${rootSuffix}`;
+        case 'idle':
+        default:
+            return `${BRAND} ○ idle${rootSuffix}`;
+    }
+}

package/dist/src/services/skills/skill-statusline-service.d.ts

@@ -0,0 +1,22 @@
+export type StatusLineStdin = {
+    workspace?: {
+        current_dir?: string;
+        project_dir?: string;
+    };
+    cwd?: string;
+};
+export type StatusLineState = 'active' | 'idle' | 'stale' | 'invalid-presence';
+export type StatusLinePresence = {
+    skill: string;
+    mode?: string;
+    gate?: string;
+    setAt?: string;
+};
+export type StatusLineModel = {
+    state: StatusLineState;
+    projectRoot: string | null;
+    presence: StatusLinePresence | null;
+    ageMs: number | null;
+};
+export declare function parseStatusLineStdin(raw: string): StatusLineStdin | null;
+export declare function buildStatusLineModel(stdin: StatusLineStdin | null, nowMs: number): StatusLineModel;

package/dist/src/services/skills/skill-statusline-service.js

@@ -0,0 +1,94 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { findProjectRoot } from '../config/config-safety.js';
+/**
+ * Out-of-band Peaks skill status renderer for the Claude Code statusLine.
+ *
+ * Claude Code invokes the configured statusLine command on every turn and pipes
+ * a JSON session payload on stdin. This renderer reads the durable presence file
+ * (.peaks/.active-skill.json) and prints a single line that Claude Code paints at
+ * the bottom of the terminal. Because it is rendered by the harness — not emitted
+ * as LLM tokens — the signal cannot be forgotten by the model, cannot be confused
+ * with normal output, and survives context compaction.
+ *
+ * This module is intentionally READ-ONLY. Unlike getSkillPresence in
+ * skill-presence-service.ts, it never deletes or rewrites the presence file:
+ * the statusLine runs on every turn and must have zero side effects.
+ */
+const PRESENCE_FILE = '.peaks/.active-skill.json';
+const STALE_THRESHOLD_MS = 24 * 60 * 60 * 1000;
+function resolveCwdFromStdin(stdin) {
+    const fromWorkspace = stdin?.workspace?.current_dir ?? stdin?.workspace?.project_dir;
+    if (typeof fromWorkspace === 'string' && fromWorkspace.length > 0) {
+        return resolve(fromWorkspace);
+    }
+    if (typeof stdin?.cwd === 'string' && stdin.cwd.length > 0) {
+        return resolve(stdin.cwd);
+    }
+    return process.cwd();
+}
+export function parseStatusLineStdin(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return null;
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (parsed && typeof parsed === 'object') {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read the presence file without any side effects. Returns null when the file is
+ * absent (idle) and a sentinel object for malformed content (invalid-presence).
+ */
+function readPresenceReadOnly(projectRoot) {
+    const presencePath = resolve(projectRoot, PRESENCE_FILE);
+    if (!existsSync(presencePath)) {
+        return { presence: null, invalid: false };
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(presencePath, 'utf8'));
+        if (!parsed || typeof parsed !== 'object') {
+            return { presence: null, invalid: true };
+        }
+        const candidate = parsed;
+        if (typeof candidate.skill !== 'string' || candidate.skill.length === 0) {
+            return { presence: null, invalid: true };
+        }
+        return {
+            presence: {
+                skill: candidate.skill,
+                ...(typeof candidate.mode === 'string' ? { mode: candidate.mode } : {}),
+                ...(typeof candidate.gate === 'string' ? { gate: candidate.gate } : {}),
+                ...(typeof candidate.setAt === 'string' ? { setAt: candidate.setAt } : {})
+            },
+            invalid: false
+        };
+    }
+    catch {
+        return { presence: null, invalid: true };
+    }
+}
+export function buildStatusLineModel(stdin, nowMs) {
+    const cwd = resolveCwdFromStdin(stdin);
+    const projectRoot = findProjectRoot(cwd);
+    if (projectRoot === null) {
+        return { state: 'idle', projectRoot: null, presence: null, ageMs: null };
+    }
+    const { presence, invalid } = readPresenceReadOnly(projectRoot);
+    if (invalid) {
+        return { state: 'invalid-presence', projectRoot, presence: null, ageMs: null };
+    }
+    if (presence === null) {
+        return { state: 'idle', projectRoot, presence: null, ageMs: null };
+    }
+    const setAtMs = presence.setAt ? Date.parse(presence.setAt) : Number.NaN;
+    const ageMs = Number.isNaN(setAtMs) ? null : nowMs - setAtMs;
+    const state = ageMs !== null && ageMs > STALE_THRESHOLD_MS ? 'stale' : 'active';
+    return { state, projectRoot, presence, ageMs };
+}

package/dist/src/services/skills/statusline-settings-service.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Installs (and removes) the Peaks statusLine entry in a Claude Code
+ * settings.json. The statusLine renders `peaks statusline` on every turn, giving
+ * users an out-of-band, harness-painted signal of which Peaks skill is active —
+ * independent of LLM tokens and immune to context compaction.
+ *
+ * Writes preserve all other settings keys, reject symlinked targets, and use an
+ * atomic rename so a partial write can never corrupt an existing settings file.
+ */
+export type StatusLineScope = 'project' | 'global';
+export type StatusLineSettingsPlan = {
+    scope: StatusLineScope;
+    settingsPath: string;
+    exists: boolean;
+    alreadyInstalled: boolean;
+    conflict: boolean;
+    conflictCommand: string | null;
+    desiredCommand: string;
+};
+export type StatusLineSettingsResult = StatusLineSettingsPlan & {
+    applied: boolean;
+};
+export declare const STATUSLINE_COMMAND = "peaks statusline";
+export declare function planStatusLineInstall(scope: StatusLineScope, projectRoot?: string): StatusLineSettingsPlan;
+export declare function applyStatusLineInstall(scope: StatusLineScope, projectRoot?: string, options?: {
+    force?: boolean;
+}): StatusLineSettingsResult;
+export declare function removeStatusLineInstall(scope: StatusLineScope, projectRoot?: string): {
+    scope: StatusLineScope;
+    settingsPath: string;
+    removed: boolean;
+};

package/dist/src/services/skills/statusline-settings-service.js

@@ -0,0 +1,144 @@
+import { closeSync, constants, existsSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { homedir } from 'node:os';
+export const STATUSLINE_COMMAND = 'peaks statusline';
+function isInsidePath(childPath, parentPath) {
+    const rel = relative(parentPath, childPath);
+    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+function resolveSettingsRoot(scope, projectRoot) {
+    if (scope === 'global')
+        return resolve(homedir());
+    if (!projectRoot) {
+        throw new Error('Project scope requires a project root');
+    }
+    return resolve(projectRoot);
+}
+function resolveSettingsPath(scope, projectRoot) {
+    const root = resolveSettingsRoot(scope, projectRoot);
+    return join(root, '.claude', 'settings.json');
+}
+/** Reject symlinked .claude dir or settings file to prevent escape. */
+function assertSafeSettingsPath(scope, root, settingsPath) {
+    const claudeDir = join(root, '.claude');
+    if (existsSync(claudeDir) && lstatSync(claudeDir).isSymbolicLink()) {
+        throw new Error('.claude directory must not be a symlink');
+    }
+    if (existsSync(settingsPath)) {
+        if (lstatSync(settingsPath).isSymbolicLink()) {
+            throw new Error('settings.json must not be a symlink');
+        }
+        const realRoot = realpathSync(root);
+        if (!isInsidePath(realpathSync(settingsPath), realRoot)) {
+            throw new Error(`settings.json must stay inside the ${scope} root`);
+        }
+    }
+}
+function readSettings(settingsPath) {
+    if (!existsSync(settingsPath))
+        return {};
+    const fd = openSync(settingsPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const raw = readFileSync(fd, 'utf8').trim();
+        if (raw.length === 0)
+            return {};
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('settings.json must contain a JSON object');
+        }
+        return parsed;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function extractExistingCommand(settings) {
+    const statusLine = settings.statusLine;
+    if (statusLine && typeof statusLine === 'object' && !Array.isArray(statusLine)) {
+        const command = statusLine.command;
+        if (typeof command === 'string')
+            return command;
+    }
+    return null;
+}
+function buildPlan(scope, settingsPath, settings, exists) {
+    const existingCommand = extractExistingCommand(settings);
+    const alreadyInstalled = existingCommand !== null && existingCommand.includes(STATUSLINE_COMMAND);
+    const conflict = existingCommand !== null && !alreadyInstalled;
+    return {
+        scope,
+        settingsPath,
+        exists,
+        alreadyInstalled,
+        conflict,
+        conflictCommand: conflict ? existingCommand : null,
+        desiredCommand: STATUSLINE_COMMAND
+    };
+}
+export function planStatusLineInstall(scope, projectRoot) {
+    const root = resolveSettingsRoot(scope, projectRoot);
+    const settingsPath = resolveSettingsPath(scope, projectRoot);
+    assertSafeSettingsPath(scope, root, settingsPath);
+    const exists = existsSync(settingsPath);
+    const settings = readSettings(settingsPath);
+    return buildPlan(scope, settingsPath, settings, exists);
+}
+function atomicWriteJson(settingsPath, settings) {
+    const dir = dirname(settingsPath);
+    mkdirSync(dir, { recursive: true });
+    const tempPath = join(dir, `.settings.${randomUUID()}.tmp`);
+    const fd = openSync(tempPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try {
+        writeFileSync(fd, `${JSON.stringify(settings, null, 2)}\n`, 'utf8');
+    }
+    finally {
+        closeSync(fd);
+    }
+    try {
+        renameSync(tempPath, settingsPath);
+    }
+    catch (error) {
+        try {
+            unlinkSync(tempPath);
+        }
+        catch {
+            // best effort cleanup
+        }
+        throw error;
+    }
+}
+export function applyStatusLineInstall(scope, projectRoot, options = {}) {
+    const root = resolveSettingsRoot(scope, projectRoot);
+    const settingsPath = resolveSettingsPath(scope, projectRoot);
+    assertSafeSettingsPath(scope, root, settingsPath);
+    const exists = existsSync(settingsPath);
+    const settings = readSettings(settingsPath);
+    const plan = buildPlan(scope, settingsPath, settings, exists);
+    if (plan.alreadyInstalled) {
+        return { ...plan, applied: false };
+    }
+    if (plan.conflict && !options.force) {
+        return { ...plan, applied: false };
+    }
+    const entry = { type: 'command', command: STATUSLINE_COMMAND, padding: 0 };
+    const nextSettings = { ...settings, statusLine: entry };
+    atomicWriteJson(settingsPath, nextSettings);
+    return { ...plan, applied: true };
+}
+export function removeStatusLineInstall(scope, projectRoot) {
+    const root = resolveSettingsRoot(scope, projectRoot);
+    const settingsPath = resolveSettingsPath(scope, projectRoot);
+    assertSafeSettingsPath(scope, root, settingsPath);
+    if (!existsSync(settingsPath)) {
+        return { scope, settingsPath, removed: false };
+    }
+    const settings = readSettings(settingsPath);
+    const existingCommand = extractExistingCommand(settings);
+    if (existingCommand === null || !existingCommand.includes(STATUSLINE_COMMAND)) {
+        return { scope, settingsPath, removed: false };
+    }
+    const { statusLine: _removed, ...rest } = settings;
+    atomicWriteJson(settingsPath, rest);
+    return { scope, settingsPath, removed: true };
+}

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

@@ -1 +1 @@
-export declare const CLI_VERSION = "1.1.0";
+export declare const CLI_VERSION = "1.1.2";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "1.1.0";
+export const CLI_VERSION = "1.1.2";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Peaks CLI and short skill family for Claude Code automation.",
   "author": "SquabbyZ",
   "license": "MIT",

package/schemas/doctor-report.schema.json

@@ -13,8 +13,8 @@
         "properties": {
           "id": {
             "type": "string",
-            "pattern": "^(skill|skill-name|skill-parse|skill-runbook|skill-apply-note|skill-presence|schema|config|doctor-self|capability):[A-Za-z0-9][A-Za-z0-9._-]*$",
-            "description": "Stable check id. Known prefixes: skill:<name> (required skill present), skill-name:<dir> (directory matches declared name), skill-parse:<dir> (skill metadata parsed), skill-runbook:<name> (Default runbook section exists), skill-apply-note:<name> (destructive --apply lines carry an authorization/--dry-run note), skill-presence:<topic> (status of .peaks/.active-skill.json — current/freshness), schema:<file> (schema file exists and is valid JSON), config:<scope> (optional config locations), doctor-self:<topic> (doctor validates its own output against this schema), capability:<name> (third-party capability is resolvable at the pinned version)."
+            "pattern": "^(skill|skill-name|skill-parse|skill-runbook|skill-apply-note|skill-presence|statusline|schema|config|doctor-self|capability):[A-Za-z0-9][A-Za-z0-9._-]*$",
+            "description": "Stable check id. Known prefixes: skill:<name> (required skill present), skill-name:<dir> (directory matches declared name), skill-parse:<dir> (skill metadata parsed), skill-runbook:<name> (Default runbook section exists), skill-apply-note:<name> (destructive --apply lines carry an authorization/--dry-run note), skill-presence:<topic> (status of .peaks/.active-skill.json — current/freshness), statusline:<topic> (whether the out-of-band Claude Code statusLine is installed), schema:<file> (schema file exists and is valid JSON), config:<scope> (optional config locations), doctor-self:<topic> (doctor validates its own output against this schema), capability:<name> (third-party capability is resolvable at the pinned version)."
           },
           "ok": { "type": "boolean" },
           "message": { "type": "string", "minLength": 1 }

package/skills/peaks-prd/SKILL.md

@@ -14,6 +14,13 @@ Before any analysis or tool call, immediately run:
 ```bash
 peaks skill presence:set peaks-prd --project <repo> --mode <mode> --gate startup
 ```
+
+On the first presence:set in a project, ensure the out-of-band status bar is installed so the user can see at a glance that Peaks is orchestrating — it renders the active skill in Claude Code's terminal status line, independent of model output:
+
+```bash
+peaks statusline install --project <repo>   # idempotent; skips if already installed
+```
+
 Read persistent project memory via CLI (durable, LLM-authored memories):
 
 ```bash

package/skills/peaks-qa/SKILL.md

@@ -14,6 +14,13 @@ Before any analysis or tool call, immediately run:
 ```bash
 peaks skill presence:set peaks-qa --project <repo> --mode <mode> --gate startup
 ```
+
+On the first presence:set in a project, ensure the out-of-band status bar is installed so the user can see at a glance that Peaks is orchestrating — it renders the active skill in Claude Code's terminal status line, independent of model output:
+
+```bash
+peaks statusline install --project <repo>   # idempotent; skips if already installed
+```
+
 Read persistent project memory via CLI (durable, LLM-authored memories):
 
 ```bash

package/skills/peaks-rd/SKILL.md

@@ -14,6 +14,13 @@ Before any analysis or tool call, immediately run:
 ```bash
 peaks skill presence:set peaks-rd --project <repo> --mode <mode> --gate startup
 ```
+
+On the first presence:set in a project, ensure the out-of-band status bar is installed so the user can see at a glance that Peaks is orchestrating — it renders the active skill in Claude Code's terminal status line, independent of model output:
+
+```bash
+peaks statusline install --project <repo>   # idempotent; skips if already installed
+```
+
 Read persistent project memory via CLI (durable, LLM-authored memories):
 
 ```bash

package/skills/peaks-sc/SKILL.md

@@ -14,6 +14,13 @@ Before any analysis or tool call, immediately run:
 ```bash
 peaks skill presence:set peaks-sc --project <repo> --mode <mode> --gate startup
 ```
+
+On the first presence:set in a project, ensure the out-of-band status bar is installed so the user can see at a glance that Peaks is orchestrating — it renders the active skill in Claude Code's terminal status line, independent of model output:
+
+```bash
+peaks statusline install --project <repo>   # idempotent; skips if already installed
+```
+
 Read persistent project memory via CLI (durable, LLM-authored memories):
 
 ```bash

package/skills/peaks-solo/SKILL.md

@@ -74,6 +74,12 @@ Only after the mode is known (user selected or explicitly named), run:
 peaks skill presence:set peaks-solo --project <repo> --mode <mode-value> --gate startup
 ```
 
+On the first presence:set in a project, ensure the out-of-band status bar is installed so the user can see at a glance that Peaks is orchestrating — it renders the active skill in Claude Code's terminal status line, independent of model output:
+
+```bash
+peaks statusline install --project <repo>   # idempotent; skips if already installed
+```
+
 Then display the compact status header: `Peaks-Cli Skill: peaks-solo | Peaks-Cli Gate: startup | Next: <one short action>`. Display this header on EVERY turn while the skill is active.
 
 Update with `peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate <gate>` when gates change. The presence file persists across the full workflow lifecycle — do NOT clear it at workflow end.

package/skills/peaks-txt/SKILL.md

@@ -14,6 +14,13 @@ Before any analysis or tool call, immediately run:
 ```bash
 peaks skill presence:set peaks-txt --project <repo> --mode <mode> --gate startup
 ```
+
+On the first presence:set in a project, ensure the out-of-band status bar is installed so the user can see at a glance that Peaks is orchestrating — it renders the active skill in Claude Code's terminal status line, independent of model output:
+
+```bash
+peaks statusline install --project <repo>   # idempotent; skips if already installed
+```
+
 Read persistent project memory via CLI (durable, LLM-authored memories):
 
 ```bash

package/skills/peaks-ui/SKILL.md

@@ -14,6 +14,13 @@ Before any analysis or tool call, immediately run:
 ```bash
 peaks skill presence:set peaks-ui --project <repo> --mode <mode> --gate startup
 ```
+
+On the first presence:set in a project, ensure the out-of-band status bar is installed so the user can see at a glance that Peaks is orchestrating — it renders the active skill in Claude Code's terminal status line, independent of model output:
+
+```bash
+peaks statusline install --project <repo>   # idempotent; skips if already installed
+```
+
 Read persistent project memory via CLI (durable, LLM-authored memories):
 
 ```bash