peaks-cli 1.0.11 → 1.0.13

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

@@ -6,6 +6,7 @@ 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 { fail, ok } from '../../shared/result.js';
 import { addJsonOption, failUnsupportedNonDryRun, getErrorMessage, isArtifactProvider, isArtifactSetupStep, printResult } from '../cli-helpers.js';
 export function registerCoreAndArtifactCommands(program, io) {
@@ -33,6 +34,28 @@ export function registerCoreAndArtifactCommands(program, io) {
             process.exitCode = 1;
         }
     });
+    addJsonOption(skill
+        .command('runbook <name>')
+        .description('Inspect a skill Default runbook section and its --apply authorization-note status')).action(async (name, options) => {
+        try {
+            const inspection = await inspectSkillRunbook(name);
+            const result = inspection.ok
+                ? ok('skill.runbook', inspection)
+                : fail('skill.runbook', inspection.hasRunbook ? 'SKILL_RUNBOOK_APPLY_UNGATED' : 'SKILL_RUNBOOK_MISSING', inspection.hasRunbook
+                    ? `Skill ${inspection.name} has ${inspection.destructiveApplyLines.length} destructive --apply command(s) without an authorization/dry-run note`
+                    : `Skill ${inspection.name} is missing a ## Default runbook section`, inspection, inspection.hasRunbook
+                    ? ['Add an authorization or --dry-run note next to destructive --apply lines in the runbook section']
+                    : ['Add a `## Default runbook` section to the skill SKILL.md']);
+            printResult(io, result, options.json);
+            if (!inspection.ok) {
+                process.exitCode = 1;
+            }
+        }
+        catch (error) {
+            printResult(io, fail('skill.runbook', 'SKILL_NOT_FOUND', getErrorMessage(error), { name }), options.json);
+            process.exitCode = 1;
+        }
+    });
     const profile = program.command('profile').description('Manage runtime profiles');
     addJsonOption(profile.command('list').description('List available profiles')).action((options) => {
         printResult(io, ok('profile.list', { profiles: listProfiles() }), options.json);

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

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

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

@@ -0,0 +1,144 @@
+import { InvalidArgumentError } from 'commander';
+import { readFile } from 'node:fs/promises';
+import { scanMcpServers } from '../../services/mcp/mcp-scan-service.js';
+import { planMcpInstall } from '../../services/mcp/mcp-plan-service.js';
+import { applyMcpInstall, rollbackMcpInstall } from '../../services/mcp/mcp-apply-service.js';
+import { callMcpTool } from '../../services/mcp/mcp-call-service.js';
+import { createStdioTransportFromSpec } from '../../services/mcp/mcp-stdio-transport.js';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, failUnsupportedNonDryRun, getErrorMessage, printResult } from '../cli-helpers.js';
+function parsePositiveInteger(value) {
+    if (!/^\d+$/.test(value)) {
+        throw new InvalidArgumentError('must be a positive integer');
+    }
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < 1) {
+        throw new InvalidArgumentError('must be a positive integer');
+    }
+    return parsed;
+}
+async function resolveCallArgs(options) {
+    if (options.argsJson !== undefined && options.args !== undefined) {
+        throw new Error('Pass either --args-json or --args, not both');
+    }
+    const raw = options.argsJson !== undefined
+        ? options.argsJson
+        : options.args !== undefined ? await readFile(options.args, 'utf8') : '{}';
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('MCP tool arguments must be a JSON object');
+    }
+    return parsed;
+}
+export function registerMcpCommands(program, io) {
+    const mcp = program.command('mcp').description('Manage Claude Code MCP servers');
+    addJsonOption(mcp
+        .command('list')
+        .alias('scan')
+        .description('Scan Claude Code settings for configured MCP servers')
+        .option('--project <path>', 'project root to also scan project-level .claude/settings.json')).action(async (options) => {
+        try {
+            const report = await scanMcpServers(options.project !== undefined ? { projectRoot: options.project } : {});
+            printResult(io, ok('mcp.list', report), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('mcp.list', 'MCP_LIST_FAILED', getErrorMessage(error), {}, ['Check Claude settings path and permissions before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(mcp
+        .command('plan')
+        .description('Plan an MCP server install diff for a capability (dry-run only)')
+        .requiredOption('--capability <id>', 'capability id from the MCP install registry')
+        .option('--project <path>', 'project root for scoped scan')
+        .option('--dry-run', 'preview the install diff (always true)', true)
+        .option('--no-dry-run', 'unsupported: peaks mcp plan never writes settings')).action(async (options) => {
+        if (options.dryRun === false) {
+            failUnsupportedNonDryRun(io, 'mcp.plan', options.json);
+            return;
+        }
+        try {
+            const planOptions = options.project !== undefined ? { projectRoot: options.project } : {};
+            const plan = await planMcpInstall(options.capability, planOptions);
+            if (plan.action === 'unknown-capability') {
+                printResult(io, fail('mcp.plan', 'MCP_UNKNOWN_CAPABILITY', `No MCP install spec registered for capability ${options.capability}`, plan, plan.nextActions), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('mcp.plan', plan, [], plan.nextActions), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('mcp.plan', 'MCP_PLAN_FAILED', getErrorMessage(error), { capabilityId: options.capability }, ['Check Claude settings path and the capability id before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(mcp
+        .command('apply')
+        .description('Apply an MCP server install for a capability (writes .claude/settings.json with backup)')
+        .requiredOption('--capability <id>', 'capability id from the MCP install registry')
+        .option('--yes', 'confirm the write — required for any real side effect')
+        .option('--claim', 'take ownership of an existing non-peaks-managed server entry')
+        .option('--project <path>', 'project root for scoped scan')).action(async (options) => {
+        if (options.yes !== true) {
+            printResult(io, fail('mcp.apply', 'MCP_APPLY_REQUIRES_YES', 'Refusing to apply without --yes', { capabilityId: options.capability }, ['Re-run with --yes to confirm the write']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const applyOptions = {};
+            if (options.project !== undefined) {
+                applyOptions.projectRoot = options.project;
+            }
+            if (options.claim === true) {
+                applyOptions.claim = true;
+            }
+            const result = await applyMcpInstall(options.capability, applyOptions);
+            printResult(io, ok('mcp.apply', result), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('mcp.apply', 'MCP_APPLY_FAILED', getErrorMessage(error), { capabilityId: options.capability }, ['Check the plan first with peaks mcp plan, then re-run apply']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(mcp
+        .command('rollback')
+        .description('Restore Claude Code settings.json from a peaks-managed MCP backup file')
+        .requiredOption('--backup <path>', 'path to a previously created backup settings.json')).action(async (options) => {
+        try {
+            const result = await rollbackMcpInstall({ backupPath: options.backup });
+            printResult(io, ok('mcp.rollback', result), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('mcp.rollback', 'MCP_ROLLBACK_FAILED', getErrorMessage(error), { backupPath: options.backup }, ['Verify the backup path and rerun']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(mcp
+        .command('call')
+        .description('Invoke a tool on an installed MCP server via stdio (spawns the server, calls tools/call, closes)')
+        .requiredOption('--capability <id>', 'capability id from the MCP install registry')
+        .requiredOption('--tool <name>', 'MCP tool name to invoke')
+        .option('--args <path>', 'path to a JSON file describing the tool arguments object')
+        .option('--args-json <jsonString>', 'inline JSON object describing the tool arguments')
+        .option('--timeout <ms>', 'per-request timeout in milliseconds', parsePositiveInteger)).action(async (options) => {
+        try {
+            const args = await resolveCallArgs(options);
+            const factory = createStdioTransportFromSpec;
+            const callOptions = {
+                capabilityId: options.capability,
+                toolName: options.tool,
+                args,
+                transportFactory: factory
+            };
+            if (options.timeout !== undefined) {
+                callOptions.timeoutMs = Number(options.timeout);
+            }
+            const result = await callMcpTool(callOptions);
+            printResult(io, ok('mcp.call', result), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('mcp.call', 'MCP_CALL_FAILED', getErrorMessage(error), { capabilityId: options.capability, toolName: options.tool }, ['Check the capability id, tool name, args JSON, and required env vars before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

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

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

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

@@ -0,0 +1,169 @@
+import { readFile } from 'node:fs/promises';
+import { loadOpenSpecChange, scanOpenSpec } from '../../services/openspec/openspec-scan-service.js';
+import { projectOpenSpecToRdInput } from '../../services/openspec/openspec-bridge-service.js';
+import { renderOpenSpecChange } from '../../services/openspec/openspec-render-service.js';
+import { validateOpenSpecChange } from '../../services/openspec/openspec-validate-service.js';
+import { archiveOpenSpecChange } from '../../services/openspec/openspec-archive-service.js';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+function resolveScanOptions(project) {
+    if (project === undefined) {
+        return {};
+    }
+    return { openspecRoot: `${project.replace(/\\/g, '/').replace(/\/$/, '')}/openspec` };
+}
+async function loadRenderRequest(requestPath) {
+    const raw = await readFile(requestPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('Render request file must contain a JSON object');
+    }
+    return parsed;
+}
+export function registerOpenSpecCommands(program, io) {
+    const openspec = program.command('openspec').description('Inspect OpenSpec changes inside the target project');
+    addJsonOption(openspec
+        .command('list')
+        .description('List OpenSpec changes detected under <project>/openspec/changes')
+        .option('--project <path>', 'project root containing an openspec/ directory')).action(async (options) => {
+        try {
+            const report = await scanOpenSpec(resolveScanOptions(options.project));
+            printResult(io, ok('openspec.list', report), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('openspec.list', 'OPENSPEC_LIST_FAILED', getErrorMessage(error), {}, ['Check the project path and openspec/ layout before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(openspec
+        .command('show')
+        .description('Show parsed proposal and tasks progress for a single OpenSpec change')
+        .argument('<changeId>', 'OpenSpec change directory name under openspec/changes')
+        .option('--project <path>', 'project root containing an openspec/ directory')).action(async (changeId, options) => {
+        try {
+            const detail = await loadOpenSpecChange(changeId, resolveScanOptions(options.project));
+            if (detail === null) {
+                printResult(io, fail('openspec.show', 'OPENSPEC_CHANGE_NOT_FOUND', `OpenSpec change ${changeId} was not found`, { changeId }, [`Verify openspec/changes/${changeId}/ exists`]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('openspec.show', detail), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('openspec.show', 'OPENSPEC_SHOW_FAILED', getErrorMessage(error), { changeId }, ['Check the project path and openspec/ layout before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(openspec
+        .command('to-rd')
+        .description('Project an OpenSpec change into an RD/SC input shape (acceptance, what-changes, commit boundaries)')
+        .argument('<changeId>', 'OpenSpec change directory name under openspec/changes')
+        .option('--project <path>', 'project root containing an openspec/ directory')).action(async (changeId, options) => {
+        try {
+            const projection = await projectOpenSpecToRdInput(changeId, resolveScanOptions(options.project));
+            if (projection === null) {
+                printResult(io, fail('openspec.to-rd', 'OPENSPEC_CHANGE_NOT_FOUND', `OpenSpec change ${changeId} was not found`, { changeId }, [`Verify openspec/changes/${changeId}/ exists`]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('openspec.to-rd', projection), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('openspec.to-rd', 'OPENSPEC_TO_RD_FAILED', getErrorMessage(error), { changeId }, ['Check the project path and openspec/ layout before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(openspec
+        .command('render')
+        .description('Render an OpenSpec change pack from a JSON request file (dry-run by default)')
+        .requiredOption('--request <path>', 'path to a JSON file describing the render request')
+        .option('--project <path>', 'project root containing an openspec/ directory')
+        .option('--apply', 'write the rendered files into openspec/changes/<id>/')
+        .option('--overwrite', 'overwrite an existing change directory when --apply is set')).action(async (options) => {
+        try {
+            const request = await loadRenderRequest(options.request);
+            const scan = resolveScanOptions(options.project);
+            const renderOptions = {};
+            if (scan.openspecRoot !== undefined) {
+                renderOptions.openspecRoot = scan.openspecRoot;
+            }
+            if (options.apply === true) {
+                renderOptions.apply = true;
+            }
+            if (options.overwrite === true) {
+                renderOptions.overwrite = true;
+            }
+            const result = await renderOpenSpecChange(request, renderOptions);
+            printResult(io, ok('openspec.render', result), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('openspec.render', 'OPENSPEC_RENDER_FAILED', getErrorMessage(error), { requestPath: options.request }, ['Check the request JSON shape and the openspec root before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(openspec
+        .command('validate')
+        .description('Validate an OpenSpec change against internal lint rules (and optionally the external openspec CLI)')
+        .argument('<changeId>', 'OpenSpec change directory name under openspec/changes')
+        .option('--project <path>', 'project root containing an openspec/ directory')
+        .option('--prefer-external', 'use the external openspec CLI when available, fall back to internal lint')).action(async (changeId, options) => {
+        try {
+            const scan = resolveScanOptions(options.project);
+            const validateOptions = {};
+            if (scan.openspecRoot !== undefined) {
+                validateOptions.openspecRoot = scan.openspecRoot;
+            }
+            if (options.preferExternal === true) {
+                validateOptions.preferExternal = true;
+            }
+            const result = await validateOpenSpecChange(changeId, validateOptions);
+            if (result === null) {
+                printResult(io, fail('openspec.validate', 'OPENSPEC_CHANGE_NOT_FOUND', `OpenSpec change ${changeId} was not found`, { changeId }, [`Verify openspec/changes/${changeId}/ exists`]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (!result.valid) {
+                printResult(io, fail('openspec.validate', 'OPENSPEC_VALIDATE_INVALID', `OpenSpec change ${changeId} failed validation`, result, result.issues.map((issue) => `${issue.level}: ${issue.rule}: ${issue.message}`)), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('openspec.validate', result, result.issues.filter((issue) => issue.level === 'warning').map((issue) => `${issue.rule}: ${issue.message}`)), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('openspec.validate', 'OPENSPEC_VALIDATE_FAILED', getErrorMessage(error), { changeId }, ['Check the project path and openspec/ layout before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(openspec
+        .command('archive')
+        .description('Move an OpenSpec change under openspec/changes/<archiveDir>/<id>/ (dry-run by default)')
+        .argument('<changeId>', 'OpenSpec change directory name under openspec/changes')
+        .option('--project <path>', 'project root containing an openspec/ directory')
+        .option('--apply', 'actually move the change directory')
+        .option('--archive-dir <name>', 'archive subdirectory name (default: archive)')).action(async (changeId, options) => {
+        try {
+            const scan = resolveScanOptions(options.project);
+            const archiveOptions = {};
+            if (scan.openspecRoot !== undefined) {
+                archiveOptions.openspecRoot = scan.openspecRoot;
+            }
+            if (options.apply === true) {
+                archiveOptions.apply = true;
+            }
+            if (options.archiveDir !== undefined) {
+                archiveOptions.archiveDirName = options.archiveDir;
+            }
+            const result = await archiveOpenSpecChange(changeId, archiveOptions);
+            if (result === null) {
+                printResult(io, fail('openspec.archive', 'OPENSPEC_CHANGE_NOT_FOUND', `OpenSpec change ${changeId} was not found`, { changeId }, [`Verify openspec/changes/${changeId}/ exists`]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('openspec.archive', result, [], result.applied ? [] : [`Re-run with --apply to move ${result.from} → ${result.to}`]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('openspec.archive', 'OPENSPEC_ARCHIVE_FAILED', getErrorMessage(error), { changeId }, ['Check the project path and openspec/ layout before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

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

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

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

@@ -0,0 +1,37 @@
+import { loadProjectDashboard } from '../../services/dashboard/project-dashboard-service.js';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+export function registerProjectCommands(program, io) {
+    const project = program.command('project').description('Aggregate Peaks state for a target project (read-only)');
+    addJsonOption(project
+        .command('dashboard')
+        .description('One-call snapshot of doctor / MCP / OpenSpec / requests / Understand Anything / capabilities for a project')
+        .requiredOption('--project <path>', 'target project root')).action(async (options) => {
+        try {
+            const dashboard = await loadProjectDashboard({ projectRoot: options.project });
+            if (!dashboard.runbookHealth.ok) {
+                const suggestions = [
+                    dashboard.runbookHealth.missingRunbook.length > 0
+                        ? `Add a ## Default runbook section to: ${dashboard.runbookHealth.missingRunbook.join(', ')}`
+                        : null,
+                    dashboard.runbookHealth.applyNoteFailed.length > 0
+                        ? `Add authorization/--dry-run notes next to destructive --apply lines in: ${dashboard.runbookHealth.applyNoteFailed.join(', ')}`
+                        : null
+                ].filter((line) => line !== null);
+                printResult(io, fail('project.dashboard', 'PROJECT_DASHBOARD_RUNBOOK_UNHEALTHY', `Skill runbook health failing: ${dashboard.runbookHealth.healthy}/${dashboard.runbookHealth.required} healthy`, dashboard, suggestions), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (!dashboard.doctor.ok) {
+                printResult(io, fail('project.dashboard', 'PROJECT_DASHBOARD_DOCTOR_FAILED', `Doctor reports ${dashboard.doctor.failed} failed check(s) (${dashboard.doctor.passed} passed)`, dashboard, ['Run `peaks doctor --json` and resolve the failing checks before re-running the dashboard']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('project.dashboard', dashboard), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('project.dashboard', 'PROJECT_DASHBOARD_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

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

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

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

@@ -0,0 +1,140 @@
+import { InvalidArgumentError } from 'commander';
+import { allowedStatesForRole, createRequestArtifact, listRequestArtifacts, showRequestArtifact, transitionRequestArtifact } from '../../services/artifacts/request-artifact-service.js';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+const VALID_ROLES = ['prd', 'ui', 'rd', 'qa'];
+function parseRole(value) {
+    if (!VALID_ROLES.includes(value)) {
+        throw new InvalidArgumentError(`must be one of ${VALID_ROLES.join(', ')}`);
+    }
+    return value;
+}
+function parseStateForRole(role, value) {
+    const allowed = allowedStatesForRole(role);
+    if (!allowed.includes(value)) {
+        throw new InvalidArgumentError(`must be one of ${allowed.join(', ')} for role ${role}`);
+    }
+    return value;
+}
+export function registerRequestCommands(program, io) {
+    const request = program.command('request').description('Manage per-request Peaks role artifacts (PRD / UI / RD / QA)');
+    addJsonOption(request
+        .command('init')
+        .description('Create the per-request artifact template for a Peaks role (dry-run by default)')
+        .requiredOption('--role <role>', `target role (${VALID_ROLES.join(' | ')})`, parseRole)
+        .requiredOption('--id <request-id>', 'request id, e.g. 2026-05-23-add-foo')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--session-id <session>', 'override the default date-stamped session id')
+        .option('--apply', 'write the artifact file (default: preview only)')).action(async (options) => {
+        try {
+            const serviceOptions = {
+                role: options.role,
+                requestId: options.id,
+                projectRoot: options.project
+            };
+            if (options.sessionId !== undefined) {
+                serviceOptions.sessionId = options.sessionId;
+            }
+            if (options.apply === true) {
+                serviceOptions.apply = true;
+            }
+            const result = await createRequestArtifact(serviceOptions);
+            printResult(io, ok('request.init', result, [], result.applied ? [] : [`Re-run with --apply to write ${result.path}`]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('request.init', 'REQUEST_INIT_FAILED', getErrorMessage(error), { role: options.role, requestId: options.id }, ['Check role, request id, and project path before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(request
+        .command('list')
+        .description('List per-request artifacts under a project workspace')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--session-id <session>', 'limit to a specific session id')
+        .option('--role <role>', `limit to a single role (${VALID_ROLES.join(' | ')})`, parseRole)).action(async (options) => {
+        try {
+            const listOptions = { projectRoot: options.project };
+            if (options.sessionId !== undefined) {
+                listOptions.sessionId = options.sessionId;
+            }
+            if (options.role !== undefined) {
+                listOptions.role = options.role;
+            }
+            const items = await listRequestArtifacts(listOptions);
+            printResult(io, ok('request.list', { count: items.length, items }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('request.list', 'REQUEST_LIST_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check project path before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(request
+        .command('show')
+        .description('Show a single per-request artifact, optionally scoped to a session')
+        .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) => {
+        try {
+            const showOptions = {
+                projectRoot: options.project,
+                role: options.role,
+                requestId
+            };
+            if (options.sessionId !== undefined) {
+                showOptions.sessionId = options.sessionId;
+            }
+            const result = await showRequestArtifact(showOptions);
+            if (result === null) {
+                printResult(io, fail('request.show', 'REQUEST_NOT_FOUND', `No artifact found for role=${options.role} requestId=${requestId}`, { role: options.role, requestId }, ['Verify the request id, role, and session id']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('request.show', result), 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);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(request
+        .command('transition')
+        .description('Move a per-request artifact to a new state defined by its role state machine')
+        .argument('<request-id>', 'request id, e.g. 2026-05-23-add-foo')
+        .requiredOption('--role <role>', `target role (${VALID_ROLES.join(' | ')})`, parseRole)
+        .requiredOption('--state <state>', 'new state name; allowed values depend on role')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--session-id <session>', 'restrict to a specific session id')
+        .option('--reason <text>', 'optional reason appended as a transition note')).action(async (requestId, options) => {
+        try {
+            const role = options.role;
+            const newState = parseStateForRole(role, options.state);
+            const transitionOptions = {
+                role,
+                requestId,
+                projectRoot: options.project,
+                newState
+            };
+            if (options.sessionId !== undefined) {
+                transitionOptions.sessionId = options.sessionId;
+            }
+            if (options.reason !== undefined) {
+                transitionOptions.reason = options.reason;
+            }
+            const result = await transitionRequestArtifact(transitionOptions);
+            if (result === null) {
+                printResult(io, fail('request.transition', 'REQUEST_NOT_FOUND', `No artifact found for role=${role} requestId=${requestId}`, { role, requestId }, ['Verify the request id, role, and session id']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('request.transition', result), options.json);
+        }
+        catch (error) {
+            if (error instanceof InvalidArgumentError) {
+                throw error;
+            }
+            printResult(io, fail('request.transition', 'REQUEST_TRANSITION_FAILED', getErrorMessage(error), { role: options.role, requestId }, ['Check role, request id, state, and project path before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

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

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

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

@@ -0,0 +1,78 @@
+import { InvalidArgumentError } from 'commander';
+import { scanUnderstandAnything, summarizeKnowledgeGraph } from '../../services/understand/understand-scan-service.js';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+function parsePositiveInteger(value) {
+    if (!/^\d+$/.test(value)) {
+        throw new InvalidArgumentError('must be a positive integer');
+    }
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < 1) {
+        throw new InvalidArgumentError('must be a positive integer');
+    }
+    return parsed;
+}
+const INSTALL_HINT = 'Install Understand Anything in Claude Code: `/plugin marketplace add Lum1104/Understand-Anything` then `/plugin install understand-anything`, then run `/understand` in the target project to generate .understand-anything/knowledge-graph.json.';
+export function registerUnderstandCommands(program, io) {
+    const understand = program.command('understand').description('Inspect Understand Anything artifacts inside a project (read-only)');
+    addJsonOption(understand
+        .command('status')
+        .description('Report whether Understand Anything has produced a knowledge graph in the target project')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--artifact-dir <path>', 'override the default .understand-anything directory')).action(async (options) => {
+        try {
+            const scanOptions = { projectRoot: options.project };
+            if (options.artifactDir !== undefined) {
+                scanOptions.artifactDir = options.artifactDir;
+            }
+            const report = await scanUnderstandAnything(scanOptions);
+            const nextActions = [];
+            if (!report.exists) {
+                nextActions.push(INSTALL_HINT);
+            }
+            else if (!report.graph.exists) {
+                nextActions.push('Run `/understand` inside Claude Code on this project to generate .understand-anything/knowledge-graph.json.');
+            }
+            else if (report.graph.parseError !== undefined) {
+                nextActions.push('Re-run `/understand` to regenerate the knowledge graph; the current file is not valid JSON.');
+            }
+            printResult(io, ok('understand.status', report, [], nextActions), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('understand.status', 'UNDERSTAND_STATUS_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path and .understand-anything directory before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(understand
+        .command('show')
+        .description('Summarize the Understand Anything knowledge graph (counts, layers, tours, sample nodes) for RD/TXT consumption')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--artifact-dir <path>', 'override the default .understand-anything directory')
+        .option('--sample <n>', 'maximum number of sample node ids to return (default 5)', parsePositiveInteger)).action(async (options) => {
+        try {
+            const summaryOptions = { projectRoot: options.project };
+            if (options.artifactDir !== undefined) {
+                summaryOptions.artifactDir = options.artifactDir;
+            }
+            if (options.sample !== undefined) {
+                summaryOptions.sampleSize = options.sample;
+            }
+            const summary = await summarizeKnowledgeGraph(summaryOptions);
+            if (!summary.exists) {
+                printResult(io, fail('understand.show', 'UNDERSTAND_GRAPH_MISSING', `No knowledge graph found at ${summary.path}`, summary, [INSTALL_HINT]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (summary.parseError !== undefined) {
+                printResult(io, fail('understand.show', 'UNDERSTAND_GRAPH_PARSE_ERROR', `Knowledge graph at ${summary.path} is not valid JSON: ${summary.parseError}`, summary, ['Re-run `/understand` to regenerate the knowledge graph']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('understand.show', summary), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('understand.show', 'UNDERSTAND_SHOW_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path and .understand-anything directory before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}