cclaw-cli 0.48.30 → 0.48.32

package/dist/content/review-loop.d.ts

@@ -0,0 +1,192 @@
+import type { FlowStage } from "../types.js";
+import type { SkillEnvelope } from "./stage-schema.js";
+export declare const REVIEW_LOOP_STAGES: readonly ["scope", "design"];
+export type ReviewLoopStage = (typeof REVIEW_LOOP_STAGES)[number];
+export declare const REVIEW_LOOP_DEFAULT_MAX_ITERATIONS = 3;
+export declare const REVIEW_LOOP_DEFAULT_TARGET_SCORE = 0.8;
+export type ReviewFindingSeverity = "critical" | "important" | "suggestion";
+export type ReviewLoopStopReason = "quality_threshold_met" | "max_iterations_reached" | "user_opt_out";
+export interface ReviewLoopDimension {
+    id: string;
+    label: string;
+    weight: number;
+    guidance: string;
+}
+export interface ReviewLoopDimensionScore {
+    dimensionId: string;
+    score: number;
+    weight?: number;
+    rationale?: string;
+}
+export interface ReviewFinding {
+    id: string;
+    dimensionId: string;
+    severity: ReviewFindingSeverity;
+    summary: string;
+    evidence?: string;
+    recommendation?: string;
+}
+export interface ReviewLoopBudget {
+    maxIterations?: number;
+    targetScore?: number;
+}
+export interface ReviewLoopIterationSummary {
+    iteration: number;
+    qualityScore: number;
+    findingsCount: number;
+}
+export interface ReviewLoopInput {
+    artifactPath: string;
+    stage: ReviewLoopStage;
+    checklist?: readonly ReviewLoopDimension[];
+    priorIterations?: ReadonlyArray<ReviewLoopIterationSummary>;
+    budget?: ReviewLoopBudget;
+}
+export interface ReviewLoopDispatchRequest {
+    stage: ReviewLoopStage;
+    artifactPath: string;
+    checklist: readonly ReviewLoopDimension[];
+    priorIterations: ReadonlyArray<ReviewLoopIterationSummary>;
+    iteration: number;
+    budget: Required<ReviewLoopBudget>;
+}
+export interface ReviewLoopIterationResult {
+    qualityScore: number;
+    findings: ReviewFinding[];
+    iteration: number;
+    shouldContinue: boolean;
+    dimensionScores: ReviewLoopDimensionScore[];
+}
+export interface ReviewLoopEnvelope {
+    type: "review-loop";
+    version: "1";
+    stage: ReviewLoopStage;
+    artifactPath: string;
+    targetScore: number;
+    maxIterations: number;
+    stopReason: ReviewLoopStopReason;
+    iterations: ReviewLoopIterationSummary[];
+}
+export interface ReviewLoopRunResult {
+    iterations: ReviewLoopIterationResult[];
+    qualityScore: number;
+    stopReason: ReviewLoopStopReason;
+    envelope: ReviewLoopEnvelope;
+}
+export type ReviewLoopDispatcher = (request: ReviewLoopDispatchRequest) => Promise<unknown>;
+export interface ReviewLoopDispatchAdapterRequest {
+    request: ReviewLoopDispatchRequest;
+    prompt: string;
+    responseSchema: string;
+}
+export type ReviewLoopDispatchAdapter = (payload: ReviewLoopDispatchAdapterRequest) => Promise<unknown>;
+export interface ReviewLoopSecondOpinionPolicy {
+    enabled?: boolean;
+    scoreDeltaThreshold?: number;
+    modelLabel?: string;
+}
+export interface ReviewLoopSecondOpinionMeta {
+    enabled: boolean;
+    modelLabel?: string;
+    primaryScore: number;
+    secondOpinionScore: number;
+    scoreDelta: number;
+    threshold: number;
+}
+export type ReviewLoopApplyFindings = (iteration: ReviewLoopIterationResult) => Promise<void> | void;
+export interface RunReviewLoopOptions {
+    dispatcher: ReviewLoopDispatcher;
+    applyFindings: ReviewLoopApplyFindings;
+    shouldOptOut?: () => boolean;
+    emitEnvelope?: (envelope: ReviewLoopEnvelope) => void;
+}
+export declare const REVIEW_LOOP_CHECKLISTS: {
+    readonly scope: readonly [{
+        readonly id: "premise_fit";
+        readonly label: "Premise fit";
+        readonly weight: 1;
+        readonly guidance: "Does the scope contract solve the actual user/problem framing without drifting into adjacent asks?";
+    }, {
+        readonly id: "alternatives_coverage";
+        readonly label: "Alternatives coverage";
+        readonly weight: 1;
+        readonly guidance: "Are meaningful alternatives compared with explicit trade-offs and one clear recommendation?";
+    }, {
+        readonly id: "error_rescue_registry";
+        readonly label: "Error and rescue coverage";
+        readonly weight: 1;
+        readonly guidance: "Does each scoped capability define failure mode, detection signal, and fallback/rescue behavior?";
+    }, {
+        readonly id: "scope_creep_risk";
+        readonly label: "Scope-creep risk";
+        readonly weight: 1;
+        readonly guidance: "Are in/out boundaries explicit and protected against silent expansion/reduction language?";
+    }, {
+        readonly id: "completion_status_fidelity";
+        readonly label: "Completion status fidelity";
+        readonly weight: 1;
+        readonly guidance: "Does the completion dashboard honestly report unresolved risks, decision count, and stop reason?";
+    }];
+    readonly design: readonly [{
+        readonly id: "architecture_fit";
+        readonly label: "Architecture fit";
+        readonly weight: 1;
+        readonly guidance: "Do architecture boundaries and diagrams align with scope and real blast-radius code?";
+    }, {
+        readonly id: "failure_mode_coverage";
+        readonly label: "Failure-mode coverage";
+        readonly weight: 1;
+        readonly guidance: "Does the failure-mode table capture method/exception/rescue/user-visible impact for critical paths?";
+    }, {
+        readonly id: "test_coverage_realism";
+        readonly label: "Test coverage realism";
+        readonly weight: 1;
+        readonly guidance: "Is the proposed test split realistic (unit/integration/e2e) with explicit gap handling?";
+    }, {
+        readonly id: "performance_budget";
+        readonly label: "Performance budget";
+        readonly weight: 1;
+        readonly guidance: "Are critical metrics, thresholds, and measurement methods concrete and enforceable?";
+    }, {
+        readonly id: "observability_adequacy";
+        readonly label: "Observability adequacy";
+        readonly weight: 1;
+        readonly guidance: "Can on-call trace a failure from user symptom to root cause via logs/metrics/traces/alerts?";
+    }];
+};
+export declare function buildOutsideVoiceReviewPrompt(request: ReviewLoopDispatchRequest): string;
+export declare function createOutsideVoiceDispatcher(adapter: ReviewLoopDispatchAdapter): ReviewLoopDispatcher;
+export declare function parseReviewLoopDispatcherResult(raw: unknown, checklist: readonly ReviewLoopDimension[]): {
+    findings: ReviewFinding[];
+    dimensionScores: ReviewLoopDimensionScore[];
+};
+export declare function mergeSecondOpinionResults(primaryRaw: unknown, secondOpinionRaw: unknown, checklist: readonly ReviewLoopDimension[], policy?: ReviewLoopSecondOpinionPolicy): {
+    findings: ReviewFinding[];
+    dimensionScores: ReviewLoopDimensionScore[];
+    secondOpinion: ReviewLoopSecondOpinionMeta;
+};
+export declare function createSecondOpinionDispatcher(args: {
+    primary: ReviewLoopDispatcher;
+    secondOpinion?: ReviewLoopDispatcher;
+    policy?: ReviewLoopSecondOpinionPolicy;
+}): ReviewLoopDispatcher;
+export declare function aggregateQualityScore(scores: readonly ReviewLoopDimensionScore[], checklist: readonly ReviewLoopDimension[]): number;
+export declare function runReviewLoopIteration(input: ReviewLoopInput & {
+    iteration: number;
+}, dispatcher: ReviewLoopDispatcher): Promise<ReviewLoopIterationResult>;
+export declare function buildReviewLoopEnvelope(args: {
+    stage: ReviewLoopStage;
+    artifactPath: string;
+    targetScore: number;
+    maxIterations: number;
+    stopReason: ReviewLoopStopReason;
+    iterations: ReadonlyArray<ReviewLoopIterationSummary>;
+}): ReviewLoopEnvelope;
+export declare function renderReviewLoopHeader(envelope: ReviewLoopEnvelope): string;
+export declare function upsertReviewLoopHeader(markdown: string, envelope: ReviewLoopEnvelope): string;
+export declare function renderReviewLoopSummarySection(envelope: ReviewLoopEnvelope): string;
+export declare function upsertReviewLoopSummary(markdown: string, envelope: ReviewLoopEnvelope): string;
+export declare function extractReviewLoopEnvelopeFromArtifact(markdown: string, stage: ReviewLoopStage, artifactPath: string): ReviewLoopEnvelope | null;
+export declare function toSkillEnvelope(envelope: ReviewLoopEnvelope, emittedAt?: string, agent?: string): SkillEnvelope;
+export declare function runReviewLoop(input: ReviewLoopInput, options: RunReviewLoopOptions): Promise<ReviewLoopRunResult>;
+export declare function isReviewLoopStage(stage: FlowStage): stage is ReviewLoopStage;