qfai 1.7.9 → 1.7.13

package/dist/index.d.ts

@@ -14,7 +14,7 @@ type TestFileScan = {
 };
 
 type IssueSeverity = "info" | "warning" | "error";
-type IssueCategory = "compatibility" | "change";
+type IssueCategory = "canonical" | "compatibility" | "change";
 type IssueLocation = {
     line: number;
     column?: number;
@@ -158,11 +158,32 @@ type QfaiUiuxConfig = {
     audit?: QfaiUiuxAuditConfig;
     migration?: QfaiUiuxMigrationConfig;
 };
+type QfaiPrototypingCalibrationConfig = {
+    packPath?: string;
+    thresholds?: {
+        accept?: number;
+        refine?: number;
+    };
+    maxIterations?: number;
+    plateauDelta?: number;
+    plateauLookback?: number;
+};
+type QfaiPrototypingConfig = {
+    calibration?: QfaiPrototypingCalibrationConfig;
+    execution?: {
+        targetUrl?: string | null;
+        browserProvider?: string;
+        renderProvider?: string;
+        reviewer?: string;
+    };
+};
 type QfaiConfig = {
     paths: QfaiPaths;
     validation: QfaiValidationConfig;
     output: QfaiOutputConfig;
     uiux?: QfaiUiuxConfig;
+    prototyping?: QfaiPrototypingConfig;
+    baseBranch?: string;
 };
 type ConfigPathKey = keyof QfaiPaths;
 type ConfigLoadResult = {
@@ -301,241 +322,354 @@ declare function extractAcSpecNumber(acId: string): string | null;
 declare function extractCaseSpecNumber(caseId: string): string | null;
 declare function extractScSpecNumber(scId: string): string | null;
 
-type SddPreflightSource = "discussion-pack";
-type SddPreflightStatus = "ready" | "blocked";
-type RunSddPreflightOptions = {
-    assumptions?: string[];
+type PrototypingMode = "low-cost" | "standard" | "full-harness";
+type ModeSelectionSource = "explicit-request" | "discussion-recommendation" | "system-default";
+type PrototypingSurface = "web" | "mobile" | "desktop" | "cli" | "mixed" | "non-ui";
+/** @deprecated Legacy surface values — use canonical PrototypingSurface instead */
+type LegacyPrototypingSurface = "web-ui" | "mobile-ui" | "desktop-ui";
+type DiscussionRecommendationSourceSchema = "canonical-namespaced" | "legacy-top-level";
+/**
+ * Canonical validated recommendation — all 4 fields required.
+ * Parser output uses this same type; fields are always populated
+ * because extractRecommendation returns null when any field is missing.
+ */
+type DiscussionModeRecommendation = {
+    recommendedMode: PrototypingMode;
+    rationale: string;
+    allowedModes: PrototypingMode[];
+    surface: PrototypingSurface;
+    updatedAt?: string | undefined;
+    sourceSchema?: DiscussionRecommendationSourceSchema | undefined;
+};
+type ModeResolutionInput = {
+    explicitMode?: PrototypingMode | undefined;
+    discussionRecommendation?: DiscussionModeRecommendation | null | undefined;
+    defaultMode?: PrototypingMode | undefined;
+};
+type ModeResolutionResult = {
+    requested?: PrototypingMode | undefined;
+    effective: PrototypingMode;
+    source: ModeSelectionSource;
+    rationale: string;
 };
-type SddPreflightResult = {
-    status: SddPreflightStatus;
-    source: SddPreflightSource;
-    selectedInputPath: string | null;
-    importedReqCount: number | null;
-    openQuestions: string[];
-    blockers: string[];
-    nextCommands: string[];
-    preflightSummaryPath: string;
+type ResolvedModeSummary = ModeResolutionResult & {
+    discussionRecommendation?: DiscussionModeRecommendation | undefined;
+    surface?: PrototypingSurface | undefined;
+    warnings: string[];
+};
+type PrototypingObligations = {
+    requireRuntimeGate: boolean;
+    requireUiFidelity: boolean;
+    requireRenderBundle: boolean;
+    requireBrowserQaBundle: boolean;
+    requireFullHarness: boolean;
+};
+type ResolveModeInput = {
+    requested?: PrototypingMode | undefined;
+    discussionArtifact?: unknown;
+    defaultMode?: PrototypingMode | undefined;
+};
+type PrototypingExecutionConfig = {
+    targetUrl?: string | null;
+    browserProvider?: string;
+    renderProvider?: string;
+};
+type UiFidelityStatus = {
+    required: boolean;
+    status: "completed" | "failed" | "n/a";
+    reason?: string;
 };
-declare function runSddPreflight(root: string, config: QfaiConfig, options?: RunSddPreflightOptions): Promise<SddPreflightResult>;
 
-type CrawlStatus = "ok" | "failed";
-type UiFidelityAutogenExpected = {
-    route: string;
-    uiContractId: string;
-    labels: string[];
-    elementIds: string[];
-    elementPairs: Array<{
-        id: string;
-        label: string;
-    }>;
-    elementCount: number;
-    actionIds: string[];
-    mockPathIds: string[];
-    navigateTargets: string[];
-};
-type UiFidelityAutogenCrawlResult = {
-    route: string;
-    status: CrawlStatus;
-    httpStatus: number | null;
-    labels: string[];
-    markers: string[];
-    error?: string;
-};
-type UiFidelityAutogenMockPathResult = {
-    route: string;
-    uiContractId: string;
-    entries: Array<{
-        id: string;
-        status: string;
-        note?: string;
-    }>;
-};
-type UiFidelityLabelCoverage = {
-    found: string[];
-    missing: string[];
-    coverage: number;
+type ParseDiscussionResult = {
+    recommendation: DiscussionModeRecommendation | null;
+    warnings: string[];
 };
-type UiFidelityGeneratedScreen = {
-    route: string;
-    uiContractId: string;
-    expected: {
-        elements: number;
-        actions: number;
-        labels: string[];
-        ids: string[];
-    };
-    found: {
-        labels: string[];
-        markers: string[];
-    };
-    missing: {
-        labels: string[];
-        markers: string[];
-    };
-    coverage: number;
-    observed: {
-        elementsPlaced: number;
-        actionsWired: number;
-    };
-    mockPaths: Array<{
-        id: string;
-        status: string;
-        note?: string;
-    }>;
-};
-type UiFidelityAutogenResult = {
-    expected: UiFidelityAutogenExpected[];
-    crawled: UiFidelityAutogenCrawlResult[];
-    mockPaths: UiFidelityAutogenMockPathResult[];
-    screens: UiFidelityGeneratedScreen[];
-};
-declare function collectExpectedFromContracts(root: string, config: QfaiConfig): Promise<UiFidelityAutogenExpected[]>;
-declare function crawlRoutesAndCollectFoundLabels(baseUrl: string, routes: string[]): Promise<UiFidelityAutogenCrawlResult[]>;
-declare function runMockPaths(expectedScreens: UiFidelityAutogenExpected[], crawledRoutes: UiFidelityAutogenCrawlResult[]): UiFidelityAutogenMockPathResult[];
-declare function computeLabelCoverage(expectedLabels: string[], foundLabelsFromDom: string[]): UiFidelityLabelCoverage;
-declare function buildUiFidelityScreens(expectedScreens: UiFidelityAutogenExpected[], crawledRoutes: UiFidelityAutogenCrawlResult[], mockPathResults: UiFidelityAutogenMockPathResult[]): UiFidelityGeneratedScreen[];
-declare function autogenerateUiFidelity(root: string, config: QfaiConfig, baseUrl: string, routeHints: string[]): Promise<UiFidelityAutogenResult>;
-declare function emitUiFidelity(input: {
-    evidence: Record<string, unknown>;
-    toolVersion: string;
-    command: string;
-    baseUrl: string;
-    status: "success" | "failed" | "skipped";
-    screens?: UiFidelityGeneratedScreen[];
-    crawled?: UiFidelityAutogenCrawlResult[];
-    reason?: string;
-}): Record<string, unknown>;
-declare function extractDomMarkers(html: string): string[];
-
 /**
- * Mode resolver for prototyping obligations.
- *
- * Separates static-first obligations (default) from runtime-heavy checks (opt-in).
- * Static-first default ensures prototyping completes without browser/backend installed.
- *
- * NOTE: v1.7.5 scope is foundation-only. This module defines the obligation
- * vocabulary and resolution logic. Wiring into the prototyping command/validator
- * evaluation path is deferred to v1.7.6 when the full mode-switching UX is added.
+ * Parse a prototyping.yaml file from a discussion pack.
+ * Supports both canonical namespaced (`prototyping.*`) and legacy top-level schema.
  */
-type PrototypingMode = "default" | "standard" | "low-cost" | "full-harness";
-/** Static obligations that require no runtime infrastructure. */
-declare const STATIC_OBLIGATIONS: readonly ["source", "route", "state", "contract-level"];
-/** Runtime-heavy checks that require external infrastructure (opt-in only). */
-declare const RUNTIME_HEAVY_CHECKS: readonly ["api-non-404", "db-existence", "ui-route-reachability"];
+declare function parseDiscussionModeRecommendation(filePath: string): Promise<DiscussionModeRecommendation | null>;
+declare function parseDiscussionModeRecommendationWithWarnings(filePath: string): Promise<ParseDiscussionResult>;
+declare function parseDiscussionFromObject(parsed: Record<string, unknown>): ParseDiscussionResult;
+declare function resolvePrototypingMode(input: ModeResolutionInput): ModeResolutionResult;
 /**
- * Resolve the active obligation set for a given prototyping mode.
- *
- * - `"default"` / `"standard"`: static obligations only
- * - `"low-cost"`: static obligations (runtime-heavy excluded)
- * - `"full-harness"`: static + runtime-heavy obligations
+ * Full resolved mode summary with discussion recommendation context and warnings.
  */
-declare function resolveObligations(mode: PrototypingMode): string[];
+declare function summarizeResolvedMode(input: ModeResolutionInput): ResolvedModeSummary;
 /**
- * Resolve obligations with explicit opt-in for runtime-heavy checks.
- * Only checks listed in RUNTIME_HEAVY_CHECKS are accepted as opt-ins.
+ * Resolve mode from raw input (ResolveModeInput) — includes discussion artifact parsing.
  */
-declare function resolveObligationsWithOptIn(mode: PrototypingMode, optIn: string[]): string[];
-
-type DiscussionRecommendation = {
-    recommended_mode: string | null;
-    rationale: string | null;
-};
+declare function resolvePrototypingModeFromInput(input: ResolveModeInput): ResolvedModeSummary;
+declare function normalizeSurface(input: unknown): PrototypingSurface | null;
+declare function inferSurfaceFromRecommendationAndEvidence(input: {
+    recommendationSurface?: PrototypingSurface | undefined;
+    evidenceSurface?: PrototypingSurface | undefined;
+    hasUiFidelity?: boolean | undefined;
+    hasRenderBundle?: boolean | undefined;
+    hasBrowserQaBundle?: boolean | undefined;
+    hasUiRoutes?: boolean | undefined;
+    hasRuntimeGateUi?: boolean | undefined;
+}): PrototypingSurface;
+declare function derivePrototypingObligations(input: {
+    surface: PrototypingSurface;
+    effectiveMode: PrototypingMode;
+}): PrototypingObligations;
+declare function isValidPrototypingMode(value: unknown): value is PrototypingMode;
+declare function isValidPrototypingSurface(value: unknown): value is PrototypingSurface;
 /**
- * Read prototyping recommendation from a discussion pack directory.
- *
- * Looks for `prototyping.yaml` in the given directory and extracts
- * `prototyping.recommended_mode` and `prototyping.rationale`.
- *
- * @param discussionPackDir - Path to the discussion pack directory
- * @returns Recommendation with nullable fields; never throws
+ * Normalize a surface value: map legacy values to canonical equivalents.
  */
-declare function readDiscussionRecommendation(discussionPackDir: string): Promise<DiscussionRecommendation>;
+declare function normalizePrototypingSurface(value: string): PrototypingSurface;
+declare function isUiBearingSurface(surface: PrototypingSurface): boolean;
+declare function normalizeAllowedModes(modes?: string[]): PrototypingMode[];
 
 /**
- * Precedence resolver for prototyping mode.
+ * Render evidence types — WS-C
  *
- * Resolves effective mode from three sources in strict order:
- * 1. CLI `--mode` flag (cli-override)
- * 2. Discussion artifact `recommended_mode` (discussion-recommendation)
- * 3. System default `standard` (default) — per DR-0084
- *
- * Phase M2 of v1.7.7 Mode Switch UX (spec-0006).
+ * Canonical types for the render evidence capture pipeline.
  */
-
-type ModeSource = "cli-override" | "discussion-recommendation" | "default";
-type ModeResolution = {
-    effective_mode: PrototypingMode;
-    mode_source: ModeSource;
-    recommended_mode: PrototypingMode | null;
-    rationale: string;
+type RenderCaptureTarget = {
+    targetId: string;
+    route?: string;
+    descriptor?: string;
+    viewport: string;
+    width?: number;
+    height?: number;
+};
+type RenderCaptureAdapter = {
+    captureScreenshot(target: RenderCaptureTarget, outputDir: string): Promise<string>;
+    captureHtml?(target: RenderCaptureTarget, outputDir: string): Promise<string>;
+};
+type RenderEvidenceEntryResult = {
+    capture_id: string;
+    target: string;
+    status: "captured" | "skipped" | "failed";
+    screenshot_path?: string;
+    html_path?: string;
+    viewport: string;
+    reason?: string;
 };
-type PrecedenceInput = {
-    cliMode: PrototypingMode | null;
-    discussion: DiscussionRecommendation | null;
+type RenderRunnerResult = {
+    entries: RenderEvidenceEntryResult[];
+    filesWritten: string[];
+    surface?: string;
+    mode?: string;
+    generatedAt?: string;
+    coverageSummary?: {
+        total: number;
+        captured: number;
+        failed: number;
+        skipped: number;
+    };
 };
+
 /**
- * Resolve the effective prototyping mode from available sources.
+ * Critique adapter types for external critique providers.
  *
- * @param input.cliMode - Mode from CLI `--mode` flag, or null if not provided
- * @param input.discussion - Discussion recommendation, or null if unavailable
- * @returns Mode resolution result with source attribution
+ * Provider interface is minimal (BR-0029-0001). Each provider implements
+ * `request()` and the adapter wraps it with fail-open semantics (NFR-0002).
  */
-declare function resolvePrecedence(input: PrecedenceInput): ModeResolution;
+type CritiqueInput = {
+    output: string;
+    context: string;
+    iteration: number;
+};
+type CritiqueResponse = {
+    scores: Record<string, number>;
+    dimensions: string[];
+    suggestions: string[];
+};
+type CritiqueProvider = {
+    name: string;
+    request: (input: CritiqueInput, signal?: AbortSignal) => Promise<CritiqueResponse>;
+};
+type CritiqueResult = {
+    failOpen: false;
+    response: CritiqueResponse;
+} | {
+    failOpen: true;
+    response: undefined;
+    reason: string;
+};
 
 /**
- * Mode resolution logger for prototyping.
- *
- * Formats mode resolution results into structured log entries containing:
- * mode_source, recommended_mode, effective_mode, rationale, evidence_expectations.
+ * Critique adapter with fail-open semantics (NFR-0002).
  *
- * Phase M3 of v1.7.7 Mode Switch UX (spec-0006).
+ * Wraps external critique providers with schema validation,
+ * timeout enforcement, and fail-open on any error.
  */
 
-type ModeLogEntry = {
-    mode_source: ModeSource;
-    recommended_mode: PrototypingMode | null;
-    effective_mode: PrototypingMode;
-    rationale: string;
-    evidence_expectations: string;
-};
-declare const VALID_MODE_SOURCES: ReadonlySet<ModeSource>;
+declare class CritiqueAdapter {
+    private provider;
+    private timeoutMs;
+    constructor(options?: {
+        timeoutMs?: number;
+    });
+    register(provider: CritiqueProvider): void;
+    requestCritique(input: CritiqueInput): Promise<CritiqueResult>;
+}
+
+type SurfaceType = "web" | "mobile" | "desktop" | "cli" | "mixed" | "non-ui";
+/** Surfaces that bear a user interface — canonical truth for UI-bearing detection. */
+declare const UI_BEARING_SURFACES: Set<SurfaceType>;
+/** Surfaces that do NOT bear a user interface. */
+declare const NON_UI_SURFACES: Set<SurfaceType>;
+/**
+ * Synchronous check: given a SurfaceType value, returns true if UI-bearing.
+ * Canonical shared helper for classification validator and prototyping mode.
+ */
+declare function isUiBearingSurfaceType(surface: SurfaceType): boolean;
+
 /**
- * Format a mode resolution into a structured log entry.
+ * Browser QA canonical types — WS-B
  *
- * @param resolution - The mode resolution result from precedenceResolver
- * @returns Structured log entry with evidence expectations mapped by effective mode
+ * Defines the 4-phase execution model with truthful status reporting.
  */
-declare function formatModeLog(resolution: ModeResolution): ModeLogEntry;
+
+type BrowserQaPhase = "smoke" | "interaction" | "visual" | "accessibility";
+declare const BROWSER_QA_PHASES: readonly BrowserQaPhase[];
+type BrowserQaPhaseStatus = "executed" | "skipped" | "failed";
+type BrowserQaFindingSeverity = "info" | "warning" | "error";
+type BrowserQaFinding = {
+    phase: BrowserQaPhase;
+    route?: string;
+    selector?: string;
+    target?: string;
+    severity: BrowserQaFindingSeverity;
+    message: string;
+    repair_hint?: string;
+};
+type BrowserQaPhaseResult = {
+    phase: BrowserQaPhase;
+    status: BrowserQaPhaseStatus;
+    findings: BrowserQaFinding[];
+    skippedReason?: string;
+};
+type BrowserQaInput = {
+    htmlContent?: string;
+    targetUrl?: string;
+    routes?: string[];
+    surface: SurfaceType;
+    required?: boolean;
+    executionSource?: "html" | "url" | "none";
+};
+type BrowserQaRunResult = {
+    phases: BrowserQaPhaseResult[];
+    provider: string;
+    timestamp: string;
+};
+type BrowserQaSummary = {
+    providerId: string;
+    phases: Record<BrowserQaPhase, {
+        status: BrowserQaPhaseStatus;
+        findingsCount: number;
+    }>;
+    totalFindings: number;
+    skippedReasons: string[];
+};
+interface BrowserQaProvider {
+    providerId: string;
+    canRun(surface: SurfaceType): boolean;
+    runSmoke(input: BrowserQaInput): Promise<BrowserQaPhaseResult>;
+    runInteraction(input: BrowserQaInput): Promise<BrowserQaPhaseResult>;
+    runVisual(input: BrowserQaInput): Promise<BrowserQaPhaseResult>;
+    runAccessibility(input: BrowserQaInput): Promise<BrowserQaPhaseResult>;
+}
 
 /**
- * Surface adapter for prototyping evidence.
+ * Browser provider types.
  *
- * Detects surface type and adapts evidence fields:
- * - Non-visual surfaces (CLI, API, library): visual-review = n/a
- * - Visual surfaces (web, mobile, desktop): visual-review = collected (when mode allows runtime)
- * - Low-cost mode: runtime and visual-review are always n/a (static-only)
+ * Provider interface is minimal (DEC-0003). Registration is optional;
+ * absence is a valid state with fail-open semantics.
  *
- * Phase M4 of v1.7.7 Mode Switch UX (spec-0006).
+ * WS-B: BrowserQaProvider is the canonical interface for 4-phase Browser QA.
+ * BrowserProvider is the legacy render-capture provider interface.
  */
-type SurfaceType = "web" | "mobile" | "desktop" | "cli" | "api" | "library";
-type EvidenceStatus = "collected" | "n/a";
-type SurfaceEvidenceResult = {
-    visual_review: EvidenceStatus;
-    static_evidence: EvidenceStatus;
-    runtime_evidence: EvidenceStatus;
+
+type ProviderCapability = "screenshot" | "viewport" | "dom" | "interaction" | "visual" | "accessibility";
+/** Legacy render-capture provider. */
+type BrowserProvider = {
+    name: string;
+    capabilities: ProviderCapability[];
+    captureScreenshot?: () => Promise<string>;
+    captureViewport?: () => Promise<{
+        width: number;
+        height: number;
+    }>;
+    captureDom?: () => Promise<string>;
+    runInteraction?: () => Promise<void>;
+    runVisual?: () => Promise<void>;
+    runAccessibility?: () => Promise<void>;
 };
-type SurfaceAdapterInput = {
-    surfaceType: SurfaceType;
-    effectiveMode: string;
+
+type ProviderLookupResult = {
+    status: "available";
+    provider: BrowserProvider;
+} | {
+    status: "skipped";
+    provider: undefined;
 };
+
 /**
- * Adapt evidence fields based on surface type and effective mode.
+ * Provider registry with optional registration and fail-open semantics.
  *
- * @param input.surfaceType - The project's surface type
- * @param input.effectiveMode - The resolved effective prototyping mode
- * @returns Evidence field statuses adapted for the surface
+ * Registration is synchronous. Lookup returns a discriminated union
+ * so callers can handle absence without try/catch.
  */
-declare function adaptSurfaceEvidence(input: SurfaceAdapterInput): SurfaceEvidenceResult;
+
+declare class ProviderRegistry {
+    private providers;
+    register(provider: BrowserProvider): void;
+    /** Atomically replace an existing provider registration. */
+    replace(provider: BrowserProvider): void;
+    get(name: string): BrowserProvider | undefined;
+    has(name: string): boolean;
+    getOrSkip(name: string): ProviderLookupResult;
+    private qaProviders;
+    registerQaProvider(provider: BrowserQaProvider): void;
+    getQaProvider(name: string): BrowserQaProvider | undefined;
+    getFirstQaProvider(): BrowserQaProvider | undefined;
+}
+
+type PrototypingExecutionRequest = {
+    root: string;
+    requestedMode?: PrototypingMode;
+    providerRegistry?: ProviderRegistry;
+    renderAdapter?: RenderCaptureAdapter;
+    browserQaProviderId?: string;
+    critiqueAdapter?: CritiqueAdapter;
+    renderProviderId?: string;
+    targetUrl?: string;
+    reviewer?: string;
+};
+type PrototypingExecutionResult = {
+    mode: PrototypingMode;
+    surface: PrototypingSurface;
+    evidencePaths: {
+        prototyping: string;
+        render: string;
+        browserQa: string;
+    };
+    generatedAt: string;
+};
+declare function runPrototypingExecution(request: PrototypingExecutionRequest): Promise<PrototypingExecutionResult>;
+
+type SddPreflightSource = "discussion-pack";
+type SddPreflightStatus = "ready" | "blocked";
+type RunSddPreflightOptions = {
+    assumptions?: string[];
+};
+type SddPreflightResult = {
+    status: SddPreflightStatus;
+    source: SddPreflightSource;
+    selectedInputPath: string | null;
+    importedReqCount: number | null;
+    openQuestions: string[];
+    blockers: string[];
+    nextCommands: string[];
+    preflightSummaryPath: string;
+};
+declare function runSddPreflight(root: string, config: QfaiConfig, options?: RunSddPreflightOptions): Promise<SddPreflightResult>;
 
 type ReportSummary = {
     specs: number;
@@ -692,6 +826,113 @@ type ReportTddCoverageSpec = {
 type ReportTddCoverage = {
     specs: ReportTddCoverageSpec[];
 };
+type ReportSurfaceClassification = {
+    primarySurface: string;
+    uiBearing: boolean;
+    secondarySurfaces?: string[];
+    classificationRationale?: string;
+};
+type ReportFullHarnessExecution = {
+    mode: "full-harness";
+    iterations: number;
+    terminationReason: string;
+    finalScore: number;
+    bestIteration: number;
+    renderCaptured: number;
+    renderSkipped: number;
+    renderFailed: number;
+    browserQaPhasesExecuted: number;
+    browserQaPhasesSkipped: number;
+    browserQaTotalFindings: number;
+};
+type ReportPrototypingSummary = {
+    surfaceClassification?: ReportSurfaceClassification;
+    fullHarnessExecution?: ReportFullHarnessExecution;
+    recommendationArtifact?: {
+        status: "valid" | "missing" | "invalid" | "no-pack";
+        path?: string;
+    };
+    mode: {
+        requested?: string;
+        effective: string;
+        source: string;
+        rationale: string;
+        discussionRecommendation?: string;
+        allowedModes?: string[];
+        surface: string;
+        sourceSchema?: string;
+    };
+    evidence: {
+        specsCoverageStatus: "complete" | "incomplete";
+        specsCoverage?: {
+            expectedSpecIds: string[];
+            observedSpecIds: string[];
+            missingSpecIds: string[];
+            unexpectedSpecIds: string[];
+        };
+        runtimeGate: {
+            present: boolean;
+            required: boolean;
+        };
+        uiFidelity: {
+            present: boolean;
+            required: boolean;
+        };
+        renderBundle: {
+            present: boolean;
+            required: boolean;
+        };
+        browserQaBundle: {
+            present: boolean;
+            required: boolean;
+        };
+        obligationProfile: string;
+    };
+    fullHarness?: {
+        enabled: boolean;
+        available?: boolean;
+        runId?: string;
+        iterationCount?: number;
+        bestIteration?: number;
+        terminationReason?: string;
+        reviewerSignoffStatus?: string;
+        scoringTraceCount?: number;
+    };
+    render?: {
+        status?: string;
+        requested?: boolean;
+        captured: number;
+        skipped: number;
+        failed: number;
+        malformed: boolean;
+        inlinePayloadViolation?: boolean;
+    };
+    browserQa?: {
+        status?: string;
+        executed?: boolean;
+        findingsBySeverity: Record<"error" | "warning" | "info", number>;
+        findingsByCategory?: Record<string, number>;
+        summaryAggregates?: {
+            totalPassed: number;
+            totalFailed: number;
+        };
+        phaseSummary?: Record<string, {
+            passed: number;
+            failed: number;
+        }>;
+        modeMismatch?: boolean;
+    };
+    calibration?: {
+        configPresent: boolean;
+        thresholdSummary?: {
+            accept: number;
+            refine: number;
+        };
+        scoringTraceAvailable: boolean;
+        belowThresholdWarning?: boolean;
+    };
+    warnings: string[];
+};
 type ReportData = {
     tool: "qfai";
     version: string;
@@ -703,6 +944,7 @@ type ReportData = {
     traceability: ReportTraceability;
     testStrategy: ReportTestStrategy;
     tddCoverage: ReportTddCoverage;
+    prototyping?: ReportPrototypingSummary;
     guardrails: ReportGuardrails;
     changeType: ReportChangeType;
     waivers: ReportWaivers;
@@ -738,4 +980,330 @@ declare function validateSpecSplitByCapability(root: string, config: QfaiConfig)
 
 declare function validateTraceability(root: string, config: QfaiConfig, phase: ValidationPhase): Promise<Issue[]>;
 
-export { type AtddCodeTraceabilityResult, type AtddForbiddenRef, type AtddSpecRefs, type AtddTestKind, type AtddTraceabilityMissing, type AtddTraceabilityScan, type AtddUnknownRef, type AtddUnknownRefKind, type ConfigLoadResult, type ConfigPathKey, type ConfigSearchResult, type DecisionGuardrail, type DecisionGuardrailEntry, type DiscussionRecommendation, type FailOn, 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 ModeLogEntry, type ModeResolution, type ModeSource, type OrphanContractsPolicy, type OutputFormat, type PrecedenceInput, type PrototypingMode, type QfaiConfig, type QfaiOutputConfig, type QfaiPaths, type QfaiUiuxAuditConfig, type QfaiUiuxConfig, type QfaiUiuxMigrationConfig, type QfaiValidationConfig, RUNTIME_HEAVY_CHECKS, type ReportChangeType, type ReportChangeTypeSummary, type ReportChangeTypeWarning, type ReportContractCoverage, type ReportData, type ReportDeltaCoverage, type ReportGuardrailItem, type ReportGuardrails, type ReportIds, type ReportRuleFinding, type ReportSpecContractRefs, type ReportSpecCoverage, type ReportSummary, type ReportTddCoverage, type ReportTddCoverageSpec, type ReportTestStrategy, type ReportTraceability, type ReportWaivers, type RunSddPreflightOptions, STATIC_OBLIGATIONS, type SddPreflightResult, type SddPreflightSource, type SddPreflightStatus, type SurfaceAdapterInput, type SurfaceEvidenceResult, type SurfaceType, type TraceabilitySeverity, type UiFidelityAutogenCrawlResult, type UiFidelityAutogenExpected, type UiFidelityAutogenMockPathResult, type UiFidelityAutogenResult, type UiFidelityGeneratedScreen, type UiFidelityLabelCoverage, VALID_MODE_SOURCES, 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, adaptSurfaceEvidence, autogenerateUiFidelity, buildUiFidelityScreens, checkDecisionGuardrails, collectExpectedFromContracts, computeLabelCoverage, crawlRoutesAndCollectFoundLabels, createReportData, defaultConfig, emitUiFidelity, evaluateAtddCodeTraceability, extractAcSpecNumber, extractAllIds, extractBrSpecNumber, extractCapSpecNumber, extractCaseSpecNumber, extractDecisionGuardrailsFromMarkdown, extractDomMarkers, extractIds, extractInvalidIds, extractScSpecNumber, extractSpecNumber, extractUsSpecNumber, filterDecisionGuardrailsByKeyword, findConfigRoot, formatGuardrailsForLlm, formatModeLog, formatReportJson, formatReportMarkdown, getConfigPath, lintSql, loadConfig, loadDecisionGuardrails, normalizeDecisionGuardrails, readDiscussionRecommendation, resolveObligations, resolveObligationsWithOptIn, resolvePath, resolvePrecedence, resolveToolVersion, runMockPaths, runSddPreflight, sortDecisionGuardrails, validateAtddCodeTraceability, validateContracts, validateDefinedIds, validateLayeredTraceability, validateOrphanProhibition, validateProject, validateSpecSplitByCapability, validateTraceability };
+/**
+ * Browser QA runner — WS-B
+ *
+ * Orchestrates the canonical 4-phase Browser QA execution model.
+ * Provider resolution → phase execution → truthful skip/fail handling.
+ */
+
+/**
+ * Run the canonical 4-phase Browser QA.
+ *
+ * - provider resolved → delegate to provider methods
+ * - no provider → use built-in static analysis phases
+ * - non-ui surface → all phases skipped
+ */
+declare function runBrowserQaOrchestrated(input: BrowserQaInput, provider?: BrowserQaProvider): Promise<BrowserQaRunResult>;
+/**
+ * Summarize a BrowserQaRunResult for report output.
+ */
+declare function summarizeBrowserQaResult(result: BrowserQaRunResult): BrowserQaSummary;
+
+/**
+ * Render runner — WS-C
+ *
+ * Executes render capture for a list of targets, producing truthful
+ * evidence entries. No placeholder paths are emitted.
+ */
+
+/**
+ * Run render capture for all targets.
+ *
+ * - adapter present + capture succeeds → `captured` with real file paths
+ * - adapter present + capture throws → `failed` with reason
+ * - adapter absent → `skipped` with reason
+ */
+declare function runRenderCapture(targets: RenderCaptureTarget[], outputDir: string, adapter?: RenderCaptureAdapter, options?: {
+    required?: boolean;
+}): Promise<RenderRunnerResult>;
+
+type PrototypingSummaryBundle = {
+    surface: PrototypingSurface;
+    specs: Array<{
+        specId: string;
+        declared: {
+            uiRoutes: number;
+            apiEndpoints: number;
+            dbObjects: number;
+        };
+        checked: {
+            uiOk: number;
+            apiNon404: number;
+            dbPresent: number;
+        };
+        missing: {
+            uiRoutes: string[];
+            apiEndpoints: string[];
+            dbObjects: string[];
+        };
+    }>;
+    mode: {
+        requested?: PrototypingMode;
+        effective: PrototypingMode;
+        source: string;
+        rationale: string;
+    };
+    meta: {
+        generatedAt: string;
+        toolVersion: string;
+        commands: string[];
+        generatedBy: string;
+        providerIds: string[];
+        targetUrl?: string;
+    };
+    uiFidelityStatus?: {
+        required: boolean;
+        status: "completed" | "failed" | "n/a";
+        reason?: string;
+    };
+    missingRequiredEvidence?: string[];
+    runtimeGate?: {
+        ui: Array<{
+            route: string;
+            status: number;
+        }>;
+        api: Array<{
+            method: string;
+            path: string;
+            status: number;
+        }>;
+    };
+    uiFidelity?: {
+        mode: "interactive" | "skeleton";
+        screens: Array<unknown>;
+    };
+    fullHarness?: {
+        enabled: true;
+        available: boolean;
+        runId: string;
+        iterationCount: number;
+        bestIteration: number;
+        terminationReason: string;
+        reviewerSignoff: {
+            status: string;
+            reviewer: string;
+            timestamp: string;
+        };
+        scoringTrace: Array<{
+            iteration: number;
+            weightedTotal: number;
+            decision: string;
+        }>;
+    };
+};
+declare function writeEvidenceBundles(input: {
+    root: string;
+    render?: {
+        result: RenderRunnerResult;
+        surface: PrototypingSurface;
+        mode: PrototypingMode;
+        generatedAt: string;
+    };
+    browserQa?: {
+        result: BrowserQaRunResult;
+        mode: PrototypingMode;
+    };
+    prototyping: PrototypingSummaryBundle;
+}): Promise<{
+    prototypingPath: string;
+    renderPath: string;
+    browserQaPath: string;
+}>;
+
+type ThresholdConfig = {
+    accept: number;
+    refine: number;
+};
+type Decision = "accept" | "refine" | "pivot";
+
+/**
+ * Full-harness mode types.
+ *
+ * Defines the planner/generator/evaluator loop interfaces
+ * and evidence structures for /qfai-prototyping full-harness mode.
+ */
+
+type HarnessConfig = {
+    maxIterations: number;
+    thresholds: ThresholdConfig;
+    dimensionWeights?: Record<string, number> | undefined;
+    dimensionFloors?: Record<string, number> | undefined;
+    plateauDelta?: number | undefined;
+    plateauLookback?: number | undefined;
+};
+type PlannerStrategy = {
+    approach: string;
+    constraints: string[];
+    budgetGuidance: string;
+};
+type GeneratorOutput = {
+    content: string;
+    metadata?: Record<string, unknown> | undefined;
+};
+type DimensionScore = {
+    dimension: string;
+    score: number;
+    weight: number;
+    floor?: number | undefined;
+};
+type EvaluatorResult = {
+    decision: Decision;
+    weightedTotal: number;
+    dimensionScores: DimensionScore[];
+    feedback?: string | undefined;
+    pivotContext?: string | undefined;
+};
+type IterationRecord = {
+    iteration: number;
+    plannerStrategy?: PlannerStrategy | undefined;
+    generatorOutput: GeneratorOutput;
+    evaluatorResult: EvaluatorResult;
+    critiqueResult?: CritiqueResult | undefined;
+};
+type LoopStatus = "converged" | "max-iterations" | "plateau";
+type LoopResult = {
+    status: LoopStatus;
+    finalOutput: GeneratorOutput;
+    finalScore: number;
+    terminationReason: LoopStatus;
+    iterationCount: number;
+    iterations: IterationRecord[];
+    bestIteration: number;
+};
+type HarnessEvidence = {
+    runId: string;
+    timestamp: string;
+    status: LoopStatus;
+    iterationCount: number;
+    finalScore: number;
+    terminationReason: LoopStatus;
+    iterations: IterationRecord[];
+    bestIteration: number;
+};
+type ReviewSummary = {
+    finalScore: number;
+    recommendation: string;
+    iterationSummary: Array<{
+        iteration: number;
+        score: number;
+        decision: Decision;
+    }>;
+};
+type SpecInputs = {
+    specId: string;
+    requirements: string[];
+    constraints?: string[] | undefined;
+    calibrationPackPath?: string | undefined;
+};
+
+/**
+ * Harness adapters — WS-D
+ *
+ * Adapter interfaces for connecting the full-harness runtime to
+ * render evidence, Browser QA, critique, and observability subsystems.
+ */
+
+type HarnessRenderAdapter = {
+    captureEvidence(iteration: number): Promise<RenderRunnerResult>;
+};
+type HarnessBrowserQaAdapter = {
+    runQa(iteration: number): Promise<BrowserQaRunResult>;
+};
+type HarnessObservabilityAdapter = {
+    recordIteration(data: {
+        iteration: number;
+        score: number;
+        decision: string;
+        terminationReason?: string;
+    }): void;
+    flush(): Promise<void>;
+};
+type FullHarnessAdapters = {
+    surface: SurfaceType;
+    render?: HarnessRenderAdapter;
+    browserQa?: HarnessBrowserQaAdapter;
+    observability?: HarnessObservabilityAdapter;
+};
+
+/**
+ * Harness result writer — WS-D
+ *
+ * Writes full-harness execution results to a structured output.
+ */
+
+type FullHarnessOutput = {
+    mode: "full-harness";
+    iterations: number;
+    terminationReason: string;
+    evaluationSummary: {
+        finalScore: number;
+        bestIteration: number;
+        decision: string;
+    };
+    evidenceSummary: {
+        renderCaptured: number;
+        renderSkipped: number;
+        renderFailed: number;
+    };
+    browserQaSummary: {
+        phasesExecuted: number;
+        phasesFailed: number;
+        phasesSkipped: number;
+        totalFindings: number;
+    };
+    calibrationSummary: {
+        thresholds: {
+            accept: number;
+            refine: number;
+        };
+    };
+    observabilityRefs: string[];
+};
+
+/**
+ * Harness evidence generator — creates structured evidence and review
+ * summaries from loop results.
+ */
+
+declare function generateEvidence(result: LoopResult, runId?: string): HarnessEvidence;
+declare function generateReviewSummary(result: LoopResult): ReviewSummary;
+
+/**
+ * Full-harness runtime — WS-D
+ *
+ * Production-path entry point for `mode=full-harness`.
+ * Orchestrates the planner → generator → evaluator loop with
+ * render evidence, Browser QA, critique, and observability.
+ */
+
+type FullHarnessRequest = {
+    inputs: SpecInputs;
+    config?: Partial<HarnessConfig>;
+    adapters?: FullHarnessAdapters;
+    critiqueAdapter?: CritiqueAdapter;
+};
+type FullHarnessResult = {
+    loopResult: LoopResult;
+    output: FullHarnessOutput;
+    evidence: ReturnType<typeof generateEvidence>;
+    reviewSummary: ReturnType<typeof generateReviewSummary>;
+};
+/**
+ * Run the full-harness mode.
+ *
+ * Termination policy:
+ * - `accept` reached → exit
+ * - `max_iterations` reached → exit
+ * - plateau detected → exit
+ * - hard execution failure → throw
+ */
+declare function runFullHarness(request: FullHarnessRequest): Promise<FullHarnessResult>;
+
+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, type DecisionGuardrail, type DecisionGuardrailEntry, type DiscussionModeRecommendation, type DiscussionRecommendationSourceSchema, type FailOn, type FullHarnessRequest, type FullHarnessResult, 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 LegacyPrototypingSurface, type ModeResolutionInput, type ModeResolutionResult, type ModeSelectionSource, NON_UI_SURFACES, type OrphanContractsPolicy, type OutputFormat, type ParseDiscussionResult, type PrototypingExecutionConfig, type PrototypingExecutionRequest, type PrototypingExecutionResult, type PrototypingMode, type PrototypingObligations, type PrototypingSurface, type QfaiConfig, type QfaiOutputConfig, type QfaiPaths, type QfaiPrototypingCalibrationConfig, type QfaiPrototypingConfig, type QfaiUiuxAuditConfig, type QfaiUiuxConfig, type QfaiUiuxMigrationConfig, type QfaiValidationConfig, 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 ResolveModeInput, type ResolvedModeSummary, type RunSddPreflightOptions, type SddPreflightResult, type SddPreflightSource, type SddPreflightStatus, type TraceabilitySeverity, UI_BEARING_SURFACES, type UiFidelityStatus, 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, checkDecisionGuardrails, createPlaywrightBrowserQaProvider, createPlaywrightRenderAdapter, createReportData, defaultConfig, derivePrototypingObligations, evaluateAtddCodeTraceability, extractAcSpecNumber, extractAllIds, extractBrSpecNumber, extractCapSpecNumber, extractCaseSpecNumber, extractDecisionGuardrailsFromMarkdown, extractIds, extractInvalidIds, extractScSpecNumber, extractSpecNumber, extractUsSpecNumber, filterDecisionGuardrailsByKeyword, findConfigRoot, formatGuardrailsForLlm, formatReportJson, formatReportMarkdown, getConfigPath, inferSurfaceFromRecommendationAndEvidence, isUiBearingSurface, isUiBearingSurfaceType, isValidPrototypingMode, isValidPrototypingSurface, lintSql, loadConfig, loadDecisionGuardrails, normalizeAllowedModes, normalizeDecisionGuardrails, normalizePrototypingSurface, normalizeSurface, parseDiscussionFromObject, parseDiscussionModeRecommendation, parseDiscussionModeRecommendationWithWarnings, resolvePath, resolvePrototypingMode, resolvePrototypingModeFromInput, resolveToolVersion, runBrowserQaOrchestrated, runFullHarness, runPrototypingExecution, runRenderCapture, runSddPreflight, sortDecisionGuardrails, summarizeBrowserQaResult, summarizeResolvedMode, validateAtddCodeTraceability, validateContracts, validateDefinedIds, validateLayeredTraceability, validateOrphanProhibition, validateProject, validateSpecSplitByCapability, validateTraceability, writeEvidenceBundles };