peaks-cli 1.3.8 → 1.4.0

package/dist/src/cli/commands/core-artifact-commands.js

@@ -5,12 +5,14 @@ import { getArtifactWorkspaceStatus, planArtifactSync } from '../../services/art
 import { executeProjectMemoryBackup, executeProjectMemoryExtract, summarizeProjectMemoryBackupResult, summarizeProjectMemoryExtractResult } from '../../services/memory/project-memory-service.js';
 import { summarizeProjectStandardsInitResult, summarizeProjectStandardsUpdateResult } from '../../services/standards/project-standards-service.js';
 import { executeProjectStandardsInitIdeAware, executeProjectStandardsUpdateIdeAware } from '../../services/standards/ide-aware-standards-service.js';
+import { migrateStandards } from '../../services/standards/migrate-service.js';
 import { listProfiles } from '../../services/profiles/profile-service.js';
 import { planProxyTest } from '../../services/proxy/proxy-service.js';
 import { runDoctor } from '../../services/doctor/doctor-service.js';
 import { listSkills } from '../../services/skills/skill-registry.js';
 import { inspectSkillRunbook } from '../../services/skills/skill-runbook-service.js';
 import { setSkillPresence, clearSkillPresence, getSkillPresence, isSkillPresenceMode, touchSkillHeartbeat } from '../../services/skills/skill-presence-service.js';
+import { detectPresenceMarker } from '../../services/hooks/presence-marker-detector.js';
 import { getSessionId, getSessionMeta, rotateSessionBinding, setSessionMeta, setSessionTitle, listSessionMetas } from '../../services/session/session-manager.js';
 import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
 import { findProjectRoot } from '../../services/config/config-safety.js';
@@ -198,6 +200,16 @@ export function registerCoreAndArtifactCommands(program, io) {
             lastHeartbeat: updated.lastHeartbeat
         }), options.json);
     });
+    addJsonOption(skill
+        .command('detect-marker-loss')
+        .description('Detect whether the latest assistant message lost the Peaks-Cli status header while a peaks skill is still active (slice 028 detection primitive).')
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
+        .option('--message <text>', 'latest assistant message text to scan (defaults to reading the most recent LLM response from the stdin pipe, or empty string when no pipe is attached)')).action((options) => {
+        const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const message = options.message ?? '';
+        const result = detectPresenceMarker({ project: projectRoot, latestAssistantMessage: message });
+        printResult(io, ok('skill.detect-marker-loss', result), options.json);
+    });
     const session = program.command('session').description('Manage Peaks session directories');
     addJsonOption(session
         .command('list')
@@ -449,6 +461,21 @@ export function registerCoreAndArtifactCommands(program, io) {
             process.exitCode = 1;
         }
     });
+    addJsonOption(standards
+        .command('migrate')
+        .description('Rewrite a consumer project CLAUDE.md to drop the legacy heartbeat block (slice 028). Dry-run by default; pass --apply to write.')
+        .option('--project <path>', 'target project root')
+        .option('--apply', 'rewrite the legacy block in place; default is dry-run')).action((options) => {
+        const projectRoot = options.project ?? process.cwd();
+        try {
+            const result = migrateStandards({ project: projectRoot, apply: options.apply === true });
+            printResult(io, ok('standards.migrate', result.data, [], result.data.nextActions), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('standards.migrate', 'STANDARDS_MIGRATE_FAILED', getErrorMessage(error), { file: null, foundOldBlock: false, wouldChange: false, applied: false, before: null, after: null, nextActions: [] }, [getErrorMessage(error)]), options.json);
+            process.exitCode = 1;
+        }
+    });
     const memory = program.command('memory').description('Manage project-local Peaks memory');
     addJsonOption(memory
         .command('extract')

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

@@ -1,6 +1,8 @@
 import { loadProjectDashboard } from '../../services/dashboard/project-dashboard-service.js';
 import { generateProjectContext, readProjectContext } from '../../services/memory/project-context-service.js';
-import { extractSessionMemories, readMemoryIndex, readProjectMemories } from '../../services/memory/project-memory-service.js';
+import { extractSessionMemories, readMemoryIndex, readProjectMemories, readProjectMemoryBody } from '../../services/memory/project-memory-service.js';
+import { applyStalePolicy, DEFAULT_STALE_DAYS } from '../../shared/stale-policy.js';
+import { formatMdCompact } from '../../shared/format-md-compact.js';
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 export function registerProjectCommands(program, io) {
@@ -158,4 +160,59 @@ export function registerProjectCommands(program, io) {
             process.exitCode = 1;
         }
     });
+    // --- Show one project memory's body (R3: default = compact) ---
+    addJsonOption(project
+        .command('memories:show <name>')
+        .description('Show one project memory body by name. Default format is `compact` (LLM-primary); pass --pretty for the disk verbatim. Stale entries (default ≥30 days) are excluded; pass --include-stale or --stale-days <N> to override.')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--pretty', 'return the on-disk body verbatim; overrides the compact default')
+        .option('--include-stale', 'include stale entries (the default excludes them)')
+        .option('--stale-days <n>', 'override the 30-day stale threshold (must be > 0)', (value) => Number(value))).action((name, options) => {
+        try {
+            const memory = readProjectMemoryBody(options.project, name);
+            if (memory === null) {
+                printResult(io, fail('project.memories:show', 'MEMORY_NOT_FOUND', `memory ${name} not found in .peaks/memory`, { name, projectRoot: options.project }, ['Run `peaks project memories --json` to see available names']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            // Compute the stale decision. R4: stale is computed at CLI load time
+            // only; the source `.md` file is never modified.
+            const updatedAt = memory.updatedAt;
+            const thresholdDays = options.staleDays !== undefined && Number.isFinite(options.staleDays) && options.staleDays > 0
+                ? options.staleDays
+                : DEFAULT_STALE_DAYS;
+            const policy = applyStalePolicy([{ name: memory.name, updatedAt }], {
+                thresholdDays,
+                includeStale: options.includeStale === true
+            });
+            if (policy.entries.length === 0) {
+                const ageDays = policy.entries.length === 0 && policy.droppedCount > 0
+                    ? applyStalePolicy([{ name: memory.name, updatedAt }], { thresholdDays, includeStale: true }).entries[0]?.ageDays ?? 0
+                    : 0;
+                printResult(io, fail('project.memories:show', 'MEMORY_STALE', `memory ${name} is stale (age ${ageDays} days > ${thresholdDays} day threshold); pass --include-stale to override`, { name, ageDays, thresholdDays }, ['Pass --include-stale to load stale memories; pass --stale-days <N> to override the threshold']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const ageDays = policy.entries[0]?.ageDays ?? 0;
+            const isStale = policy.entries[0]?.stale ?? false;
+            const format = options.pretty === true ? 'pretty' : 'compact';
+            const body = format === 'pretty' ? memory.body : formatMdCompact(memory.body);
+            printResult(io, ok('project.memories:show', {
+                name: memory.name,
+                title: memory.title,
+                kind: memory.kind,
+                sourcePath: memory.filePath,
+                updatedAt,
+                ageDays,
+                stale: isStale,
+                body,
+                format,
+                bodyBytes: Buffer.byteLength(body, 'utf8')
+            }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('project.memories:show', 'PROJECT_MEMORY_SHOW_FAILED', getErrorMessage(error), { name, projectRoot: options.project }, ['Check the project path and .peaks/memory directory']), options.json);
+            process.exitCode = 1;
+        }
+    });
 }

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

@@ -5,7 +5,82 @@ import { recordBypass, isBypassLimitReached, MAX_BYPASSES_PER_SESSION } from '..
 import { lintRequestArtifact } from '../../services/artifacts/artifact-lint-service.js';
 import { getRepairCycleStatus } from '../../services/artifacts/repair-cycle-service.js';
 import { fail, ok } from '../../shared/result.js';
+import { formatMdCompact } from '../../shared/format-md-compact.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+/**
+ * Per-artifact default format. Only PRD and tech-doc are user-review
+ * surfaces; all other RD/QA/TXT artifacts default to compact. The
+ * `--pretty` / `--compact` flags override uniformly. See tech-doc
+ * §1.3.
+ */
+const DEFAULT_FORMAT_BY_ARTIFACT = {
+    prd: 'pretty',
+    'tech-doc': 'pretty',
+    'code-review': 'compact',
+    'security-review': 'compact',
+    'perf-baseline': 'compact',
+    'bug-analysis': 'compact',
+    'test-cases': 'compact',
+    'test-reports': 'compact',
+    'security-findings': 'compact',
+    'performance-findings': 'compact',
+    handoff: 'compact'
+};
+function resolveDefaultFormat(artifactName) {
+    return DEFAULT_FORMAT_BY_ARTIFACT[artifactName] ?? 'compact';
+}
+function applyPerArtifactFormat(envelope, override) {
+    if (override === null || envelope === null || typeof envelope !== 'object')
+        return envelope;
+    // The service returns `{ id, sessionId, role, body, ... }` for a
+    // single-artifact show. The per-artifact `body` field is the only
+    // thing that changes; we attach a `format` field to surface the
+    // choice to the caller. Slice 023 (R3) AC6 / AC7.
+    const obj = envelope;
+    if (typeof obj.body === 'string') {
+        return {
+            ...obj,
+            body: override === 'compact' ? formatMdCompact(obj.body) : obj.body,
+            format: override
+        };
+    }
+    return envelope;
+}
+/**
+ * Map a request-artifact envelope to a `DEFAULT_FORMAT_BY_ARTIFACT` key.
+ * The service returns the path of the artifact in `path`; the role +
+ * filename stem gives us the artifact name. Falls back to the role
+ * itself when no `path` field is present.
+ */
+function inferArtifactName(envelope, role) {
+    if (envelope === null || typeof envelope !== 'object')
+        return role;
+    const obj = envelope;
+    const pathField = typeof obj.path === 'string' ? obj.path : '';
+    // Path looks like `.peaks/_runtime/<sid>/<role>/requests/<file>.md`.
+    // The role is the second-to-last directory; the file stem is the
+    // last segment. For RD role, the artifact is one of {code-review,
+    // security-review, perf-baseline, bug-analysis, tech-doc}; the file
+    // stem usually carries the artifact name (e.g. `tech-doc.md`,
+    // `code-review-002.md`). We strip the trailing `-<digits>` suffix
+    // when present.
+    const stem = pathField.split(/[\\/]/).pop()?.replace(/\.md$/, '') ?? '';
+    if (stem.length > 0) {
+        // Try the stem verbatim first.
+        if (DEFAULT_FORMAT_BY_ARTIFACT[stem] !== undefined)
+            return stem;
+        // Strip a trailing -<digits> (e.g. code-review-002 -> code-review).
+        const trimmed = stem.replace(/-\d+$/, '');
+        if (DEFAULT_FORMAT_BY_ARTIFACT[trimmed] !== undefined)
+            return trimmed;
+        // Last-ditch: match by prefix.
+        for (const key of Object.keys(DEFAULT_FORMAT_BY_ARTIFACT)) {
+            if (stem.startsWith(key))
+                return key;
+        }
+    }
+    return role;
+}
 const VALID_ROLES = ['prd', 'ui', 'rd', 'qa', 'sc'];
 function parseRole(value) {
     if (!VALID_ROLES.includes(value)) {
@@ -119,11 +194,13 @@ export function registerRequestCommands(program, io) {
     });
     addJsonOption(request
         .command('show')
-        .description('Show a single per-request artifact, optionally scoped to a session')
+        .description('Show a single per-request artifact, optionally scoped to a session. R3: default body format is per-artifact (PRD/tech-doc pretty; everything else compact); pass --pretty or --compact to override uniformly.')
         .argument('<request-id>', 'request id, e.g. 2026-05-23-add-foo')
         .requiredOption('--role <role>', `target role (${VALID_ROLES.join(' | ')})`, parseRole)
         .requiredOption('--project <path>', 'target project root')
-        .option('--session-id <session>', 'restrict to a specific session id')).action(async (requestId, options) => {
+        .option('--session-id <session>', 'restrict to a specific session id')
+        .option('--pretty', 'force the body to render pretty (overrides the per-artifact default)')
+        .option('--compact', 'force the body to render compact (overrides the per-artifact default)')).action(async (requestId, options) => {
         try {
             const showOptions = {
                 projectRoot: options.project,
@@ -139,7 +216,20 @@ export function registerRequestCommands(program, io) {
                 process.exitCode = 1;
                 return;
             }
-            printResult(io, ok('request.show', result), options.json);
+            // R3: pick the per-artifact default format and apply the override
+            // if either flag is set. Last-flag-wins if both are passed.
+            const override = options.compact === true
+                ? 'compact'
+                : options.pretty === true
+                    ? 'pretty'
+                    : null;
+            const artifactName = inferArtifactName(result, options.role);
+            const format = override ?? resolveDefaultFormat(artifactName);
+            const transformed = applyPerArtifactFormat(result, override ?? format);
+            const payload = transformed === result
+                ? { ...result, format }
+                : transformed;
+            printResult(io, ok('request.show', payload), options.json);
         }
         catch (error) {
             printResult(io, fail('request.show', 'REQUEST_SHOW_FAILED', getErrorMessage(error), { role: options.role, requestId }, ['Check role, request id, and project path before retrying']), options.json);

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

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

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

@@ -0,0 +1,113 @@
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { loadRetrospectiveIndex } from '../../services/retrospective/retrospective-index.js';
+import { showRetrospective } from '../../services/retrospective/retrospective-show.js';
+import { migrateRetrospectiveFromMd } from '../../services/retrospective/migrate-from-md.js';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+export function registerRetrospectiveCommands(program, io) {
+    const retrospective = program.command('retrospective').description('Read the peaks retrospective index (R3: index.json, not the legacy <id>/ MD tree)');
+    addJsonOption(retrospective
+        .command('index')
+        .description('List all retrospective entries from .peaks/retrospective/index.json (R3: replaces the per-workflow MD dirs)')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')).action((options) => {
+        const projectRoot = options.project !== undefined
+            ? resolveCanonicalProjectRoot(options.project)
+            : (findProjectRoot(process.cwd()) ?? process.cwd());
+        try {
+            const result = loadRetrospectiveIndex(projectRoot);
+            const warnings = result.warning === null ? [] : [result.warning];
+            printResult(io, ok('retrospective.index', {
+                indexPath: result.indexPath,
+                source: result.source,
+                total: result.totalCount,
+                entries: result.entries
+            }, warnings), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('retrospective.index', 'RETROSPECTIVE_INDEX_FAILED', getErrorMessage(error), { projectRoot }, ['Check the project path and .peaks/retrospective/index.json']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(retrospective
+        .command('show <id>')
+        .description('Show one retrospective entry by id. Default format is `compact` (LLM-primary); pass --pretty to get the disk / re-hydrated pretty form.')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')
+        .option('--pretty', 'return the pretty form (re-hydrated from source artifacts); overrides the compact default')).action((id, options) => {
+        const projectRoot = options.project !== undefined
+            ? resolveCanonicalProjectRoot(options.project)
+            : (findProjectRoot(process.cwd()) ?? process.cwd());
+        try {
+            const format = options.pretty === true ? 'pretty' : 'compact';
+            const result = showRetrospective({ projectRoot, id, format });
+            if (!result.ok) {
+                const suggestions = [];
+                if (result.code === 'INDEX_MISSING')
+                    suggestions.push('Run `peaks retrospective migrate --apply` to build the index');
+                if (result.code === 'NOT_FOUND')
+                    suggestions.push('Run `peaks retrospective index --json` to see available ids');
+                if (result.code === 'ARTIFACT_MISSING' || result.missingArtifacts !== undefined) {
+                    suggestions.push('Re-hydrate from the legacy archive at .peaks/_archive/retrospective-2026-06-09-pre-r3.tar.gz');
+                }
+                printResult(io, fail('retrospective.show', result.code, result.message, { id, projectRoot, ...(result.missingArtifacts !== undefined ? { missingArtifacts: result.missingArtifacts } : {}) }, suggestions), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('retrospective.show', {
+                id: result.entry.id,
+                sessionId: result.entry.sessionId,
+                sliceId: result.entry.sliceId ?? null,
+                type: result.entry.type,
+                title: result.entry.title,
+                summary: result.entry.summary,
+                outcome: result.entry.outcome,
+                keyDecisions: result.entry.keyDecisions,
+                lessonsLearned: result.entry.lessonsLearned,
+                artifactPaths: result.entry.artifactPaths,
+                updatedAt: result.entry.updatedAt,
+                body: result.body,
+                format: result.format
+            }, result.warnings), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('retrospective.show', 'RETROSPECTIVE_SHOW_FAILED', getErrorMessage(error), { id, projectRoot }, ['Check the project path and id']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(retrospective
+        .command('migrate')
+        .description('One-time migration from per-workflow .peaks/retrospective/<id>/*.md dirs to a single .peaks/retrospective/index.json + .peaks/_archive/retrospective-2026-06-09-pre-r3.tar.gz archive. Dry-run by default; --apply is destructive.')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')
+        .option('--apply', 'write the index.json + archive + delete legacy MDs (default: dry-run preview)')
+        .option('--include-failed', 'include malformed MDs as best-effort entries; default is to skip + warn')
+        .option('--expected-entries <n>', 'override the default expected entry count (88) for the no-op check', (value) => Number(value))).action((options) => {
+        const projectRoot = options.project !== undefined
+            ? resolveCanonicalProjectRoot(options.project)
+            : (findProjectRoot(process.cwd()) ?? process.cwd());
+        try {
+            const result = migrateRetrospectiveFromMd({
+                projectRoot,
+                apply: options.apply === true,
+                includeFailed: options.includeFailed === true,
+                ...(options.expectedEntries !== undefined && Number.isFinite(options.expectedEntries) ? { expectedEntries: options.expectedEntries } : {})
+            });
+            const exitCode = result.status === 'failed' ? 1 : 0;
+            printResult(io, ok('retrospective.migrate', {
+                status: result.status,
+                indexPath: result.indexPath,
+                archivePath: result.archivePath,
+                totalLegacyDirs: result.totalLegacyDirs,
+                totalLegacyMds: result.totalLegacyMds,
+                parsedEntries: result.parsedEntries,
+                failedEntries: result.failedEntries,
+                archiveVerified: result.archiveVerified
+            }, result.warnings), options.json);
+            if (exitCode !== 0)
+                process.exitCode = exitCode;
+        }
+        catch (error) {
+            printResult(io, fail('retrospective.migrate', 'RETROSPECTIVE_MIGRATE_FAILED', getErrorMessage(error), { projectRoot }, ['Check the project path and .peaks/retrospective/ directory']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/src/cli/commands/skill-scope-commands.d.ts

@@ -0,0 +1,49 @@
+/**
+ * `peaks skill scope` CLI surface (slice 025.1).
+ *
+ * Four subcommands (mutually exclusive):
+ * - `--detect` — dry-run; prints the relevance matrix, never touches files.
+ * - `--apply`  — writes the source-of-truth + IDE-native config.
+ * - `--show`   — reads the source-of-truth + native config back.
+ * - `--reset`  — removes the source-of-truth + IDE-native config.
+ *
+ * Exit code matrix (tech-doc §6.3):
+ *   0  success
+ *   1  uncaught error
+ *   2  invalid usage (missing/incompatible flags)
+ *   3  source-of-truth written but adapter returned NOT_SUPPORTED
+ *   4  adapter failure other than NOT_SUPPORTED
+ */
+import { Command } from 'commander';
+import { type ResultEnvelope } from '../../shared/result.js';
+import { type ProgramIO } from '../cli-helpers.js';
+export type SkillScopeAction = 'detect' | 'apply' | 'show' | 'reset';
+export interface RunSkillScopeInput {
+    readonly subcommand: SkillScopeAction;
+    readonly project: string;
+    readonly strict?: boolean;
+    readonly loose?: boolean;
+    readonly ide?: string;
+    readonly shadowFallback?: boolean;
+    readonly json?: boolean;
+    /** Test seam: override the detected allowlist (CLI re-adds peaks-* per G6). */
+    readonly overrideAllowlist?: readonly string[];
+    /** Test seam: force the source-of-truth write to fail (simulates atomicity test). */
+    readonly simulateSourceOfTruthWriteFailure?: boolean;
+}
+export interface RunSkillScopeResult {
+    readonly exitCode: number;
+    readonly envelope: ResultEnvelope<unknown> | null;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/**
+ * Programmatic entry point for `peaks skill scope`. Used by the CLI shim
+ * AND by the unit tests.
+ */
+export declare function runSkillScopeCommand(input: RunSkillScopeInput): Promise<RunSkillScopeResult>;
+/**
+ * Register the `peaks skill scope` subcommand on the `skill` command group.
+ * Mutually-exclusive flags: exactly one of --detect / --apply / --show / --reset.
+ */
+export declare function registerSkillScopeCommands(program: Command, io: ProgramIO): void;