cclaw-cli 0.5.3 → 0.5.4

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/examples.js

@@ -16,6 +16,22 @@ const STAGE_EXAMPLES = {
 **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

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/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.",
@@ -75,7 +80,10 @@ const BRAINSTORM = {
         { 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 and user confirmed the understanding." },
+        {
+            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." },
@@ -84,8 +92,12 @@ 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."
     ],
@@ -117,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",
@@ -135,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"
     ],
@@ -163,7 +183,11 @@ const BRAINSTORM = {
     artifactValidation: [
         { 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." },
+        {
+            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." },

package/dist/doctor.js

@@ -750,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, "handoff.md")),
-        details: `${RUNTIME_ROOT}/runs/${flowState.activeRunId}/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

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