cclaw-cli 0.51.5 → 0.51.7

package/dist/content/hooks.d.ts

@@ -1,3 +1,4 @@
+export declare function startFlowScript(): string;
 export declare function stageCompleteScript(): string;
 export declare function runHookCmdScript(): string;
 export { claudeHooksJsonWithObservation as claudeHooksJson } from "./observe.js";

package/dist/content/hooks.js

@@ -16,6 +16,128 @@ function resolveCliEntrypointForGeneratedHook() {
     }
     return null;
 }
+function internalHelperScript(helperName, internalSubcommand, usage) {
+    const cliEntrypoint = resolveCliEntrypointForGeneratedHook();
+    return `#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { spawn } from "node:child_process";
+
+const RUNTIME_ROOT = ${JSON.stringify(RUNTIME_ROOT)};
+const CCLAW_CLI_ENTRYPOINT = ${JSON.stringify(cliEntrypoint)};
+const HELPER_NAME = ${JSON.stringify(helperName)};
+const INTERNAL_SUBCOMMAND = ${JSON.stringify(internalSubcommand)};
+const USAGE = ${JSON.stringify(usage)};
+
+async function detectRoot() {
+  const candidates = [
+    process.env.CCLAW_PROJECT_ROOT,
+    process.env.CLAUDE_PROJECT_DIR,
+    process.env.CURSOR_PROJECT_DIR,
+    process.env.CURSOR_PROJECT_ROOT,
+    process.env.OPENCODE_PROJECT_DIR,
+    process.env.OPENCODE_PROJECT_ROOT,
+    process.cwd()
+  ].filter((value) => typeof value === "string" && value.length > 0);
+
+  for (const candidate of candidates) {
+    try {
+      const runtimePath = path.join(candidate, RUNTIME_ROOT);
+      const stat = await fs.stat(runtimePath);
+      if (stat.isDirectory()) return candidate;
+    } catch {
+      // continue
+    }
+  }
+  return candidates[0] || process.cwd();
+}
+
+function printUsage() {
+  process.stderr.write(USAGE + "\\n");
+}
+
+async function main() {
+  const [, , ...flags] = process.argv;
+  if (flags.includes("--help") || flags.includes("-h")) {
+    printUsage();
+    return;
+  }
+
+  const root = await detectRoot();
+  const runtimePath = path.join(root, RUNTIME_ROOT);
+  try {
+    const stat = await fs.stat(runtimePath);
+    if (!stat.isDirectory()) throw new Error("not-dir");
+  } catch {
+    process.stderr.write("[cclaw] " + HELPER_NAME + ": runtime root not found at " + runtimePath + "\\n");
+    process.exitCode = 1;
+    return;
+  }
+
+  const cliEntrypoint = process.env.CCLAW_CLI_JS || CCLAW_CLI_ENTRYPOINT;
+  if (!cliEntrypoint || cliEntrypoint.trim().length === 0) {
+    process.stderr.write(
+      "[cclaw] " + HELPER_NAME + ": local Node runtime entrypoint is missing. Re-run npx cclaw-cli sync or npx cclaw-cli upgrade to regenerate hooks.\\n"
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    const stat = await fs.stat(cliEntrypoint);
+    if (!stat.isFile()) throw new Error("not-file");
+  } catch {
+    process.stderr.write(
+      "[cclaw] " + HELPER_NAME + ": local Node runtime entrypoint not found at " + cliEntrypoint + ". Re-run npx cclaw-cli sync or npx cclaw-cli upgrade to regenerate hooks.\\n"
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const child = spawn(process.execPath, [cliEntrypoint, "internal", INTERNAL_SUBCOMMAND, ...flags], {
+    cwd: root,
+    env: process.env,
+    stdio: "inherit"
+  });
+  let spawnErrored = false;
+
+  child.on("error", (error) => {
+    spawnErrored = true;
+    const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
+    if (code === "ENOENT") {
+      process.stderr.write(
+        "[cclaw] " + HELPER_NAME + ": node executable not found while invoking local runtime. Re-run npx cclaw-cli doctor.\\n"
+      );
+    } else {
+      process.stderr.write(
+        "[cclaw] " + HELPER_NAME + ": failed to invoke local Node runtime (" +
+          (error instanceof Error ? error.message : String(error)) +
+          ").\\n"
+      );
+    }
+    process.exitCode = 1;
+  });
+
+  child.on("close", (code, signal) => {
+    if (spawnErrored) {
+      process.exitCode = 1;
+      return;
+    }
+    if (signal) {
+      process.exitCode = 1;
+      return;
+    }
+    process.exitCode = typeof code === "number" && code >= 0 ? code : 1;
+  });
+}
+
+void main();
+`;
+}
+export function startFlowScript() {
+    return internalHelperScript("start-flow", "start-flow", "Usage: node " + RUNTIME_ROOT + "/hooks/start-flow.mjs --track=<standard|medium|quick> [--class=...] [--prompt=...] [--stack=...] [--reason=...] [--reclassify] [--force-reset]");
+}
 export function stageCompleteScript() {
     const cliEntrypoint = resolveCliEntrypointForGeneratedHook();
     return `#!/usr/bin/env node

package/dist/content/stages/scope.js

@@ -45,37 +45,34 @@ export const SCOPE = {
     },
     executionModel: {
         checklist: [
-            "**Default path first** — read brainstorm, challenge premise, recommend one mode, draft 3-5 key in/out boundaries plus deferred items, then seek approval.",
-            "**Optional audits by trigger** — run the pre-scope system audit only when configured; use deep-mode prime directives, dream-state mapping, and temporal interrogation only for complex/high-risk scope.",
-            "**Premise and leverage check** — test whether this is the right problem, what happens if nothing changes, and what existing code can be reused.",
-            "**Calibrate ambition** — for EXPAND/SELECTIVE candidates, do a brief landscape scan and align the quality bar to 2-3 strong in-repo modules.",
-            "**Compare implementation alternatives** — give 2-3 distinct options with effort, risk, pros/cons, and explicit reuse; include minimal viable and ideal architecture options.",
-            "**Select scope mode explicitly** — present expand/selective/hold/reduce with a recommendation and default heuristic justification.",
-            "**Run mode-specific analysis** — expand, selective, hold, or reduce according to the selected mode; do not silently add or trim scope.",
-            "**Handle deferred upside** — optionally park high-upside deferred/out-of-scope ideas in `.cclaw/seeds/`.",
-            `**Outside voice when warranted** — run/reconcile the loop for complex/high-risk or configured scope; otherwise do a concise adversarial self-check. ${reviewLoopPolicySummary("scope")} ${reviewLoopSecondOpinionSummary("scope")}`,
-            "**Write the scope contract** — include in-scope/out-of-scope, discretion areas, deferred items, locked decisions, error/rescue notes, completion dashboard, and explicit approval."
+            "**CEO pass first** — read brainstorm, name the job-to-be-done, challenge whether this is the right product slice, and propose the highest-leverage scope in one pass.",
+            "**Pick one of four gstack modes** — SCOPE EXPANSION, SELECTIVE EXPANSION, HOLD SCOPE, or SCOPE REDUCTION. State why and what user signal would change the mode.",
+            "**Draft the 10-star vs v1 boundary** — show what would make the product meaningfully better, then explicitly choose what ships now, what is deferred, and what is excluded.",
+            "**Premise and leverage check** — test right problem, direct path, no-action outcome, existing-code leverage, and reversibility before asking the user anything.",
+            "**Compare implementation alternatives** — include minimum viable, product-grade, and ideal architecture options with effort/risk/reuse, then recommend one.",
+            "**Run outside voice before final approval** — always do at least a concise adversarial self-check for scope; for complex/high-risk/configured scope, iterate until threshold. Record the loop summary in `## Spec Review Loop` before asking approval.",
+            "**Ask only one decision-changing question** — if the user rejects the contract but is unsure, offer 3-4 concrete scope moves instead of open-ended interrogation.",
+            "**Write the scope contract** — include in-scope/out-of-scope, discretion areas, deferred items, locked decisions, error/rescue notes, completion dashboard, scope summary, and explicit approval."
         ],
         interactionProtocol: [
             decisionProtocolInstruction("scope mode selection", "present expand/selective/hold/reduce as labeled options with trade-offs and mark one as (recommended)", "recommend the option that best covers the prime-directive failure modes, four data-flow paths, observability, and deferred handling for the in-scope set with the smallest blast radius. Base your recommendation on default heuristics: greenfield -> expand, enhancement -> selective, bugfix/hotfix/refactor -> hold, broad blast radius -> reduce"),
-            "Do not walk the full checklist by default. Lead with the default scope contract; ask only when the answer changes in/out/deferred boundaries.",
+            "Do not walk the full checklist by default. Lead with an opinionated scope contract and the one decision that matters most.",
             "Challenge premise first, take a firm position, and name one concrete condition that would change it.",
             "Push back on weak framing: vague scope needs a specific user/problem, platform vision needs a narrow wedge, social proof needs behavioral evidence.",
             "Resolve one structural scope issue at a time; otherwise state the assumption and move on.",
-            "After acceptance/rejection, commit fully and do not re-argue.",
-            `Before final approval, reconcile outside-voice findings when the loop runs and bound retries with ${reviewLoopPolicySummary("scope")}`,
+            "If the user says no but cannot name the change, offer concrete moves: keep scope, add one obvious adjacent capability, reduce to wedge, or re-open stack/product direction.",
+            `Before final approval, record outside-voice findings and a \`## Spec Review Loop\` table using ${reviewLoopPolicySummary("scope")}`,
             "**STOP.** Wait for explicit approval of the scope contract before advancing.",
-            "**STOP BEFORE ADVANCE.** Mandatory delegation `planner` must be completed or explicitly waived, then close via `node .cclaw/hooks/stage-complete.mjs scope`."
+            "**STOP BEFORE ADVANCE.** Mandatory delegation `planner` must be completed or explicitly waived. Then close with `node .cclaw/hooks/stage-complete.mjs scope --passed=scope_mode_selected,scope_contract_written,scope_user_approved --evidence-json '{\"scope_mode_selected\":\"<mode + rationale>\",\"scope_contract_written\":\"<artifact path + sections>\"}'`. Do not include `scope_user_approved` manually; stage-complete auto-hydrates its review-loop envelope from `## Spec Review Loop`."
         ],
         process: [
             "Run configured pre-scope audit only when enabled.",
-            "Challenge premise, check existing-code leverage, and calibrate ambition/quality bar.",
-            "Compare structured scope alternatives with minimum viable and ideal architecture options.",
-            "Select scope mode with explicit user approval.",
-            "Run the selected mode analysis and park high-upside deferred ideas when useful.",
-            `Use outside-voice review only when complex/high-risk or configured; otherwise run a short adversarial self-check. If loop runs, enforce ${reviewLoopPolicySummary("scope")}`,
-            "Write explicit scope contract, discretion areas, deferred items, and D-XX locked decisions.",
-            "Produce scope summary and completion dashboard."
+            "Run the gstack-style CEO scope pass: job-to-be-done, premise challenge, 10-star upside, smallest useful wedge, and what would change the recommendation.",
+            "Compare minimum viable, product-grade, and ideal architecture scope alternatives with explicit reuse/effort/risk.",
+            "Select scope mode with explicit rationale; ask for user opt-in only when changing or expanding scope.",
+            "Run outside voice / adversarial self-check before final approval and record a valid `## Spec Review Loop` table.",
+            "Write explicit scope contract, discretion areas, deferred items, error/rescue registry, and D-XX locked decisions.",
+            "Produce scope summary and completion dashboard before asking final approval."
         ],
         requiredGates: [
             { id: "scope_mode_selected", description: "One scope mode was explicitly selected." },
@@ -90,8 +87,8 @@ export const SCOPE = {
             "Selected mode and rationale are documented.",
             "Locked Decisions section lists stable D-XX IDs for non-negotiable boundaries.",
             "Premise challenge findings documented.",
-            "Outside Voice findings and dispositions are recorded (accept/reject/defer with rationale).",
-            `Spec review loop summary includes iteration count and quality score trajectory per ${reviewLoopPolicySummary("scope")}`,
+            "Outside Voice findings and dispositions are recorded (accept/reject/defer with rationale) before final approval.",
+            `Spec review loop summary includes a table with columns Iteration, Quality Score, Findings, plus Stop reason, Target score, and Max iterations. stage-complete auto-hydrates scope_user_approved evidence from this section. ${reviewLoopPolicySummary("scope")}`,
             reviewLoopSecondOpinionSummary("scope"),
             "Deferred items list with one-line rationale for each.",
             "When an upside deferred idea is parked, a seed file is created under `.cclaw/seeds/` and referenced in the artifact.",

package/dist/content/start-command.js

@@ -86,7 +86,7 @@ ${conversationLanguagePolicyMarkdown()}
    > 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.
 10. Start the tracked flow only through the managed helper:
-   \`cclaw internal start-flow --track=<quick|medium|standard> --class=<class> --prompt=<prompt> --stack=<stack> --reason=<matched heuristic>\`
+   \`node .cclaw/hooks/start-flow.mjs --track=<quick|medium|standard> --class=<class> --prompt=<prompt> --stack=<stack> --reason=<matched heuristic>\`
    If this helper fails, STOP and report the exact command/output. Do **not** manually edit \`${flowPath}\`.
 11. The helper persists \`${flowPath}\`, computes \`skippedStages\`, sets the first stage for the track, resets the gate catalog, and writes \`.cclaw/artifacts/00-idea.md\`.
 12. Load the **first-stage skill for the chosen track** and its command file:
@@ -102,7 +102,7 @@ If during any stage the agent discovers evidence that contradicts the initial Ph
 1. Surface the new evidence in plain text.
 2. Propose the updated \`Class\` + \`Track\` with a one-line reason.
 3. Use the Decision Protocol to let the user accept, override, or cancel.
-4. On acceptance: run \`cclaw internal start-flow --reclassify --track=<new-track> --class=<new-class> --reason=<why>\`. The helper appends a \`Reclassification:\` entry to \`00-idea.md\` and updates flow state atomically. If it fails, STOP and report the exact output; do NOT manually edit \`flow-state.json\`.
+4. On acceptance: run \`node .cclaw/hooks/start-flow.mjs --reclassify --track=<new-track> --class=<new-class> --reason=<why>\`. The helper appends a \`Reclassification:\` entry to \`00-idea.md\` and updates flow state atomically. If it fails, STOP and report the exact output; do NOT manually edit \`flow-state.json\`.
 
 ### Without prompt (\`/cc\`)
 
@@ -181,12 +181,12 @@ ${conversationLanguagePolicyMarkdown()}
 
    - On conflict, prefer \`standard\` over \`medium\`, and \`medium\` over \`quick\`.
    - Always state the recommendation as a one-line reason citing matched triggers.
-8. Run the managed start helper: \`cclaw internal start-flow --track=<quick|medium|standard> --class=<class> --prompt=<prompt> --stack=<stack> --reason=<matched heuristic>\`. The helper writes \`${flowPath}\`, computes \`skippedStages\`, resets the gate catalog, and writes \`${RUNTIME_ROOT}/artifacts/00-idea.md\`. If it fails, STOP and report the exact command/output; do not manually edit flow state.
+8. Run the managed start helper: \`node .cclaw/hooks/start-flow.mjs --track=<quick|medium|standard> --class=<class> --prompt=<prompt> --stack=<stack> --reason=<matched heuristic>\`. The helper writes \`${flowPath}\`, computes \`skippedStages\`, resets the gate catalog, and writes \`${RUNTIME_ROOT}/artifacts/00-idea.md\`. If it fails, STOP and report the exact command/output; do not manually edit flow state.
 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.
 
 ### Reclassification on discovery
 
-If mid-stage evidence contradicts the initial Class/Track decision (the "trivial" change needs a migration, the "quick" bug fix needs architecture work, an origin doc multiplies scope), STOP and re-classify using the Decision Protocol. On acceptance, run \`cclaw internal start-flow --reclassify --track=<new-track> --class=<new-class> --reason=<why>\`; the helper records \`Reclassification:\` in \`00-idea.md\` and updates state atomically. Do NOT rewrite prior artifacts or manually edit flow-state.
+If mid-stage evidence contradicts the initial Class/Track decision (the "trivial" change needs a migration, the "quick" bug fix needs architecture work, an origin doc multiplies scope), STOP and re-classify using the Decision Protocol. On acceptance, run \`node .cclaw/hooks/start-flow.mjs --reclassify --track=<new-track> --class=<new-class> --reason=<why>\`; the helper records \`Reclassification:\` in \`00-idea.md\` and updates state atomically. Do NOT rewrite prior artifacts or manually edit flow-state.
 
 ### Path B: \`/cc\` (no arguments)
 

package/dist/doctor.js

@@ -92,7 +92,7 @@ function extractGeneratedCliEntrypoints(scriptContent) {
     return paths;
 }
 async function generatedCliEntrypointsOk(projectRoot) {
-    const hookScripts = ["stage-complete.mjs", "run-hook.mjs"];
+    const hookScripts = ["stage-complete.mjs", "start-flow.mjs", "run-hook.mjs"];
     const problems = [];
     const checked = [];
     for (const script of hookScripts) {
@@ -644,6 +644,7 @@ export async function doctorChecks(projectRoot, options = {}) {
         "run-hook.mjs",
         "run-hook.cmd",
         "stage-complete.mjs",
+        "start-flow.mjs",
         "opencode-plugin.mjs"
     ]) {
         const scriptPath = path.join(projectRoot, RUNTIME_ROOT, "hooks", script);

package/dist/install.js

@@ -12,7 +12,7 @@ import { viewCommandContract, viewCommandSkillMarkdown } from "./content/view-co
 import { subagentDrivenDevSkill, parallelAgentsSkill } from "./content/subagents.js";
 import { sessionHooksSkillMarkdown } from "./content/session-hooks.js";
 import { ironLawRuntimeDocument, ironLawsSkillMarkdown } from "./content/iron-laws.js";
-import { stageCompleteScript, runHookCmdScript, opencodePluginJs, claudeHooksJson, codexHooksJson, cursorHooksJson } from "./content/hooks.js";
+import { stageCompleteScript, startFlowScript, runHookCmdScript, opencodePluginJs, claudeHooksJson, codexHooksJson, cursorHooksJson } from "./content/hooks.js";
 import { nodeHookRuntimeScript } from "./content/node-hooks.js";
 import { META_SKILL_NAME, usingCclawSkillMarkdown } from "./content/meta-skill.js";
 import { ARTIFACT_TEMPLATES, CURSOR_WORKFLOW_RULE_MDC, RULEBOOK_MARKDOWN, buildRulesJson } from "./content/templates.js";
@@ -705,6 +705,7 @@ async function writeHooks(projectRoot, config) {
         strictLaws: config.ironLaws?.strictLaws
     }), null, 2)}\n`);
     await writeFileSafe(path.join(hooksDir, "stage-complete.mjs"), stageCompleteScript());
+    await writeFileSafe(path.join(hooksDir, "start-flow.mjs"), startFlowScript());
     await writeFileSafe(path.join(hooksDir, "run-hook.mjs"), nodeHookRuntimeScript({
         strictness: effectiveStrictness,
         tddTestPathPatterns: config.tdd?.testPathPatterns ?? config.tddTestGlobs,
@@ -717,6 +718,7 @@ async function writeHooks(projectRoot, config) {
     try {
         for (const script of [
             "stage-complete.mjs",
+            "start-flow.mjs",
             "run-hook.mjs",
             "run-hook.cmd",
             "opencode-plugin.mjs"

package/dist/internal/advance-stage.js

@@ -359,9 +359,15 @@ async function hydrateReviewLoopEvidenceFromArtifact(projectRoot, stage, track,
         return;
     if (!selectedGateIds.includes(gateId))
         return;
-    const existing = evidenceByGate[gateId];
-    if (typeof existing === "string" && existing.trim().length > 0)
+    const reviewStage = stage === "scope" || stage === "design" ? stage : null;
+    if (!reviewStage)
         return;
+    const existing = evidenceByGate[gateId];
+    if (typeof existing === "string" && existing.trim().length > 0) {
+        const existingIssue = validateGateEvidenceShape(stage, gateId, existing);
+        if (!existingIssue)
+            return;
+    }
     const resolved = await resolveArtifactPath(stage, {
         projectRoot,
         track,
@@ -374,9 +380,6 @@ async function hydrateReviewLoopEvidenceFromArtifact(projectRoot, stage, track,
     catch {
         return;
     }
-    const reviewStage = stage === "scope" || stage === "design" ? stage : null;
-    if (!reviewStage)
-        return;
     const envelope = extractReviewLoopEnvelopeFromArtifact(raw, reviewStage, resolved.relPath);
     if (!envelope)
         return;

package/package.json

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