cclaw-cli 0.5.2 → 0.5.4

package/README.md

@@ -119,7 +119,7 @@ Required repository secret:
 │   └── <activeRunId>/
 │       ├── artifacts/        # canonical run artifacts
 │       ├── run.json
-│       └── 00-handoff.md
+│       └── handoff.md
 └── learnings.jsonl
 ```
 

package/dist/artifact-linter.js

@@ -85,6 +85,24 @@ function countListItems(sectionBody) {
     const tableDataRows = tableRows.length > 0 ? Math.max(0, tableRows.length - 1) : 0;
     return Math.max(bullets, tableDataRows);
 }
+function parseMarkdownTableRow(line) {
+    return line
+        .trim()
+        .split("|")
+        .map((cell) => cell.trim())
+        .filter((cell) => cell.length > 0);
+}
+function tableHeaderCells(sectionBody) {
+    const lines = sectionBody.split(/\r?\n/).map((line) => line.trim());
+    const headerIndex = lines.findIndex((line) => /^\|.*\|$/u.test(line));
+    if (headerIndex < 0)
+        return null;
+    const separator = lines[headerIndex + 1];
+    if (!separator || !/^\|[-:| ]+\|$/u.test(separator)) {
+        return null;
+    }
+    return parseMarkdownTableRow(lines[headerIndex]);
+}
 function extractMinItemsFromRule(rule) {
     const match = /at least\s+(\d+)/iu.exec(rule);
     if (!match)
@@ -129,6 +147,26 @@ function validateSectionBody(sectionBody, rule) {
             };
         }
     }
+    if (/table must use 4 columns/iu.test(rule)) {
+        const header = tableHeaderCells(sectionBody);
+        if (!header) {
+            return {
+                ok: false,
+                details: "Rule expects a markdown table header with a separator row."
+            };
+        }
+        const expected = ["Category", "Question asked", "User answer", "Evidence note"];
+        const normalizedHeader = header.map((cell) => cell.toLowerCase());
+        const normalizedExpected = expected.map((cell) => cell.toLowerCase());
+        const matches = normalizedHeader.length === normalizedExpected.length &&
+            normalizedHeader.every((cell, index) => cell === normalizedExpected[index]);
+        if (!matches) {
+            return {
+                ok: false,
+                details: `Rule expects Clarification Log header: ${expected.join(" | ")}.`
+            };
+        }
+    }
     if (/exactly one/iu.test(rule)) {
         const tokens = tokensFromRule(rule);
         if (tokens.length > 0) {

package/dist/content/contracts.js

@@ -26,7 +26,7 @@ ${schema.hardGate}
 
 ## In / Out
 - **Reads:** ${readsLine}
-- **Writes:** \`.cclaw/artifacts/${schema.artifactFile}\` (canonical run copy: \`.cclaw/runs/<activeRunId>/artifacts/${schema.artifactFile}\`)
+- **Writes:** \`.cclaw/artifacts/${schema.artifactFile}\` (run snapshot under \`.cclaw/runs/<activeRunId>/artifacts/${schema.artifactFile}\` is synchronized by cclaw runtime)
 - **Next:** \`/cc-next\` (updates flow-state and loads the next stage)
 
 ## Context Hydration (mandatory before stage work)
@@ -35,7 +35,7 @@ ${schema.hardGate}
 3. Load required upstream artifacts for this stage:
 ${hydrationLines}
 4. If a canonical run artifact is missing, fallback to the matching file under \`.cclaw/artifacts/\` and record that fallback in the stage artifact.
-5. Write stage output to \`.cclaw/artifacts/${schema.artifactFile}\` and keep canonical run copy aligned at \`.cclaw/runs/<activeRunId>/artifacts/${schema.artifactFile}\`.
+5. Write stage output to \`.cclaw/artifacts/${schema.artifactFile}\`. Do NOT manually copy into run directories; cclaw sync/runtime keeps run snapshots aligned.
 
 ## Gates
 ${gateIds}

package/dist/content/examples.js

@@ -1,5 +1,38 @@
 const STAGE_EXAMPLES = {
-    brainstorm: `### Alternatives comparison
+    brainstorm: `### Clarification sequence (Socratic)
+
+**Q1 (PURPOSE):** "What decision will this demo help your audience make, and who exactly is that audience?"  
+**A1:** "Internal platform team; they should see whether our release flow can be trusted."
+
+**Q2 (SCOPE):** "Which outcomes are explicitly OUT of scope for this demo so we avoid accidental expansion?"  
+**A2:** "No production rollout automation; only release metadata validation + publish safety checks."
+
+**Q3 (BOUNDARIES):** "When release metadata is missing or invalid, what should happen and what should NEVER happen?"  
+**A3:** "Must block release with a clear reason; must never auto-publish anyway."
+
+**Q4 (ENVIRONMENT):** "Where will this run in practice: local only, CI only, or both? How is it installed and invoked?"  
+**A4:** "CI-first in GitHub Actions, but reproducible locally with npm scripts."
+
+**Q5 (CONSTRAINTS):** "What constraints are non-negotiable (runtime deps, latency, compatibility, policy)?"  
+**A5:** "No new runtime dependencies; checks should stay under 2 minutes; compatible with current workflow."
+
+### One-question-per-message discipline
+
+**Bad (bundled):** "Where will this run? Which Python version? Stdlib only? Any perf limits?"
+
+**Good (single ask):** "Where will this run in practice: local only, CI only, or both?"
+
+**Then next turn:** "Which runtime version should we lock as minimum?"
+
+**Then next turn:** "Should we treat 'stdlib-only' as a hard dependency constraint?"
+
+### Premise challenge and boundary stress-test
+
+**Premise challenge:** "If the goal is only to demonstrate filesystem I/O, why is a CLI better than a tiny script or notebook for this demo?"
+
+**Boundary stress-test:** "When a write fails midway (permissions or partial path issues), what outcome should NEVER happen?"
+
+### Alternatives comparison
 
 | Approach | Pros | Cons | Effort | Recommendation |
 | --- | --- | --- | --- | --- |

package/dist/content/hooks.js

@@ -678,9 +678,98 @@ if [ "$CHECKPOINT_WRITTEN" -eq 0 ]; then
   CHECKPOINT_NOTE="Checkpoint update failed. Review ${RUNTIME_ROOT}/state/checkpoint.json manually."
 fi
 
+RUN_SYNC_NOTE="Run metadata sync skipped."
+if [ -n "$ACTIVE_RUN" ] && [ "$ACTIVE_RUN" != "none" ] && [ "$ACTIVE_RUN" != "run-pending" ]; then
+  RUN_DIR="$ROOT/${RUNTIME_ROOT}/runs/$ACTIVE_RUN"
+  RUN_META_FILE="$RUN_DIR/run.json"
+  RUN_HANDOFF_FILE="$RUN_DIR/handoff.md"
+  if [ -f "$RUN_META_FILE" ] && [ -f "$STATE_FILE" ] && command -v python3 >/dev/null 2>&1; then
+    if python3 - "$STATE_FILE" "$RUN_META_FILE" "$RUN_HANDOFF_FILE" "$ACTIVE_RUN" "$TS" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+state_path, run_meta_path, handoff_path, active_run, timestamp = sys.argv[1:6]
+
+try:
+    state = json.loads(Path(state_path).read_text(encoding="utf-8"))
+except Exception:
+    raise SystemExit(1)
+
+try:
+    meta = json.loads(Path(run_meta_path).read_text(encoding="utf-8"))
+except Exception:
+    raise SystemExit(1)
+
+if not isinstance(state, dict) or not isinstance(meta, dict):
+    raise SystemExit(1)
+
+completed = state.get("completedStages")
+if not isinstance(completed, list):
+    completed = []
+completed = [stage for stage in completed if isinstance(stage, str)]
+
+guard_evidence = state.get("guardEvidence")
+if not isinstance(guard_evidence, dict):
+    guard_evidence = {}
+guard_evidence = {k: v for k, v in guard_evidence.items() if isinstance(k, str) and isinstance(v, str)}
+
+stage_gate_catalog = state.get("stageGateCatalog")
+if not isinstance(stage_gate_catalog, dict):
+    stage_gate_catalog = {}
+
+snapshot = {
+    "currentStage": state.get("currentStage") if isinstance(state.get("currentStage"), str) else "brainstorm",
+    "completedStages": completed,
+    "guardEvidence": guard_evidence,
+    "stageGateCatalog": stage_gate_catalog,
+}
+meta["stateSnapshot"] = snapshot
+Path(run_meta_path).write_text(json.dumps(meta, indent=2) + "\\n", encoding="utf-8")
+
+title = meta.get("title") if isinstance(meta.get("title"), str) and meta.get("title") else active_run
+created_at = meta.get("createdAt") if isinstance(meta.get("createdAt"), str) and meta.get("createdAt") else "unknown"
+archived_at = meta.get("archivedAt") if isinstance(meta.get("archivedAt"), str) and meta.get("archivedAt") else None
+completed_display = ", ".join(completed) if completed else "(none)"
+
+handoff_lines = [
+    "# Run Handoff",
+    "",
+    f"- ID: {active_run}",
+    f"- Title: {title}",
+    f"- Created: {created_at}",
+    f"- Archived: {archived_at if archived_at else 'active'}",
+    "",
+    "## Flow Snapshot",
+    f"- Active stage: {snapshot['currentStage']}",
+    f"- Completed stages: {completed_display}",
+    f"- Active run ID in flow-state: {state.get('activeRunId') if isinstance(state.get('activeRunId'), str) else active_run}",
+    "",
+    "## Paths",
+    f"- Active artifacts: ${RUNTIME_ROOT}/artifacts/",
+    f"- Run artifacts snapshot: ${RUNTIME_ROOT}/runs/{active_run}/artifacts/",
+    f"- Flow state: ${RUNTIME_ROOT}/state/flow-state.json",
+    "",
+    "## Resume",
+    "1. Open ${RUNTIME_ROOT}/state/flow-state.json and verify current stage.",
+    "2. Review ${RUNTIME_ROOT}/artifacts/ for the latest working artifacts.",
+    "3. Continue using /cc or /cc-next from the current stage.",
+    "",
+    f"- Last updated: {timestamp}",
+]
+Path(handoff_path).write_text("\\n".join(handoff_lines) + "\\n", encoding="utf-8")
+PY
+    then
+      RUN_SYNC_NOTE="Run metadata synchronized for $ACTIVE_RUN."
+    else
+      RUN_SYNC_NOTE="Run metadata sync failed for $ACTIVE_RUN."
+    fi
+  fi
+fi
+
 # --- Escape for JSON ---
 ${ESCAPE_FN}
-MSG=$(escape_json "Cclaw: session ending (stage=$STAGE, run=$ACTIVE_RUN). $CHECKPOINT_NOTE Before stopping: (1) confirm flow-state reflects reality, (2) ensure artifact changes match active run intent, (3) log reusable learnings, (4) commit or revert pending changes.")
+MSG=$(escape_json "Cclaw: session ending (stage=$STAGE, run=$ACTIVE_RUN). $CHECKPOINT_NOTE $RUN_SYNC_NOTE Before stopping: (1) confirm flow-state reflects reality, (2) ensure artifact changes match active run intent, (3) log reusable learnings, (4) commit or revert pending changes.")
 
 # --- Output harness-specific JSON ---
 case "$HARNESS" in
@@ -1078,6 +1167,14 @@ export default function cclawPlugin(ctx) {
       payload?.command,
       payload?.tool?.name,
       payload?.tool?.id,
+      payload?.input?.tool,
+      payload?.input?.toolName,
+      payload?.input?.tool_name,
+      payload?.input?.name,
+      payload?.input?.id,
+      payload?.input?.command,
+      payload?.input?.tool?.name,
+      payload?.input?.tool?.id
     ];
     for (const value of candidates) {
       if (typeof value === "string" && value.trim()) return value.trim();
@@ -1085,6 +1182,36 @@ export default function cclawPlugin(ctx) {
     return "unknown";
   }
 
+  function normalizeToolPayload(input, output) {
+    if (typeof output === "undefined") {
+      return input ?? {};
+    }
+    return {
+      input: input ?? {},
+      output: output ?? {}
+    };
+  }
+
+  function resolveEventType(payload) {
+    if (typeof payload === "string") return payload;
+    if (payload && typeof payload === "object") {
+      if (typeof payload.type === "string") return payload.type;
+      if (typeof payload.name === "string") return payload.name;
+      if (payload.event && typeof payload.event === "object") {
+        if (typeof payload.event.type === "string") return payload.event.type;
+        if (typeof payload.event.name === "string") return payload.event.name;
+      }
+    }
+    return "";
+  }
+
+  function resolveEventData(payload) {
+    if (payload && typeof payload === "object" && payload.event && typeof payload.event === "object") {
+      return payload.event;
+    }
+    return payload;
+  }
+
   function appendJsonLine(filePath, value) {
     try {
       appendFileSync(filePath, JSON.stringify(value) + "\\n", "utf8");
@@ -1120,28 +1247,43 @@ export default function cclawPlugin(ctx) {
   }
 
   return {
-    event: async (name, data) => {
-      if (name === "session.created" || name === "session.resumed" || name === "session.compacted" || name === "session.cleared") {
+    event: async (payload) => {
+      const eventType = resolveEventType(payload);
+      const eventData = resolveEventData(payload);
+      if (eventType === "session.created" || eventType === "session.resumed" || eventType === "session.compacted" || eventType === "session.cleared") {
         emitBootstrap();
       }
-      if (name === "session.updated") {
+      if (eventType === "session.updated") {
         // no-op: tracked via activity log
       }
-      if (name === "session.idle") {
+      if (eventType === "session.idle") {
         if (!observationEnabled()) return;
         await runHookScript("summarize-observations.sh");
         await runHookScript("stop-checkpoint.sh", { loop_count: 0 });
       }
-      if (name === "tool.execute.before") {
-        await runHookScript("prompt-guard.sh", data ?? {});
-        await runHookScript("workflow-guard.sh", data ?? {});
-        recordToolEvent("pre", data);
+      if (eventType === "tool.execute.before") {
+        const toolPayload = normalizeToolPayload(eventData, undefined);
+        await runHookScript("prompt-guard.sh", toolPayload);
+        await runHookScript("workflow-guard.sh", toolPayload);
+        recordToolEvent("pre", toolPayload);
       }
-      if (name === "tool.execute.after") {
-        await runHookScript("context-monitor.sh", data ?? {});
-        recordToolEvent("post", data);
+      if (eventType === "tool.execute.after") {
+        const toolPayload = normalizeToolPayload(eventData, undefined);
+        await runHookScript("context-monitor.sh", toolPayload);
+        recordToolEvent("post", toolPayload);
       }
     },
+    "tool.execute.before": async (input, output) => {
+      const payload = normalizeToolPayload(input, output);
+      await runHookScript("prompt-guard.sh", payload);
+      await runHookScript("workflow-guard.sh", payload);
+      recordToolEvent("pre", payload);
+    },
+    "tool.execute.after": async (input, output) => {
+      const payload = normalizeToolPayload(input, output);
+      await runHookScript("context-monitor.sh", payload);
+      recordToolEvent("post", payload);
+    },
     "experimental.chat.system.transform": (payload) => {
       const bootstrap = buildBootstrap();
       if (typeof payload === "string") {

package/dist/content/meta-skill.js

@@ -47,7 +47,7 @@ Before starting work, ALWAYS:
 2. **Stages are workflows, not suggestions.** Follow the skill steps in order. Do not skip verification steps.
 3. **One stage at a time.** Complete the current stage before advancing to the next.
 4. **Gates must pass.** Every stage has required gates — the agent cannot claim completion without satisfying them.
-5. **Artifacts are mandatory.** Each stage writes to \`.cclaw/artifacts/\` and keeps the active run copy in \`.cclaw/runs/<activeRunId>/artifacts/\` — this is the evidence trail.
+5. **Artifacts are mandatory.** Each stage writes to \`.cclaw/artifacts/\`; cclaw sync/runtime keeps run snapshots in \`.cclaw/runs/<activeRunId>/artifacts/\` aligned as the evidence trail.
 6. **When in doubt, use \`/cc\`.** If the task is non-trivial and there's no prior artifact, run \`/cc <idea>\` to start brainstorming.
 
 ## Stage Quick Reference

package/dist/content/observe.js

@@ -39,7 +39,7 @@ INPUT=$(cat 2>/dev/null || echo '{}')
 TOOL="unknown"
 PAYLOAD=""
 if command -v jq >/dev/null 2>&1; then
-  TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // .tool // "unknown"' 2>/dev/null || echo "unknown")
+  TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // .tool // .toolName // .name // .id // .command // .tool.name // .tool.id // .input.tool_name // .input.tool // .input.toolName // .input.name // .input.id // .input.command // .input.tool.name // .input.tool.id // "unknown"' 2>/dev/null || echo "unknown")
   PAYLOAD=$(printf '%s' "$INPUT" | jq -r '.tool_input // .input // .arguments // .params // .payload // {} | tostring' 2>/dev/null || echo "")
 elif command -v python3 >/dev/null 2>&1; then
   TOOL=$(INPUT_JSON="$INPUT" python3 - <<'PY'
@@ -50,8 +50,40 @@ try:
     value = json.loads(os.environ.get("INPUT_JSON", "{}"))
 except Exception:
     value = {}
-tool = value.get("tool_name") or value.get("tool") or "unknown"
-print(tool if isinstance(tool, str) else "unknown")
+
+def pick_tool(payload):
+    if not isinstance(payload, dict):
+        return "unknown"
+    candidates = [
+        payload.get("tool_name"),
+        payload.get("tool"),
+        payload.get("toolName"),
+        payload.get("name"),
+        payload.get("id"),
+        payload.get("command")
+    ]
+    top_tool = payload.get("tool")
+    if isinstance(top_tool, dict):
+        candidates.extend([top_tool.get("name"), top_tool.get("id")])
+    nested = payload.get("input")
+    if isinstance(nested, dict):
+        candidates.extend([
+            nested.get("tool_name"),
+            nested.get("tool"),
+            nested.get("toolName"),
+            nested.get("name"),
+            nested.get("id"),
+            nested.get("command")
+        ])
+        nested_tool = nested.get("tool")
+        if isinstance(nested_tool, dict):
+            candidates.extend([nested_tool.get("name"), nested_tool.get("id")])
+    for candidate in candidates:
+        if isinstance(candidate, str) and candidate.strip():
+            return candidate.strip()
+    return "unknown"
+
+print(pick_tool(value))
 PY
 )
   PAYLOAD=$(printf '%s' "$INPUT")
@@ -146,7 +178,7 @@ INPUT=$(cat 2>/dev/null || echo '{}')
 TOOL="unknown"
 PAYLOAD=""
 if command -v jq >/dev/null 2>&1; then
-  TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // .tool // "unknown"' 2>/dev/null || echo "unknown")
+  TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // .tool // .toolName // .name // .id // .command // .tool.name // .tool.id // .input.tool_name // .input.tool // .input.toolName // .input.name // .input.id // .input.command // .input.tool.name // .input.tool.id // "unknown"' 2>/dev/null || echo "unknown")
   PAYLOAD=$(printf '%s' "$INPUT" | jq -r '.tool_input // .input // .arguments // .params // .payload // {} | tostring' 2>/dev/null || echo "")
 elif command -v python3 >/dev/null 2>&1; then
   TOOL=$(INPUT_JSON="$INPUT" python3 - <<'PY'
@@ -156,8 +188,40 @@ try:
     value = json.loads(os.environ.get("INPUT_JSON", "{}"))
 except Exception:
     value = {}
-tool = value.get("tool_name") or value.get("tool") or "unknown"
-print(tool if isinstance(tool, str) else "unknown")
+
+def pick_tool(payload):
+    if not isinstance(payload, dict):
+        return "unknown"
+    candidates = [
+        payload.get("tool_name"),
+        payload.get("tool"),
+        payload.get("toolName"),
+        payload.get("name"),
+        payload.get("id"),
+        payload.get("command")
+    ]
+    top_tool = payload.get("tool")
+    if isinstance(top_tool, dict):
+        candidates.extend([top_tool.get("name"), top_tool.get("id")])
+    nested = payload.get("input")
+    if isinstance(nested, dict):
+        candidates.extend([
+            nested.get("tool_name"),
+            nested.get("tool"),
+            nested.get("toolName"),
+            nested.get("name"),
+            nested.get("id"),
+            nested.get("command")
+        ])
+        nested_tool = nested.get("tool")
+        if isinstance(nested_tool, dict):
+            candidates.extend([nested_tool.get("name"), nested_tool.get("id")])
+    for candidate in candidates:
+        if isinstance(candidate, str) and candidate.strip():
+            return candidate.strip()
+    return "unknown"
+
+print(pick_tool(value))
 PY
 )
   PAYLOAD=$(printf '%s' "$INPUT")
@@ -527,7 +591,7 @@ INPUT=$(cat 2>/dev/null || echo '{}')
 TOOL="unknown"
 PAYLOAD=""
 if command -v jq >/dev/null 2>&1; then
-  TOOL=$(echo "$INPUT" | jq -r '.tool_name // .tool // "unknown"' 2>/dev/null || echo "unknown")
+  TOOL=$(echo "$INPUT" | jq -r '.tool_name // .tool // .toolName // .name // .id // .command // .tool.name // .tool.id // .input.tool_name // .input.tool // .input.toolName // .input.name // .input.id // .input.command // .input.tool.name // .input.tool.id // "unknown"' 2>/dev/null || echo "unknown")
   if [ "$PHASE" = "pre" ]; then
     PAYLOAD=$(echo "$INPUT" | jq -r --arg max "$MAX_LEN" '.tool_input // .input // {} | tostring | .[0:($max|tonumber)]' 2>/dev/null || echo "")
   else

package/dist/content/skills.js

@@ -174,7 +174,7 @@ When all required gates are satisfied and the artifact is written:
 1. **Update \`${RUNTIME_ROOT}/state/flow-state.json\`:**
 ${stateUpdate}
    - For each passed gate, add an entry to \`guardEvidence\`: \`"<gate_id>": "<artifact path or excerpt proving the gate>"\`. Do NOT leave \`guardEvidence\` empty.
-2. **Sync artifact** to \`${RUNTIME_ROOT}/runs/<activeRunId>/artifacts/${schema.artifactFile}\`
+2. **Persist artifact** at \`${RUNTIME_ROOT}/artifacts/${schema.artifactFile}\`. Do NOT manually copy into run directories; cclaw sync/runtime keeps \`${RUNTIME_ROOT}/runs/<activeRunId>/artifacts/\` aligned.
 ${nextAction}
 
 **STOP.** Do not load the next stage skill yourself. The user will run \`/cc-next\` when ready (same session or new session).
@@ -287,7 +287,7 @@ function quickStartBlock(stage) {
 
 > **Even if you read nothing else, do these 3 things:**
 > 1. Obey the HARD-GATE below — violating it invalidates the entire stage.
-> 2. Complete every checklist step in order and write the artifact to \`.cclaw/artifacts/${schema.artifactFile}\` (canonical run copy: \`.cclaw/runs/<activeRunId>/artifacts/${schema.artifactFile}\`).
+> 2. Complete every checklist step in order and write the artifact to \`.cclaw/artifacts/${schema.artifactFile}\`. Run snapshots in \`.cclaw/runs/<activeRunId>/artifacts/\` are synchronized by cclaw runtime.
 > 3. Do not claim completion without satisfying gates: ${topGates}${schema.requiredGates.length > 3 ? ` (+${schema.requiredGates.length - 3} more)` : ""}.
 >
 > **After this stage:** update \`flow-state.json\` and tell the user to run \`/cc-next\`.
@@ -385,7 +385,7 @@ ${progressiveDisclosureBlock(stage)}
 ${selfImprovementBlock(stage)}
 ## Handoff
 - Next command: \`/cc-next\` (loads whatever stage is current in flow-state)
-- Required artifact: \`.cclaw/artifacts/${schema.artifactFile}\` (canonical: \`.cclaw/runs/<activeRunId>/artifacts/${schema.artifactFile}\`)
+- Required artifact: \`.cclaw/artifacts/${schema.artifactFile}\` (run snapshot at \`.cclaw/runs/<activeRunId>/artifacts/${schema.artifactFile}\`, synchronized by cclaw runtime)
 - Stage stays blocked if any required gate is unsatisfied
 `;
 }

package/dist/content/stage-schema.js

@@ -38,8 +38,9 @@ const BRAINSTORM = {
     checklist: [
         "Explore project context — check files, docs, recent commits, existing behavior. Summarize what you found (even for seemingly simple projects).",
         "Assess scope — if the request describes multiple independent subsystems, flag for decomposition before detailed questions.",
-        "Restate the problem — in a SEPARATE message (no questions in this message), summarize what you understood the user wants and why. **STOP and wait** for user to confirm or correct before asking any clarifying questions.",
-        "Ask clarifying questions — one at a time, one per message. You MUST cover these categories before proposing approaches: (a) PURPOSE — why this project exists, who it serves; (b) SCOPE — what it must do, what it must NOT do; (c) BOUNDARIES — error handling, edge cases, failure modes; (d) ENVIRONMENT — how it runs, deploys, installs; (e) CONSTRAINTS — performance, compatibility, dependencies. Skip a category only if the user already provided that info. Do NOT rush — 3 generic questions are never enough for a non-trivial project.",
+        "Restate the problem — in a SEPARATE message (no questions in this message), summarize what you understood the user wants and why. The restatement message must contain zero clarifying questions and no option prompts. **STOP and wait** for user to confirm or correct before asking any clarifying questions.",
+        "Ask clarifying questions — one at a time, one per message. Each clarification message must ask exactly one decision-seeking question (no bundled sub-questions). You MUST cover these categories before proposing approaches: (a) PURPOSE — why this project exists, who it serves; (b) SCOPE — what it must do, what it must NOT do; (c) BOUNDARIES — error handling, edge cases, failure modes; (d) ENVIRONMENT — how it runs, deploys, installs; (e) CONSTRAINTS — performance, compatibility, dependencies. Skip a category only if the user already provided that info. If user answers 'I don't know' / 'не знаю', convert it into explicit assumptions and ask for confirmation before moving on. Do NOT rush — 3 generic questions are never enough for a non-trivial project.",
+        "Before proposing approaches, perform at least one premise-challenge question (\"Is this the right problem framing?\") and at least one boundary stress-test question (\"What should never happen even on failure?\").",
         "Propose 2-3 approaches — with real trade-offs (not cosmetic differences) and your explicit recommendation with reasoning. Explain WHY you recommend this option over others.",
         "Present design — in sections. After each section, explicitly state what you are asking the user to approve: 'Do you approve [specific thing]?' Never ask a bare 'одобряете?/approve?' without context.",
         "Write design doc — save to `.cclaw/artifacts/01-brainstorm.md`.",
@@ -49,8 +50,11 @@ const BRAINSTORM = {
     ],
     interactionProtocol: [
         "Explore context first (files, docs, existing behavior). Share a brief summary of what you found.",
-        "Restate the problem in your own words in a SEPARATE message. Do NOT add any questions to this message. Wait for user to confirm or correct.",
+        "Restate the problem in your own words in a SEPARATE message. Do NOT add any questions, options, or approval asks to this message. Wait for user to confirm or correct.",
         "Ask clarifying questions — one per message. Cover mandatory categories: PURPOSE, SCOPE, BOUNDARIES, ENVIRONMENT, CONSTRAINTS. Do NOT combine questions. Do NOT propose approaches until all categories are addressed.",
+        "Do not package multiple asks as bullet points in one message; split them into separate turns even if related.",
+        "When user answer is ambiguous or unknown (for example: 'не знаю'), propose explicit defaults as assumptions and get a one-message confirmation before treating that category as closed.",
+        "Include at least one premise-challenge and one boundary stress-test question before locking options. Do not accept 'simple demo' framing without challenge.",
         "For approach selection: use the Decision Protocol — present labeled options (A/B/C) with REAL trade-offs (not cosmetic) and mark one as (recommended) with clear reasoning. If AskQuestion/AskUserQuestion is available, send exactly ONE question per call, validate fields against runtime schema, and on schema error immediately fall back to plain-text question instead of retrying guessed payloads.",
         "Every approval question MUST state what exactly is being approved: 'Do you approve [the architecture / the API shape / the dependency choice]?' Never ask a bare 'approve?' or 'looks good?'.",
         "Get section-by-section approval before finalizing the design direction.",
@@ -59,8 +63,9 @@ const BRAINSTORM = {
     ],
     process: [
         "Explore project context — files, docs, behavior, recent changes. Share findings.",
-        "Restate the problem — summarize what the user wants and why in a SEPARATE message. Wait for confirmation before questions.",
+        "Restate the problem — summarize what the user wants and why in a SEPARATE message. Keep this message declarative only; no questions. Wait for confirmation before questions.",
         "Clarify iteratively — ask questions one at a time covering mandatory categories: PURPOSE, SCOPE, BOUNDARIES, ENVIRONMENT, CONSTRAINTS. Do not skip to approaches early.",
+        "Convert unknown answers into explicit assumptions and confirm them before approaches.",
         "Identify whether request should be decomposed into smaller sub-problems.",
         "Offer 2-3 alternatives with real trade-offs and recommendation with rationale.",
         "Present design in sections. After each section explicitly name what you ask the user to approve.",
@@ -70,8 +75,15 @@ const BRAINSTORM = {
         "Handoff to scope stage only after approval is explicit."
     ],
     requiredGates: [
-        { id: "brainstorm_context_explored", description: "Project context and constraints have been reviewed and summarized." },
-        { id: "brainstorm_problem_restated", description: "Problem was restated in agent's words and user confirmed the understanding." },
+        { id: "brainstorm_discovery_purpose", description: "Discovery captured WHY this project exists and WHO it serves, with explicit user confirmation." },
+        { id: "brainstorm_discovery_scope", description: "Discovery captured explicit in-scope and out-of-scope boundaries before approach selection." },
+        { id: "brainstorm_discovery_boundaries", description: "Discovery captured failure modes, edge cases, and error-handling boundaries." },
+        { id: "brainstorm_discovery_environment", description: "Discovery captured runtime/install/deployment environment assumptions." },
+        { id: "brainstorm_discovery_constraints", description: "Discovery captured constraints (performance, compatibility, dependency limits) before deciding architecture." },
+        {
+            id: "brainstorm_problem_restated",
+            description: "Problem was restated in agent's words in a standalone non-question message, and user confirmed the understanding."
+        },
         { id: "brainstorm_options_compared", description: "At least two alternatives were compared with real trade-offs." },
         { id: "brainstorm_design_approved", description: "User approved a concrete design direction (with explicit statement of what was approved)." },
         { id: "brainstorm_self_review_passed", description: "Design doc passed placeholder/ambiguity/consistency checks." },
@@ -79,7 +91,13 @@ const BRAINSTORM = {
     ],
     requiredEvidence: [
         "Artifact written to `.cclaw/artifacts/01-brainstorm.md`.",
+        "Clarification log explicitly records PURPOSE, SCOPE, BOUNDARIES, ENVIRONMENT, and CONSTRAINTS coverage.",
+        "Clarification sequence evidence shows one explicit question per message (no bundled multi-question turns).",
+        "Clarification log includes at least one premise-challenge question and one boundary stress-test question before approach selection.",
+        "Unknown or ambiguous user answers are converted into explicit assumptions and confirmed (or explicitly waived) before closure.",
+        "Discovery sections include explicit in-scope/out-of-scope boundaries and failure handling boundaries.",
         "Approved direction captured in artifact.",
+        "Restatement evidence shows a standalone non-question restatement message before clarification Q&A.",
         "Open questions explicitly listed (if any).",
         "Self-review pass completed with no unresolved issues."
     ],
@@ -111,6 +129,10 @@ const BRAINSTORM = {
         "Jumping directly into implementation",
         "Combining visual companion offer with a clarifying question",
         "Invoking implementation skills before writing plans",
+        "Appending clarifying questions to the restatement message instead of waiting for confirmation",
+        "Packing multiple clarifying questions into one message (including bullet-list question bundles)",
+        "Silently filling defaults after 'не знаю'/'I don't know' without explicit assumption confirmation",
+        "Accepting 'simple/test/demo' framing without premise challenge or failure stress testing",
         "Asking bare 'approve?' or 'одобряете?' without stating WHAT is being approved",
         "Presenting a single summary and asking for blanket approval instead of section-by-section review",
         "Rushing through clarification — asking 1-2 generic questions then jumping to design",
@@ -129,6 +151,10 @@ const BRAINSTORM = {
         "Implementation-related actions before approval",
         "Self-review skipped or glossed over",
         "Artifact has TBD or placeholder sections",
+        "Restatement step includes clarifying questions or option prompts",
+        "Clarification turns repeatedly include multi-question bundles instead of single asks",
+        "Unknown user answers are treated as settled requirements without explicit assumption confirmation",
+        "No evidence of premise challenge or failure stress-test questions before options",
         "Fewer than 3 clarifying questions asked for any non-trivial project",
         "Approval requested without stating what exactly is being approved"
     ],
@@ -155,8 +181,18 @@ const BRAINSTORM = {
         traceabilityRule: "Every approved direction must be traceable forward through scope and design. Downstream stages must reference brainstorm decisions."
     },
     artifactValidation: [
-        { section: "Problem Statement", required: true, validationRule: "Must describe the user problem, not the solution. Include WHO and WHY." },
+        { section: "Problem Statement", required: true, validationRule: "Must describe the user problem, not the solution. Include WHO and WHY and success signal." },
         { section: "Known Context", required: true, validationRule: "Files, patterns, constraints discovered during exploration. Evidence that context was actually explored." },
+        {
+            section: "Clarification Log",
+            required: true,
+            validationRule: "At least 5 rows covering PURPOSE, SCOPE, BOUNDARIES, ENVIRONMENT, CONSTRAINTS. Table must use 4 columns: Category, Question asked, User answer, Evidence note."
+        },
+        { section: "Purpose & Beneficiaries", required: true, validationRule: "At least 3 meaningful lines describing why this exists and who benefits." },
+        { section: "Scope Boundaries", required: true, validationRule: "At least 2 scope items including explicit out-of-scope boundaries." },
+        { section: "Failure Boundaries", required: true, validationRule: "At least 2 failure/edge-case expectations and error visibility behavior." },
+        { section: "Runtime Environment", required: true, validationRule: "At least 2 lines describing runtime, install/distribution, and execution environment." },
+        { section: "Constraints", required: true, validationRule: "At least 2 concrete constraints (performance, compatibility, dependency, or policy)." },
         { section: "Alternatives Table", required: true, validationRule: "At least 2 approaches with real trade-offs (not cosmetic) and recommendation with reasoning." },
         { section: "Approved Direction", required: true, validationRule: "Must contain explicit approval marker from user. State what was approved." },
         { section: "Assumptions & Risks", required: true, validationRule: "Explicit assumptions made during design. Known risks. If none, state 'None'." },

package/dist/content/templates.d.ts

@@ -1,4 +1,4 @@
 export declare const ARTIFACT_TEMPLATES: Record<string, string>;
 export declare const RULEBOOK_MARKDOWN = "# Cclaw Rulebook\n\n## MUST_ALWAYS\n- Follow flow order: brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship\n- Require explicit user confirmation after plan before TDD\n- Keep evidence artifacts in `.cclaw/artifacts/`\n- Enforce RED before GREEN in TDD\n- Run two-layer review (spec_compliance and code_quality) before ship\n- Validate all inputs before processing \u2014 never trust external data without sanitization\n- Prefer immutable data patterns and pure functions where the language supports them\n- Follow existing repo conventions, patterns, and directory structure \u2014 match the codebase\n- Verify claims with fresh evidence: \"tests pass\" requires running tests in this message\n- Use conventional commits: `type(scope): description` (feat, fix, refactor, test, docs, chore)\n\n## MUST_NEVER\n- Skip RED phase and jump directly to GREEN in TDD\n- Ship with critical review findings\n- Start implementation during /brainstorm\n- Modify generated cclaw files manually when CLI can regenerate them\n- Commit `.cclaw/` or generated shim files\n- Expose secrets, tokens, API keys, or absolute system paths in agent output\n- Duplicate existing functionality without explicit justification \u2014 search before building\n- Bypass security checks, linting hooks, or type checking to \"move faster\"\n- Claim success (\"Done,\" \"All good,\" \"Tests pass\") without running verification in this message\n- Make changes outside the blast radius of the current task without user consent\n\n## DELEGATION\nWhen a task requires specialist knowledge (security audit, performance profiling, database review),\ndelegate to a specialized agent or skill if the harness supports it. The primary agent should:\n1. Identify the specialist domain\n2. Provide focused context (relevant files, the specific concern)\n3. Evaluate the specialist output before acting on it \u2014 do not blindly apply recommendations\n";
-export declare const CURSOR_WORKFLOW_RULE_MDC = "---\ndescription: cclaw workflow guardrails for Cursor agent sessions\nglobs:\n  - \"**/*\"\nalwaysApply: true\n---\n\n<!-- cclaw-managed-cursor-workflow-rule -->\n\n# Cclaw Workflow Guardrails\n\n- Follow stage order: brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship.\n- Read `.cclaw/state/flow-state.json` before acting; continue from current stage when active.\n- Use `/cc-next` only after required gates pass; never bypass explicit pause/approval rules.\n- Keep evidence in `.cclaw/artifacts/` and canonical run copies in `.cclaw/runs/<activeRunId>/artifacts/`.\n- For machine-only checks in design/plan/tdd/review/ship, dispatch required specialists automatically when tooling supports it.\n- Ask for user input only at explicit approval gates (scope mode, plan approval, user challenge resolution, ship finalization).\n- Treat `.cclaw/skills/using-cclaw/SKILL.md` as routing source of truth; load contextual utility skills only when their triggers apply.\n";
+export declare const CURSOR_WORKFLOW_RULE_MDC = "---\ndescription: cclaw workflow guardrails for Cursor agent sessions\nglobs:\n  - \"**/*\"\nalwaysApply: true\n---\n\n<!-- cclaw-managed-cursor-workflow-rule -->\n\n# Cclaw Workflow Guardrails\n\n- Follow stage order: brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship.\n- Read `.cclaw/state/flow-state.json` before acting; continue from current stage when active.\n- Use `/cc-next` only after required gates pass; never bypass explicit pause/approval rules.\n- Keep evidence in `.cclaw/artifacts/`; cclaw sync/runtime maintains run snapshots in `.cclaw/runs/<activeRunId>/artifacts/`.\n- For machine-only checks in design/plan/tdd/review/ship, dispatch required specialists automatically when tooling supports it.\n- Ask for user input only at explicit approval gates (scope mode, plan approval, user challenge resolution, ship finalization).\n- Treat `.cclaw/skills/using-cclaw/SKILL.md` as routing source of truth; load contextual utility skills only when their triggers apply.\n";
 export declare function buildRulesJson(): Record<string, unknown>;

package/dist/content/templates.js

@@ -8,13 +8,48 @@ export const ARTIFACT_TEMPLATES = {
 - **Who benefits:**
 - **Why now:**
 - **Success signal:**
-- **Constraints:**
 
 ## Known Context
 - **Explored files/patterns:**
 - **Existing behavior:**
 - **Relevant dependencies:**
 
+## Clarification Log
+| Category | Question asked | User answer | Evidence note |
+|---|---|---|---|
+| PURPOSE |  |  |  |
+| SCOPE |  |  |  |
+| BOUNDARIES |  |  |  |
+| ENVIRONMENT |  |  |  |
+| CONSTRAINTS |  |  |  |
+
+## Purpose & Beneficiaries
+- **Project purpose:**
+- **Primary users:**
+- **Value outcome:**
+
+## Scope Boundaries
+### In Scope
+- 
+
+### Out of Scope
+- 
+
+## Failure Boundaries
+- **Edge cases to handle:**
+- **Expected failures and behavior:**
+- **Error visibility expectations:**
+
+## Runtime Environment
+- **Runtime/platform:**
+- **Install/distribution model:**
+- **Execution context (local/CI/deploy):**
+
+## Constraints
+- **Performance constraints:**
+- **Compatibility constraints:**
+- **Dependency constraints:**
+
 ## Alternatives Table
 | Option | Summary | Trade-offs | Recommendation |
 |---|---|---|---|
@@ -347,7 +382,7 @@ alwaysApply: true
 - Follow stage order: brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship.
 - Read \`.cclaw/state/flow-state.json\` before acting; continue from current stage when active.
 - Use \`/cc-next\` only after required gates pass; never bypass explicit pause/approval rules.
-- Keep evidence in \`.cclaw/artifacts/\` and canonical run copies in \`.cclaw/runs/<activeRunId>/artifacts/\`.
+- Keep evidence in \`.cclaw/artifacts/\`; cclaw sync/runtime maintains run snapshots in \`.cclaw/runs/<activeRunId>/artifacts/\`.
 - For machine-only checks in design/plan/tdd/review/ship, dispatch required specialists automatically when tooling supports it.
 - Ask for user input only at explicit approval gates (scope mode, plan approval, user challenge resolution, ship finalization).
 - Treat \`.cclaw/skills/using-cclaw/SKILL.md\` as routing source of truth; load contextual utility skills only when their triggers apply.

package/dist/doctor.js

@@ -1,6 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { execFile } from "node:child_process";
+import { pathToFileURL } from "node:url";
 import { promisify } from "node:util";
 import { COMMAND_FILE_ORDER, REQUIRED_DIRS, RUNTIME_ROOT } from "./constants.js";
 import { CCLAW_AGENTS } from "./content/agents.js";
@@ -186,6 +187,47 @@ async function opencodeRegistrationCheck(projectRoot) {
     }
     return { ok: false, details: `No opencode.json/opencode.jsonc found with plugin ${expected}` };
 }
+async function opencodePluginRuntimeShapeCheck(projectRoot) {
+    const pluginPath = path.join(projectRoot, ".opencode/plugins/cclaw-plugin.mjs");
+    if (!(await exists(pluginPath))) {
+        return { ok: false, details: `${path.relative(projectRoot, pluginPath)} not found` };
+    }
+    try {
+        const moduleUrl = `${pathToFileURL(pluginPath).href}?doctor=${Date.now()}`;
+        const imported = await import(moduleUrl);
+        if (typeof imported.default !== "function") {
+            return {
+                ok: false,
+                details: `${path.relative(projectRoot, pluginPath)} must export a default plugin factory function`
+            };
+        }
+        const plugin = imported.default({ directory: projectRoot });
+        const requiredHandlers = [
+            "event",
+            "tool.execute.before",
+            "tool.execute.after",
+            "experimental.chat.system.transform"
+        ];
+        const missing = requiredHandlers.filter((name) => typeof plugin?.[name] !== "function");
+        if (missing.length > 0) {
+            return {
+                ok: false,
+                details: `${path.relative(projectRoot, pluginPath)} missing runtime handlers: ${missing.join(", ")}`
+            };
+        }
+        await plugin.event({ event: { type: "session.updated", data: {} } });
+        return {
+            ok: true,
+            details: `${path.relative(projectRoot, pluginPath)} exports compatible runtime handler shape`
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            details: `runtime load failed for .opencode/plugins/cclaw-plugin.mjs: ${error instanceof Error ? error.message : String(error)}`
+        };
+    }
+}
 export async function doctorChecks(projectRoot, options = {}) {
     const checks = [];
     for (const dir of REQUIRED_DIRS) {
@@ -595,6 +637,12 @@ export async function doctorChecks(projectRoot, options = {}) {
             ok,
             details: `${file} must include event lifecycle handler, tool.execute.before/after with prompt/workflow/context hooks, session.idle summarization, and transform rehydration`
         });
+        const runtimeShape = await opencodePluginRuntimeShapeCheck(projectRoot);
+        checks.push({
+            name: "hook:opencode:runtime_shape",
+            ok: runtimeShape.ok,
+            details: runtimeShape.details
+        });
         const registration = await opencodeRegistrationCheck(projectRoot);
         checks.push({
             name: "hook:opencode:config_registration",
@@ -702,25 +750,39 @@ export async function doctorChecks(projectRoot, options = {}) {
                 : `no gate reconciliation changes needed for stage "${reconciliation.stage}"`
         });
     }
+    const activeRunId = typeof flowState.activeRunId === "string" ? flowState.activeRunId.trim() : "";
+    const runActivationDeferred = activeRunId === "run-pending";
     checks.push({
         name: "flow_state:active_run_id",
-        ok: typeof flowState.activeRunId === "string" && flowState.activeRunId.trim().length > 0,
-        details: `${RUNTIME_ROOT}/state/flow-state.json must include activeRunId`
+        ok: activeRunId.length > 0,
+        details: `${RUNTIME_ROOT}/state/flow-state.json must include activeRunId (run-pending is allowed before first active run is materialized)`
     });
     checks.push({
         name: "run:active_artifacts",
-        ok: await exists(path.join(projectRoot, RUNTIME_ROOT, "runs", flowState.activeRunId, "artifacts")),
-        details: `${RUNTIME_ROOT}/runs/${flowState.activeRunId}/artifacts must exist`
+        ok: runActivationDeferred
+            ? true
+            : await exists(path.join(projectRoot, RUNTIME_ROOT, "runs", activeRunId, "artifacts")),
+        details: runActivationDeferred
+            ? "active run artifacts are deferred until first feature run activation"
+            : `${RUNTIME_ROOT}/runs/${activeRunId}/artifacts must exist`
     });
     checks.push({
         name: "run:active_metadata",
-        ok: await exists(path.join(projectRoot, RUNTIME_ROOT, "runs", flowState.activeRunId, "run.json")),
-        details: `${RUNTIME_ROOT}/runs/${flowState.activeRunId}/run.json must exist`
+        ok: runActivationDeferred
+            ? true
+            : await exists(path.join(projectRoot, RUNTIME_ROOT, "runs", activeRunId, "run.json")),
+        details: runActivationDeferred
+            ? "active run metadata is deferred until first feature run activation"
+            : `${RUNTIME_ROOT}/runs/${activeRunId}/run.json must exist`
     });
     checks.push({
         name: "run:active_handoff",
-        ok: await exists(path.join(projectRoot, RUNTIME_ROOT, "runs", flowState.activeRunId, "00-handoff.md")),
-        details: `${RUNTIME_ROOT}/runs/${flowState.activeRunId}/00-handoff.md must exist`
+        ok: runActivationDeferred
+            ? true
+            : await exists(path.join(projectRoot, RUNTIME_ROOT, "runs", activeRunId, "handoff.md")),
+        details: runActivationDeferred
+            ? "active run handoff is deferred until first feature run activation"
+            : `${RUNTIME_ROOT}/runs/${activeRunId}/handoff.md must exist`
     });
     const delegation = await checkMandatoryDelegations(projectRoot, flowState.currentStage);
     checks.push({

package/dist/install.js

@@ -766,7 +766,7 @@ async function materializeRuntime(projectRoot, config, forceStateReset) {
     await writeArtifactTemplates(projectRoot);
     await writeRulebook(projectRoot);
     await writeState(projectRoot, forceStateReset);
-    await ensureRunSystem(projectRoot);
+    await ensureRunSystem(projectRoot, { createIfMissing: false });
     await ensureSessionStateFiles(projectRoot);
     await writeAdapterManifest(projectRoot, harnesses);
     await ensureLearningsStore(projectRoot);

package/dist/runs.d.ts

@@ -6,13 +6,17 @@ export interface CclawRunMeta {
     archivedAt?: string;
     stateSnapshot?: Omit<FlowState, "activeRunId">;
 }
+interface EnsureRunSystemOptions {
+    createIfMissing?: boolean;
+}
 export declare function readFlowState(projectRoot: string): Promise<FlowState>;
 export declare function writeFlowState(projectRoot: string, state: FlowState): Promise<void>;
 export declare function listRuns(projectRoot: string): Promise<CclawRunMeta[]>;
-export declare function ensureRunSystem(projectRoot: string): Promise<FlowState>;
+export declare function ensureRunSystem(projectRoot: string, options?: EnsureRunSystemOptions): Promise<FlowState>;
 export declare function startNewFeatureRun(projectRoot: string, title?: string): Promise<CclawRunMeta>;
 export declare function resumeRun(projectRoot: string, runId: string): Promise<CclawRunMeta>;
 export declare function archiveRun(projectRoot: string, runId?: string): Promise<{
     archived: CclawRunMeta;
     active: CclawRunMeta;
 }>;
+export {};

package/dist/runs.js

@@ -7,7 +7,7 @@ const FLOW_STATE_REL_PATH = `${RUNTIME_ROOT}/state/flow-state.json`;
 const RUNS_DIR_REL_PATH = `${RUNTIME_ROOT}/runs`;
 const ACTIVE_ARTIFACTS_REL_PATH = `${RUNTIME_ROOT}/artifacts`;
 const RUN_META_FILE = "run.json";
-const RUN_HANDOFF_FILE = "00-handoff.md";
+const RUN_HANDOFF_FILE = "handoff.md";
 const FLOW_STAGE_SET = new Set(COMMAND_FILE_ORDER);
 function flowStatePath(projectRoot) {
     return path.join(projectRoot, FLOW_STATE_REL_PATH);
@@ -323,13 +323,17 @@ async function ensureRunHandoff(projectRoot, runId) {
         return;
     await writeFileSafe(runHandoffPath(projectRoot, runId), handoffMarkdown(meta, state));
 }
-export async function ensureRunSystem(projectRoot) {
+export async function ensureRunSystem(projectRoot, options = {}) {
     await ensureDir(runsRoot(projectRoot));
     await ensureDir(activeArtifactsPath(projectRoot));
     let state = await readFlowState(projectRoot);
     let activeRunId = state.activeRunId;
+    const createIfMissing = options.createIfMissing !== false;
     const activeRunExists = activeRunId.trim().length > 0 && (await exists(runArtifactsPath(projectRoot, activeRunId)));
     if (!activeRunExists) {
+        if (!createIfMissing) {
+            return state;
+        }
         const activeHasArtifacts = (await listImmediateFiles(activeArtifactsPath(projectRoot))).length > 0;
         const initialRun = await createRun(projectRoot, {
             title: activeHasArtifacts ? "Migrated active run" : "Initial feature run",

package/package.json

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