peaks-cli 1.0.20 → 1.0.22

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

@@ -1,5 +1,7 @@
 import { InvalidArgumentError } from 'commander';
-import { allowedStatesForRole, createRequestArtifact, listRequestArtifacts, showRequestArtifact, transitionRequestArtifact, PrerequisitesNotSatisfiedError, VALID_REQUEST_TYPES, isRequestType } from '../../services/artifacts/request-artifact-service.js';
+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';
@@ -118,7 +120,9 @@ export function registerRequestCommands(program, io) {
         .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')).action(async (requestId, options) => {
+        .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);
@@ -127,6 +131,26 @@ export function registerRequestCommands(program, io) {
                 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();
+                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;
+                    }
+                    // Check bypass count
+                    const sessionRoot = (await import('node:path')).join(options.project, '.peaks', options.sessionId ?? '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,
@@ -142,6 +166,28 @@ export function registerRequestCommands(program, io) {
             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);
@@ -163,6 +209,40 @@ export function registerRequestCommands(program, io) {
                 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;
         }

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

@@ -4,6 +4,7 @@ import { scanExistingSystem } from '../../services/scan/existing-system-service.
 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 { scanFileSize, DEFAULT_FILE_SIZE_THRESHOLD } from '../../services/scan/file-size-scan.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';
@@ -191,4 +192,33 @@ export function registerScanCommands(program, io) {
             process.exitCode = 1;
         }
     });
+    addJsonOption(scan
+        .command('file-size')
+        .description('Check git diff for files exceeding a line count threshold (karpathy-skills "Simplicity First")')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--base-ref <ref>', 'compare working tree against this git ref (default: HEAD)')
+        .option('--threshold <n>', `line count threshold (default: ${DEFAULT_FILE_SIZE_THRESHOLD})`)).action((options) => {
+        try {
+            const threshold = options.threshold !== undefined && /^\d+$/.test(options.threshold)
+                ? Number(options.threshold)
+                : undefined;
+            const result = scanFileSize({
+                projectRoot: options.project,
+                ...(options.baseRef !== undefined ? { baseRef: options.baseRef } : {}),
+                ...(threshold !== undefined ? { threshold } : {})
+            });
+            const nextActions = [];
+            if (!result.ok) {
+                nextActions.push(`${result.violations.length} file(s) exceed ${result.threshold} lines. Split into smaller modules.`);
+            }
+            printResult(io, ok('scan.file-size', result, [], nextActions), options.json);
+            if (!result.ok) {
+                process.exitCode = 1;
+            }
+        }
+        catch (error) {
+            printResult(io, fail('scan.file-size', 'FILE_SIZE_SCAN_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path is a git repository']), options.json);
+            process.exitCode = 1;
+        }
+    });
 }

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

@@ -5,21 +5,25 @@ import { createAutonomousWorkflowPlan } from '../../services/workflow/workflow-a
 import { writeAutonomousResumeArtifacts } from '../../services/workflow/autonomous-resume-writer.js';
 import { createRecommendationPlan } from '../../services/recommendations/recommendation-service.js';
 import { createRefactorDryRun } from '../../services/refactor/refactor-service.js';
-import { ensureWorkspaceConfigForCurrentPath, getCurrentWorkspaceConfig, readConfig } from '../../services/config/config-service.js';
+import { getWorkspaceConfigForPath, readConfig } from '../../services/config/config-service.js';
 import { validateChangeIdOrThrow } from '../../shared/change-id.js';
 import { getEconomyAwareExecutionModelId } from '../../services/config/model-routing.js';
 import { getLocalArtifactPath } from '../../services/artifacts/workspace-service.js';
+import { getSessionId } from '../../services/session/session-manager.js';
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, failUnsupportedNonDryRun, getErrorMessage, isRecommendationWorkflow, printResult } from '../cli-helpers.js';
 function getCurrentWorkspaceContext() {
-    const workspace = getCurrentWorkspaceConfig();
-    if (!workspace)
+    try {
+        const sessionId = getSessionId(process.cwd());
+        return sessionId ? { sessionId, sessionDir: `.peaks/${sessionId}` } : {};
+    }
+    catch {
         return {};
-    return { workspace, artifactWorkspacePath: getLocalArtifactPath(workspace) };
+    }
 }
 function getWorkflowWorkspaceContext() {
     try {
-        const workspace = ensureWorkspaceConfigForCurrentPath() ?? getCurrentWorkspaceConfig();
+        const workspace = getWorkspaceConfigForPath(process.cwd());
         if (!workspace)
             return {};
         return { workspace, artifactWorkspacePath: getLocalArtifactPath(workspace) };

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

@@ -14,14 +14,42 @@ 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 TECH_DOC = {
+    relativePath: 'rd/tech-doc.md',
+    description: 'RD technical design doc (architecture, files changed, data flow)',
+    mustContain: ['## Red-line scope', '## Implementation evidence']
+};
+const BUG_ANALYSIS = {
+    relativePath: 'rd/bug-analysis.md',
+    description: 'Bug root-cause analysis (reproduction, affected paths, fix approach, regression test plan)',
+    mustContain: ['## Root cause', '## Fix approach']
+};
+const CODE_REVIEW = {
+    relativePath: 'rd/code-review.md',
+    description: 'Code review evidence (CRITICAL/HIGH must be fixed before handoff)',
+    mustContain: ['## Findings', 'CRITICAL']
+};
 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 TEST_CASES = {
+    relativePath: 'qa/test-cases/<rid>.md',
+    description: 'Generated test cases (unit / integration / UI regression)',
+    mustContain: ['## Test cases']
+};
+const TEST_REPORT = {
+    relativePath: 'qa/test-reports/<rid>.md',
+    description: 'Test execution report with actual pass/fail/coverage results',
+    mustContain: ['## Test execution']
+};
+const SECURITY_FINDINGS = {
+    relativePath: 'qa/security-findings.md',
+    description: 'Security test findings (record "no findings" inside if truly clean)',
+    mustContain: ['## Findings']
+};
+const PERFORMANCE_FINDINGS = {
+    relativePath: 'qa/performance-findings.md',
+    description: 'Performance test findings (record baseline/after numbers or explicit "not applicable" rationale)',
+    mustContain: ['## Baseline']
+};
 // PRD content prereq: ensures the PRD artifact has actual scope/acceptance content
 // before handoff to RD/UI/QA. The SKILL says "Handoff to RD/UI/QA is blocked while
 // the artifact is missing or in `draft` state" — this gives that claim a CLI gate.
@@ -30,10 +58,19 @@ const PRD_CONTENT = {
     description: 'PRD artifact must contain Goal and Acceptance criteria sections before handoff',
     mustContain: ['## Goals', '## Acceptance']
 };
+const UNIT_TESTS = {
+    relativePath: 'qa/test-cases/<rid>.md',
+    description: 'Unit test files for the implemented changes (enforces peaks-rd Gate B2)',
+    mustContain: ['## Test cases', 'test(']
+};
+const QA_INITIATED = {
+    relativePath: 'qa/.initiated',
+    description: 'QA skill must be invoked before RD handoff (run peaks request init --role qa)'
+};
 const FEATURE_TABLE = {
     'prd:handed-off': [PRD_CONTENT],
     'rd:implemented': [TECH_DOC],
-    'rd:qa-handoff': [TECH_DOC, CODE_REVIEW, SECURITY_REVIEW],
+    'rd:qa-handoff': [TECH_DOC, CODE_REVIEW, SECURITY_REVIEW, UNIT_TESTS, QA_INITIATED],
     'qa:running': [TEST_CASES],
     'qa:verdict-issued': [TEST_CASES, TEST_REPORT, SECURITY_FINDINGS, PERFORMANCE_FINDINGS]
 };
@@ -42,14 +79,17 @@ const FEATURE_TABLE = {
 const BUGFIX_TABLE = {
     'prd:handed-off': [PRD_CONTENT],
     'rd:implemented': [BUG_ANALYSIS],
-    'rd:qa-handoff': [BUG_ANALYSIS, CODE_REVIEW, SECURITY_REVIEW],
+    'rd:qa-handoff': [BUG_ANALYSIS, CODE_REVIEW, SECURITY_REVIEW, UNIT_TESTS, QA_INITIATED],
     '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 = {};
+// Docs / chore: minimal gate — require PRD content before proceeding.
+// Prevents jumping to implementation without planning.
+const MINIMAL_TABLE = {
+    'prd:handed-off': [PRD_CONTENT]
+};
 // Config: security review is the only mandatory check (config changes can break auth, CORS, CSP, secrets handling).
 const CONFIG_TABLE = {
     'prd:handed-off': [PRD_CONTENT],
@@ -60,9 +100,9 @@ const PREREQUISITES_BY_TYPE = {
     feature: FEATURE_TABLE,
     bugfix: BUGFIX_TABLE,
     refactor: REFACTOR_TABLE,
-    docs: NO_GATES,
+    docs: MINIMAL_TABLE,
     config: CONFIG_TABLE,
-    chore: NO_GATES
+    chore: MINIMAL_TABLE
 };
 export function getPrerequisitesFor(role, newState, requestType = DEFAULT_REQUEST_TYPE) {
     const table = PREREQUISITES_BY_TYPE[requestType];

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

@@ -2,7 +2,7 @@ import { existsSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import { resolve } from 'node:path';
-import { getCurrentWorkspaceConfig } from '../config/config-service.js';
+import { getWorkspaceConfigForPath } from '../config/config-service.js';
 import { getArtifactRemoteRepo, getLocalArtifactPath } from './workspace-service.js';
 function getRemoteUrl(artifactRepo) {
     if (!artifactRepo)
@@ -45,7 +45,7 @@ export function createArtifactInitPlan(options) {
     };
 }
 export function createGuidedArtifactSetup() {
-    const workspace = getCurrentWorkspaceConfig();
+    const workspace = getWorkspaceConfigForPath(process.cwd());
     const artifactRepo = workspace ? getArtifactRemoteRepo(workspace) : null;
     const validationResult = {
         workspaceExists: workspace !== null,

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

@@ -54,6 +54,12 @@ export type TransitionRequestArtifactOptions = {
     sessionId?: string;
     reason?: string;
     allowIncomplete?: boolean;
+    confirmed?: boolean;
+    forceConfirm?: boolean;
+    typeSanityCheck?: {
+        projectRoot: string;
+        declaredType: RequestType;
+    };
     clock?: () => string;
 };
 export type TransitionRequestArtifactResult = RequestArtifactSummary & {
@@ -69,4 +75,30 @@ export declare class PrerequisitesNotSatisfiedError extends Error {
     readonly missing: PrerequisiteCheckResult['missing'];
     constructor(role: RequestArtifactRole, newState: RequestArtifactState, sessionId: string, missing: PrerequisiteCheckResult['missing']);
 }
+export declare class LintGateError extends Error {
+    readonly code = "LINT_GATE_FAILED";
+    readonly role: RequestArtifactRole;
+    readonly newState: RequestArtifactState;
+    readonly errorCount: number;
+    constructor(role: RequestArtifactRole, newState: RequestArtifactState, errorCount: number);
+}
+export declare class TypeSanityViolationError extends Error {
+    readonly code = "TYPE_SANITY_VIOLATION";
+    readonly declaredType: RequestType;
+    readonly suggestedTypes: ReadonlyArray<RequestType>;
+    readonly rationale: string;
+    constructor(declaredType: RequestType, suggestedTypes: ReadonlyArray<RequestType>, rationale: string);
+}
+export declare class FileSizeViolationError extends Error {
+    readonly code = "FILE_SIZE_VIOLATION";
+    readonly violations: Array<{
+        file: string;
+        lines: number;
+    }>;
+    readonly threshold: number;
+    constructor(violations: Array<{
+        file: string;
+        lines: number;
+    }>, threshold: number);
+}
 export declare function transitionRequestArtifact(options: TransitionRequestArtifactOptions): Promise<TransitionRequestArtifactResult | null>;

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

@@ -1,7 +1,14 @@
 import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { isDirectory, listDirectories, pathExists } from '../../shared/fs.js';
+import { isDirectory, listDirectories } from '../../shared/fs.js';
 import { checkPrerequisites, DEFAULT_REQUEST_TYPE, isRequestType, VALID_REQUEST_TYPES } from './artifact-prerequisites.js';
+import { ensureSession } from '../session/session-manager.js';
+import { getNextNumber, buildNumberedFilename } from '../../shared/incrementing-number.js';
+import { lintRequestArtifact } from './artifact-lint-service.js';
+import { checkTypeSanity } from '../scan/type-sanity-service.js';
+import { requireUserConfirmation } from '../mode/mode-enforcement.js';
+import { scanFileSize } from '../scan/file-size-scan.js';
 export { VALID_REQUEST_TYPES, DEFAULT_REQUEST_TYPE, isRequestType };
 const REQUEST_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 const VALID_ROLES = new Set(['prd', 'ui', 'rd', 'qa', 'sc']);
@@ -299,17 +306,42 @@ export async function createRequestArtifact(options) {
     const requestType = options.requestType ?? DEFAULT_REQUEST_TYPE;
     const clock = options.clock ?? defaultClock;
     const timestamp = clock();
-    const sessionId = options.sessionId ?? defaultSessionId(timestamp);
-    const path = join(options.projectRoot, '.peaks', sessionId, options.role, 'requests', `${options.requestId}.md`);
+    // Use provided session ID or get/create current session
+    const sessionId = options.sessionId ?? await ensureSession(options.projectRoot);
+    // Build numbered path in session directory
+    const requestsDir = join(options.projectRoot, '.peaks', sessionId, options.role, 'requests');
+    // Check if a file with this requestId already exists (regardless of number prefix)
+    if (await isDirectory(requestsDir)) {
+        const existingFiles = await listMarkdownFiles(requestsDir);
+        const alreadyExists = existingFiles.some((file) => {
+            if (file === `${options.requestId}.md`)
+                return true;
+            if (/^\d+-/.test(file) && file.endsWith(`-${options.requestId}.md`))
+                return true;
+            return false;
+        });
+        if (alreadyExists) {
+            throw new Error(`A request artifact with id "${options.requestId}" already exists in ${requestsDir}. Remove it before re-running peaks request init.`);
+        }
+    }
+    const number = getNextNumber(requestsDir);
+    const filename = buildNumberedFilename(number, options.requestId);
+    const path = join(requestsDir, filename);
     const content = renderTemplate(options.role, options.requestId, sessionId, timestamp, requestType);
     if (options.apply !== true) {
         return { role: options.role, requestId: options.requestId, sessionId, path, content, applied: false };
     }
-    if (await pathExists(path)) {
-        throw new Error(`Refusing to write: ${path} already exists. Update it in place or remove it before re-running peaks request init.`);
-    }
     await mkdir(dirname(path), { recursive: true });
     await writeFile(path, content, 'utf8');
+    // Create QA initiated marker so rd:qa-handoff gate can verify QA was invoked
+    if (options.role === 'qa') {
+        const qaDir = join(options.projectRoot, '.peaks', sessionId, 'qa');
+        const initiatedPath = join(qaDir, '.initiated');
+        if (!existsSync(initiatedPath)) {
+            await mkdir(qaDir, { recursive: true });
+            await writeFile(initiatedPath, '', 'utf8');
+        }
+    }
     return { role: options.role, requestId: options.requestId, sessionId, path, content, applied: true };
 }
 function extractMetadata(markdown) {
@@ -346,7 +378,9 @@ async function readSummary(projectRoot, sessionId, role, fileName) {
     const path = join(projectRoot, '.peaks', sessionId, role, 'requests', fileName);
     const body = await readFile(path, 'utf8');
     const { state, createdAt, requestType } = extractMetadata(body);
-    const requestId = fileName.replace(/\.md$/, '');
+    // Strip numbered prefix (e.g., "001-requestId.md" -> "requestId")
+    // Only strip 3-digit zero-padded prefixes (our incrementing number format)
+    const requestId = fileName.replace(/^0\d{2}-/, '').replace(/\.md$/, '');
     const summary = { role, sessionId, requestId, path, state, requestType };
     if (createdAt !== undefined) {
         summary.createdAt = createdAt;
@@ -389,14 +423,29 @@ export async function showRequestArtifact(options) {
     if (!REQUEST_ID_PATTERN.test(options.requestId)) {
         throw new Error(`Invalid request id: ${options.requestId} (expected letters, digits, dots, underscores, or dashes)`);
     }
-    const fileName = `${options.requestId}.md`;
+    // Search for files matching the requestId (supports both legacy and numbered formats)
+    const findFileInDir = async (dir) => {
+        const files = await listMarkdownFiles(dir);
+        for (const file of files) {
+            // Match legacy format: ${requestId}.md
+            if (file === `${options.requestId}.md`) {
+                return { fileName: file, path: join(dir, file) };
+            }
+            // Match numbered format: ${number}-${requestId}.md
+            if (/^\d+-/.test(file) && file.endsWith(`-${options.requestId}.md`)) {
+                return { fileName: file, path: join(dir, file) };
+            }
+        }
+        return null;
+    };
     if (options.sessionId !== undefined) {
-        const path = join(options.projectRoot, '.peaks', options.sessionId, options.role, 'requests', fileName);
-        if (!(await pathExists(path))) {
+        const dir = join(options.projectRoot, '.peaks', options.sessionId, options.role, 'requests');
+        const found = await findFileInDir(dir);
+        if (found === null) {
             return null;
         }
-        const summary = await readSummary(options.projectRoot, options.sessionId, options.role, fileName);
-        const content = await readFile(path, 'utf8');
+        const summary = await readSummary(options.projectRoot, options.sessionId, options.role, found.fileName);
+        const content = await readFile(found.path, 'utf8');
         return { ...summary, content };
     }
     const peaksRoot = join(options.projectRoot, '.peaks');
@@ -405,10 +454,11 @@ export async function showRequestArtifact(options) {
     }
     const sessions = await listDirectories(peaksRoot);
     for (const sessionId of sessions) {
-        const path = join(peaksRoot, sessionId, options.role, 'requests', fileName);
-        if (await pathExists(path)) {
-            const summary = await readSummary(options.projectRoot, sessionId, options.role, fileName);
-            const content = await readFile(path, 'utf8');
+        const dir = join(peaksRoot, sessionId, options.role, 'requests');
+        const found = await findFileInDir(dir);
+        if (found !== null) {
+            const summary = await readSummary(options.projectRoot, sessionId, options.role, found.fileName);
+            const content = await readFile(found.path, 'utf8');
             return { ...summary, content };
         }
     }
@@ -439,6 +489,48 @@ export class PrerequisitesNotSatisfiedError extends Error {
         this.missing = missing;
     }
 }
+export class LintGateError extends Error {
+    code = 'LINT_GATE_FAILED';
+    role;
+    newState;
+    errorCount;
+    constructor(role, newState, errorCount) {
+        super(`Cannot transition ${role} to ${newState}: ${errorCount} lint error(s) found in artifact. ` +
+            'Fix lint errors or use --allow-incomplete to bypass.');
+        this.name = 'LintGateError';
+        this.role = role;
+        this.newState = newState;
+        this.errorCount = errorCount;
+    }
+}
+export class TypeSanityViolationError extends Error {
+    code = 'TYPE_SANITY_VIOLATION';
+    declaredType;
+    suggestedTypes;
+    rationale;
+    constructor(declaredType, suggestedTypes, rationale) {
+        super(`Type sanity violation: declared --type=${declaredType} disagrees with changed files. ` +
+            `Suggested types: ${suggestedTypes.join(' | ')}. ` +
+            `Rationale: ${rationale}`);
+        this.name = 'TypeSanityViolationError';
+        this.declaredType = declaredType;
+        this.suggestedTypes = suggestedTypes;
+        this.rationale = rationale;
+    }
+}
+export class FileSizeViolationError extends Error {
+    code = 'FILE_SIZE_VIOLATION';
+    violations;
+    threshold;
+    constructor(violations, threshold) {
+        const summary = violations.map((v) => `${v.file} (${v.lines} lines)`).join(', ');
+        super(`File size violation: ${violations.length} file(s) exceed ${threshold} lines: ${summary}. ` +
+            'Split into smaller modules or use --allow-incomplete to bypass.');
+        this.name = 'FileSizeViolationError';
+        this.violations = violations;
+        this.threshold = threshold;
+    }
+}
 function updateStatusBlock(markdown, newState, timestamp, reason) {
     const lines = markdown.split(/\r?\n/);
     let previousState = 'unknown';
@@ -499,6 +591,14 @@ export async function transitionRequestArtifact(options) {
     if (existing === null) {
         return null;
     }
+    // Mode enforcement: require user confirmation in assisted/strict modes
+    const transitionKey = `${options.role}:${options.newState}`;
+    await requireUserConfirmation({
+        projectRoot: options.projectRoot,
+        transitionKey,
+        confirmed: options.confirmed,
+        forceConfirm: options.forceConfirm
+    });
     const prerequisiteResult = await checkPrerequisites({
         projectRoot: options.projectRoot,
         sessionId: existing.sessionId,
@@ -510,6 +610,38 @@ export async function transitionRequestArtifact(options) {
     if (!prerequisiteResult.ok && options.allowIncomplete !== true) {
         throw new PrerequisitesNotSatisfiedError(options.role, options.newState, existing.sessionId, prerequisiteResult.missing);
     }
+    // Type sanity check for PRD handoff
+    if (options.typeSanityCheck !== undefined && options.role === 'prd' && options.newState === 'handed-off') {
+        const sanityReport = checkTypeSanity({
+            projectRoot: options.typeSanityCheck.projectRoot,
+            declaredType: options.typeSanityCheck.declaredType
+        });
+        if (!sanityReport.consistent) {
+            throw new TypeSanityViolationError(options.typeSanityCheck.declaredType, sanityReport.suggestedTypes, sanityReport.rationale);
+        }
+    }
+    // Lint gate: when transitioning OUT of draft, lint must pass (unless --allow-incomplete)
+    if (existing.state === 'draft' && options.allowIncomplete !== true) {
+        const lintReport = await lintRequestArtifact({
+            projectRoot: options.projectRoot,
+            role: options.role,
+            requestId: options.requestId,
+            sessionId: existing.sessionId
+        });
+        if (lintReport !== null && !lintReport.ok) {
+            const errorCount = lintReport.findings.filter((f) => f.severity === 'error').length;
+            if (errorCount > 0) {
+                throw new LintGateError(options.role, options.newState, errorCount);
+            }
+        }
+    }
+    // File size gate: when RD declares implemented, scan for oversized files (karpathy-skills "Simplicity First")
+    if (options.role === 'rd' && options.newState === 'implemented' && options.allowIncomplete !== true) {
+        const sizeResult = scanFileSize({ projectRoot: options.projectRoot });
+        if (!sizeResult.ok) {
+            throw new FileSizeViolationError(sizeResult.violations, sizeResult.threshold);
+        }
+    }
     const clock = options.clock ?? defaultClock;
     const timestamp = clock();
     const bypassNote = !prerequisiteResult.ok && options.allowIncomplete === true

package/dist/src/services/artifacts/workspace-service.js

@@ -1,9 +1,8 @@
 import { existsSync } from 'node:fs';
 import { Buffer } from 'node:buffer';
-import { homedir } from 'node:os';
 import { resolve } from 'node:path';
 import { isInsidePath, stablePath } from '../../shared/path-utils.js';
-import { readConfig, getCurrentWorkspaceConfig } from '../config/config-service.js';
+import { getWorkspaceConfig, getWorkspaceConfigForCurrentPath } from '../config/config-service.js';
 import { pathExists } from '../../shared/fs.js';
 import { execCommand } from '../../shared/process.js';
 function canonicalPath(path) {
@@ -16,7 +15,7 @@ export function getLocalArtifactPath(workspace) {
     if (workspace.artifactStorage?.localPath) {
         return resolve(workspace.artifactStorage.localPath);
     }
-    return resolve(homedir(), '.peaks', 'workspaces', workspace.workspaceId, 'artifacts');
+    return resolve(workspace.rootPath, '.peaks', 'artifacts');
 }
 export function isArtifactWorkspaceOutsideTarget(workspace, artifactWorkspacePath = getLocalArtifactPath(workspace)) {
     const targetRoot = canonicalPath(workspace.rootPath);
@@ -88,8 +87,8 @@ function redactSecrets(message) {
 }
 export async function executeArtifactSync(workspaceId) {
     const workspace = workspaceId
-        ? readConfig().workspaces.find((w) => w.workspaceId === workspaceId) ?? null
-        : getCurrentWorkspaceConfig();
+        ? getWorkspaceConfig(workspaceId)
+        : getWorkspaceConfigForCurrentPath();
     if (!workspace) {
         return {
             workspaceId: workspaceId ?? 'unknown',
@@ -190,8 +189,8 @@ export async function executeArtifactSync(workspaceId) {
 }
 export function getArtifactWorkspaceStatus(workspaceId) {
     const workspace = workspaceId
-        ? readConfig().workspaces.find((w) => w.workspaceId === workspaceId) ?? null
-        : getCurrentWorkspaceConfig();
+        ? getWorkspaceConfig(workspaceId)
+        : getWorkspaceConfigForCurrentPath();
     if (!workspace) {
         return {
             workspaceId: workspaceId ?? 'unknown',
@@ -230,8 +229,8 @@ export function getArtifactWorkspaceStatus(workspaceId) {
 }
 export function planArtifactSync(workspaceId, dryRun = true) {
     const workspace = workspaceId
-        ? readConfig().workspaces.find((w) => w.workspaceId === workspaceId) ?? null
-        : getCurrentWorkspaceConfig();
+        ? getWorkspaceConfig(workspaceId)
+        : getWorkspaceConfigForCurrentPath();
     if (!workspace) {
         return {
             workspaceId: workspaceId ?? 'unknown',