peaks-cli 1.0.17 → 1.0.19

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

@@ -1,5 +1,7 @@
 import { InvalidArgumentError } from 'commander';
-import { allowedStatesForRole, createRequestArtifact, listRequestArtifacts, showRequestArtifact, transitionRequestArtifact } from '../../services/artifacts/request-artifact-service.js';
+import { allowedStatesForRole, createRequestArtifact, listRequestArtifacts, showRequestArtifact, transitionRequestArtifact, PrerequisitesNotSatisfiedError, VALID_REQUEST_TYPES, isRequestType } from '../../services/artifacts/request-artifact-service.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 { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 const VALID_ROLES = ['prd', 'ui', 'rd', 'qa', 'sc'];
@@ -16,6 +18,12 @@ function parseStateForRole(role, value) {
     }
     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
@@ -25,7 +33,8 @@ export function registerRequestCommands(program, io) {
         .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) => {
+        .option('--apply', 'write the artifact file (default: preview only)')
+        .option('--type <type>', `request type (${VALID_REQUEST_TYPES.join(' | ')}); default: feature`, parseRequestType)).action(async (options) => {
         try {
             const serviceOptions = {
                 role: options.role,
@@ -38,6 +47,9 @@ export function registerRequestCommands(program, io) {
             if (options.apply === true) {
                 serviceOptions.apply = true;
             }
+            if (options.type !== undefined) {
+                serviceOptions.requestType = options.type;
+            }
             const result = await createRequestArtifact(serviceOptions);
             printResult(io, ok('request.init', result, [], result.applied ? [] : [`Re-run with --apply to write ${result.path}`]), options.json);
         }
@@ -105,10 +117,16 @@ export function registerRequestCommands(program, io) {
         .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) => {
+        .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')).action(async (requestId, options) => {
         try {
             const role = options.role;
             const newState = parseStateForRole(role, options.state);
+            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;
+            }
             const transitionOptions = {
                 role,
                 requestId,
@@ -121,6 +139,9 @@ export function registerRequestCommands(program, io) {
             if (options.reason !== undefined) {
                 transitionOptions.reason = options.reason;
             }
+            if (options.allowIncomplete === true) {
+                transitionOptions.allowIncomplete = true;
+            }
             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);
@@ -133,8 +154,93 @@ export function registerRequestCommands(program, io) {
             if (error instanceof InvalidArgumentError) {
                 throw error;
             }
+            if (error instanceof PrerequisitesNotSatisfiedError) {
+                printResult(io, fail('request.transition', error.code, error.message, { role: error.role, newState: error.newState, sessionId: error.sessionId, missing: error.missing }, [
+                    ...error.missing.map((entry) => `Produce ${entry.path}: ${entry.description}`),
+                    '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;
+            }
             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/scan-commands.d.ts

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

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

@@ -0,0 +1,194 @@
+import { InvalidArgumentError } from 'commander';
+import { scanArchetype } from '../../services/scan/archetype-service.js';
+import { scanExistingSystem } from '../../services/scan/existing-system-service.js';
+import { checkTypeSanity } from '../../services/scan/type-sanity-service.js';
+import { getAcceptanceCoverage, isAcceptanceCoverageError } from '../../services/scan/acceptance-coverage-service.js';
+import { getDiffVsScope, isDiffScopeError } from '../../services/scan/diff-scope-service.js';
+import { isRequestType, VALID_REQUEST_TYPES } from '../../services/artifacts/artifact-prerequisites.js';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+function parsePositiveInt(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!/^\d+$/.test(value))
+        return fallback;
+    const parsed = Number(value);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+function parseRequestType(value) {
+    if (!isRequestType(value)) {
+        throw new InvalidArgumentError(`must be one of ${VALID_REQUEST_TYPES.join(', ')}`);
+    }
+    return value;
+}
+export function registerScanCommands(program, io) {
+    const scan = program.command('scan').description('Deterministic project scans (archetype, existing system) for Peaks workflows');
+    addJsonOption(scan
+        .command('archetype')
+        .description('Detect project archetype, frontend-only mode, and supporting signals from the filesystem (read-only)')
+        .requiredOption('--project <path>', 'target project root')).action(async (options) => {
+        try {
+            const report = await scanArchetype({ projectRoot: options.project });
+            const nextActions = [];
+            if (report.archetype === 'unknown') {
+                nextActions.push('Archetype could not be determined; surface to user before proceeding.');
+            }
+            else if (report.archetype === 'legacy-frontend' || report.archetype === 'legacy-fullstack' || report.archetype === 'frontend-monorepo') {
+                nextActions.push('Run `peaks scan existing-system --project <path>` to extract visual tokens and conventions.');
+            }
+            printResult(io, ok('scan.archetype', report, [], nextActions), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('scan.archetype', 'SCAN_ARCHETYPE_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path exists and is readable']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(scan
+        .command('existing-system')
+        .description('Extract visual tokens (colors/spacing/typography/radii) and code conventions from a legacy project (read-only)')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--max-tokens <n>', 'maximum tokens to return per category (default 40)')
+        .option('--max-samples <n>', 'maximum convention samples per kind (default 5)')).action(async (options) => {
+        try {
+            const report = await scanExistingSystem({
+                projectRoot: options.project,
+                maxTokens: parsePositiveInt(options.maxTokens, 40),
+                maxSamplesPerKind: parsePositiveInt(options.maxSamples, 5)
+            });
+            const nextActions = [];
+            if (!report.scanned) {
+                nextActions.push(report.scanSkippedReason ?? 'Extraction skipped.');
+            }
+            else if (report.inconsistencies.length > 0) {
+                nextActions.push('Surface inconsistencies in the TXT handoff before proceeding.');
+            }
+            printResult(io, ok('scan.existing-system', report, [], nextActions), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('scan.existing-system', 'SCAN_EXISTING_SYSTEM_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path exists and is readable']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(scan
+        .command('request-type-sanity')
+        .description('Cross-verify a declared --type against the actual git diff file mix (catches "feature mis-declared as docs" workflow violations)')
+        .requiredOption('--project <path>', 'target project root')
+        .requiredOption('--type <type>', `declared request type (${VALID_REQUEST_TYPES.join(' | ')})`, parseRequestType)
+        .option('--base-ref <ref>', 'compare working tree against this git ref (default: HEAD)')).action((options) => {
+        try {
+            const serviceOptions = { projectRoot: options.project, declaredType: options.type };
+            if (options.baseRef !== undefined) {
+                serviceOptions.baseRef = options.baseRef;
+            }
+            const report = checkTypeSanity(serviceOptions);
+            const nextActions = [];
+            if (!report.consistent) {
+                nextActions.push(`Re-classify the request — likely correct type: ${report.suggestedTypes.join(' | ')}`);
+                nextActions.push('Or, if the declared type is correct, surface the mismatch reason to the user in the TXT handoff.');
+            }
+            if (!report.gitAvailable) {
+                nextActions.push('git not available; manual cross-check required.');
+            }
+            printResult(io, ok('scan.request-type-sanity', report, [], nextActions), options.json);
+            if (!report.consistent) {
+                process.exitCode = 1;
+            }
+        }
+        catch (error) {
+            if (error instanceof InvalidArgumentError)
+                throw error;
+            printResult(io, fail('scan.request-type-sanity', 'REQUEST_TYPE_SANITY_FAILED', getErrorMessage(error), { projectRoot: options.project, type: options.type }, ['Verify the project path is a git repository or omit the check']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(scan
+        .command('acceptance-coverage')
+        .description('Verify every PRD "Acceptance criteria" item has at least one linked QA test case (via `- **Acceptance:** A1, A2` field in qa/test-cases/<rid>.md)')
+        .requiredOption('--rid <request-id>', 'request id')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--session-id <session>', 'restrict to a specific session id')).action(async (options) => {
+        try {
+            const coverageOptions = { projectRoot: options.project, requestId: options.rid };
+            if (options.sessionId !== undefined) {
+                coverageOptions.sessionId = options.sessionId;
+            }
+            const result = await getAcceptanceCoverage(coverageOptions);
+            if (isAcceptanceCoverageError(result)) {
+                const code = result.kind === 'prd-not-found' ? 'PRD_NOT_FOUND' : 'TEST_CASES_NOT_FOUND';
+                const message = result.kind === 'prd-not-found'
+                    ? `PRD artifact for requestId=${options.rid} not found`
+                    : `QA test-cases file not found at ${result.expectedPath}`;
+                printResult(io, fail('scan.acceptance-coverage', code, message, { requestId: options.rid }, [
+                    result.kind === 'prd-not-found'
+                        ? 'Run `peaks request init --role prd --id <rid> --apply --type <type>` first.'
+                        : 'Generate qa/test-cases/<rid>.md before running this check.'
+                ]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const nextActions = [];
+            if (result.acceptanceItems.length === 0) {
+                nextActions.push('PRD has no "## Acceptance criteria" bullets. Fill them in before running the coverage check.');
+            }
+            if (result.uncovered.length > 0) {
+                nextActions.push(`${result.uncovered.length} acceptance item(s) have no linked test case. Add a "- **Acceptance:** ${result.uncovered.map((u) => u.id).join(', ')}" field to the relevant test cases.`);
+            }
+            if (result.invalidReferences.length > 0) {
+                nextActions.push(`${result.invalidReferences.length} test case(s) reference an acceptance id that does not exist in the PRD. Fix or remove these references.`);
+            }
+            if (result.unlinkedTestCases.length > 0) {
+                nextActions.push(`${result.unlinkedTestCases.length} test case(s) have no Acceptance: field. Link them to acceptance items, or document why they exist (e.g. defense-in-depth regressions).`);
+            }
+            printResult(io, ok('scan.acceptance-coverage', result, [], nextActions), options.json);
+            if (!result.ok) {
+                process.exitCode = 1;
+            }
+        }
+        catch (error) {
+            printResult(io, fail('scan.acceptance-coverage', 'ACCEPTANCE_COVERAGE_FAILED', getErrorMessage(error), { requestId: options.rid }, ['Verify the project path and artifacts before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(scan
+        .command('diff-vs-scope')
+        .description('Verify every file in the git diff matches the RD artifact "Red-line scope" patterns; flags out-of-scope writes and unclassified files')
+        .requiredOption('--rid <request-id>', 'request id')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--session-id <session>', 'restrict to a specific session id')
+        .option('--base-ref <ref>', 'compare working tree against this git ref (default: HEAD)')).action(async (options) => {
+        try {
+            const scopeOptions = { projectRoot: options.project, requestId: options.rid };
+            if (options.sessionId !== undefined)
+                scopeOptions.sessionId = options.sessionId;
+            if (options.baseRef !== undefined)
+                scopeOptions.baseRef = options.baseRef;
+            const result = await getDiffVsScope(scopeOptions);
+            if (isDiffScopeError(result)) {
+                printResult(io, fail('scan.diff-vs-scope', 'RD_NOT_FOUND', `RD artifact for requestId=${options.rid} not found`, { requestId: options.rid }, ['Run `peaks request init --role rd --id <rid> --apply --type <type>` first.']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const nextActions = [];
+            if (!result.gitAvailable) {
+                nextActions.push('git not available; scope check skipped. Cross-check the diff manually.');
+            }
+            if (!result.patternsDeclared) {
+                nextActions.push('RD artifact has no in-scope or out-of-scope patterns under "## Red-line scope". Add concrete path/glob patterns (e.g. `src/services/login/**`) before re-running.');
+            }
+            if (result.violations.length > 0) {
+                nextActions.push(`${result.violations.length} file(s) match an explicit out-of-scope pattern. Revert these or expand the RD red-line scope with PRD approval.`);
+            }
+            if (result.unclassified.length > 0) {
+                nextActions.push(`${result.unclassified.length} changed file(s) do not match any declared scope pattern. Either add them to the in-scope list (if intentional) or revert them.`);
+            }
+            printResult(io, ok('scan.diff-vs-scope', result, [], nextActions), options.json);
+            if (!result.ok) {
+                process.exitCode = 1;
+            }
+        }
+        catch (error) {
+            printResult(io, fail('scan.diff-vs-scope', 'DIFF_VS_SCOPE_FAILED', getErrorMessage(error), { requestId: options.rid }, ['Verify the project path is a git repository and the RD artifact exists']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

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

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

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

@@ -0,0 +1,32 @@
+import { initWorkspace, InvalidSessionIdError } from '../../services/workspace/workspace-service.js';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+export function registerWorkspaceCommands(program, io) {
+    const workspace = program.command('workspace').description('Manage the Peaks per-session artifact workspace (.peaks/<session-id>/)');
+    addJsonOption(workspace
+        .command('init')
+        .description('Create the .peaks/<session-id>/ directory structure (prd, ui, rd, qa, sc, txt, system) — validates the session id format')
+        .requiredOption('--project <path>', 'target project root')
+        .requiredOption('--session-id <id>', 'session id in YYYY-MM-DD-<kebab-slug> format')).action(async (options) => {
+        try {
+            const report = await initWorkspace({ projectRoot: options.project, sessionId: options.sessionId });
+            const nextActions = [];
+            if (report.created.length === 0) {
+                nextActions.push('Workspace already initialized — proceed to project scan.');
+            }
+            else {
+                nextActions.push('Run `peaks scan archetype --project <path> --json` next to populate rd/project-scan.md.');
+            }
+            printResult(io, ok('workspace.init', report, [], nextActions), options.json);
+        }
+        catch (error) {
+            if (error instanceof InvalidSessionIdError) {
+                printResult(io, fail('workspace.init', error.code, error.message, { sessionId: options.sessionId }, ['Use a date-prefixed kebab slug like 2026-05-25-add-user-auth']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, fail('workspace.init', 'WORKSPACE_INIT_FAILED', getErrorMessage(error), { projectRoot: options.project, sessionId: options.sessionId }, ['Verify the project path exists and is writable']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/src/cli/program.js

@@ -8,8 +8,10 @@ import { registerMcpCommands } from './commands/mcp-commands.js';
 import { registerOpenSpecCommands } from './commands/openspec-commands.js';
 import { registerProjectCommands } from './commands/project-commands.js';
 import { registerRequestCommands } from './commands/request-commands.js';
+import { registerScanCommands } from './commands/scan-commands.js';
 import { registerShadcnCommands } from './commands/shadcn-commands.js';
 import { registerUnderstandCommands } from './commands/understand-commands.js';
+import { registerWorkspaceCommands } from './commands/workspace-commands.js';
 export { printResult } from './cli-helpers.js';
 export function createProgram(io = { stdout: (text) => console.log(text), stderr: (text) => console.error(text) }) {
     const program = new Command();
@@ -36,7 +38,9 @@ export function createProgram(io = { stdout: (text) => console.log(text), stderr
     registerOpenSpecCommands(program, io);
     registerProjectCommands(program, io);
     registerRequestCommands(program, io);
+    registerScanCommands(program, io);
     registerShadcnCommands(program, io);
     registerUnderstandCommands(program, io);
+    registerWorkspaceCommands(program, io);
     return program;
 }

package/dist/src/services/artifacts/artifact-lint-service.d.ts

@@ -0,0 +1,23 @@
+import { type RequestArtifactRole } from './request-artifact-service.js';
+export type ArtifactLintSeverity = 'error' | 'warning';
+export type ArtifactLintFinding = {
+    line: number;
+    text: string;
+    reason: string;
+    severity: ArtifactLintSeverity;
+};
+export type ArtifactLintReport = {
+    ok: boolean;
+    role: RequestArtifactRole;
+    requestId: string;
+    path: string;
+    totalLines: number;
+    findings: ArtifactLintFinding[];
+};
+export type LintArtifactOptions = {
+    projectRoot: string;
+    role: RequestArtifactRole;
+    requestId: string;
+    sessionId?: string;
+};
+export declare function lintRequestArtifact(options: LintArtifactOptions): Promise<ArtifactLintReport | null>;

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

@@ -0,0 +1,80 @@
+import { showRequestArtifact } from './request-artifact-service.js';
+const RULES = [
+    {
+        test: (line) => /<[A-Za-z][^>]*>/.test(line.trim()) && !/^\s*-?\s*linked-/i.test(line),
+        reason: 'Contains an unfilled <placeholder> token',
+        severity: 'error'
+    },
+    {
+        test: (line) => /^\s*-\s*\.\.\.\s*$/.test(line),
+        reason: 'Bullet point is only "..." — replace with real content',
+        severity: 'error'
+    },
+    {
+        test: (line) => /\bTBD\b|\bTODO\b|\bFIXME\b|\bXXX\b/.test(line),
+        reason: 'Contains TBD/TODO/FIXME/XXX marker',
+        severity: 'warning'
+    },
+    {
+        test: (line) => /^\s*-\s*$/.test(line),
+        reason: 'Empty bullet point — replace with real content or remove',
+        severity: 'warning'
+    }
+];
+// Lines that should never be flagged even if they match a rule (template scaffolding).
+const ALLOWLIST_PATTERNS = [
+    /^#+\s/, // markdown headers
+    /^\s*```/, // code fences
+    /^\s*-\s*last update:/i, // metadata
+    /^\s*-\s*created:/i,
+    /^\s*-\s*state:/i,
+    /^\s*-\s*type:\s*(feature|bugfix|refactor|docs|config|chore)\s*$/i,
+    /^\s*-\s*session:\s*[a-z0-9-]+/i,
+    /^\s*-\s*transition note/i // bypass / repair notes are not placeholders
+];
+function isAllowlisted(line) {
+    return ALLOWLIST_PATTERNS.some((pattern) => pattern.test(line));
+}
+export async function lintRequestArtifact(options) {
+    const showOptions = {
+        projectRoot: options.projectRoot,
+        role: options.role,
+        requestId: options.requestId
+    };
+    if (options.sessionId !== undefined) {
+        showOptions.sessionId = options.sessionId;
+    }
+    const artifact = await showRequestArtifact(showOptions);
+    if (artifact === null) {
+        return null;
+    }
+    const lines = artifact.content.split(/\r?\n/);
+    const findings = [];
+    for (let index = 0; index < lines.length; index += 1) {
+        const rawLine = lines[index];
+        if (rawLine === undefined)
+            continue;
+        if (isAllowlisted(rawLine))
+            continue;
+        for (const rule of RULES) {
+            if (rule.test(rawLine)) {
+                findings.push({
+                    line: index + 1,
+                    text: rawLine.trim(),
+                    reason: rule.reason,
+                    severity: rule.severity
+                });
+                break;
+            }
+        }
+    }
+    const hasError = findings.some((finding) => finding.severity === 'error');
+    return {
+        ok: !hasError,
+        role: options.role,
+        requestId: options.requestId,
+        path: artifact.path,
+        totalLines: lines.length,
+        findings
+    };
+}

package/dist/src/services/artifacts/artifact-prerequisites.d.ts

@@ -0,0 +1,28 @@
+import type { RequestArtifactRole, RequestArtifactState } from './request-artifact-service.js';
+export type RequestType = 'feature' | 'bugfix' | 'refactor' | 'docs' | 'config' | 'chore';
+export declare const VALID_REQUEST_TYPES: ReadonlyArray<RequestType>;
+export declare const DEFAULT_REQUEST_TYPE: RequestType;
+export declare function isRequestType(value: string): value is RequestType;
+export type ArtifactPrerequisite = {
+    /** Relative path under `.peaks/<session-id>/`. May contain `<rid>` placeholder. */
+    relativePath: string;
+    /** Human-readable description of what this artifact represents. */
+    description: string;
+};
+export type PrerequisiteCheckResult = {
+    ok: boolean;
+    missing: Array<{
+        path: string;
+        description: string;
+    }>;
+};
+export type CheckPrerequisitesOptions = {
+    projectRoot: string;
+    sessionId: string;
+    role: RequestArtifactRole;
+    newState: RequestArtifactState;
+    requestId: string;
+    requestType?: RequestType;
+};
+export declare function getPrerequisitesFor(role: RequestArtifactRole, newState: RequestArtifactState, requestType?: RequestType): ReadonlyArray<ArtifactPrerequisite>;
+export declare function checkPrerequisites(options: CheckPrerequisitesOptions): Promise<PrerequisiteCheckResult>;

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

@@ -0,0 +1,77 @@
+import { join } from 'node:path';
+import { pathExists } from '../../shared/fs.js';
+export const VALID_REQUEST_TYPES = [
+    'feature',
+    'bugfix',
+    'refactor',
+    'docs',
+    'config',
+    'chore'
+];
+export const DEFAULT_REQUEST_TYPE = 'feature';
+export function isRequestType(value) {
+    return VALID_REQUEST_TYPES.includes(value);
+}
+// Shared prerequisite fragments
+const TECH_DOC = { relativePath: 'rd/tech-doc.md', description: 'RD technical design doc (architecture, files changed, data flow)' };
+const BUG_ANALYSIS = { relativePath: 'rd/bug-analysis.md', description: 'Bug root-cause analysis (reproduction, affected paths, fix approach, regression test plan)' };
+const CODE_REVIEW = { relativePath: 'rd/code-review.md', description: 'Code review evidence (CRITICAL/HIGH must be fixed before handoff)' };
+const SECURITY_REVIEW = { relativePath: 'rd/security-review.md', description: 'Security review evidence for the changed surface' };
+const TEST_CASES = { relativePath: 'qa/test-cases/<rid>.md', description: 'Generated test cases (unit / integration / UI regression)' };
+const TEST_REPORT = { relativePath: 'qa/test-reports/<rid>.md', description: 'Test execution report with actual pass/fail/coverage results' };
+const SECURITY_FINDINGS = { relativePath: 'qa/security-findings.md', description: 'Security test findings (record "no findings" inside if truly clean)' };
+const PERFORMANCE_FINDINGS = { relativePath: 'qa/performance-findings.md', description: 'Performance test findings (record baseline/after numbers or explicit "not applicable" rationale)' };
+const FEATURE_TABLE = {
+    'rd:implemented': [TECH_DOC],
+    'rd:qa-handoff': [TECH_DOC, CODE_REVIEW, SECURITY_REVIEW],
+    'qa:running': [TEST_CASES],
+    'qa:verdict-issued': [TEST_CASES, TEST_REPORT, SECURITY_FINDINGS, PERFORMANCE_FINDINGS]
+};
+// Bugfix: lighter planning artifact (bug-analysis instead of tech-doc), still requires code review + security review + regression test.
+// Performance findings not mandatory for non-perf bugs (use --allow-incomplete --reason if a perf bug requires it).
+const BUGFIX_TABLE = {
+    'rd:implemented': [BUG_ANALYSIS],
+    'rd:qa-handoff': [BUG_ANALYSIS, CODE_REVIEW, SECURITY_REVIEW],
+    'qa:running': [TEST_CASES],
+    'qa:verdict-issued': [TEST_CASES, TEST_REPORT, SECURITY_FINDINGS]
+};
+// Refactor: same as feature; refactor hard gates (coverage ≥ 95%) are enforced separately in peaks-rd SKILL.
+const REFACTOR_TABLE = FEATURE_TABLE;
+// Docs / chore: no artifact gates. Use sparingly — for genuinely doc-only or formatter-only changes.
+const NO_GATES = {};
+// Config: security review is the only mandatory check (config changes can break auth, CORS, CSP, secrets handling).
+const CONFIG_TABLE = {
+    'rd:qa-handoff': [SECURITY_REVIEW],
+    'qa:verdict-issued': [SECURITY_FINDINGS]
+};
+const PREREQUISITES_BY_TYPE = {
+    feature: FEATURE_TABLE,
+    bugfix: BUGFIX_TABLE,
+    refactor: REFACTOR_TABLE,
+    docs: NO_GATES,
+    config: CONFIG_TABLE,
+    chore: NO_GATES
+};
+export function getPrerequisitesFor(role, newState, requestType = DEFAULT_REQUEST_TYPE) {
+    const table = PREREQUISITES_BY_TYPE[requestType];
+    return table[`${role}:${newState}`] ?? [];
+}
+function resolvePrerequisitePath(prerequisite, requestId) {
+    return prerequisite.relativePath.replace('<rid>', requestId);
+}
+export async function checkPrerequisites(options) {
+    const requirements = getPrerequisitesFor(options.role, options.newState, options.requestType);
+    if (requirements.length === 0) {
+        return { ok: true, missing: [] };
+    }
+    const sessionRoot = join(options.projectRoot, '.peaks', options.sessionId);
+    const missing = [];
+    for (const prerequisite of requirements) {
+        const relative = resolvePrerequisitePath(prerequisite, options.requestId);
+        const absolute = join(sessionRoot, relative);
+        if (!(await pathExists(absolute))) {
+            missing.push({ path: relative, description: prerequisite.description });
+        }
+    }
+    return { ok: missing.length === 0, missing };
+}

package/dist/src/services/artifacts/repair-cycle-service.d.ts

@@ -0,0 +1,23 @@
+export type RepairCycleEntry = {
+    cycle: number;
+    timestamp: string;
+    reason: string;
+};
+export type RepairCycleReport = {
+    requestId: string;
+    sessionId: string;
+    path: string;
+    cycleCount: number;
+    maxCycles: number;
+    remaining: number;
+    atCap: boolean;
+    blocked: boolean;
+    entries: RepairCycleEntry[];
+};
+export type RepairCycleStatusOptions = {
+    projectRoot: string;
+    requestId: string;
+    sessionId?: string;
+    maxCycles?: number;
+};
+export declare function getRepairCycleStatus(options: RepairCycleStatusOptions): Promise<RepairCycleReport | null>;