cclaw-cli 0.51.1 → 0.51.3

package/dist/content/skills.js

@@ -216,10 +216,11 @@ function completionParametersBlock(schema, track) {
 - \`artifact\`: \`${RUNTIME_ROOT}/artifacts/${schema.artifactRules.artifactFile}\`
 - \`mandatory delegations\`: ${mandatory}
 - \`completion helper\`: \`node .cclaw/hooks/stage-complete.mjs ${schema.stage}\`
+- \`completion helper with evidence\`: \`node .cclaw/hooks/stage-complete.mjs ${schema.stage} --evidence-json '{"<gate_id>":"<evidence note>"}' --passed=<gate_id>[,<gate_id>]\`
 - Fill \`## Learnings\` before closeout: either \`- None this stage.\` or JSON bullets with required keys \`type\`, \`trigger\`, \`action\`, \`confidence\` (knowledge-schema compatible).
 - Record mandatory delegation completion/waiver in \`${RUNTIME_ROOT}/state/delegation-log.json\` with rationale as needed.
-- Use the completion helper instead of raw \`flow-state.json\` edits (legacy direct edits trigger workflow-guard warnings or strict-mode blocks).
-- Completion protocol: verify required gates, update the artifact, then use the completion helper.
+- Never edit raw \`flow-state.json\` to complete a stage, even in advisory mode; that bypasses validation, gate evidence, and Learnings harvest. If the helper fails, stop and report the exact command/output instead of applying a manual state workaround.
+- Completion protocol: verify required gates, update the artifact, then use the completion helper with \`--evidence-json\` and \`--passed\` for every satisfied gate.
 `;
 }
 function quickStartBlock(stage, track) {

package/dist/content/stages/brainstorm.js

@@ -48,7 +48,7 @@ export const BRAINSTORM = {
         ],
         interactionProtocol: [
             "Start from observed project context; if the idea is vague, first narrow the project type.",
-            "Ask at most one question per turn, only when decision-changing; prefer multiple choice, and summarize after 2-3 answers.",
+            "Ask at most one question per turn, only when decision-changing; if using a structured question tool, send exactly one question object, not a multi-question form.",
             "If likely answers do not change architecture or scope boundaries, choose the default and state the assumption.",
             "Show approaches before the recommendation; include a higher-upside challenger and gather reaction first.",
             "State exactly what is being approved, then **STOP** until the user explicitly approves the artifact."
@@ -119,9 +119,9 @@ export const BRAINSTORM = {
             { section: "Clarifying Questions", required: false, validationRule: "Must capture question, answer, and decision impact for each clarifying question." },
             { section: "Approach Tier", required: true, validationRule: "Must classify depth as Lightweight/Standard/Deep and explain why." },
             { section: "Short-Circuit Decision", required: false, validationRule: "Must include Status/Why/Scope handoff lines when short-circuit is discussed; compact stubs are valid for concrete asks." },
-            { section: "Approaches", required: true, validationRule: "Must compare 2-3 architecturally distinct options with real trade-offs and include one row labeled `challenger: higher-upside`." },
-            { section: "Approach Reaction", required: true, validationRule: "Must summarize user reaction before recommendation, including concerns that changed direction." },
-            { section: "Selected Direction", required: true, validationRule: "Must include the selected approach, rationale tied to user reaction/feedback, and explicit approval marker." },
+            { section: "Approaches", required: true, validationRule: "Must compare 2-3 architecturally distinct options with real trade-offs; include at least one table/bullet row containing both `challenger` and `higher-upside`." },
+            { section: "Approach Reaction", required: true, validationRule: "Must appear before Selected Direction and summarize user reaction before recommendation, including `Closest option`, `Concerns`, and what changed after reaction." },
+            { section: "Selected Direction", required: true, validationRule: "Must include the selected approach, an explicit approval marker, and rationale tied to user reaction/feedback/concerns so the recommendation traces to the user response." },
             { section: "Design", required: false, validationRule: "Must cover architecture, key components, and data flow scaled to complexity." },
             { section: "Visual Companion", required: false, validationRule: "If architecture/data-flow complexity is medium+, include compact ASCII/Mermaid diagram or explicitly justify omission." },
             { section: "Assumptions and Open Questions", required: false, validationRule: "Must capture unresolved assumptions/open questions, or explicitly state none." }

package/dist/content/templates.js

@@ -58,7 +58,7 @@ export const ARTIFACT_TEMPLATES = {
 
 ## Selected Direction
 - **Approach:**
-- **Rationale:**
+- **Rationale:** Based on user reaction/feedback/concerns, ...
 - **Approval:** pending
 
 ${SEED_SHELF_SECTION}

package/dist/gate-evidence.js

@@ -215,11 +215,21 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
     if (shouldValidateArtifact) {
         const lint = await lintArtifact(projectRoot, stage, flowState.track);
         if (!lint.passed) {
-            const failedRequired = lint.findings
-                .filter((finding) => finding.required && !finding.found)
-                .map((finding) => finding.section);
+            const failedRequiredFindings = lint.findings
+                .filter((finding) => finding.required && !finding.found);
+            const failedRequired = failedRequiredFindings.map((finding) => finding.section);
             if (failedRequired.length > 0) {
-                issues.push(`artifact validation failed for required sections: ${failedRequired.join(", ")}.`);
+                const failureDetails = failedRequiredFindings
+                    .map((finding) => {
+                    const details = finding.details?.trim();
+                    const rule = finding.rule?.trim();
+                    const explanation = details && details.length > 0 ? details : rule;
+                    return explanation && explanation.length > 0
+                        ? `${finding.section}: ${explanation}`
+                        : finding.section;
+                })
+                    .join("; ");
+                issues.push(`artifact validation failed for required sections: ${failedRequired.join(", ")}. ${failureDetails}`);
             }
         }
         if (stage === "review") {

package/dist/internal/advance-stage.js

@@ -309,6 +309,19 @@ function coerceCandidateFlowState(raw, fallback) {
         stageGateCatalog: parseCandidateGateCatalog(typed.stageGateCatalog, fallback.stageGateCatalog)
     };
 }
+function stringifyGateEvidenceValue(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "boolean")
+        return value ? "passed" : "failed";
+    if (typeof value === "number" || typeof value === "bigint")
+        return String(value);
+    if (value === null || value === undefined)
+        return "";
+    if (typeof value === "object")
+        return JSON.stringify(value);
+    return String(value);
+}
 function parseEvidenceByGate(raw) {
     if (!raw || raw.trim().length === 0) {
         return {};
@@ -325,12 +338,10 @@ function parseEvidenceByGate(raw) {
     }
     const next = {};
     for (const [key, value] of Object.entries(parsed)) {
-        if (typeof value !== "string")
-            continue;
-        const trimmed = value.trim();
-        if (trimmed.length === 0)
+        const normalized = stringifyGateEvidenceValue(value).trim();
+        if (normalized.length === 0)
             continue;
-        next[key] = trimmed;
+        next[key] = normalized;
     }
     return next;
 }
@@ -381,28 +392,62 @@ function parseAdvanceStageArgs(tokens) {
     let waiveDelegations = [];
     let waiverReason;
     let quiet = false;
-    for (const token of flagTokens) {
+    for (let i = 0; i < flagTokens.length; i += 1) {
+        const token = flagTokens[i];
+        const nextToken = flagTokens[i + 1];
         if (token === "--quiet") {
             quiet = true;
             continue;
         }
+        if (token === "--evidence-json") {
+            if (!nextToken || nextToken.startsWith("--")) {
+                throw new Error("--evidence-json requires a JSON object value.");
+            }
+            evidenceJson = nextToken;
+            i += 1;
+            continue;
+        }
         if (token.startsWith("--evidence-json=")) {
-            evidenceJson = token.replace("--evidence-json=", "");
+            evidenceJson = token.slice("--evidence-json=".length);
+            continue;
+        }
+        if (token === "--passed") {
+            if (!nextToken || nextToken.startsWith("--")) {
+                throw new Error("--passed requires a comma-separated gate list.");
+            }
+            passed = [...passed, ...parseCsv(nextToken)];
+            i += 1;
             continue;
         }
         if (token.startsWith("--passed=")) {
-            passed = [...passed, ...parseCsv(token.replace("--passed=", ""))];
+            passed = [...passed, ...parseCsv(token.slice("--passed=".length))];
+            continue;
+        }
+        if (token === "--waive-delegation") {
+            if (!nextToken || nextToken.startsWith("--")) {
+                throw new Error("--waive-delegation requires a comma-separated agent list.");
+            }
+            waiveDelegations = [...waiveDelegations, ...parseCsv(nextToken)];
+            i += 1;
             continue;
         }
         if (token.startsWith("--waive-delegation=")) {
             waiveDelegations = [
                 ...waiveDelegations,
-                ...parseCsv(token.replace("--waive-delegation=", ""))
+                ...parseCsv(token.slice("--waive-delegation=".length))
             ];
             continue;
         }
+        if (token === "--waiver-reason") {
+            if (!nextToken || nextToken.startsWith("--")) {
+                throw new Error("--waiver-reason requires a text value.");
+            }
+            waiverReason = nextToken.trim();
+            i += 1;
+            continue;
+        }
         if (token.startsWith("--waiver-reason=")) {
-            waiverReason = token.replace("--waiver-reason=", "").trim();
+            waiverReason = token.slice("--waiver-reason=".length).trim();
             continue;
         }
         throw new Error(`Unknown flag for internal advance-stage: ${token}`);

package/package.json

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