peaks-cli 1.0.17 → 1.0.18

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>;

package/dist/src/services/artifacts/repair-cycle-service.js

@@ -0,0 +1,52 @@
+import { showRequestArtifact } from './request-artifact-service.js';
+const DEFAULT_MAX_CYCLES = 3;
+// Matches transition notes Solo writes during repair routing.
+// Format example:
+//   - transition note (2026-05-25T08:00:00.000Z): QA return-to-rd cycle 1: failing acceptance items A, B
+//   - transition note (2026-05-25T09:00:00.000Z): QA cycle 2: regression in module X
+const REPAIR_NOTE_PATTERN = /-\s*transition note\s*\(([^)]+)\)\s*:\s*(?:QA(?:\s+return-to-rd)?\s+cycle\s+(\d+))\s*:?\s*(.*?)$/i;
+export async function getRepairCycleStatus(options) {
+    const showOptions = {
+        projectRoot: options.projectRoot,
+        role: 'rd',
+        requestId: options.requestId
+    };
+    if (options.sessionId !== undefined) {
+        showOptions.sessionId = options.sessionId;
+    }
+    const artifact = await showRequestArtifact(showOptions);
+    if (artifact === null) {
+        return null;
+    }
+    const maxCycles = options.maxCycles ?? DEFAULT_MAX_CYCLES;
+    const lines = artifact.content.split(/\r?\n/);
+    const entries = [];
+    for (const rawLine of lines) {
+        const match = REPAIR_NOTE_PATTERN.exec(rawLine);
+        if (match === null)
+            continue;
+        const [, timestamp, cycleStr, reason] = match;
+        if (timestamp === undefined || cycleStr === undefined)
+            continue;
+        const cycle = Number(cycleStr);
+        if (!Number.isFinite(cycle) || cycle < 1)
+            continue;
+        entries.push({ cycle, timestamp, reason: (reason ?? '').trim() });
+    }
+    // Distinct cycle numbers — repair loop may write the same cycle note multiple times.
+    const distinct = new Set(entries.map((entry) => entry.cycle));
+    const cycleCount = distinct.size;
+    const remaining = Math.max(0, maxCycles - cycleCount);
+    const atCap = cycleCount >= maxCycles;
+    return {
+        requestId: options.requestId,
+        sessionId: artifact.sessionId,
+        path: artifact.path,
+        cycleCount,
+        maxCycles,
+        remaining,
+        atCap,
+        blocked: atCap,
+        entries
+    };
+}

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

@@ -1,3 +1,5 @@
+import { DEFAULT_REQUEST_TYPE, isRequestType, VALID_REQUEST_TYPES, type PrerequisiteCheckResult, type RequestType } from './artifact-prerequisites.js';
+export { VALID_REQUEST_TYPES, DEFAULT_REQUEST_TYPE, isRequestType, type RequestType };
 export type RequestArtifactRole = 'prd' | 'ui' | 'rd' | 'qa' | 'sc';
 export type CreateRequestArtifactOptions = {
     role: RequestArtifactRole;
@@ -5,6 +7,7 @@ export type CreateRequestArtifactOptions = {
     projectRoot: string;
     sessionId?: string;
     apply?: boolean;
+    requestType?: RequestType;
     clock?: () => string;
 };
 export type CreateRequestArtifactResult = {
@@ -22,6 +25,7 @@ export type RequestArtifactSummary = {
     requestId: string;
     path: string;
     state: string;
+    requestType: RequestType;
     createdAt?: string;
 };
 export type ListRequestArtifactsOptions = {
@@ -49,10 +53,20 @@ export type TransitionRequestArtifactOptions = {
     newState: RequestArtifactState;
     sessionId?: string;
     reason?: string;
+    allowIncomplete?: boolean;
     clock?: () => string;
 };
 export type TransitionRequestArtifactResult = RequestArtifactSummary & {
     previousState: string;
     content: string;
+    bypassedPrerequisites?: PrerequisiteCheckResult;
 };
+export declare class PrerequisitesNotSatisfiedError extends Error {
+    readonly code = "PREREQUISITES_MISSING";
+    readonly role: RequestArtifactRole;
+    readonly newState: RequestArtifactState;
+    readonly sessionId: string;
+    readonly missing: PrerequisiteCheckResult['missing'];
+    constructor(role: RequestArtifactRole, newState: RequestArtifactState, sessionId: string, missing: PrerequisiteCheckResult['missing']);
+}
 export declare function transitionRequestArtifact(options: TransitionRequestArtifactOptions): Promise<TransitionRequestArtifactResult | null>;

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

@@ -1,6 +1,8 @@
 import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { isDirectory, listDirectories, pathExists } from '../../shared/fs.js';
+import { checkPrerequisites, DEFAULT_REQUEST_TYPE, isRequestType, VALID_REQUEST_TYPES } from './artifact-prerequisites.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']);
 function defaultClock() {
@@ -12,11 +14,11 @@ function dateSlugFromIso(iso) {
 function defaultSessionId(iso) {
     return `${dateSlugFromIso(iso)}-session`;
 }
-function renderPrdTemplate(requestId, sessionId, timestamp) {
+function renderPrdTemplate(requestId, sessionId, timestamp, requestType) {
     return `# PRD Request ${requestId}
 
 - session: ${sessionId}
-- type: feature | bug | refactor | clarification
+- type: ${requestType}
 - source: <ticket, message URL, or "verbal" with a short sanitized quote>
 - raw input (sanitized): <one-paragraph restatement of what the user actually asked for>
 
@@ -59,11 +61,12 @@ function renderPrdTemplate(requestId, sessionId, timestamp) {
 - state: draft
 `;
 }
-function renderUiTemplate(requestId, sessionId, timestamp) {
+function renderUiTemplate(requestId, sessionId, timestamp, requestType) {
     return `# UI Request ${requestId}
 
 - session: ${sessionId}
 - linked-prd: .peaks/${sessionId}/prd/requests/${requestId}.md
+- type: ${requestType}
 - scope: full new surface | iteration on existing surface | regression fix | visual refresh
 - design direction: editorial | bento | Swiss | luxury | retro-futurist | glass | product-system | other-explicit-name
 
@@ -108,13 +111,13 @@ function renderUiTemplate(requestId, sessionId, timestamp) {
 - state: draft
 `;
 }
-function renderRdTemplate(requestId, sessionId, timestamp) {
+function renderRdTemplate(requestId, sessionId, timestamp, requestType) {
     return `# RD Request ${requestId}
 
 - session: ${sessionId}
 - linked-prd: .peaks/${sessionId}/prd/requests/${requestId}.md
 - linked-ui:  .peaks/${sessionId}/ui/requests/${requestId}.md  (when UI involved)
-- type: feature | bug | refactor | clarification
+- type: ${requestType}
 
 ## Red-line scope
 
@@ -165,14 +168,14 @@ function renderRdTemplate(requestId, sessionId, timestamp) {
 - state: draft
 `;
 }
-function renderQaTemplate(requestId, sessionId, timestamp) {
+function renderQaTemplate(requestId, sessionId, timestamp, requestType) {
     return `# QA Request ${requestId}
 
 - session: ${sessionId}
 - linked-prd: .peaks/${sessionId}/prd/requests/${requestId}.md
 - linked-rd:  .peaks/${sessionId}/rd/requests/${requestId}.md
 - linked-ui:  .peaks/${sessionId}/ui/requests/${requestId}.md  (when UI involved)
-- type: feature | bug | refactor | clarification
+- type: ${requestType}
 
 ## Red-line boundary check
 
@@ -220,7 +223,7 @@ function renderQaTemplate(requestId, sessionId, timestamp) {
 - state: draft
 `;
 }
-function renderScTemplate(requestId, sessionId, timestamp) {
+function renderScTemplate(requestId, sessionId, timestamp, requestType) {
     return `# SC Request ${requestId}
 
 - session: ${sessionId}
@@ -228,7 +231,7 @@ function renderScTemplate(requestId, sessionId, timestamp) {
 - linked-rd:  .peaks/${sessionId}/rd/requests/${requestId}.md
 - linked-qa:  .peaks/${sessionId}/qa/requests/${requestId}.md
 - linked-ui:  .peaks/${sessionId}/ui/requests/${requestId}.md  (when UI involved)
-- type: feature | bug | refactor | clarification
+- type: ${requestType}
 
 ## Change impact
 
@@ -272,18 +275,18 @@ function renderScTemplate(requestId, sessionId, timestamp) {
 - state: draft
 `;
 }
-function renderTemplate(role, requestId, sessionId, timestamp) {
+function renderTemplate(role, requestId, sessionId, timestamp, requestType) {
     switch (role) {
         case 'prd':
-            return renderPrdTemplate(requestId, sessionId, timestamp);
+            return renderPrdTemplate(requestId, sessionId, timestamp, requestType);
         case 'ui':
-            return renderUiTemplate(requestId, sessionId, timestamp);
+            return renderUiTemplate(requestId, sessionId, timestamp, requestType);
         case 'rd':
-            return renderRdTemplate(requestId, sessionId, timestamp);
+            return renderRdTemplate(requestId, sessionId, timestamp, requestType);
         case 'qa':
-            return renderQaTemplate(requestId, sessionId, timestamp);
+            return renderQaTemplate(requestId, sessionId, timestamp, requestType);
         case 'sc':
-            return renderScTemplate(requestId, sessionId, timestamp);
+            return renderScTemplate(requestId, sessionId, timestamp, requestType);
     }
 }
 export async function createRequestArtifact(options) {
@@ -293,11 +296,12 @@ export async function createRequestArtifact(options) {
     if (!REQUEST_ID_PATTERN.test(options.requestId)) {
         throw new Error(`Invalid request id: ${options.requestId} (expected letters, digits, dots, underscores, or dashes)`);
     }
+    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`);
-    const content = renderTemplate(options.role, options.requestId, sessionId, timestamp);
+    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 };
     }
@@ -308,9 +312,10 @@ export async function createRequestArtifact(options) {
     await writeFile(path, content, 'utf8');
     return { role: options.role, requestId: options.requestId, sessionId, path, content, applied: true };
 }
-function extractStateAndCreated(markdown) {
+function extractMetadata(markdown) {
     let state = 'unknown';
     let createdAt;
+    let requestType = DEFAULT_REQUEST_TYPE;
     for (const rawLine of markdown.split(/\r?\n/)) {
         const line = rawLine.trim();
         const stateMatch = /^-\s*state:\s*(.+?)\s*$/.exec(line);
@@ -321,16 +326,28 @@ function extractStateAndCreated(markdown) {
         const createdMatch = /^-\s*created:\s*(.+?)\s*$/.exec(line);
         if (createdMatch !== null && createdMatch[1] !== undefined) {
             createdAt = createdMatch[1];
+            continue;
+        }
+        const typeMatch = /^-\s*type:\s*(.+?)\s*$/.exec(line);
+        if (typeMatch !== null && typeMatch[1] !== undefined) {
+            const candidate = typeMatch[1];
+            if (isRequestType(candidate)) {
+                requestType = candidate;
+            }
+            // Placeholder values (e.g. "feature | bug | refactor | clarification") fall back to default.
         }
     }
-    return createdAt === undefined ? { state } : { state, createdAt };
+    const base = { state, requestType };
+    if (createdAt !== undefined)
+        base.createdAt = createdAt;
+    return base;
 }
 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 } = extractStateAndCreated(body);
+    const { state, createdAt, requestType } = extractMetadata(body);
     const requestId = fileName.replace(/\.md$/, '');
-    const summary = { role, sessionId, requestId, path, state };
+    const summary = { role, sessionId, requestId, path, state, requestType };
     if (createdAt !== undefined) {
         summary.createdAt = createdAt;
     }
@@ -407,6 +424,21 @@ const ALLOWED_STATES_PER_ROLE = {
 export function allowedStatesForRole(role) {
     return ALLOWED_STATES_PER_ROLE[role];
 }
+export class PrerequisitesNotSatisfiedError extends Error {
+    code = 'PREREQUISITES_MISSING';
+    role;
+    newState;
+    sessionId;
+    missing;
+    constructor(role, newState, sessionId, missing) {
+        super(`Cannot transition ${role} to ${newState}: ${missing.length} required artifact${missing.length === 1 ? '' : 's'} missing under .peaks/${sessionId}/`);
+        this.name = 'PrerequisitesNotSatisfiedError';
+        this.role = role;
+        this.newState = newState;
+        this.sessionId = sessionId;
+        this.missing = missing;
+    }
+}
 function updateStatusBlock(markdown, newState, timestamp, reason) {
     const lines = markdown.split(/\r?\n/);
     let previousState = 'unknown';
@@ -467,9 +499,25 @@ export async function transitionRequestArtifact(options) {
     if (existing === null) {
         return null;
     }
+    const prerequisiteResult = await checkPrerequisites({
+        projectRoot: options.projectRoot,
+        sessionId: existing.sessionId,
+        role: options.role,
+        newState: options.newState,
+        requestId: options.requestId,
+        requestType: existing.requestType
+    });
+    if (!prerequisiteResult.ok && options.allowIncomplete !== true) {
+        throw new PrerequisitesNotSatisfiedError(options.role, options.newState, existing.sessionId, prerequisiteResult.missing);
+    }
     const clock = options.clock ?? defaultClock;
     const timestamp = clock();
-    const { updated, previousState } = updateStatusBlock(existing.content, options.newState, timestamp, options.reason);
+    const bypassNote = !prerequisiteResult.ok && options.allowIncomplete === true
+        ? `bypassed prerequisites (${prerequisiteResult.missing.map((entry) => entry.path).join(', ')})`
+        : undefined;
+    const combinedReason = [options.reason, bypassNote].filter((part) => part !== undefined && part.length > 0).join(' | ');
+    const reasonForNote = combinedReason.length > 0 ? combinedReason : undefined;
+    const { updated, previousState } = updateStatusBlock(existing.content, options.newState, timestamp, reasonForNote);
     await writeFile(existing.path, updated, 'utf8');
     const result = {
         role: options.role,
@@ -477,11 +525,15 @@ export async function transitionRequestArtifact(options) {
         requestId: options.requestId,
         path: existing.path,
         state: options.newState,
+        requestType: existing.requestType,
         previousState,
         content: updated
     };
     if (existing.createdAt !== undefined) {
         result.createdAt = existing.createdAt;
     }
+    if (!prerequisiteResult.ok && options.allowIncomplete === true) {
+        result.bypassedPrerequisites = prerequisiteResult;
+    }
     return result;
 }

package/dist/src/services/scan/acceptance-coverage-service.d.ts

@@ -0,0 +1,42 @@
+export type AcceptanceItem = {
+    id: string;
+    text: string;
+    line: number;
+};
+export type TestCase = {
+    title: string;
+    acceptanceIds: string[];
+    line: number;
+};
+export type CoverageEntry = {
+    acceptanceId: string;
+    acceptanceText: string;
+    testCases: string[];
+};
+export type AcceptanceCoverageReport = {
+    ok: boolean;
+    prdPath: string;
+    testCasesPath: string;
+    acceptanceItems: AcceptanceItem[];
+    testCases: TestCase[];
+    coverage: CoverageEntry[];
+    uncovered: AcceptanceItem[];
+    unlinkedTestCases: TestCase[];
+    invalidReferences: Array<{
+        testCaseTitle: string;
+        reference: string;
+    }>;
+};
+export type AcceptanceCoverageOptions = {
+    projectRoot: string;
+    requestId: string;
+    sessionId?: string;
+};
+export type AcceptanceCoverageError = {
+    kind: 'prd-not-found';
+} | {
+    kind: 'test-cases-not-found';
+    expectedPath: string;
+};
+export declare function getAcceptanceCoverage(options: AcceptanceCoverageOptions): Promise<AcceptanceCoverageReport | AcceptanceCoverageError>;
+export declare function isAcceptanceCoverageError(value: AcceptanceCoverageReport | AcceptanceCoverageError): value is AcceptanceCoverageError;

package/dist/src/services/scan/acceptance-coverage-service.js

@@ -0,0 +1,135 @@
+import { join } from 'node:path';
+import { pathExists, readText } from '../../shared/fs.js';
+import { showRequestArtifact } from '../artifacts/request-artifact-service.js';
+const ACCEPTANCE_SECTION_PATTERN = /^##\s+(?:Acceptance criteria|验收标准|Acceptance Criteria)\s*$/m;
+function extractAcceptanceItems(prdBody) {
+    const lines = prdBody.split(/\r?\n/);
+    const startMatch = ACCEPTANCE_SECTION_PATTERN.exec(prdBody);
+    if (startMatch === null) {
+        return [];
+    }
+    // Find the line where the header starts.
+    let headerLine = -1;
+    for (let i = 0; i < lines.length; i += 1) {
+        if (ACCEPTANCE_SECTION_PATTERN.test((lines[i] ?? '') + '\n')) {
+            headerLine = i;
+            break;
+        }
+    }
+    if (headerLine === -1) {
+        return [];
+    }
+    const items = [];
+    let counter = 0;
+    for (let i = headerLine + 1; i < lines.length; i += 1) {
+        const raw = lines[i] ?? '';
+        if (/^##\s/.test(raw))
+            break; // next section
+        const bulletMatch = /^\s*-\s+(.+?)\s*$/.exec(raw);
+        if (bulletMatch === null)
+            continue;
+        const text = bulletMatch[1] ?? '';
+        if (text.length === 0)
+            continue;
+        // Skip placeholder-only bullets ("...", "<...>", etc.)
+        if (/^\.{2,}$/.test(text) || /^<[^>]+>$/.test(text))
+            continue;
+        counter += 1;
+        items.push({ id: `A${counter}`, text, line: i + 1 });
+    }
+    return items;
+}
+const TEST_CASE_HEADER_PATTERN = /^##\s+Test Case:\s*(.+?)\s*$/;
+const ACCEPTANCE_FIELD_PATTERN = /^\s*-\s+\*\*Acceptance:\*\*\s+(.+?)\s*$/i;
+function extractTestCases(qaBody) {
+    const lines = qaBody.split(/\r?\n/);
+    const cases = [];
+    let current = null;
+    for (let i = 0; i < lines.length; i += 1) {
+        const raw = lines[i] ?? '';
+        const headerMatch = TEST_CASE_HEADER_PATTERN.exec(raw);
+        if (headerMatch !== null) {
+            if (current !== null) {
+                cases.push({ title: current.title, acceptanceIds: current.ids, line: current.line });
+            }
+            current = { title: (headerMatch[1] ?? '').trim(), line: i + 1, ids: [] };
+            continue;
+        }
+        if (current === null)
+            continue;
+        const acceptanceMatch = ACCEPTANCE_FIELD_PATTERN.exec(raw);
+        if (acceptanceMatch !== null) {
+            const refs = (acceptanceMatch[1] ?? '').split(/[,\s]+/).map((part) => part.trim()).filter((part) => part.length > 0);
+            current.ids.push(...refs);
+        }
+    }
+    if (current !== null) {
+        cases.push({ title: current.title, acceptanceIds: current.ids, line: current.line });
+    }
+    return cases;
+}
+function buildCoverage(items, cases) {
+    const itemMap = new Map();
+    for (const item of items)
+        itemMap.set(item.id, item);
+    const coverageMap = new Map();
+    for (const item of items)
+        coverageMap.set(item.id, []);
+    const invalidReferences = [];
+    for (const testCase of cases) {
+        for (const ref of testCase.acceptanceIds) {
+            const normalized = ref.toUpperCase();
+            if (!itemMap.has(normalized)) {
+                invalidReferences.push({ testCaseTitle: testCase.title, reference: ref });
+                continue;
+            }
+            coverageMap.get(normalized)?.push(testCase.title);
+        }
+    }
+    const coverage = items.map((item) => ({
+        acceptanceId: item.id,
+        acceptanceText: item.text,
+        testCases: coverageMap.get(item.id) ?? []
+    }));
+    const uncovered = items.filter((item) => (coverageMap.get(item.id) ?? []).length === 0);
+    return { coverage, uncovered, invalidReferences };
+}
+export async function getAcceptanceCoverage(options) {
+    const showOptions = {
+        projectRoot: options.projectRoot,
+        role: 'prd',
+        requestId: options.requestId
+    };
+    if (options.sessionId !== undefined) {
+        showOptions.sessionId = options.sessionId;
+    }
+    const prdArtifact = await showRequestArtifact(showOptions);
+    if (prdArtifact === null) {
+        return { kind: 'prd-not-found' };
+    }
+    const sessionId = prdArtifact.sessionId;
+    const testCasesPath = join(options.projectRoot, '.peaks', sessionId, 'qa', 'test-cases', `${options.requestId}.md`);
+    if (!(await pathExists(testCasesPath))) {
+        return { kind: 'test-cases-not-found', expectedPath: testCasesPath };
+    }
+    const qaBody = await readText(testCasesPath);
+    const acceptanceItems = extractAcceptanceItems(prdArtifact.content);
+    const testCases = extractTestCases(qaBody);
+    const { coverage, uncovered, invalidReferences } = buildCoverage(acceptanceItems, testCases);
+    const unlinkedTestCases = testCases.filter((testCase) => testCase.acceptanceIds.length === 0);
+    const ok = uncovered.length === 0 && invalidReferences.length === 0 && acceptanceItems.length > 0;
+    return {
+        ok,
+        prdPath: prdArtifact.path,
+        testCasesPath,
+        acceptanceItems,
+        testCases,
+        coverage,
+        uncovered,
+        unlinkedTestCases,
+        invalidReferences
+    };
+}
+export function isAcceptanceCoverageError(value) {
+    return value.kind !== undefined;
+}

package/dist/src/services/scan/archetype-service.d.ts

@@ -0,0 +1,5 @@
+import type { ArchetypeReport } from './scan-types.js';
+export type ArchetypeScanOptions = {
+    projectRoot: string;
+};
+export declare function scanArchetype(options: ArchetypeScanOptions): Promise<ArchetypeReport>;