peaks-loop 4.0.0-beta.7 → 4.0.0-beta.8

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

@@ -1,548 +0,0 @@
-import { InvalidArgumentError } from 'commander';
-import { allowedStatesForRole, createRequestArtifact, listRequestArtifacts, showRequestArtifact, transitionRequestArtifact, PrerequisitesNotSatisfiedError, LintGateError, TypeSanityViolationError, FileSizeViolationError, VALID_REQUEST_TYPES, isRequestType } from '../../services/artifacts/request-artifact-service.js';
-import { ConfirmationRequiredError } from '../../services/mode/mode-enforcement.js';
-import { recordBypass, isBypassLimitReached, MAX_BYPASSES_PER_SESSION } from '../../services/mode/bypass-tracker.js';
-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)) {
-        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;
-}
-function parseRequestType(value) {
-    if (!isRequestType(value)) {
-        throw new InvalidArgumentError(`must be one of ${VALID_REQUEST_TYPES.join(', ')}`);
-    }
-    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. With --apply, also pre-creates the canonical change-id scope dir at .peaks/_runtime/change/<id>/ so sub-agents never write .peaks/_runtime/<id>/ at top level.')
-        .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)')
-        .option('--type <type>', `request type (${VALID_REQUEST_TYPES.join(' | ')}); default: feature`, parseRequestType)
-        // Slice 020 — caller-keyed session binding. Per-invocation override
-        // (D4 priority level 1). When set, the resolved callerId is surfaced
-        // in the JSON envelope; the on-disk artifact records it in the
-        // artifact body so future reads know which caller produced it.
-        .option('--caller-id <id>', 'Override the caller id for this invocation (D4 priority: flag beats env beats platform fallback). The resolved callerId is stamped on the artifact body and surfaced in the response envelope.')).action(async (options) => {
-        try {
-            // One-axis layout: --session-id is REQUIRED. The on-disk root
-            // is always `.peaks/_runtime/<sessionId>/<role>/...`. The user
-            // has forbidden the `.peaks/_runtime/<id>/` root layout — without an
-            // explicit session id, we cannot guarantee the artifact lands
-            // under `_runtime/`. See
-            // `.peaks/memory/2026-06-21-peaks-request-session-id-leaks-into-change-id.md`.
-            if (options.sessionId === undefined || options.sessionId.trim().length === 0) {
-                printResult(io, fail('request.init', 'SESSION_ID_REQUIRED', '--session-id is required: the CLI writes envelopes only to .peaks/_runtime/<sessionId>/... (one-axis layout)', { role: options.role, requestId: options.id }, ['Re-run with --session-id <sid>', 'Or run `peaks workspace init` to create a session first']), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            const serviceOptions = {
-                role: options.role,
-                requestId: options.id,
-                projectRoot: options.project
-            };
-            serviceOptions.sessionId = options.sessionId;
-            if (options.apply === true) {
-                serviceOptions.apply = true;
-            }
-            if (options.type !== undefined) {
-                serviceOptions.requestType = options.type;
-            }
-            // Slice 020.1 — resolve the callerId via D4 priority (flag > env >
-            // platform fallback > reject). The CLI integration layer is the
-            // single entry point for the resolver; we do not pre-judge whether
-            // the caller passed a flag. D2 (no callerId available) and D5
-            // (regex fail) both surface as `CALLER_ID_INVALID` with the inner
-            // `CallerIdError.source` propagated for caller-side audit.
-            const { resolveCallerId, CallerIdError } = await import('../../services/session/resolve-caller-id.js');
-            try {
-                const callerId = resolveCallerId(options.callerId !== undefined ? { flagValue: options.callerId } : {});
-                serviceOptions.callerId = callerId;
-            }
-            catch (error) {
-                if (error instanceof CallerIdError) {
-                    // D2 (EX_USAGE, exit 64) = nothing usable; D5 (EX_DATAERR, exit 65)
-                    // = something was passed but did not match the D1 regex.
-                    const code = error.code === 'EX_USAGE' ? 64 : 65;
-                    printResult(io, fail('request.init', 'CALLER_ID_INVALID', error.message, { source: error.source }, [
-                        'Set --caller-id to a value matching ^[a-zA-Z0-9._-]{1,200}$',
-                        'Or set PEAKS_CALLER_ID env var (or CLAUDE_CODE_SESSION_ID for Claude Code)'
-                    ]), options.json);
-                    process.exitCode = code;
-                    return;
-                }
-                throw error;
-            }
-            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. 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')
-        .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,
-                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;
-            }
-            // 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);
-            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>', 'reason appended as a transition note; required when --allow-incomplete is set')
-        .option('--allow-incomplete', 'bypass artifact prerequisite checks; requires --reason and records the bypass in the artifact')
-        .option('--confirm', 'skip interactive confirmation prompt (for non-interactive / LLM contexts)')
-        .option('--force-confirm', 'bypass mode-enforced confirmation (use with caution)')).action(async (requestId, options) => {
-        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;
-                return;
-            }
-            // Restrict --allow-incomplete in assisted/strict modes: require --confirm
-            if (options.allowIncomplete === true && options.forceConfirm !== true) {
-                const { getSkillPresence } = await import('../../services/skills/skill-presence-service.js');
-                const presence = getSkillPresence(options.project);
-                if (presence?.mode === 'assisted' || presence?.mode === 'strict') {
-                    if (options.confirm !== true) {
-                        printResult(io, fail('request.transition', 'ALLOW_INCOMPLETE_RESTRICTED', `--allow-incomplete requires --confirm in ${presence.mode} mode`, { role, requestId, mode: presence.mode }, ['Add --confirm to proceed non-interactively, or run in an interactive terminal.']), options.json);
-                        process.exitCode = 1;
-                        return;
-                    }
-                    // 2.7.1 fix: bypass-count must live under the canonical session
-                    // home `.peaks/_runtime/<sid>/`, NOT `.peaks/_runtime/<sid>/`. The legacy
-                    // path landed `.bypass-count.json` at the project root and was
-                    // ignored only by `.gitignore`, not by the runtime — a
-                    // back-compat reader on the root would never see it. The
-                    // canonical home is the same one `peaks session info --active`
-                    // resolves from `_runtime/session.json`, so all session-scoped
-                    // state (artifacts + bypass counter) now lives in one tree.
-                    const sessionRoot = (await import('node:path')).join(options.project, '.peaks', '_runtime', 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;
-                        return;
-                    }
-                    recordBypass(sessionRoot);
-                }
-            }
-            const transitionOptions = {
-                role,
-                requestId,
-                projectRoot: options.project,
-                newState
-            };
-            if (options.sessionId !== undefined) {
-                transitionOptions.sessionId = options.sessionId;
-            }
-            if (options.reason !== undefined) {
-                transitionOptions.reason = options.reason;
-            }
-            if (options.allowIncomplete === true) {
-                transitionOptions.allowIncomplete = true;
-            }
-            if (options.confirm === true) {
-                transitionOptions.confirmed = true;
-            }
-            if (options.forceConfirm === true) {
-                transitionOptions.forceConfirm = true;
-            }
-            // Type sanity check for PRD handoff
-            if (role === 'prd' && newState === 'handed-off') {
-                const { showRequestArtifact: showForType } = await import('../../services/artifacts/request-artifact-service.js');
-                const showTypeOptions = {
-                    projectRoot: options.project,
-                    role: 'prd',
-                    requestId
-                };
-                if (options.sessionId !== undefined) {
-                    showTypeOptions.sessionId = options.sessionId;
-                }
-                const existing = await showForType(showTypeOptions);
-                if (existing !== null) {
-                    transitionOptions.typeSanityCheck = { projectRoot: options.project, declaredType: existing.requestType };
-                }
-            }
-            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;
-            }
-            // Slice 2026-07-01-strategic-compact-cli — slice-boundary pre-compact
-            // hook. When transitioning across the RD → QA boundary (rd:qa-handoff),
-            // check the active session's context-fill ratio. If it is in the
-            // 0.85–0.95 pre-compact zone, write a checkpoint BEFORE the
-            // transition completes and attach `preCompactCheckpoint: true` to
-            // the response envelope. The LLM remains the decision-maker; this
-            // hook only surfaces the signal. The 0.95 red-line behaviour is
-            // unchanged — the existing auto-compact orchestrator continues to
-            // refuse dispatch at ratio ≥ 0.95.
-            let preCompact = null;
-            if (role === 'rd' && newState === 'qa-handoff') {
-                try {
-                    const { maybePreCompactCheckpoint } = await import('../../services/compact/request-transition-hook.js');
-                    const hook = maybePreCompactCheckpoint({
-                        projectRoot: options.project,
-                        sessionId: result.sessionId,
-                        transitionKey: `${role}:${newState}`
-                    });
-                    preCompact = hook.triggered
-                        ? ok('request.transition.preCompact', hook)
-                        : null;
-                }
-                catch {
-                    // The hook is best-effort; never block the transition.
-                    preCompact = null;
-                }
-            }
-            // v2.13.2 AC-4 — auto-regen prd/handoff.md on prd:handed-off success.
-            // Only fires when the handoff is missing; existing handoffs are not overwritten.
-            if (role === 'prd' && newState === 'handed-off' && options.sessionId !== undefined) {
-                const { autoRegenPrdHandoff } = await import('../../services/prd/handoff-auto-regen.js');
-                const regen = await autoRegenPrdHandoff({
-                    projectRoot: options.project,
-                    sessionId: result.sessionId,
-                    requestId,
-                    role: 'prd'
-                });
-                if (regen.status === 'created') {
-                    // Stitch into the result envelope
-                    printResult(io, ok('request.transition', { ...result, handoffAutoRegen: { status: 'created', path: regen.path, sha256: regen.sha256 } }), options.json);
-                    return;
-                }
-                if (regen.status === 'skipped-exists') {
-                    printResult(io, ok('request.transition', { ...result, handoffAutoRegen: { status: 'skipped-exists', path: regen.path } }), options.json);
-                    return;
-                }
-                // status === 'failed' — surface a warning but don't block the transition
-                printResult(io, ok('request.transition', { ...result, handoffAutoRegen: { status: 'failed', reason: regen.reason } }, [`prd handoff auto-regen failed: ${regen.reason}`]), options.json);
-                return;
-            }
-            // Slice 2026-07-01-strategic-compact-cli: stitch the pre-compact
-            // checkpoint signal into the final response envelope. When the
-            // hook did not trigger (zone is not pre-compact OR the
-            // transition is not a slice boundary), preCompact is null and
-            // we emit a `preCompactCheckpoint: null` field so LLM callers
-            // can branch on it without re-deriving zone membership.
-            printResult(io, ok('request.transition', { ...result, preCompactCheckpoint: preCompact?.data ?? null }, preCompact !== null
-                ? [
-                    `Pre-compact checkpoint written at ratio=${typeof preCompact.data === 'object' && preCompact.data !== null && 'ratio' in preCompact.data
-                        ? String(preCompact.data.ratio)
-                        : 'unknown'} (zone=pre-compact)`
-                ]
-                : []), options.json);
-        }
-        catch (error) {
-            if (error instanceof InvalidArgumentError) {
-                throw error;
-            }
-            if (error instanceof PrerequisitesNotSatisfiedError) {
-                // v2.13.3 AC-3 — surface `warnings` (soft-block entries from
-                // the 1-minor-release back-compat window, e.g. MUT_REPORT) so
-                // the operator sees both the hard-blocked `missing` paths and
-                // the soft-blocked ones. `warnings` is always present (possibly
-                // empty) to keep the response shape stable.
-                printResult(io, fail('request.transition', error.code, error.message, {
-                    role: error.role,
-                    newState: error.newState,
-                    sessionId: error.sessionId,
-                    missing: error.missing,
-                    warnings: error.warnings
-                }, [
-                    ...error.missing.map((entry) => `Produce ${entry.path}: ${entry.description}`),
-                    ...error.warnings.map((w) => `Soft-blocked (v2.13.3 back-compat window): ${w.path} — ${w.message}`),
-                    'Once every required artifact exists, rerun this transition.',
-                    'For exceptional cases (docs-only / config-only change), bypass with: --allow-incomplete --reason "<justification>"'
-                ]), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            if (error instanceof LintGateError) {
-                printResult(io, fail('request.transition', error.code, error.message, { role: error.role, newState: error.newState, errorCount: error.errorCount }, [
-                    'Fix lint errors in the artifact before transitioning.',
-                    'Run `peaks request lint --role <role> --id <rid> --project <path>` to see details.',
-                    'Or bypass with: --allow-incomplete --reason "<justification>"'
-                ]), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            if (error instanceof TypeSanityViolationError) {
-                printResult(io, fail('request.transition', error.code, error.message, { declaredType: error.declaredType, suggestedTypes: error.suggestedTypes, rationale: error.rationale }, [
-                    `Re-classify the request — likely correct type: ${error.suggestedTypes.join(' | ')}`,
-                    'Or, if the declared type is correct, surface the mismatch reason to the user.'
-                ]), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            if (error instanceof FileSizeViolationError) {
-                printResult(io, fail('request.transition', error.code, error.message, { violations: error.violations, threshold: error.threshold }, [
-                    ...error.violations.map((v) => `Split ${v.file} (${v.lines} lines) into smaller modules (< ${error.threshold} lines)`),
-                    'Or bypass with: --allow-incomplete --reason "<justification>"'
-                ]), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            if (error instanceof ConfirmationRequiredError) {
-                printResult(io, fail('request.transition', 'CONFIRMATION_REQUIRED', error.message, { role: options.role, requestId }, [
-                    'Add --confirm to proceed non-interactively.',
-                    'Or run in an interactive terminal.',
-                    'In assisted/strict mode, major workflow boundaries require explicit user approval.'
-                ]), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            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;
-        }
-    });
-    addJsonOption(request
-        .command('lint')
-        .description('Scan a request artifact body for unfilled placeholders (<...>, TBD, bare bullets) before declaring it complete')
-        .argument('<request-id>', 'request id')
-        .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 lintOptions = {
-                projectRoot: options.project,
-                role: options.role,
-                requestId
-            };
-            if (options.sessionId !== undefined) {
-                lintOptions.sessionId = options.sessionId;
-            }
-            const report = await lintRequestArtifact(lintOptions);
-            if (report === null) {
-                printResult(io, fail('request.lint', '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;
-            }
-            const nextActions = [];
-            if (!report.ok) {
-                nextActions.push(`Fix ${report.findings.filter((f) => f.severity === 'error').length} error finding(s) before transitioning this artifact.`);
-            }
-            printResult(io, ok('request.lint', report, [], nextActions), options.json);
-            if (!report.ok) {
-                process.exitCode = 1;
-            }
-        }
-        catch (error) {
-            printResult(io, fail('request.lint', 'REQUEST_LINT_FAILED', getErrorMessage(error), { role: options.role, requestId }, ['Verify the artifact path before retrying']), options.json);
-            process.exitCode = 1;
-        }
-    });
-    addJsonOption(request
-        .command('repair-status')
-        .description('Count RD↔QA repair cycles for a request from its RD artifact transition notes; reports cycle count and whether the 3-cycle cap is reached')
-        .argument('<request-id>', 'request id')
-        .requiredOption('--project <path>', 'target project root')
-        .option('--session-id <session>', 'restrict to a specific session id')
-        .option('--max-cycles <n>', 'override the default max cycle cap (default 3)')).action(async (requestId, options) => {
-        try {
-            const max = options.maxCycles !== undefined && /^\d+$/.test(options.maxCycles) ? Number(options.maxCycles) : 3;
-            const statusOptions = {
-                projectRoot: options.project,
-                requestId,
-                maxCycles: max
-            };
-            if (options.sessionId !== undefined) {
-                statusOptions.sessionId = options.sessionId;
-            }
-            const report = await getRepairCycleStatus(statusOptions);
-            if (report === null) {
-                printResult(io, fail('request.repair-status', 'REQUEST_NOT_FOUND', `No RD artifact found for requestId=${requestId}`, { requestId }, ['Verify the request id and session id']), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            const nextActions = [];
-            if (report.atCap) {
-                nextActions.push(`Repair cap reached (${report.cycleCount}/${report.maxCycles}). Emit a blocked TXT handoff and stop the loop.`);
-            }
-            else if (report.cycleCount > 0) {
-                nextActions.push(`${report.remaining} repair cycle(s) remaining before block.`);
-            }
-            printResult(io, ok('request.repair-status', report, [], nextActions), options.json);
-            if (report.atCap) {
-                process.exitCode = 1;
-            }
-        }
-        catch (error) {
-            printResult(io, fail('request.repair-status', 'REQUEST_REPAIR_STATUS_FAILED', getErrorMessage(error), { requestId }, ['Verify the artifact path before retrying']), options.json);
-            process.exitCode = 1;
-        }
-    });
-}

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

@@ -1,12 +0,0 @@
-import { Command } from 'commander';
-import { type ProgramIO } from '../cli-helpers.js';
-export interface RetrospectiveSearchCommandOptions {
-    query: string;
-    type?: string;
-    outcome?: string;
-    limit?: number;
-    project?: string;
-    json?: boolean;
-}
-export declare function runRetrospectiveSearch(io: ProgramIO, options: RetrospectiveSearchCommandOptions): void;
-export declare function registerRetrospectiveCommands(program: Command, io: ProgramIO): void;