cclaw-cli 5.0.0 → 6.1.0

package/dist/delegation.js

@@ -7,7 +7,7 @@ import { readConfig } from "./config.js";
 import { exists, withDirectoryLock, writeFileSafe } from "./fs-utils.js";
 import { HARNESS_ADAPTERS } from "./harness-adapters.js";
 import { readFlowState } from "./runs.js";
-import { stageSchema } from "./content/stage-schema.js";
+import { mandatoryAgentsFor, stageSchema } from "./content/stage-schema.js";
 const execFileAsync = promisify(execFile);
 const TERMINAL_DELEGATION_STATUSES = new Set(["completed", "failed", "waived", "stale"]);
 export const DELEGATION_DISPATCH_SURFACES = [
@@ -320,6 +320,23 @@ export async function readDelegationLedger(projectRoot) {
         return { runId: activeRunId, entries: [] };
     }
 }
+/**
+ * Wave 24 (v6.0.0) audit-only event types that live in
+ * `delegation-events.jsonl` but do NOT carry a delegation lifecycle
+ * payload (no agent/spanId). The parser must accept them so they
+ * don't show up as corrupt lines.
+ */
+const NON_DELEGATION_AUDIT_EVENTS = new Set([
+    "mandatory_delegations_skipped_by_track",
+    "artifact_validation_demoted_by_track",
+    "expansion_strategist_skipped_by_track"
+]);
+function isAuditEventLine(parsed) {
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return false;
+    const evt = parsed.event;
+    return typeof evt === "string" && NON_DELEGATION_AUDIT_EVENTS.has(evt);
+}
 export async function readDelegationEvents(projectRoot) {
     const filePath = delegationEventsPath(projectRoot);
     if (!(await exists(filePath))) {
@@ -338,6 +355,11 @@ export async function readDelegationEvents(projectRoot) {
             if (isDelegationEvent(parsed)) {
                 events.push(parsed);
             }
+            else if (isAuditEventLine(parsed)) {
+                // Wave 24 audit-only row (e.g. mandatory_delegations_skipped_by_track).
+                // Not a delegation lifecycle event but valid audit content.
+                continue;
+            }
             else {
                 corruptLines.push(index + 1);
             }
@@ -451,7 +473,17 @@ export async function checkMandatoryDelegations(projectRoot, stage, options = {}
     const flowState = await readFlowState(projectRoot, {
         repairFeatureSystem: options.repairFeatureSystem
     });
-    const mandatory = stageSchema(stage, flowState.track).mandatoryDelegations;
+    const mandatory = mandatoryAgentsFor(stage, flowState.track, options.taskClass ?? null);
+    const skippedByTrack = mandatory.length === 0 &&
+        stageSchema(stage, flowState.track).mandatoryDelegations.length > 0;
+    if (skippedByTrack) {
+        await recordMandatorySkippedByTrack(projectRoot, {
+            stage,
+            track: flowState.track,
+            taskClass: options.taskClass ?? null,
+            runId: flowState.activeRunId
+        });
+    }
     const { activeRunId } = flowState;
     const ledger = await readDelegationLedger(projectRoot);
     const events = await readDelegationEvents(projectRoot);
@@ -553,6 +585,99 @@ export async function checkMandatoryDelegations(projectRoot, stage, options = {}
         legacyInferredCompletions,
         corruptEventLines: events.corruptLines,
         staleWorkers,
-        expectedMode
+        expectedMode,
+        skippedByTrack
+    };
+}
+/**
+ * Wave 24 (v6.0.0) — append a non-delegation audit event to
+ * `delegation-events.jsonl` recording that the mandatory delegation
+ * gate was skipped because of the active track / task class. Plays the
+ * same audit role as a `waived` row but does NOT carry an agent —
+ * downstream tooling treats `event === "mandatory_delegations_skipped_by_track"`
+ * lines as informational.
+ *
+ * Failures are swallowed: the audit log is best-effort. Missing the
+ * event must never block stage advance because the gate skip itself is
+ * authoritative.
+ */
+async function recordMandatorySkippedByTrack(projectRoot, params) {
+    const eventsPath = delegationEventsPath(projectRoot);
+    const payload = {
+        event: "mandatory_delegations_skipped_by_track",
+        stage: params.stage,
+        track: params.track,
+        taskClass: params.taskClass,
+        runId: params.runId,
+        ts: new Date().toISOString()
     };
+    try {
+        await fs.mkdir(path.dirname(eventsPath), { recursive: true });
+        await fs.appendFile(eventsPath, `${JSON.stringify(payload)}\n`, "utf8");
+    }
+    catch {
+        // best-effort audit; never block stage advance.
+    }
+}
+/**
+ * Wave 25 (v6.1.0) — append a non-delegation audit event recording
+ * that one or more required artifact-validation findings were
+ * demoted from blocking to advisory because the active run is on a
+ * small-fix lane (`track === "quick"` or `taskClass === "software-bugfix"`).
+ *
+ * The event mirrors the Wave 24 `mandatory_delegations_skipped_by_track`
+ * audit pattern: best-effort write to `delegation-events.jsonl`, no
+ * agent payload, recognized by `readDelegationEvents` so it does not
+ * corrupt downstream parsers. Failures are swallowed.
+ */
+export async function recordArtifactValidationDemotedByTrack(projectRoot, params) {
+    if (params.sections.length === 0)
+        return;
+    const eventsPath = delegationEventsPath(projectRoot);
+    const payload = {
+        event: "artifact_validation_demoted_by_track",
+        stage: params.stage,
+        track: params.track,
+        taskClass: params.taskClass,
+        runId: params.runId,
+        sections: params.sections,
+        ts: new Date().toISOString()
+    };
+    try {
+        await fs.mkdir(path.dirname(eventsPath), { recursive: true });
+        await fs.appendFile(eventsPath, `${JSON.stringify(payload)}\n`, "utf8");
+    }
+    catch {
+        // best-effort audit; never block stage advance.
+    }
+}
+/**
+ * Wave 25 (v6.1.0) — append a non-delegation audit event recording
+ * that the scope-stage Expansion Strategist (`product-discovery`)
+ * delegation requirement was skipped because the active run is on a
+ * small-fix lane (`track === "quick"` or `taskClass === "software-bugfix"`).
+ *
+ * Mirrors the Wave 24 `mandatory_delegations_skipped_by_track`
+ * audit pattern: best-effort write to `delegation-events.jsonl`, no
+ * agent payload, recognized by `readDelegationEvents` so it does not
+ * corrupt downstream parsers. Failures are swallowed.
+ */
+export async function recordExpansionStrategistSkippedByTrack(projectRoot, params) {
+    const eventsPath = delegationEventsPath(projectRoot);
+    const payload = {
+        event: "expansion_strategist_skipped_by_track",
+        stage: "scope",
+        track: params.track,
+        taskClass: params.taskClass,
+        runId: params.runId,
+        selectedScopeMode: params.selectedScopeMode,
+        ts: new Date().toISOString()
+    };
+    try {
+        await fs.mkdir(path.dirname(eventsPath), { recursive: true });
+        await fs.appendFile(eventsPath, `${JSON.stringify(payload)}\n`, "utf8");
+    }
+    catch {
+        // best-effort audit; never block stage advance.
+    }
 }

package/dist/flow-state.d.ts

@@ -76,6 +76,20 @@ export interface FlowState {
     stageGateCatalog: Record<FlowStage, StageGateState>;
     /** Active flow track (determines which stages are in the critical path for this run). */
     track: FlowTrack;
+    /**
+     * Wave 25 (v6.1.0) — optional task class for the active run.
+     *
+     * Mirrors the `MandatoryDelegationTaskClass` union used by Wave 24's
+     * `mandatoryAgentsFor` helper. When set to `"software-bugfix"`, the
+     * artifact-validation escape (`shouldDemoteArtifactValidationByTrack`)
+     * collapses lite-tier-only checks (Architecture Diagram async/failure
+     * edges, Interaction Edge Case mandatory rows, Stale Diagram Drift,
+     * Expansion Strategist) from required → advisory.
+     *
+     * Persistence is best-effort: existing flow-state.json files written
+     * before Wave 25 simply omit the field (treated as `null`).
+     */
+    taskClass?: "software-standard" | "software-trivial" | "software-bugfix" | null;
     /** Stages explicitly skipped for this track (empty for standard; populated for quick). */
     skippedStages: FlowStage[];
     /** Stages invalidated by rewind operations and awaiting explicit acknowledgement. */

package/dist/harness-adapters.js

@@ -349,7 +349,7 @@ Before responding to a coding request:
 
 Three rules apply to every cclaw stage in this project, regardless of which skills loaded:
 
-1. **Q&A convergence before drafting** — for brainstorm / scope / design, walk the stage forcing questions one at a time via the harness-native question tool (Claude \`AskUserQuestion\`, Cursor \`AskQuestion\`, Codex \`request_user_input\`, Gemini \`ask_user\`). The \`qa_log_unconverged\` linter rule will block \`stage-complete\` when convergence has not been reached. Convergence is satisfied when ANY of: (a) all forcing-question topics are addressed in \`## Q&A Log\`, (b) the last 2 substantive rows produce no decision-changing impact (Ralph-Loop), or (c) an explicit user stop-signal row is recorded. The fixed count floor (10 for standard) was removed in Wave 23.
+1. **Q&A convergence before drafting** — for brainstorm / scope / design, walk the stage forcing questions one at a time via the harness-native question tool (Claude \`AskUserQuestion\`, Cursor \`AskQuestion\`, Codex \`request_user_input\`, Gemini \`ask_user\`). The \`qa_log_unconverged\` linter rule will block \`stage-complete\` when convergence has not been reached. Convergence is satisfied when ANY of: (a) every forcing-question topic id is tagged \`[topic:<id>]\` in at least one \`## Q&A Log\` row, (b) the last 2 substantive rows produce no decision-changing impact (Ralph-Loop), or (c) an explicit user stop-signal row is recorded. The fixed count floor (10 for standard) was removed in Wave 23. Wave 24 (v6.0.0) made \`[topic:<id>]\` tagging mandatory (no English keyword fallback) so the gate works in any natural language.
 2. **Subagents run after Q&A approval** — mandatory subagents in brainstorm / scope / design (\`product-discovery\`, \`critic\`, \`planner\`, \`architect\`, \`test-author\`) run only AFTER the user approves the elicitation outcome. See each stage's "Run Phase: post-elicitation" rows in the materialized Automatic Subagent Dispatch table.
 3. **No command-line echo to chat** — the user does not run cclaw helpers manually. Never paste \`node .cclaw/hooks/...\` invocations, \`--evidence-json '{...}'\` payloads, or shell hash commands (\`shasum\`, \`sha256sum\`, \`Get-FileHash\`, \`certutil\`, etc.) into chat. Run helpers via the tool layer; report only the resulting summary.
 

package/dist/internal/advance-stage/advance.d.ts

@@ -19,6 +19,8 @@ interface InternalValidationReport {
         corruptEventLines: number[];
         staleWorkers: string[];
         expectedMode: string;
+        /** Wave 24: true when mandatoryAgentsFor returned [] for the run's track / taskClass. */
+        skippedByTrack: boolean;
     };
     gates: {
         ok: boolean;
@@ -32,7 +34,43 @@ interface InternalValidationReport {
         issues: string[];
     };
 }
+/**
+ * Wave 24 entry point — auto-hydrate evidence for an auto-hydratable
+ * gate that the agent already included in --passed but for which they
+ * forgot to provide --evidence-json. Returns silently when no
+ * hydration is possible (no auto-hydratable gate, no artifact, no
+ * envelope, etc.).
+ *
+ * Wave 25 (v6.1.0) layered `tryAutoHydrateAndSelectReviewLoopGate` on
+ * top of this so the gate is also auto-included in selectedGateIds
+ * when the artifact yields a valid envelope. Together the two helpers
+ * remove the contradiction the user reported in Wave 24:
+ *   - "omit this gate from --evidence-json so stage-complete can
+ *      auto-hydrate it" → "missing --evidence-json entries for passed
+ *      gates: design_diagram_freshness".
+ */
 export declare function hydrateReviewLoopEvidenceFromArtifact(projectRoot: string, stage: FlowStage, track: FlowState["track"], selectedGateIds: string[], evidenceByGate: Record<string, string>): Promise<void>;
+/**
+ * Wave 25 (v6.1.0) — auto-include an auto-hydratable review-loop gate
+ * in `selectedGateIds` when:
+ *   - The stage has an auto-hydratable gate registered via
+ *     `AUTO_REVIEW_LOOP_GATE_BY_STAGE` (currently `design`).
+ *   - The artifact yields a valid review-loop envelope via
+ *     `extractReviewLoopEnvelopeFromArtifact`.
+ *   - The gate is required for the active track.
+ *   - The agent has NOT passed the gate yet (so we don't double-add).
+ *
+ * Returns the (possibly extended) array of selected gate IDs and
+ * mutates `evidenceByGate` to include the hydrated envelope.
+ *
+ * Together with `hydrateReviewLoopEvidenceFromArtifact` this makes the
+ * flow consistent: if the artifact contains the envelope, the agent
+ * neither has to include the gate in --passed nor pass --evidence-json
+ * for it. If the artifact does NOT contain the envelope, the agent
+ * gets a clear error pointing at the artifact section to add (via
+ * `reviewLoopArtifactFixHint`).
+ */
+export declare function tryAutoHydrateAndSelectReviewLoopGate(projectRoot: string, stage: FlowStage, track: FlowState["track"], requiredGateIds: string[], selectedGateIds: string[], evidenceByGate: Record<string, string>): Promise<string[]>;
 export declare function buildValidationReport(projectRoot: string, flowState: FlowState, options?: {
     allowBlockedReviewRoute?: boolean;
     extraStageFlags?: string[];

package/dist/internal/advance-stage/advance.js

@@ -10,7 +10,7 @@ import { readFlowState, writeFlowState } from "../../runs.js";
 import { stageSchema } from "../../content/stage-schema.js";
 import { extractReviewLoopEnvelopeFromArtifact } from "../../content/review-loop.js";
 import { unique } from "./helpers.js";
-import { AUTO_REVIEW_LOOP_GATE_BY_STAGE, reviewLoopArtifactFixHint, validateGateEvidenceShape } from "./review-loop.js";
+import { AUTO_REVIEW_LOOP_GATE_BY_STAGE, reviewLoopArtifactFixHint, reviewLoopEnvelopeExample, validateGateEvidenceShape } from "./review-loop.js";
 import { ensureProactiveDelegationTrace } from "./verify.js";
 function resolveSuccessorTransition(stage, track, transitionTargets, satisfiedGuards, selectedTransitionGuards) {
     const natural = transitionTargets[0] ?? null;
@@ -57,6 +57,21 @@ function nextInteractionHints(flowState, args, successor) {
     }
     return hints;
 }
+/**
+ * Wave 24 entry point — auto-hydrate evidence for an auto-hydratable
+ * gate that the agent already included in --passed but for which they
+ * forgot to provide --evidence-json. Returns silently when no
+ * hydration is possible (no auto-hydratable gate, no artifact, no
+ * envelope, etc.).
+ *
+ * Wave 25 (v6.1.0) layered `tryAutoHydrateAndSelectReviewLoopGate` on
+ * top of this so the gate is also auto-included in selectedGateIds
+ * when the artifact yields a valid envelope. Together the two helpers
+ * remove the contradiction the user reported in Wave 24:
+ *   - "omit this gate from --evidence-json so stage-complete can
+ *      auto-hydrate it" → "missing --evidence-json entries for passed
+ *      gates: design_diagram_freshness".
+ */
 export async function hydrateReviewLoopEvidenceFromArtifact(projectRoot, stage, track, selectedGateIds, evidenceByGate) {
     const gateId = AUTO_REVIEW_LOOP_GATE_BY_STAGE[stage];
     if (!gateId)
@@ -87,6 +102,63 @@ export async function hydrateReviewLoopEvidenceFromArtifact(projectRoot, stage,
         return;
     evidenceByGate[gateId] = JSON.stringify(envelope);
 }
+/**
+ * Wave 25 (v6.1.0) — auto-include an auto-hydratable review-loop gate
+ * in `selectedGateIds` when:
+ *   - The stage has an auto-hydratable gate registered via
+ *     `AUTO_REVIEW_LOOP_GATE_BY_STAGE` (currently `design`).
+ *   - The artifact yields a valid review-loop envelope via
+ *     `extractReviewLoopEnvelopeFromArtifact`.
+ *   - The gate is required for the active track.
+ *   - The agent has NOT passed the gate yet (so we don't double-add).
+ *
+ * Returns the (possibly extended) array of selected gate IDs and
+ * mutates `evidenceByGate` to include the hydrated envelope.
+ *
+ * Together with `hydrateReviewLoopEvidenceFromArtifact` this makes the
+ * flow consistent: if the artifact contains the envelope, the agent
+ * neither has to include the gate in --passed nor pass --evidence-json
+ * for it. If the artifact does NOT contain the envelope, the agent
+ * gets a clear error pointing at the artifact section to add (via
+ * `reviewLoopArtifactFixHint`).
+ */
+export async function tryAutoHydrateAndSelectReviewLoopGate(projectRoot, stage, track, requiredGateIds, selectedGateIds, evidenceByGate) {
+    const gateId = AUTO_REVIEW_LOOP_GATE_BY_STAGE[stage];
+    if (!gateId)
+        return selectedGateIds;
+    const reviewStage = stage === "scope" || stage === "design" ? stage : null;
+    if (!reviewStage)
+        return selectedGateIds;
+    if (!requiredGateIds.includes(gateId))
+        return selectedGateIds;
+    if (selectedGateIds.includes(gateId)) {
+        // Already selected — fall through to the existing hydration helper
+        // for the manual --evidence-json path.
+        await hydrateReviewLoopEvidenceFromArtifact(projectRoot, stage, track, selectedGateIds, evidenceByGate);
+        return selectedGateIds;
+    }
+    const existing = evidenceByGate[gateId];
+    if (typeof existing === "string" && existing.trim().length > 0) {
+        return [...selectedGateIds, gateId];
+    }
+    const resolved = await resolveArtifactPath(stage, {
+        projectRoot,
+        track,
+        intent: "read"
+    });
+    let raw = "";
+    try {
+        raw = await fs.readFile(resolved.absPath, "utf8");
+    }
+    catch {
+        return selectedGateIds;
+    }
+    const envelope = extractReviewLoopEnvelopeFromArtifact(raw, reviewStage, resolved.relPath);
+    if (!envelope)
+        return selectedGateIds;
+    evidenceByGate[gateId] = JSON.stringify(envelope);
+    return [...selectedGateIds, gateId];
+}
 export async function buildValidationReport(projectRoot, flowState, options = {}) {
     const delegation = await checkMandatoryDelegations(projectRoot, flowState.currentStage);
     const gates = await verifyCurrentStageGateEvidence(projectRoot, flowState, {
@@ -111,7 +183,8 @@ export async function buildValidationReport(projectRoot, flowState, options = {}
             legacyInferredCompletions: delegation.legacyInferredCompletions,
             corruptEventLines: delegation.corruptEventLines,
             staleWorkers: delegation.staleWorkers,
-            expectedMode: delegation.expectedMode
+            expectedMode: delegation.expectedMode,
+            skippedByTrack: delegation.skippedByTrack
         },
         gates: {
             ok: gates.ok,
@@ -228,9 +301,17 @@ export async function runAdvanceStage(projectRoot, args, io) {
         .flatMap((target) => getTransitionGuards(args.stage, target, flowState.track))
         .filter((guardId) => !allowedGateIds.has(guardId)));
     const selectableGateIds = new Set([...allowedGateIds, ...transitionGuardIds]);
-    const selectedGateIds = args.passedGateIds.length > 0
+    let selectedGateIds = args.passedGateIds.length > 0
         ? args.passedGateIds.filter((gateId) => selectableGateIds.has(gateId))
         : requiredGateIds;
+    // Wave 25 (v6.1.0): if the active stage has an auto-hydratable
+    // review-loop gate (currently `design.design_architecture_locked`)
+    // and the artifact already contains a valid review-loop envelope,
+    // include the gate in selectedGateIds and hydrate evidence in one
+    // step. This removes the Wave 24 contradiction between "omit from
+    // --evidence-json so we can auto-hydrate" and "missing
+    // --evidence-json entries for passed gates".
+    selectedGateIds = await tryAutoHydrateAndSelectReviewLoopGate(projectRoot, args.stage, flowState.track, requiredGateIds, selectedGateIds, args.evidenceByGate);
     const selectedGateIdSet = new Set(selectedGateIds);
     const selectedTransitionGuards = selectedGateIds.filter((gateId) => transitionGuardIds.has(gateId));
     const blockedReviewRoute = args.stage === "review" && selectedGateIdSet.has("review_verdict_blocked");
@@ -239,7 +320,11 @@ export async function runAdvanceStage(projectRoot, args, io) {
         : requiredGateIds;
     const missingRequired = requiredForSelectedRoute.filter((gateId) => !selectedGateIdSet.has(gateId));
     if (missingRequired.length > 0) {
-        io.stderr.write(`cclaw internal advance-stage: required gates not selected as passed: ${missingRequired.join(", ")}.\n`);
+        const autoHydrateGate = AUTO_REVIEW_LOOP_GATE_BY_STAGE[args.stage];
+        const autoHydrateHint = autoHydrateGate && missingRequired.includes(autoHydrateGate) && (args.stage === "scope" || args.stage === "design")
+            ? ` Auto-hydratable gate "${autoHydrateGate}" was NOT auto-included because the design artifact is missing the review-loop envelope. Add a \`## ${args.stage === "scope" ? "Scope Outside Voice Loop" : "Design Outside Voice Loop"}\` table (example envelope: ${reviewLoopEnvelopeExample(args.stage)}), or pass --evidence-json='{"${autoHydrateGate}": "<envelope-json>"}' alongside --passed=...,${autoHydrateGate}.`
+            : "";
+        io.stderr.write(`cclaw internal advance-stage: required gates not selected as passed: ${missingRequired.join(", ")}.${autoHydrateHint}\n`);
         return 1;
     }
     const mandatory = new Set(schema.mandatoryDelegations);
@@ -268,7 +353,10 @@ export async function runAdvanceStage(projectRoot, args, io) {
             });
         }
     }
-    await hydrateReviewLoopEvidenceFromArtifact(projectRoot, args.stage, flowState.track, selectedGateIds, args.evidenceByGate);
+    // Wave 25 (v6.1.0): hydration + auto-select happens earlier via
+    // `tryAutoHydrateAndSelectReviewLoopGate`. The previous explicit
+    // call here was redundant (helper already covered both the
+    // already-selected and not-yet-selected paths).
     const catalog = flowState.stageGateCatalog[args.stage];
     const nextPassed = unique([...catalog.passed, ...selectedGateIds]).filter((gateId) => allowedGateIds.has(gateId));
     const nextPassedSet = new Set(nextPassed);

package/dist/internal/advance-stage/review-loop.d.ts

@@ -1,5 +1,14 @@
 import type { FlowStage } from "../../types.js";
 export declare const AUTO_REVIEW_LOOP_GATE_BY_STAGE: Partial<Record<FlowStage, string>>;
+/**
+ * Wave 25 (v6.1.0) — exact JSON shape that gate-evidence validators
+ * accept for a review-loop envelope. The error messages emitted by
+ * `validateReviewLoopGateEvidence` always include this example so the
+ * agent never has to guess where `stage` lives (top-level of the
+ * envelope, NOT inside `payload`). Keep `stage`/`targetScore`/etc. in
+ * the order shown so a copy-paste from the error survives.
+ */
+export declare function reviewLoopEnvelopeExample(stage: "scope" | "design"): string;
 export declare function pickReviewLoopEnvelope(value: unknown): Record<string, unknown> | null;
 export declare function validateReviewLoopGateEvidence(stage: "scope" | "design", evidence: string): string | null;
 export declare function validateUserApprovalEvidence(evidence: string): string | null;

package/dist/internal/advance-stage/review-loop.js

@@ -11,6 +11,29 @@ const REVIEW_LOOP_STOP_REASONS = new Set([
     "max_iterations_reached",
     "user_opt_out"
 ]);
+/**
+ * Wave 25 (v6.1.0) — exact JSON shape that gate-evidence validators
+ * accept for a review-loop envelope. The error messages emitted by
+ * `validateReviewLoopGateEvidence` always include this example so the
+ * agent never has to guess where `stage` lives (top-level of the
+ * envelope, NOT inside `payload`). Keep `stage`/`targetScore`/etc. in
+ * the order shown so a copy-paste from the error survives.
+ */
+export function reviewLoopEnvelopeExample(stage) {
+    return JSON.stringify({
+        type: "review-loop",
+        stage,
+        targetScore: 0.8,
+        maxIterations: 3,
+        stopReason: "quality_threshold_met",
+        iterations: [{ iteration: 1, qualityScore: 0.8, findingsCount: 0 }]
+    });
+}
+function reviewLoopEnvelopeShapeHint(stage) {
+    return (`Expected envelope: ${reviewLoopEnvelopeExample(stage)}` +
+        " (top-level keys: type, stage, targetScore, maxIterations, stopReason, iterations[]). " +
+        "Stage MUST be at the top level — not inside payload.");
+}
 export function pickReviewLoopEnvelope(value) {
     const direct = asRecord(value);
     if (!direct)
@@ -31,14 +54,17 @@ export function validateReviewLoopGateEvidence(stage, evidence) {
         parsed = JSON.parse(evidence);
     }
     catch {
-        return "must be JSON containing a review-loop envelope (`type: \"review-loop\"`) in top-level, `payload`, or `reviewLoop`.";
+        return ("must be JSON containing a review-loop envelope (`type: \"review-loop\"`) in top-level, `payload`, or `reviewLoop`. " +
+            reviewLoopEnvelopeShapeHint(stage));
     }
     const envelope = pickReviewLoopEnvelope(parsed);
     if (!envelope) {
-        return "must include a review-loop envelope (`type: \"review-loop\"`) in top-level, `payload`, or `reviewLoop`.";
+        return ("must include a review-loop envelope (`type: \"review-loop\"`) in top-level, `payload`, or `reviewLoop`. " +
+            reviewLoopEnvelopeShapeHint(stage));
     }
     if (envelope.stage !== stage) {
-        return `review-loop envelope stage must be "${stage}".`;
+        return (`review-loop envelope stage must be "${stage}" at the top level of the envelope, not inside payload. ` +
+            reviewLoopEnvelopeShapeHint(stage));
     }
     const targetScore = envelope.targetScore;
     if (typeof targetScore !== "number" || Number.isNaN(targetScore) || targetScore < 0 || targetScore > 1) {
@@ -157,5 +183,17 @@ export async function validateGateEvidenceShape(projectRoot, stage, gateId, evid
 export function reviewLoopArtifactFixHint(stage, gateId) {
     if (AUTO_REVIEW_LOOP_GATE_BY_STAGE[stage] !== gateId)
         return "";
-    return ` Add a \`## ${stage === "scope" ? "Scope Outside Voice Loop" : "Design Outside Voice Loop"}\` table to the artifact with rows like \`| 1 | 0.80 | 0 |\` plus \`- Stop reason: quality_threshold_met\`, \`- Target score: 0.80\`, and \`- Max iterations: 3\`; then omit this gate from manual evidence so stage-complete can auto-hydrate it.`;
+    // Wave 25 (v6.1.0): the consistent flow is "include the gate in
+    // --passed AND let stage-complete auto-hydrate evidence from the
+    // artifact". Wave 24's hint told agents to omit the gate from
+    // --evidence-json, but they then hit
+    // `missing --evidence-json entries for passed gates: <gateId>`
+    // because hydration only runs when --evidence-json is also present
+    // OR when an artifact section yields a parseable envelope. The new
+    // hint tells the agent to:
+    //   1. Add the artifact section (so hydration succeeds), AND
+    //   2. Include the gate in --passed.
+    // No --evidence-json entry is required in that case.
+    const stageReviewSection = stage === "scope" ? "Scope Outside Voice Loop" : "Design Outside Voice Loop";
+    return (` Fix in two steps: (1) Add a \`## ${stageReviewSection}\` table to the artifact with rows like \`| 1 | 0.80 | 0 |\` plus \`- Stop reason: quality_threshold_met\`, \`- Target score: 0.80\`, and \`- Max iterations: 3\`. (2) Re-run \`stage-complete ${stage} --passed=...,${gateId},...\` — stage-complete will auto-hydrate the envelope from the artifact, so you do NOT need to pass --evidence-json for ${gateId}.`);
 }

package/package.json

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