cclaw-cli 0.48.31 → 0.48.32

package/dist/content/start-command.js

@@ -47,13 +47,18 @@ This is the **recommended way to start** working with cclaw. Use \`/cc-next\` fo
 
    Record the chosen class in \`.cclaw/artifacts/00-idea.md\` on the \`Class:\` line. Do NOT silently treat a non-software task as software.
 
-2. **Phase 1 — Origin-document discovery.** Before asking the user for context, scan for existing requirements/plan artifacts and merge them into initial context:
+2. **Phase 0.5 — Seed shelf recall.** Before routing, scan \`${RUNTIME_ROOT}/seeds/SEED-*.md\` and match each seed's \`trigger_when\` tokens against the prompt text (substring match is enough). If any match:
+   - Surface up to 3 matches (file + title + one-line action) as \`Seed recalls\`.
+   - Ask whether to apply now, keep as reference, or ignore for this run.
+   - If applied/reference, append selected seeds to \`00-idea.md\` under \`Discovered context\` so downstream stages keep the trace.
+
+3. **Phase 1 — Origin-document discovery.** Before asking the user for context, scan for existing requirements/plan artifacts and merge them into initial context:
    - \`.cclaw/artifacts/00-idea.md\` if it already exists (resumed flow).
    - Common origin locations: \`docs/prd/**\`, \`docs/rfcs/**\`, \`docs/adr/**\`, \`docs/design/**\`, \`specs/**\`, \`prd/**\`, \`rfc/**\`, \`design/**\`, root-level \`PRD.md\` / \`SPEC.md\` / \`DESIGN.md\` / \`REQUIREMENTS.md\` / \`ROADMAP.md\`.
    - Summarize each discovered doc in \`00-idea.md\` under a \`Discovered context\` section with path + 1-line summary.
    - If an origin doc contradicts the prompt, surface the conflict to the user before routing.
 
-3. **Phase 2 — Tech-stack + version detection.** Sniff the repo for stack + language versions and record under \`Stack:\`:
+4. **Phase 2 — Tech-stack + version detection.** Sniff the repo for stack + language versions and record under \`Stack:\`:
    - Node: \`package.json\` \`engines\` / \`volta\` / \`packageManager\` / \`devDependencies\`.
    - Python: \`pyproject.toml\` / \`requirements*.txt\` / \`.python-version\`.
    - Go: \`go.mod\` (module + Go version).
@@ -63,9 +68,9 @@ This is the **recommended way to start** working with cclaw. Use \`/cc-next\` fo
    - CI: \`.github/workflows\`, \`.gitlab-ci.yml\`.
    Skip detection quietly if no markers are found — do NOT invent a stack.
 
-4. Read \`${flowPath}\`.
-5. If flow already has completed stages, warn the user that starting a new tracked flow will reset progress. Ask for confirmation before proceeding.
-6. **Track heuristic** — classify the idea text and **recommend** a track (the user can override before any state mutation):
+5. Read \`${flowPath}\`.
+6. If flow already has completed stages, warn the user that starting a new tracked flow will reset progress. Ask for confirmation before proceeding.
+7. **Track heuristic** — classify the idea text and **recommend** a track (the user can override before any state mutation):
    - First, load \`${RUNTIME_ROOT}/config.yaml\`. If \`trackHeuristics\` is defined, apply those per-track vocabulary hints (\`fallback\`, \`tracks.<id>.{triggers,veto}\`) on top of the built-in defaults. Evaluation order is always \`standard -> medium -> quick\` (narrow-to-broad).
    - **quick** (\`spec → tdd → review → ship\`) — single-purpose work where the spec is essentially already known.
      Triggers (case-insensitive substring or close variant): \`bug\`, \`bugfix\`, \`fix\`, \`hotfix\`, \`patch\`, \`typo\`, \`regression\`, \`copy change\`, \`rename\`, \`bump\`, \`upgrade dep\`, \`config tweak\`, \`docs only\`, \`comment\`, \`lint\`, \`format\`, \`small\`, \`tiny\`, \`one-liner\`, \`revert\`.
@@ -74,17 +79,17 @@ This is the **recommended way to start** working with cclaw. Use \`/cc-next\` fo
    - **standard** (full 8 stages — default fallback) — anything that introduces a new capability with architecture uncertainty, touches many modules, or has unclear scope.
      Triggers: \`new feature\`, \`refactor\`, \`migration\`, \`platform\`, \`architecture\`, \`schema\`, \`integrate\`, \`workflow\`, \`onboarding\`, or any prompt that does not match quick/medium confidently.
    - When triggers conflict, prefer **standard** over **medium**, and **medium** over **quick**.
-7. Present the recommendation as a single decision with explicit options:
+8. Present the recommendation as a single decision with explicit options:
    > \`Recommended track: <quick|medium|standard>\` because \`<one-line reason citing matched triggers>\`.
    > Override? (A) keep \`<recommended>\`  (B) switch track  (C) cancel.
    If the harness's native ask tool is available (\`AskUserQuestion\` / \`AskQuestion\` / \`question\` / \`request_user_input\`), send exactly ONE question; on schema error, fall back to a plain-text lettered list.
-8. Persist the chosen track to \`${flowPath}\` (\`track\` field). Compute \`skippedStages\` from the track and write that too. Use the **first stage of the chosen track** as \`currentStage\` (quick → \`spec\`, medium/standard → \`brainstorm\`, trivial fast-path → \`design\` or \`spec\` per Phase 0).
-9. Write the prompt to \`.cclaw/artifacts/00-idea.md\` with the following header lines: \`Class:\` (from Phase 0), \`Track:\` (chosen track + matched heuristic), \`Stack:\` (from Phase 2 detection, or \`unknown\`), and a \`Discovered context\` section if Phase 1 found origin docs.
-10. Load the **first-stage skill for the chosen track** and its command file:
+9. Persist the chosen track to \`${flowPath}\` (\`track\` field). Compute \`skippedStages\` from the track and write that too. Use the **first stage of the chosen track** as \`currentStage\` (quick → \`spec\`, medium/standard → \`brainstorm\`, trivial fast-path → \`design\` or \`spec\` per Phase 0).
+10. Write the prompt to \`.cclaw/artifacts/00-idea.md\` with the following header lines: \`Class:\` (from Phase 0), \`Track:\` (chosen track + matched heuristic), \`Stack:\` (from Phase 2 detection, or \`unknown\`), and a \`Discovered context\` section if Phase 1/seed recall found references.
+11. Load the **first-stage skill for the chosen track** and its command file:
     - quick → \`.cclaw/skills/specification-authoring/SKILL.md\` + \`.cclaw/commands/spec.md\`
     - medium/standard → \`.cclaw/skills/brainstorming/SKILL.md\` + \`.cclaw/commands/brainstorm.md\`
     - trivial fast-path → design or spec skill per Phase 0 decision.
-11. Execute that stage with the prompt + Phase 1/Phase 2 context as initial input.
+12. Execute that stage with the prompt + Phase 1/Phase 2 + seed context as initial input.
 
 ### Reclassification on discovery
 
@@ -152,14 +157,15 @@ Do **not** silently discard an existing flow when the user provides a prompt. If
 ### Path A: \`/cc <prompt>\`
 
 1. **Task classification (Phase 0).** Decide whether the prompt is \`software-standard\`, \`software-trivial\`, \`software-bugfix\`, \`pure-question\`, or \`non-software\`. Non-software and pure-question exit immediately — answer directly, do not open a stage.
-2. **Origin-document discovery (Phase 1).** Scan for \`docs/prd/**\`, \`docs/rfcs/**\`, \`docs/adr/**\`, \`docs/design/**\`, \`specs/**\`, root-level \`PRD.md\` / \`SPEC.md\` / \`DESIGN.md\` / \`REQUIREMENTS.md\`. Summarize any hits in \`00-idea.md\` under \`Discovered context\`. Surface conflicts with the prompt before routing.
-3. **Stack detection (Phase 2).** Inspect \`package.json\` engines, \`pyproject.toml\`, \`go.mod\`, \`Cargo.toml\`, \`pom.xml\`, \`build.gradle*\`, \`Dockerfile\`, \`docker-compose*.yml\`, and CI configs. Record stack + versions on the \`Stack:\` line. Do not invent stack details.
-4. Read \`${flowPath}\`.
-5. If \`completedStages\` is non-empty:
+2. **Seed shelf recall (Phase 0.5).** Scan \`${RUNTIME_ROOT}/seeds/SEED-*.md\` and match \`trigger_when\` tokens against the prompt text. Surface up to 3 matching seeds with file/title/action and ask whether to apply or ignore. When applied, add them to \`00-idea.md\` under \`Discovered context\`.
+3. **Origin-document discovery (Phase 1).** Scan for \`docs/prd/**\`, \`docs/rfcs/**\`, \`docs/adr/**\`, \`docs/design/**\`, \`specs/**\`, root-level \`PRD.md\` / \`SPEC.md\` / \`DESIGN.md\` / \`REQUIREMENTS.md\`. Summarize any hits in \`00-idea.md\` under \`Discovered context\`. Surface conflicts with the prompt before routing.
+4. **Stack detection (Phase 2).** Inspect \`package.json\` engines, \`pyproject.toml\`, \`go.mod\`, \`Cargo.toml\`, \`pom.xml\`, \`build.gradle*\`, \`Dockerfile\`, \`docker-compose*.yml\`, and CI configs. Record stack + versions on the \`Stack:\` line. Do not invent stack details.
+5. Read \`${flowPath}\`.
+6. If \`completedStages\` is non-empty:
    - Inform: "You have an active flow at stage **{currentStage}** with {N} completed stages. Starting a new tracked flow will reset progress."
    - Ask: "Continue with reset? (A) Yes, start fresh (B) No, resume current flow"
    - If (B) → switch to Path B behavior.
-6. **Classify the idea** using the heuristic below and present a single track recommendation. Wait for explicit confirmation or override before mutating any state.
+7. **Classify the idea** using the heuristic below and present a single track recommendation. Wait for explicit confirmation or override before mutating any state.
    - If \`${RUNTIME_ROOT}/config.yaml\` defines \`trackHeuristics\`, apply those vocabulary hints (\`fallback\`, \`tracks.<id>.{triggers,veto}\`) on top of built-in defaults. Evaluation order is fixed: \`standard -> medium -> quick\`. (Honest note: this is advisory prose; the LLM applies it, not a Node-level router.)
 
    **Track heuristic** (lowercase substring match against the user prompt):
@@ -172,9 +178,9 @@ Do **not** silently discard an existing flow when the user provides a prompt. If
 
    - On conflict, prefer \`standard\` over \`medium\`, and \`medium\` over \`quick\`.
    - Always state the recommendation as a one-line reason citing matched triggers.
-7. Persist the chosen track in \`${flowPath}\` (\`track\` + \`skippedStages\`). Set \`currentStage\` to the first stage of the chosen track (\`quick\` → \`spec\`, \`medium\`/ \`standard\` → \`brainstorm\`, trivial fast-path → \`design\` or \`spec\`). Reset gate catalog.
-8. Write \`${RUNTIME_ROOT}/artifacts/00-idea.md\` with the user's prompt plus header lines: \`Class:\`, \`Track:\`, \`Stack:\`, and a \`Discovered context\` section from Phase 1.
-9. Load and execute the **first stage skill of the chosen track** (\`brainstorming\` for medium/standard, \`specification-authoring\` for quick) plus its matching command file.
+8. Persist the chosen track in \`${flowPath}\` (\`track\` + \`skippedStages\`). Set \`currentStage\` to the first stage of the chosen track (\`quick\` → \`spec\`, \`medium\`/ \`standard\` → \`brainstorm\`, trivial fast-path → \`design\` or \`spec\`). Reset gate catalog.
+9. Write \`${RUNTIME_ROOT}/artifacts/00-idea.md\` with the user's prompt plus header lines: \`Class:\`, \`Track:\`, \`Stack:\`, and a \`Discovered context\` section from Phase 0.5/1.
+10. Load and execute the **first stage skill of the chosen track** (\`brainstorming\` for medium/standard, \`specification-authoring\` for quick) plus its matching command file.
 
 ### Reclassification on discovery
 

package/dist/content/templates.js

@@ -28,17 +28,36 @@ inputs_hash: sha256:pending
 |---|---|---|---|
 | 1 |  |  |  |
 
+## Approach Tier
+- Tier: Lightweight | Standard | Deep
+- Why this tier:
+
+## Short-Circuit Decision
+- Status: bypassed
+- Why:
+- Scope handoff:
+
 ## Approaches
-| Approach | Architecture | Trade-offs | Recommendation |
-|---|---|---|---|
-| A |  |  |  |
-| B |  |  |  |
+| Approach | Role | Architecture | Trade-offs | Recommendation |
+|---|---|---|---|---|
+| A | baseline |  |  |  |
+| B | challenger: higher-upside |  |  |  |
+
+## Approach Reaction
+- Closest option:
+- Concerns:
+- What changed after reaction:
 
 ## Selected Direction
 - **Approach:**
 - **Rationale:**
 - **Approval:** pending
 
+## Seed Shelf Candidates (optional)
+| Seed file | Trigger when | Suggested action | Status (planted/deferred/ignored) |
+|---|---|---|---|
+| .cclaw/seeds/SEED-YYYY-MM-DD-<slug>.md |  |  |  |
+
 ## Design
 - **Architecture:**
 - **Key components:**
@@ -62,6 +81,14 @@ inputs_hash: sha256:pending
 
 # Scope Artifact
 
+## Pre-Scope System Audit
+| Check | Command | Findings |
+|---|---|---|
+| Recent commits | \`git log -30 --oneline\` |  |
+| Current diff | \`git diff --stat\` |  |
+| Stash state | \`git stash list\` |  |
+| Debt markers | \`rg -n "TODO|FIXME|XXX|HACK"\` |  |
+
 ## Prime Directives
 - Zero silent failures:
 - Every error has a name:
@@ -138,11 +165,28 @@ inputs_hash: sha256:pending
 |---|---|
 |  |  |
 
+## Seed Shelf Candidates (optional)
+| Seed file | Trigger when | Suggested action | Status (planted/deferred/ignored) |
+|---|---|---|---|
+| .cclaw/seeds/SEED-YYYY-MM-DD-<slug>.md |  |  |  |
+
 ## Error & Rescue Registry
 | Capability | Failure mode | Detection | Fallback |
 |---|---|---|---|
 |  |  |  |  |
 
+## Outside Voice Findings
+| ID | Dimension | Finding | Disposition | Rationale |
+|---|---|---|---|---|
+| F-1 | premise_fit |  | accept/reject/defer |  |
+
+## Spec Review Loop
+| Iteration | Quality Score | Findings | Stop decision |
+|---|---|---|---|
+| 1 | 0.00 | 0 | continue/stop |
+- Stop reason:
+- Unresolved concerns:
+
 ## Completion Dashboard
 - Checklist findings:
 - Resolved decisions count:
@@ -236,21 +280,55 @@ inputs_hash: sha256:pending
 
 ## Architecture Diagram
 
+<!-- diagram: architecture -->
+
 \`\`\`
 (ASCII, Mermaid, or tool-generated diagram showing component boundaries and data flow direction)
 \`\`\`
 
 ## Data-Flow Shadow Paths
+<!-- diagram: data-flow-shadow-paths -->
 | Path | Trigger | Fallback/Degrade behavior |
 |---|---|---|
 |  |  |  |
 
 ## Error Flow Diagram
 
+<!-- diagram: error-flow -->
+
 \`\`\`
 (failure detection -> rescue action -> user-visible outcome)
 \`\`\`
 
+## State Machine Diagram
+
+<!-- diagram: state-machine -->
+
+\`\`\`
+(state transitions for the critical flow lifecycle)
+\`\`\`
+
+## Rollback Flowchart
+
+<!-- diagram: rollback-flowchart -->
+
+\`\`\`
+(trigger -> rollback actions -> verification)
+\`\`\`
+
+## Deployment Sequence Diagram
+
+<!-- diagram: deployment-sequence -->
+
+\`\`\`
+(rollout order, guard checks, and verification sequence)
+\`\`\`
+
+## Stale Diagram Audit
+| File | Last modified | Diagram marker baseline | Status | Notes |
+|---|---|---|---|---|
+|  |  |  | clear/stale |  |
+
 ## What Already Exists
 | Sub-problem | Existing code/library | Layer | Reuse decision |
 |---|---|---|---|
@@ -262,6 +340,15 @@ inputs_hash: sha256:pending
 - Upstream error path:
 - Timeout/downstream path:
 
+### Interaction Edge Case Matrix
+| Edge case | Handled? | Design response | Deferred item (if not handled) |
+|---|---|---|---|
+| double-click | yes/no |  | None / D-XX |
+| nav-away-mid-request | yes/no |  | None / D-XX |
+| 10K-result dataset | yes/no |  | None / D-XX |
+| background-job abandonment | yes/no |  | None / D-XX |
+| zombie connection | yes/no |  | None / D-XX |
+
 ## Security & Threat Model
 | Boundary | Threat | Mitigation | Owner |
 |---|---|---|---|
@@ -292,6 +379,18 @@ inputs_hash: sha256:pending
 |---|---|---|
 |  |  |  |
 
+## Outside Voice Findings
+| ID | Dimension | Finding | Disposition | Rationale |
+|---|---|---|---|---|
+| F-1 | architecture_fit |  | accept/reject/defer |  |
+
+## Spec Review Loop
+| Iteration | Quality Score | Findings | Stop decision |
+|---|---|---|---|
+| 1 | 0.00 | 0 | continue/stop |
+- Stop reason:
+- Unresolved concerns:
+
 ## NOT in scope
 - 
 
@@ -314,6 +413,11 @@ inputs_hash: sha256:pending
 |---|---|---|---|
 |  |  |  |  |
 
+## Seed Shelf Candidates (optional)
+| Seed file | Trigger when | Suggested action | Status (planted/deferred/ignored) |
+|---|---|---|---|
+| .cclaw/seeds/SEED-YYYY-MM-DD-<slug>.md |  |  |  |
+
 ## Completion Dashboard
 | Review Section | Status | Issues |
 |---|---|---|

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.31",
+  "version": "0.48.32",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {