qfai 1.8.2 → 1.8.4

package/dist/index.d.cts

@@ -37,7 +37,7 @@ type ValidationCounts = {
     warning: number;
     error: number;
 };
-type ValidationPhase = "full" | "atdd" | "tdd" | "refinement";
+type ValidationProfile = "discussion" | "sdd" | "prototyping" | "atdd" | "tdd" | "verify" | "full";
 type ValidationTraceability = {
     sc: ScCoverage;
     testFiles: TestFileScan;
@@ -78,7 +78,7 @@ type ValidationWaivers = {
 };
 type ValidationResult = {
     toolVersion: string;
-    phase?: ValidationPhase;
+    profile?: ValidationProfile;
     issues: Issue[];
     counts: ValidationCounts;
     traceability: ValidationTraceability;
@@ -121,6 +121,12 @@ type QfaiValidationConfig = {
         requireSizeTags: boolean;
         maxE2eScenarioRatio: number | null;
         maxE2eScenarioCount: number | null;
+        /**
+         * When true (default), `qfai validate` rejects `it.todo` / `test.todo` /
+         * `describe.todo` stubs in test files (spec-0012, QFAI-TEST-001).
+         * Set to false to opt out while migrating an existing project.
+         */
+        forbidTestTodoStubs: boolean;
     };
     traceability: {
         brMustHaveSc: boolean;
@@ -156,13 +162,24 @@ type QfaiUiuxConfig = {
 type QfaiPrototypingCalibrationConfig = {
     packPath?: string;
 };
+type QfaiPrototypingExecutionConfig = {
+    targetUrl?: string | null;
+    /**
+     * Browser tool handed to the AI evaluator sub-agent (spec-0012).
+     * The only accepted value is `"playwright-cli"`.
+     */
+    browserTool: "playwright-cli";
+};
 type QfaiPrototypingConfig = {
     calibration?: QfaiPrototypingCalibrationConfig;
-    execution?: {
-        targetUrl?: string | null;
-        browserProvider?: string;
-        renderProvider?: string;
-    };
+    execution?: QfaiPrototypingExecutionConfig;
+    /**
+     * v1.8.4: explicit primary spec ID for `/qfai-prototyping`. If omitted,
+     * `resolvePrimaryPrototypingSpec` auto-detects via the prototyping marker
+     * (`surface_type: ui-bearing`) in `01_Spec.md`. Format: 4-digit string,
+     * e.g. `"0012"`.
+     */
+    primarySpecId?: string;
 };
 type QfaiConfig = {
     paths: QfaiPaths;
@@ -314,6 +331,22 @@ type CanonicalPrototypingSurface = (typeof CANONICAL_PROTOTYPING_SURFACES)[numbe
 
 declare const PROTOTYPING_MODES: readonly ["low-cost", "standard", "full-harness"];
 declare const DEFAULT_PROTOTYPING_MODE: "standard";
+/**
+ * Maximum cycles permitted per prototyping mode.
+ *
+ * Per spec-0017 REQ-0001 (mode invariant), modes differ only in maxCycles.
+ * All other obligations (review cycle, evidence, reviewer gate, completion
+ * criteria) are identical across modes.
+ */
+declare const PROTOTYPING_MAX_CYCLES: {
+    readonly "low-cost": 1;
+    readonly standard: 3;
+    readonly "full-harness": 20;
+};
+/**
+ * Alias retained for callers still using spec-0012 wording.
+ * Will be removed in a later phase once all callers reference PROTOTYPING_MAX_CYCLES.
+ */
 declare const PROTOTYPING_MAX_ITERATIONS: {
     readonly "low-cost": 1;
     readonly standard: 3;
@@ -323,18 +356,42 @@ declare const PROTOTYPING_SUPPORTED_SURFACES: readonly ["web", "mobile", "deskto
 type PrototypingMode = (typeof PROTOTYPING_MODES)[number];
 type ModeSelectionSource = "explicit-request" | "system-default";
 type PrototypingSurface = CanonicalPrototypingSurface;
+type PrototypingBrowserTool = "playwright-cli";
 type ModeResolutionResult = {
     requested?: PrototypingMode;
     effective: PrototypingMode;
     source: ModeSelectionSource;
     rationale: string;
 };
+/**
+ * Prototyping obligations (spec-0017 REQ-0001, REQ-0002, REQ-0004).
+ *
+ * Every obligation flag is true for every mode. The only mode-dependent
+ * value is {@link maxCycles}. Validators enforcing per-mode differentiation
+ * for any other field violate the mode invariant (QFAI-PROT-MODE-001).
+ */
 type PrototypingObligations = {
+    /** Browser tool handed to the AI evaluator sub-agent. */
+    browserTool: PrototypingBrowserTool;
+    requireExecutionPlan: boolean;
+    requirePlaywrightEvidence: boolean;
+    requireReviewBundle: boolean;
+    requireEvaluatorReview: boolean;
+    requireBestOfHistory: boolean;
+    requireBreakthrough: boolean;
+    requireIndependentReviewerGate: boolean;
+    requirePerfect100Completion: boolean;
     requireRuntimeGate: boolean;
     requireUiFidelity: boolean;
     requireRenderBundle: boolean;
     requireBrowserQaBundle: boolean;
     requireIterations: boolean;
+    /** Cycle budget; the only mode-dependent value (spec-0017 REQ-0001). */
+    maxCycles: number;
+    /**
+     * Alias for {@link maxCycles} kept for callers still using the spec-0012
+     * "iterations" vocabulary. Same numeric value.
+     */
     maxIterations: number;
     validCombination: boolean;
     invalidReason?: string;
@@ -348,6 +405,13 @@ declare function isValidPrototypingMode(value: unknown): value is PrototypingMod
 declare function isValidPrototypingSurface(value: unknown): value is PrototypingSurface;
 declare function isSupportedPrototypingSurface(surface: string): surface is PrototypingSurface;
 declare function resolvePrototypingMode(requested?: PrototypingMode): ModeResolutionResult;
+/**
+ * Derive prototyping obligations for a (surface, mode) pair.
+ *
+ * Per spec-0017 REQ-0001 the return value is identical across modes except
+ * for {@link PrototypingObligations.maxCycles}. Callers MUST NOT branch
+ * on mode when deciding which obligation to enforce.
+ */
 declare function derivePrototypingObligations(input: {
     surface: PrototypingSurface;
     effectiveMode: PrototypingMode;
@@ -544,9 +608,25 @@ type ReportFullHarnessExecution = {
     browserQaPhasesSkipped: number;
     browserQaTotalFindings: number;
 };
+type ReportRoundLifecycle = {
+    schemaVersion: "2.0";
+    rounds: number;
+    roundIds: string[];
+    candidatesObserved: number;
+    perfectRounds: number;
+    harvestArtifacts: number;
+    narrowDecisions: number;
+    absorptionPlans: number;
+    reimplementations: number;
+    polishCycles: number;
+    completedPolishCycles: number;
+    perfectPolishCycles: number;
+    polishKinds: Record<string, number>;
+};
 type ReportPrototypingSummary = {
     surfaceClassification?: ReportSurfaceClassification;
     fullHarnessExecution?: ReportFullHarnessExecution;
+    roundLifecycle?: ReportRoundLifecycle;
     mode: {
         requested?: string;
         effective: string;
@@ -662,7 +742,7 @@ declare function formatReportMarkdown(data: ReportData, options?: ReportMarkdown
 declare function formatReportJson(data: ReportData): string;
 
 type ValidationOptions = {
-    phase?: ValidationPhase;
+    profile?: ValidationProfile;
     platform?: string;
 };
 declare function validateProject(root: string, configResult?: ConfigLoadResult, options?: ValidationOptions): Promise<ValidationResult>;
@@ -682,7 +762,9 @@ declare function validateOrphanProhibition(root: string, config: QfaiConfig): Pr
 
 declare function validateSpecSplitByCapability(root: string, config: QfaiConfig): Promise<Issue[]>;
 
-declare function validateTraceability(root: string, config: QfaiConfig, phase: ValidationPhase): Promise<Issue[]>;
+declare function validateTraceability(root: string, config: QfaiConfig, options: {
+    includeCodeReferences: boolean;
+}): Promise<Issue[]>;
 
 type SurfaceType = CanonicalPrototypingSurface | "non-ui";
 declare const DISCUSSION_UI_BEARING_SURFACES: Set<SurfaceType>;
@@ -843,10 +925,13 @@ type FullHarnessHandoff = {
 };
 
 /**
- * Full-harness mode types.
+ * Legacy full-harness mode types (spec-0012).
  *
- * Full-harness now follows the reviewerScores/allItemsPass95 evidence schema
- * used by prototyping.json. Legacy weighted totals are intentionally excluded.
+ * NOTE: superseded by the cycle-centric `PrototypingCycleEvidence` /
+ * `PrototypingEvidenceRecord` schema in
+ * `packages/qfai/src/core/prototyping/types.ts` (spec-0017 REQ-0005).
+ * New code should consume the prototyping schema. Legacy callers remain
+ * supported for back-compat with spec-0012 callers.
  */
 type FullHarnessAxisScore = {
     axisId: string;
@@ -877,7 +962,7 @@ type FullHarnessIteration = {
     limitations: string[];
     evidenceRefs: FullHarnessEvidenceRefs;
     reviewerScores: FullHarnessReviewerScore[];
-    allItemsPass95: boolean;
+    allReviewerAxesPerfect100: boolean;
     stopReason?: string;
 };
 type TerminationReason = "converged" | "max-iterations" | "plateau" | "manual-stop";
@@ -890,7 +975,7 @@ type FullHarnessScoreSnapshot = {
     axisCount: number;
     minScore: number | null;
     averageScore: number | null;
-    allItemsPass95: boolean;
+    allReviewerAxesPerfect100: boolean;
     commitSha: string;
 };
 type FullHarnessHistory = {
@@ -918,7 +1003,7 @@ type MeasurementInput = {
     discussionDirRelative?: string;
     trendRefs: string[];
     reviewerScores: FullHarnessReviewerScore[];
-    allItemsPass95: boolean;
+    allReviewerAxesPerfect100: boolean;
     stopReason?: string;
 };
 type MeasurementResult = {
@@ -1065,7 +1150,7 @@ declare function writeEvidenceBundles(input: {
  *
  * Reads previous iterations from prototyping.json,
  * appends new iteration, and recomputes bestIteration/scoringTrace from
- * reviewerScores/allItemsPass95 evidence.
+ * reviewerScores/allReviewerAxesPerfect100 evidence.
  */
 
 declare function loadHistory(root: string): Promise<FullHarnessHistory | null>;
@@ -1097,10 +1182,4 @@ declare function validateReviewer(reviewer: string | undefined): string;
  */
 declare function resolveCommitSha(root: string): Promise<string>;
 
-declare function createPlaywrightRenderAdapter(input: {
-    targetUrl?: string;
-}): RenderCaptureAdapter;
-
-declare function createPlaywrightBrowserQaProvider(): BrowserQaProvider;
-
-export { type AtddCodeTraceabilityResult, type AtddForbiddenRef, type AtddSpecRefs, type AtddTestKind, type AtddTraceabilityMissing, type AtddTraceabilityScan, type AtddUnknownRef, type AtddUnknownRefKind, BROWSER_QA_PHASES, type ConfigLoadResult, type ConfigPathKey, type ConfigSearchResult, DEFAULT_PROTOTYPING_MODE, DISCUSSION_NON_UI_SURFACES, DISCUSSION_UI_BEARING_SURFACES, type DecisionGuardrail, type DecisionGuardrailEntry, type FailOn, type FinalDecision, type FullHarnessAxisScore, type FullHarnessCalibrationRef, type FullHarnessEvidenceRefs, type FullHarnessHistory, type FullHarnessIteration, type FullHarnessReviewerScore, type FullHarnessScoreSnapshot, type GuardrailCheckResult, type GuardrailIssue, type GuardrailIssueSeverity, type GuardrailLoadError, type GuardrailLoadResult, type GuardrailType, ID_PREFIXES, type IdFormatPrefix, type IdPrefix, type Issue, type IssueCategory, type IssueLocation, type IssueSeverity, type MeasurementInput, type MeasurementResult, type ModeResolutionResult, type ModeSelectionSource, type OrphanContractsPolicy, type OutputFormat, PROTOTYPING_MAX_ITERATIONS, PROTOTYPING_MODES, PROTOTYPING_SUPPORTED_SURFACES, type PrototypingMode, type PrototypingObligations, type PrototypingSurface, type QfaiConfig, type QfaiOutputConfig, type QfaiPaths, type QfaiPrototypingCalibrationConfig, type QfaiPrototypingConfig, type QfaiUiuxAuditConfig, type QfaiUiuxConfig, type QfaiValidationConfig, REVIEWER_PLACEHOLDERS, type ReportChangeType, type ReportChangeTypeSummary, type ReportChangeTypeWarning, type ReportContractCoverage, type ReportData, type ReportDeltaCoverage, type ReportFullHarnessExecution, type ReportGuardrailItem, type ReportGuardrails, type ReportIds, type ReportPrototypingSummary, type ReportRuleFinding, type ReportSpecContractRefs, type ReportSpecCoverage, type ReportSummary, type ReportSurfaceClassification, type ReportTddCoverage, type ReportTddCoverageSpec, type ReportTestStrategy, type ReportTraceability, type ReportWaivers, type ReviewerLogVerdict, type ReviewerSignoffStatus, type RunSddPreflightOptions, type SddPreflightResult, type SddPreflightSource, type SddPreflightStatus, type TerminationReason, type TraceabilitySeverity, type UiFidelityStatus, VISUAL_BROWSER_SURFACES, type ValidationCounts, type ValidationOptions, type ValidationPhase, type ValidationResult, type ValidationTraceability, type ValidationWaiverAction, type ValidationWaiverDowngradeTo, type ValidationWaiverEntry, type ValidationWaiverMatch, type ValidationWaiverScope, type ValidationWaiverSeverity, type ValidationWaiverSuppressed, type ValidationWaivers, appendIteration, checkDecisionGuardrails, computeTerminationReason, createPlaywrightBrowserQaProvider, createPlaywrightRenderAdapter, createReportData, defaultConfig, derivePrototypingObligations, evaluateAtddCodeTraceability, extractAcSpecNumber, extractAllIds, extractBrSpecNumber, extractCapSpecNumber, extractCaseSpecNumber, extractDecisionGuardrailsFromMarkdown, extractIds, extractInvalidIds, extractScSpecNumber, extractSpecNumber, extractUsSpecNumber, filterDecisionGuardrailsByKeyword, findConfigRoot, formatGuardrailsForLlm, formatReportJson, formatReportMarkdown, getConfigPath, isDiscussionUiBearingSurfaceType, isNonUiDiscussionSurface, isSupportedPrototypingSurface, isValidPrototypingMode, isValidPrototypingSurface, lintSql, loadConfig, loadDecisionGuardrails, loadHistory, normalizeDecisionGuardrails, requiresVisualBrowserEvidence, resolveCommitSha, resolvePath, resolvePrototypingMode, resolveToolVersion, runBrowserQaOrchestrated, runRenderCapture, runSddPreflight, sortDecisionGuardrails, summarizeBrowserQaResult, validateAtddCodeTraceability, validateContracts, validateDefinedIds, validateLayeredTraceability, validateOrphanProhibition, validateProject, validateReviewer, validateSpecSplitByCapability, validateTraceability, writeEvidenceBundles };
+export { type AtddCodeTraceabilityResult, type AtddForbiddenRef, type AtddSpecRefs, type AtddTestKind, type AtddTraceabilityMissing, type AtddTraceabilityScan, type AtddUnknownRef, type AtddUnknownRefKind, BROWSER_QA_PHASES, type ConfigLoadResult, type ConfigPathKey, type ConfigSearchResult, DEFAULT_PROTOTYPING_MODE, DISCUSSION_NON_UI_SURFACES, DISCUSSION_UI_BEARING_SURFACES, type DecisionGuardrail, type DecisionGuardrailEntry, type FailOn, type FinalDecision, type FullHarnessAxisScore, type FullHarnessCalibrationRef, type FullHarnessEvidenceRefs, type FullHarnessHistory, type FullHarnessIteration, type FullHarnessReviewerScore, type FullHarnessScoreSnapshot, type GuardrailCheckResult, type GuardrailIssue, type GuardrailIssueSeverity, type GuardrailLoadError, type GuardrailLoadResult, type GuardrailType, ID_PREFIXES, type IdFormatPrefix, type IdPrefix, type Issue, type IssueCategory, type IssueLocation, type IssueSeverity, type MeasurementInput, type MeasurementResult, type ModeResolutionResult, type ModeSelectionSource, type OrphanContractsPolicy, type OutputFormat, PROTOTYPING_MAX_CYCLES, PROTOTYPING_MAX_ITERATIONS, PROTOTYPING_MODES, PROTOTYPING_SUPPORTED_SURFACES, type PrototypingBrowserTool, type PrototypingMode, type PrototypingObligations, type PrototypingSurface, type QfaiConfig, type QfaiOutputConfig, type QfaiPaths, type QfaiPrototypingCalibrationConfig, type QfaiPrototypingConfig, type QfaiPrototypingExecutionConfig, type QfaiUiuxAuditConfig, type QfaiUiuxConfig, type QfaiValidationConfig, REVIEWER_PLACEHOLDERS, type ReportChangeType, type ReportChangeTypeSummary, type ReportChangeTypeWarning, type ReportContractCoverage, type ReportData, type ReportDeltaCoverage, type ReportFullHarnessExecution, type ReportGuardrailItem, type ReportGuardrails, type ReportIds, type ReportPrototypingSummary, type ReportRoundLifecycle, type ReportRuleFinding, type ReportSpecContractRefs, type ReportSpecCoverage, type ReportSummary, type ReportSurfaceClassification, type ReportTddCoverage, type ReportTddCoverageSpec, type ReportTestStrategy, type ReportTraceability, type ReportWaivers, type ReviewerLogVerdict, type ReviewerSignoffStatus, type RunSddPreflightOptions, type SddPreflightResult, type SddPreflightSource, type SddPreflightStatus, type TerminationReason, type TraceabilitySeverity, type UiFidelityStatus, VISUAL_BROWSER_SURFACES, type ValidationCounts, type ValidationOptions, type ValidationProfile, type ValidationResult, type ValidationTraceability, type ValidationWaiverAction, type ValidationWaiverDowngradeTo, type ValidationWaiverEntry, type ValidationWaiverMatch, type ValidationWaiverScope, type ValidationWaiverSeverity, type ValidationWaiverSuppressed, type ValidationWaivers, appendIteration, checkDecisionGuardrails, computeTerminationReason, createReportData, defaultConfig, derivePrototypingObligations, evaluateAtddCodeTraceability, extractAcSpecNumber, extractAllIds, extractBrSpecNumber, extractCapSpecNumber, extractCaseSpecNumber, extractDecisionGuardrailsFromMarkdown, extractIds, extractInvalidIds, extractScSpecNumber, extractSpecNumber, extractUsSpecNumber, filterDecisionGuardrailsByKeyword, findConfigRoot, formatGuardrailsForLlm, formatReportJson, formatReportMarkdown, getConfigPath, isDiscussionUiBearingSurfaceType, isNonUiDiscussionSurface, isSupportedPrototypingSurface, isValidPrototypingMode, isValidPrototypingSurface, lintSql, loadConfig, loadDecisionGuardrails, loadHistory, normalizeDecisionGuardrails, requiresVisualBrowserEvidence, resolveCommitSha, resolvePath, resolvePrototypingMode, resolveToolVersion, runBrowserQaOrchestrated, runRenderCapture, runSddPreflight, sortDecisionGuardrails, summarizeBrowserQaResult, validateAtddCodeTraceability, validateContracts, validateDefinedIds, validateLayeredTraceability, validateOrphanProhibition, validateProject, validateReviewer, validateSpecSplitByCapability, validateTraceability, writeEvidenceBundles };

package/dist/index.d.ts

@@ -37,7 +37,7 @@ type ValidationCounts = {
     warning: number;
     error: number;
 };
-type ValidationPhase = "full" | "atdd" | "tdd" | "refinement";
+type ValidationProfile = "discussion" | "sdd" | "prototyping" | "atdd" | "tdd" | "verify" | "full";
 type ValidationTraceability = {
     sc: ScCoverage;
     testFiles: TestFileScan;
@@ -78,7 +78,7 @@ type ValidationWaivers = {
 };
 type ValidationResult = {
     toolVersion: string;
-    phase?: ValidationPhase;
+    profile?: ValidationProfile;
     issues: Issue[];
     counts: ValidationCounts;
     traceability: ValidationTraceability;
@@ -121,6 +121,12 @@ type QfaiValidationConfig = {
         requireSizeTags: boolean;
         maxE2eScenarioRatio: number | null;
         maxE2eScenarioCount: number | null;
+        /**
+         * When true (default), `qfai validate` rejects `it.todo` / `test.todo` /
+         * `describe.todo` stubs in test files (spec-0012, QFAI-TEST-001).
+         * Set to false to opt out while migrating an existing project.
+         */
+        forbidTestTodoStubs: boolean;
     };
     traceability: {
         brMustHaveSc: boolean;
@@ -156,13 +162,24 @@ type QfaiUiuxConfig = {
 type QfaiPrototypingCalibrationConfig = {
     packPath?: string;
 };
+type QfaiPrototypingExecutionConfig = {
+    targetUrl?: string | null;
+    /**
+     * Browser tool handed to the AI evaluator sub-agent (spec-0012).
+     * The only accepted value is `"playwright-cli"`.
+     */
+    browserTool: "playwright-cli";
+};
 type QfaiPrototypingConfig = {
     calibration?: QfaiPrototypingCalibrationConfig;
-    execution?: {
-        targetUrl?: string | null;
-        browserProvider?: string;
-        renderProvider?: string;
-    };
+    execution?: QfaiPrototypingExecutionConfig;
+    /**
+     * v1.8.4: explicit primary spec ID for `/qfai-prototyping`. If omitted,
+     * `resolvePrimaryPrototypingSpec` auto-detects via the prototyping marker
+     * (`surface_type: ui-bearing`) in `01_Spec.md`. Format: 4-digit string,
+     * e.g. `"0012"`.
+     */
+    primarySpecId?: string;
 };
 type QfaiConfig = {
     paths: QfaiPaths;
@@ -314,6 +331,22 @@ type CanonicalPrototypingSurface = (typeof CANONICAL_PROTOTYPING_SURFACES)[numbe
 
 declare const PROTOTYPING_MODES: readonly ["low-cost", "standard", "full-harness"];
 declare const DEFAULT_PROTOTYPING_MODE: "standard";
+/**
+ * Maximum cycles permitted per prototyping mode.
+ *
+ * Per spec-0017 REQ-0001 (mode invariant), modes differ only in maxCycles.
+ * All other obligations (review cycle, evidence, reviewer gate, completion
+ * criteria) are identical across modes.
+ */
+declare const PROTOTYPING_MAX_CYCLES: {
+    readonly "low-cost": 1;
+    readonly standard: 3;
+    readonly "full-harness": 20;
+};
+/**
+ * Alias retained for callers still using spec-0012 wording.
+ * Will be removed in a later phase once all callers reference PROTOTYPING_MAX_CYCLES.
+ */
 declare const PROTOTYPING_MAX_ITERATIONS: {
     readonly "low-cost": 1;
     readonly standard: 3;
@@ -323,18 +356,42 @@ declare const PROTOTYPING_SUPPORTED_SURFACES: readonly ["web", "mobile", "deskto
 type PrototypingMode = (typeof PROTOTYPING_MODES)[number];
 type ModeSelectionSource = "explicit-request" | "system-default";
 type PrototypingSurface = CanonicalPrototypingSurface;
+type PrototypingBrowserTool = "playwright-cli";
 type ModeResolutionResult = {
     requested?: PrototypingMode;
     effective: PrototypingMode;
     source: ModeSelectionSource;
     rationale: string;
 };
+/**
+ * Prototyping obligations (spec-0017 REQ-0001, REQ-0002, REQ-0004).
+ *
+ * Every obligation flag is true for every mode. The only mode-dependent
+ * value is {@link maxCycles}. Validators enforcing per-mode differentiation
+ * for any other field violate the mode invariant (QFAI-PROT-MODE-001).
+ */
 type PrototypingObligations = {
+    /** Browser tool handed to the AI evaluator sub-agent. */
+    browserTool: PrototypingBrowserTool;
+    requireExecutionPlan: boolean;
+    requirePlaywrightEvidence: boolean;
+    requireReviewBundle: boolean;
+    requireEvaluatorReview: boolean;
+    requireBestOfHistory: boolean;
+    requireBreakthrough: boolean;
+    requireIndependentReviewerGate: boolean;
+    requirePerfect100Completion: boolean;
     requireRuntimeGate: boolean;
     requireUiFidelity: boolean;
     requireRenderBundle: boolean;
     requireBrowserQaBundle: boolean;
     requireIterations: boolean;
+    /** Cycle budget; the only mode-dependent value (spec-0017 REQ-0001). */
+    maxCycles: number;
+    /**
+     * Alias for {@link maxCycles} kept for callers still using the spec-0012
+     * "iterations" vocabulary. Same numeric value.
+     */
     maxIterations: number;
     validCombination: boolean;
     invalidReason?: string;
@@ -348,6 +405,13 @@ declare function isValidPrototypingMode(value: unknown): value is PrototypingMod
 declare function isValidPrototypingSurface(value: unknown): value is PrototypingSurface;
 declare function isSupportedPrototypingSurface(surface: string): surface is PrototypingSurface;
 declare function resolvePrototypingMode(requested?: PrototypingMode): ModeResolutionResult;
+/**
+ * Derive prototyping obligations for a (surface, mode) pair.
+ *
+ * Per spec-0017 REQ-0001 the return value is identical across modes except
+ * for {@link PrototypingObligations.maxCycles}. Callers MUST NOT branch
+ * on mode when deciding which obligation to enforce.
+ */
 declare function derivePrototypingObligations(input: {
     surface: PrototypingSurface;
     effectiveMode: PrototypingMode;
@@ -544,9 +608,25 @@ type ReportFullHarnessExecution = {
     browserQaPhasesSkipped: number;
     browserQaTotalFindings: number;
 };
+type ReportRoundLifecycle = {
+    schemaVersion: "2.0";
+    rounds: number;
+    roundIds: string[];
+    candidatesObserved: number;
+    perfectRounds: number;
+    harvestArtifacts: number;
+    narrowDecisions: number;
+    absorptionPlans: number;
+    reimplementations: number;
+    polishCycles: number;
+    completedPolishCycles: number;
+    perfectPolishCycles: number;
+    polishKinds: Record<string, number>;
+};
 type ReportPrototypingSummary = {
     surfaceClassification?: ReportSurfaceClassification;
     fullHarnessExecution?: ReportFullHarnessExecution;
+    roundLifecycle?: ReportRoundLifecycle;
     mode: {
         requested?: string;
         effective: string;
@@ -662,7 +742,7 @@ declare function formatReportMarkdown(data: ReportData, options?: ReportMarkdown
 declare function formatReportJson(data: ReportData): string;
 
 type ValidationOptions = {
-    phase?: ValidationPhase;
+    profile?: ValidationProfile;
     platform?: string;
 };
 declare function validateProject(root: string, configResult?: ConfigLoadResult, options?: ValidationOptions): Promise<ValidationResult>;
@@ -682,7 +762,9 @@ declare function validateOrphanProhibition(root: string, config: QfaiConfig): Pr
 
 declare function validateSpecSplitByCapability(root: string, config: QfaiConfig): Promise<Issue[]>;
 
-declare function validateTraceability(root: string, config: QfaiConfig, phase: ValidationPhase): Promise<Issue[]>;
+declare function validateTraceability(root: string, config: QfaiConfig, options: {
+    includeCodeReferences: boolean;
+}): Promise<Issue[]>;
 
 type SurfaceType = CanonicalPrototypingSurface | "non-ui";
 declare const DISCUSSION_UI_BEARING_SURFACES: Set<SurfaceType>;
@@ -843,10 +925,13 @@ type FullHarnessHandoff = {
 };
 
 /**
- * Full-harness mode types.
+ * Legacy full-harness mode types (spec-0012).
  *
- * Full-harness now follows the reviewerScores/allItemsPass95 evidence schema
- * used by prototyping.json. Legacy weighted totals are intentionally excluded.
+ * NOTE: superseded by the cycle-centric `PrototypingCycleEvidence` /
+ * `PrototypingEvidenceRecord` schema in
+ * `packages/qfai/src/core/prototyping/types.ts` (spec-0017 REQ-0005).
+ * New code should consume the prototyping schema. Legacy callers remain
+ * supported for back-compat with spec-0012 callers.
  */
 type FullHarnessAxisScore = {
     axisId: string;
@@ -877,7 +962,7 @@ type FullHarnessIteration = {
     limitations: string[];
     evidenceRefs: FullHarnessEvidenceRefs;
     reviewerScores: FullHarnessReviewerScore[];
-    allItemsPass95: boolean;
+    allReviewerAxesPerfect100: boolean;
     stopReason?: string;
 };
 type TerminationReason = "converged" | "max-iterations" | "plateau" | "manual-stop";
@@ -890,7 +975,7 @@ type FullHarnessScoreSnapshot = {
     axisCount: number;
     minScore: number | null;
     averageScore: number | null;
-    allItemsPass95: boolean;
+    allReviewerAxesPerfect100: boolean;
     commitSha: string;
 };
 type FullHarnessHistory = {
@@ -918,7 +1003,7 @@ type MeasurementInput = {
     discussionDirRelative?: string;
     trendRefs: string[];
     reviewerScores: FullHarnessReviewerScore[];
-    allItemsPass95: boolean;
+    allReviewerAxesPerfect100: boolean;
     stopReason?: string;
 };
 type MeasurementResult = {
@@ -1065,7 +1150,7 @@ declare function writeEvidenceBundles(input: {
  *
  * Reads previous iterations from prototyping.json,
  * appends new iteration, and recomputes bestIteration/scoringTrace from
- * reviewerScores/allItemsPass95 evidence.
+ * reviewerScores/allReviewerAxesPerfect100 evidence.
  */
 
 declare function loadHistory(root: string): Promise<FullHarnessHistory | null>;
@@ -1097,10 +1182,4 @@ declare function validateReviewer(reviewer: string | undefined): string;
  */
 declare function resolveCommitSha(root: string): Promise<string>;
 
-declare function createPlaywrightRenderAdapter(input: {
-    targetUrl?: string;
-}): RenderCaptureAdapter;
-
-declare function createPlaywrightBrowserQaProvider(): BrowserQaProvider;
-
-export { type AtddCodeTraceabilityResult, type AtddForbiddenRef, type AtddSpecRefs, type AtddTestKind, type AtddTraceabilityMissing, type AtddTraceabilityScan, type AtddUnknownRef, type AtddUnknownRefKind, BROWSER_QA_PHASES, type ConfigLoadResult, type ConfigPathKey, type ConfigSearchResult, DEFAULT_PROTOTYPING_MODE, DISCUSSION_NON_UI_SURFACES, DISCUSSION_UI_BEARING_SURFACES, type DecisionGuardrail, type DecisionGuardrailEntry, type FailOn, type FinalDecision, type FullHarnessAxisScore, type FullHarnessCalibrationRef, type FullHarnessEvidenceRefs, type FullHarnessHistory, type FullHarnessIteration, type FullHarnessReviewerScore, type FullHarnessScoreSnapshot, type GuardrailCheckResult, type GuardrailIssue, type GuardrailIssueSeverity, type GuardrailLoadError, type GuardrailLoadResult, type GuardrailType, ID_PREFIXES, type IdFormatPrefix, type IdPrefix, type Issue, type IssueCategory, type IssueLocation, type IssueSeverity, type MeasurementInput, type MeasurementResult, type ModeResolutionResult, type ModeSelectionSource, type OrphanContractsPolicy, type OutputFormat, PROTOTYPING_MAX_ITERATIONS, PROTOTYPING_MODES, PROTOTYPING_SUPPORTED_SURFACES, type PrototypingMode, type PrototypingObligations, type PrototypingSurface, type QfaiConfig, type QfaiOutputConfig, type QfaiPaths, type QfaiPrototypingCalibrationConfig, type QfaiPrototypingConfig, type QfaiUiuxAuditConfig, type QfaiUiuxConfig, type QfaiValidationConfig, REVIEWER_PLACEHOLDERS, type ReportChangeType, type ReportChangeTypeSummary, type ReportChangeTypeWarning, type ReportContractCoverage, type ReportData, type ReportDeltaCoverage, type ReportFullHarnessExecution, type ReportGuardrailItem, type ReportGuardrails, type ReportIds, type ReportPrototypingSummary, type ReportRuleFinding, type ReportSpecContractRefs, type ReportSpecCoverage, type ReportSummary, type ReportSurfaceClassification, type ReportTddCoverage, type ReportTddCoverageSpec, type ReportTestStrategy, type ReportTraceability, type ReportWaivers, type ReviewerLogVerdict, type ReviewerSignoffStatus, type RunSddPreflightOptions, type SddPreflightResult, type SddPreflightSource, type SddPreflightStatus, type TerminationReason, type TraceabilitySeverity, type UiFidelityStatus, VISUAL_BROWSER_SURFACES, type ValidationCounts, type ValidationOptions, type ValidationPhase, type ValidationResult, type ValidationTraceability, type ValidationWaiverAction, type ValidationWaiverDowngradeTo, type ValidationWaiverEntry, type ValidationWaiverMatch, type ValidationWaiverScope, type ValidationWaiverSeverity, type ValidationWaiverSuppressed, type ValidationWaivers, appendIteration, checkDecisionGuardrails, computeTerminationReason, createPlaywrightBrowserQaProvider, createPlaywrightRenderAdapter, createReportData, defaultConfig, derivePrototypingObligations, evaluateAtddCodeTraceability, extractAcSpecNumber, extractAllIds, extractBrSpecNumber, extractCapSpecNumber, extractCaseSpecNumber, extractDecisionGuardrailsFromMarkdown, extractIds, extractInvalidIds, extractScSpecNumber, extractSpecNumber, extractUsSpecNumber, filterDecisionGuardrailsByKeyword, findConfigRoot, formatGuardrailsForLlm, formatReportJson, formatReportMarkdown, getConfigPath, isDiscussionUiBearingSurfaceType, isNonUiDiscussionSurface, isSupportedPrototypingSurface, isValidPrototypingMode, isValidPrototypingSurface, lintSql, loadConfig, loadDecisionGuardrails, loadHistory, normalizeDecisionGuardrails, requiresVisualBrowserEvidence, resolveCommitSha, resolvePath, resolvePrototypingMode, resolveToolVersion, runBrowserQaOrchestrated, runRenderCapture, runSddPreflight, sortDecisionGuardrails, summarizeBrowserQaResult, validateAtddCodeTraceability, validateContracts, validateDefinedIds, validateLayeredTraceability, validateOrphanProhibition, validateProject, validateReviewer, validateSpecSplitByCapability, validateTraceability, writeEvidenceBundles };
+export { type AtddCodeTraceabilityResult, type AtddForbiddenRef, type AtddSpecRefs, type AtddTestKind, type AtddTraceabilityMissing, type AtddTraceabilityScan, type AtddUnknownRef, type AtddUnknownRefKind, BROWSER_QA_PHASES, type ConfigLoadResult, type ConfigPathKey, type ConfigSearchResult, DEFAULT_PROTOTYPING_MODE, DISCUSSION_NON_UI_SURFACES, DISCUSSION_UI_BEARING_SURFACES, type DecisionGuardrail, type DecisionGuardrailEntry, type FailOn, type FinalDecision, type FullHarnessAxisScore, type FullHarnessCalibrationRef, type FullHarnessEvidenceRefs, type FullHarnessHistory, type FullHarnessIteration, type FullHarnessReviewerScore, type FullHarnessScoreSnapshot, type GuardrailCheckResult, type GuardrailIssue, type GuardrailIssueSeverity, type GuardrailLoadError, type GuardrailLoadResult, type GuardrailType, ID_PREFIXES, type IdFormatPrefix, type IdPrefix, type Issue, type IssueCategory, type IssueLocation, type IssueSeverity, type MeasurementInput, type MeasurementResult, type ModeResolutionResult, type ModeSelectionSource, type OrphanContractsPolicy, type OutputFormat, PROTOTYPING_MAX_CYCLES, PROTOTYPING_MAX_ITERATIONS, PROTOTYPING_MODES, PROTOTYPING_SUPPORTED_SURFACES, type PrototypingBrowserTool, type PrototypingMode, type PrototypingObligations, type PrototypingSurface, type QfaiConfig, type QfaiOutputConfig, type QfaiPaths, type QfaiPrototypingCalibrationConfig, type QfaiPrototypingConfig, type QfaiPrototypingExecutionConfig, type QfaiUiuxAuditConfig, type QfaiUiuxConfig, type QfaiValidationConfig, REVIEWER_PLACEHOLDERS, type ReportChangeType, type ReportChangeTypeSummary, type ReportChangeTypeWarning, type ReportContractCoverage, type ReportData, type ReportDeltaCoverage, type ReportFullHarnessExecution, type ReportGuardrailItem, type ReportGuardrails, type ReportIds, type ReportPrototypingSummary, type ReportRoundLifecycle, type ReportRuleFinding, type ReportSpecContractRefs, type ReportSpecCoverage, type ReportSummary, type ReportSurfaceClassification, type ReportTddCoverage, type ReportTddCoverageSpec, type ReportTestStrategy, type ReportTraceability, type ReportWaivers, type ReviewerLogVerdict, type ReviewerSignoffStatus, type RunSddPreflightOptions, type SddPreflightResult, type SddPreflightSource, type SddPreflightStatus, type TerminationReason, type TraceabilitySeverity, type UiFidelityStatus, VISUAL_BROWSER_SURFACES, type ValidationCounts, type ValidationOptions, type ValidationProfile, type ValidationResult, type ValidationTraceability, type ValidationWaiverAction, type ValidationWaiverDowngradeTo, type ValidationWaiverEntry, type ValidationWaiverMatch, type ValidationWaiverScope, type ValidationWaiverSeverity, type ValidationWaiverSuppressed, type ValidationWaivers, appendIteration, checkDecisionGuardrails, computeTerminationReason, createReportData, defaultConfig, derivePrototypingObligations, evaluateAtddCodeTraceability, extractAcSpecNumber, extractAllIds, extractBrSpecNumber, extractCapSpecNumber, extractCaseSpecNumber, extractDecisionGuardrailsFromMarkdown, extractIds, extractInvalidIds, extractScSpecNumber, extractSpecNumber, extractUsSpecNumber, filterDecisionGuardrailsByKeyword, findConfigRoot, formatGuardrailsForLlm, formatReportJson, formatReportMarkdown, getConfigPath, isDiscussionUiBearingSurfaceType, isNonUiDiscussionSurface, isSupportedPrototypingSurface, isValidPrototypingMode, isValidPrototypingSurface, lintSql, loadConfig, loadDecisionGuardrails, loadHistory, normalizeDecisionGuardrails, requiresVisualBrowserEvidence, resolveCommitSha, resolvePath, resolvePrototypingMode, resolveToolVersion, runBrowserQaOrchestrated, runRenderCapture, runSddPreflight, sortDecisionGuardrails, summarizeBrowserQaResult, validateAtddCodeTraceability, validateContracts, validateDefinedIds, validateLayeredTraceability, validateOrphanProhibition, validateProject, validateReviewer, validateSpecSplitByCapability, validateTraceability, writeEvidenceBundles };