cclaw-cli 0.48.30 → 0.48.32

package/dist/internal/advance-stage.js

@@ -19,6 +19,11 @@ import { runEnvelopeValidateCommand } from "./envelope-validate.js";
 import { runKnowledgeDigestCommand } from "./knowledge-digest.js";
 import { runTddLoopStatusCommand } from "./tdd-loop-status.js";
 import { runTddRedEvidenceCommand } from "./tdd-red-evidence.js";
+import { extractReviewLoopEnvelopeFromArtifact } from "../content/review-loop.js";
+const AUTO_REVIEW_LOOP_GATE_BY_STAGE = {
+    scope: "scope_user_approved",
+    design: "design_architecture_locked"
+};
 function unique(values) {
     return [...new Set(values)];
 }
@@ -55,6 +60,111 @@ const SHA_WITH_LABEL_PATTERN = /\b(?:sha|commit)(?:\s*[:=]|\s+)\s*[0-9a-f]{7,40}
 const PASS_STATUS_PATTERN = /\b(?:pass|passed|green|ok)\b/iu;
 const SHIP_FINALIZATION_MODE_PATTERN = new RegExp(`\\b(?:${SHIP_FINALIZATION_MODES.join("|")})\\b`, "u");
 const SHIP_FINALIZATION_MODE_HINT = SHIP_FINALIZATION_MODES.join(", ");
+const REVIEW_LOOP_STOP_REASONS = new Set([
+    "quality_threshold_met",
+    "max_iterations_reached",
+    "user_opt_out"
+]);
+function asRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    return value;
+}
+function pickReviewLoopEnvelope(value) {
+    const direct = asRecord(value);
+    if (!direct)
+        return null;
+    if (direct.type === "review-loop")
+        return direct;
+    const payload = asRecord(direct.payload);
+    if (payload?.type === "review-loop")
+        return payload;
+    const nested = asRecord(direct.reviewLoop);
+    if (nested?.type === "review-loop")
+        return nested;
+    return null;
+}
+function validateReviewLoopGateEvidence(stage, evidence) {
+    let parsed;
+    try {
+        parsed = JSON.parse(evidence);
+    }
+    catch {
+        return "must be JSON containing a review-loop envelope (`type: \"review-loop\"`) in top-level, `payload`, or `reviewLoop`.";
+    }
+    const envelope = pickReviewLoopEnvelope(parsed);
+    if (!envelope) {
+        return "must include a review-loop envelope (`type: \"review-loop\"`) in top-level, `payload`, or `reviewLoop`.";
+    }
+    if (envelope.stage !== stage) {
+        return `review-loop envelope stage must be "${stage}".`;
+    }
+    const targetScore = envelope.targetScore;
+    if (typeof targetScore !== "number" || Number.isNaN(targetScore) || targetScore < 0 || targetScore > 1) {
+        return "review-loop targetScore must be a number between 0 and 1.";
+    }
+    const maxIterations = envelope.maxIterations;
+    if (typeof maxIterations !== "number" ||
+        Number.isNaN(maxIterations) ||
+        !Number.isInteger(maxIterations) ||
+        maxIterations < 1) {
+        return "review-loop maxIterations must be an integer >= 1.";
+    }
+    if (typeof envelope.stopReason !== "string" || !REVIEW_LOOP_STOP_REASONS.has(envelope.stopReason)) {
+        return "review-loop stopReason must be one of quality_threshold_met, max_iterations_reached, user_opt_out.";
+    }
+    const rows = envelope.iterations;
+    if (!Array.isArray(rows) || rows.length === 0) {
+        return "review-loop iterations must be a non-empty array.";
+    }
+    if (rows.length > maxIterations) {
+        return "review-loop iterations count cannot exceed maxIterations.";
+    }
+    let prevScore = -Infinity;
+    let reachedTarget = false;
+    for (let index = 0; index < rows.length; index++) {
+        const row = asRecord(rows[index]);
+        if (!row) {
+            return `review-loop iterations[${index}] must be an object.`;
+        }
+        const iteration = row.iteration;
+        const qualityScore = row.qualityScore;
+        const findingsCount = row.findingsCount;
+        if (typeof iteration !== "number" ||
+            Number.isNaN(iteration) ||
+            !Number.isInteger(iteration) ||
+            iteration < 1) {
+            return `review-loop iterations[${index}].iteration must be an integer >= 1.`;
+        }
+        if (typeof qualityScore !== "number" ||
+            Number.isNaN(qualityScore) ||
+            qualityScore < 0 ||
+            qualityScore > 1) {
+            return `review-loop iterations[${index}].qualityScore must be between 0 and 1.`;
+        }
+        if (typeof findingsCount !== "number" ||
+            Number.isNaN(findingsCount) ||
+            !Number.isInteger(findingsCount) ||
+            findingsCount < 0) {
+            return `review-loop iterations[${index}].findingsCount must be an integer >= 0.`;
+        }
+        if (qualityScore + Number.EPSILON < prevScore) {
+            return "review-loop qualityScore must be monotonic non-decreasing across iterations.";
+        }
+        if (qualityScore >= targetScore) {
+            reachedTarget = true;
+        }
+        prevScore = qualityScore;
+    }
+    if (envelope.stopReason === "quality_threshold_met" && !reachedTarget) {
+        return "review-loop stopReason is quality_threshold_met but no iteration reached targetScore.";
+    }
+    if (envelope.stopReason === "max_iterations_reached" && rows.length < maxIterations) {
+        return "review-loop stopReason is max_iterations_reached but iterations are below maxIterations.";
+    }
+    return null;
+}
 // Per-gate validators keyed by `${stage}:${gateId}`. Returning a non-null
 // string surfaces the reason as an `advance-stage` failure so evidence is
 // guaranteed to carry the structural breadcrumbs downstream tooling
@@ -77,7 +187,9 @@ const GATE_EVIDENCE_VALIDATORS = {
             return `must name the finalization mode that ran (for example ${SHIP_FINALIZATION_MODE_HINT}).`;
         }
         return null;
-    }
+    },
+    "scope:scope_user_approved": (evidence) => validateReviewLoopGateEvidence("scope", evidence),
+    "design:design_architecture_locked": (evidence) => validateReviewLoopGateEvidence("design", evidence)
 };
 function validateGateEvidenceShape(stage, gateId, evidence) {
     const validator = GATE_EVIDENCE_VALIDATORS[`${stage}:${gateId}`];
@@ -232,6 +344,35 @@ function parseCsv(raw) {
         .map((item) => item.trim())
         .filter((item) => item.length > 0);
 }
+async function hydrateReviewLoopEvidenceFromArtifact(projectRoot, stage, track, selectedGateIds, evidenceByGate) {
+    const gateId = AUTO_REVIEW_LOOP_GATE_BY_STAGE[stage];
+    if (!gateId)
+        return;
+    if (!selectedGateIds.includes(gateId))
+        return;
+    const existing = evidenceByGate[gateId];
+    if (typeof existing === "string" && existing.trim().length > 0)
+        return;
+    const resolved = await resolveArtifactPath(stage, {
+        projectRoot,
+        track,
+        intent: "read"
+    });
+    let raw = "";
+    try {
+        raw = await fs.readFile(resolved.absPath, "utf8");
+    }
+    catch {
+        return;
+    }
+    const reviewStage = stage === "scope" || stage === "design" ? stage : null;
+    if (!reviewStage)
+        return;
+    const envelope = extractReviewLoopEnvelopeFromArtifact(raw, reviewStage, resolved.relPath);
+    if (!envelope)
+        return;
+    evidenceByGate[gateId] = JSON.stringify(envelope);
+}
 function parseAdvanceStageArgs(tokens) {
     const [stageRaw, ...flagTokens] = tokens;
     if (!isFlowStageValue(stageRaw)) {
@@ -488,6 +629,7 @@ async function runAdvanceStage(projectRoot, args, io) {
             });
         }
     }
+    await hydrateReviewLoopEvidenceFromArtifact(projectRoot, args.stage, flowState.track, selectedGateIds, args.evidenceByGate);
     const catalog = flowState.stageGateCatalog[args.stage];
     const nextPassed = unique([...catalog.passed, ...selectedGateIds]).filter((gateId) => allowedGateIds.has(gateId));
     const nextPassedSet = new Set(nextPassed);

package/dist/trace-matrix.d.ts

@@ -4,10 +4,24 @@ export interface TraceEntry {
     testSlices: string[];
     reviewFindings: string[];
 }
+export interface ReviewLoopTraceEntry {
+    stage: "scope" | "design";
+    artifactPath: string;
+    targetScore: number;
+    maxIterations: number;
+    stopReason: "quality_threshold_met" | "max_iterations_reached" | "user_opt_out";
+    finalScore: number;
+    iterations: Array<{
+        iteration: number;
+        qualityScore: number;
+        findingsCount: number;
+    }>;
+}
 export interface TraceMatrix {
     entries: TraceEntry[];
     orphanedCriteria: string[];
     orphanedTasks: string[];
     orphanedTests: string[];
+    reviewLoops: ReviewLoopTraceEntry[];
 }
 export declare function buildTraceMatrix(projectRoot: string): Promise<TraceMatrix>;

package/dist/trace-matrix.js

@@ -1,6 +1,8 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { resolveArtifactPath } from "./artifact-paths.js";
 import { RUNTIME_ROOT } from "./constants.js";
+import { extractReviewLoopEnvelopeFromArtifact } from "./content/review-loop.js";
 import { exists } from "./fs-utils.js";
 function activeArtifactPath(projectRoot, name) {
     return path.join(projectRoot, RUNTIME_ROOT, "artifacts", name);
@@ -110,6 +112,56 @@ function layer1LinesForCriterion(layer1, criterionId) {
     }
     return out;
 }
+async function readStageArtifact(projectRoot, stage) {
+    let resolved = null;
+    try {
+        resolved = await resolveArtifactPath(stage, {
+            projectRoot,
+            intent: "read"
+        });
+    }
+    catch {
+        resolved = null;
+    }
+    if (!resolved || !(await exists(resolved.absPath))) {
+        return null;
+    }
+    try {
+        const markdown = await fs.readFile(resolved.absPath, "utf8");
+        return { markdown, relPath: resolved.relPath };
+    }
+    catch {
+        return null;
+    }
+}
+async function collectReviewLoopTraceEntries(projectRoot) {
+    const entries = [];
+    for (const stage of ["scope", "design"]) {
+        const artifact = await readStageArtifact(projectRoot, stage);
+        if (!artifact)
+            continue;
+        const envelope = extractReviewLoopEnvelopeFromArtifact(artifact.markdown, stage, artifact.relPath);
+        if (!envelope)
+            continue;
+        const finalScore = envelope.iterations.length > 0
+            ? envelope.iterations[envelope.iterations.length - 1].qualityScore
+            : 0;
+        entries.push({
+            stage,
+            artifactPath: artifact.relPath,
+            targetScore: envelope.targetScore,
+            maxIterations: envelope.maxIterations,
+            stopReason: envelope.stopReason,
+            finalScore,
+            iterations: envelope.iterations.map((row) => ({
+                iteration: row.iteration,
+                qualityScore: row.qualityScore,
+                findingsCount: row.findingsCount
+            }))
+        });
+    }
+    return entries;
+}
 export async function buildTraceMatrix(projectRoot) {
     const spec = await readArtifact(projectRoot, "04-spec.md");
     const plan = await readArtifact(projectRoot, "05-plan.md");
@@ -163,10 +215,12 @@ export async function buildTraceMatrix(projectRoot) {
             return !acs || acs.length === 0;
         });
     });
+    const reviewLoops = await collectReviewLoopTraceEntries(projectRoot);
     return {
         entries,
         orphanedCriteria,
         orphanedTasks,
-        orphanedTests
+        orphanedTests,
+        reviewLoops
     };
 }

package/dist/types.d.ts

@@ -118,6 +118,29 @@ export interface IronLawsConfig {
      */
     strictLaws?: string[];
 }
+/**
+ * Optional opt-in audit toggles for additional stage lint gates.
+ *
+ * Disabled by default so existing projects are not forced into stricter
+ * checks until they explicitly enable them in config.
+ */
+export interface OptInAuditsConfig {
+    /** When true, scope lint requires a filled `Pre-Scope System Audit` section. */
+    scopePreAudit?: boolean;
+    /** When true, design lint runs stale diagram drift checks against blast radius files. */
+    staleDiagramAudit?: boolean;
+}
+export interface ReviewLoopExternalSecondOpinionConfig {
+    /** Enables a second outside-voice pass for review-loop iterations. */
+    enabled?: boolean;
+    /** Optional model label for traceability in artifacts/logs. */
+    model?: string;
+    /** Minimum score delta that should be surfaced as disagreement context. */
+    scoreDeltaThreshold?: number;
+}
+export interface ReviewLoopConfig {
+    externalSecondOpinion?: ReviewLoopExternalSecondOpinionConfig;
+}
 export interface CclawConfig {
     version: string;
     flowVersion: string;
@@ -170,6 +193,10 @@ export interface CclawConfig {
     sliceReview?: SliceReviewConfig;
     /** Optional per-law strictness controls for hook-enforced iron laws. */
     ironLaws?: IronLawsConfig;
+    /** Optional opt-in audit gates for scope/design stages. */
+    optInAudits?: OptInAuditsConfig;
+    /** Optional runtime knobs for outside-voice review loops. */
+    reviewLoop?: ReviewLoopConfig;
 }
 /**
  * @deprecated Use `CclawConfig` instead.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "0.48.30",
+  "version": "0.48.32",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {