cclaw-cli 0.42.0 → 0.44.0

package/dist/content/observe.js

@@ -154,6 +154,7 @@ exit 0
 `;
 }
 export function workflowGuardScript(options = {}) {
+    const workflowGuardMode = options.workflowGuardMode === "strict" ? "strict" : "advisory";
     const tddEnforcementMode = options.tddEnforcementMode === "strict" ? "strict" : "advisory";
     const tddTestGlobs = options.tddTestGlobs && options.tddTestGlobs.length > 0
         ? options.tddTestGlobs.join(",")
@@ -162,7 +163,7 @@ export function workflowGuardScript(options = {}) {
 # cclaw workflow guard hook — generated by cclaw sync
 # Enforces stage-aware command discipline and recent flow-state read hygiene.
 set -uo pipefail
-WORKFLOW_GUARD_MODE="\${CCLAW_WORKFLOW_GUARD_MODE:-advisory}"
+WORKFLOW_GUARD_MODE="\${CCLAW_WORKFLOW_GUARD_MODE:-${workflowGuardMode}}"
 MAX_FLOW_READ_AGE_SEC="\${CCLAW_WORKFLOW_GUARD_MAX_AGE_SEC:-1800}"
 TDD_ENFORCEMENT_MODE="${tddEnforcementMode}"
 TDD_TEST_GLOBS="${tddTestGlobs}"
@@ -342,6 +343,81 @@ is_cclaw_cli_payload() {
   printf '%s' "$1" | grep -Eq '(cclaw |npx cclaw |/cc-|/cc[^[:alnum:]_-])'
 }
 
+extract_flow_state_after_json() {
+  if command -v jq >/dev/null 2>&1; then
+    printf '%s' "$INPUT" | jq -r '
+      .tool_input?.content //
+      .input?.content //
+      .arguments?.content //
+      .params?.content //
+      .payload?.content //
+      .content //
+      .input?.new_string //
+      .tool_input?.new_string //
+      ""
+    ' 2>/dev/null || echo ""
+    return 0
+  fi
+
+  if command -v python3 >/dev/null 2>&1; then
+    INPUT_JSON="$INPUT" python3 - <<'PY'
+import json
+import os
+
+try:
+    payload = json.loads(os.environ.get("INPUT_JSON", "{}"))
+except Exception:
+    payload = {}
+
+def pick(value):
+    if not isinstance(value, dict):
+        return ""
+    for key in ("tool_input", "input", "arguments", "params", "payload"):
+        nested = value.get(key)
+        if isinstance(nested, dict):
+            content = nested.get("content")
+            if isinstance(content, str) and content.strip():
+                return content
+            new_string = nested.get("new_string")
+            if isinstance(new_string, str) and new_string.strip():
+                return new_string
+    content = value.get("content")
+    if isinstance(content, str) and content.strip():
+        return content
+    return ""
+
+print(pick(payload))
+PY
+    return 0
+  fi
+
+  printf ''
+  return 0
+}
+
+verify_flow_state_candidate() {
+  local candidate_json="$1"
+  [ -n "$candidate_json" ] || return 1
+  local tmp_file="$STATE_DIR/.flow-state-candidate.$$.$RANDOM.json"
+  printf '%s' "$candidate_json" > "$tmp_file" 2>/dev/null || {
+    rm -f "$tmp_file" 2>/dev/null || true
+    return 1
+  }
+
+  local verify_cmd=(npx -y cclaw-cli internal verify-flow-state-diff --after-file="$tmp_file" --quiet)
+  if command -v cclaw >/dev/null 2>&1; then
+    verify_cmd=(cclaw internal verify-flow-state-diff --after-file="$tmp_file" --quiet)
+  fi
+
+  if "\${verify_cmd[@]}" >/dev/null 2>&1; then
+    rm -f "$tmp_file" 2>/dev/null || true
+    return 0
+  fi
+
+  rm -f "$tmp_file" 2>/dev/null || true
+  return 1
+}
+
 is_preimplementation_stage() {
   case "$1" in
     brainstorm|scope|design|spec|plan) return 0 ;;
@@ -480,6 +556,22 @@ if [ -n "$TARGET_STAGE" ] && [ "$CURRENT_STAGE" != "none" ]; then
   fi
 fi
 
+if is_mutating_tool "$TOOL_LOWER" && printf '%s' "$PAYLOAD_LOWER" | grep -Eq '\.cclaw/state/flow-state\.json'; then
+  if [ -n "$REASONS" ]; then
+    REASONS="$REASONS,direct_flow_state_edit"
+  else
+    REASONS="direct_flow_state_edit"
+  fi
+  FLOW_STATE_AFTER_JSON=$(extract_flow_state_after_json)
+  if [ -n "$FLOW_STATE_AFTER_JSON" ]; then
+    if ! verify_flow_state_candidate "$FLOW_STATE_AFTER_JSON"; then
+      REASONS="$REASONS,flow_state_edit_failed_internal_validation"
+    fi
+  else
+    REASONS="$REASONS,flow_state_edit_without_serialized_content"
+  fi
+fi
+
 if is_preimplementation_stage "$CURRENT_STAGE" && is_mutating_tool "$TOOL_LOWER"; then
   if ! printf '%s' "$PAYLOAD_LOWER" | grep -Eq '\.cclaw/'; then
     if [ -n "$REASONS" ]; then
@@ -567,7 +659,11 @@ PY
 fi
 
 if [ -n "$REASONS" ]; then
-  NOTE="Cclaw workflow guard: detected potential flow violation (\${REASONS}). Re-read ${RUNTIME_ROOT}/state/flow-state.json, avoid source edits before tdd stage, and enforce RED -> GREEN -> REFACTOR discipline inside tdd."
+  if printf '%s' "$REASONS" | grep -Eq 'direct_flow_state_edit'; then
+    NOTE="Cclaw workflow guard: direct flow-state edit bypasses the canonical stage-complete helper (\${REASONS}). Prefer: bash ${RUNTIME_ROOT}/hooks/stage-complete.sh <stage>. In strict mode this is blocked."
+  else
+    NOTE="Cclaw workflow guard: detected potential flow violation (\${REASONS}). Re-read ${RUNTIME_ROOT}/state/flow-state.json, avoid source edits before tdd stage, and enforce RED -> GREEN -> REFACTOR discipline inside tdd."
+  fi
   if command -v jq >/dev/null 2>&1; then
     ENTRY=$(jq -n -c \
       --arg ts "$TS" \
@@ -1826,6 +1922,9 @@ export function codexHooksJsonWithObservation() {
                     hooks: [{
                             type: "command",
                             command: `bash ${RUNTIME_ROOT}/hooks/prompt-guard.sh`
+                        }, {
+                            type: "command",
+                            command: "bash -lc 'if command -v cclaw >/dev/null 2>&1; then cclaw internal verify-current-state --quiet >/dev/null || true; else npx -y cclaw-cli internal verify-current-state --quiet >/dev/null || true; fi'"
                         }]
                 }],
             PreToolUse: [{

package/dist/content/protocols.js

@@ -99,16 +99,21 @@ Shared closeout sequence applied by every stage skill.
 ## Required order
 
 1. Verify mandatory delegations are completed or explicitly waived.
-2. Update \`.cclaw/state/flow-state.json\`:
-   - mark passed gates,
-   - clear blocked gates that are resolved,
-   - update \`guardEvidence\`.
-3. Persist stage artifact under \`.cclaw/artifacts/\`.
-4. Run \`npx cclaw doctor\` and resolve failures.
-5. **Capture through-flow learnings** — see the policy below. Knowledge
+2. Persist stage artifact under \`.cclaw/artifacts/\`.
+3. Use the canonical helper:
+   - \`bash .cclaw/hooks/stage-complete.sh <stage>\`
+   - helper responsibilities: validate mandatory delegations, validate
+     current-stage gate evidence/artifact lint, update
+     \`stageGateCatalog\` + \`guardEvidence\`, and advance \`currentStage\`.
+4. Legacy fallback (only when helper is unavailable): manually edit
+   \`.cclaw/state/flow-state.json\` to mark passed gates, clear resolved
+   blocked gates, and update \`guardEvidence\`. This path is legacy and
+   intentionally noisy in workflow guards.
+5. Run \`npx cclaw doctor\` and resolve failures.
+6. **Capture through-flow learnings** — see the policy below. Knowledge
    accrues continuously across stages, not just at retro.
-6. Notify user with stage completion and next action (\`/cc-next\`).
-7. Stop; do not auto-run the next stage unless user asks.
+7. Notify user with stage completion and next action (\`/cc-next\`).
+8. Stop; do not auto-run the next stage unless user asks.
 
 ## Through-flow knowledge capture
 

package/dist/content/skills.js

@@ -222,6 +222,9 @@ function completionParametersBlock(schema) {
 - \`gates\`: ${gateList}
 - \`artifact\`: \`${RUNTIME_ROOT}/artifacts/${schema.artifactFile}\`
 - \`mandatory delegations\`: ${mandatory}
+- \`completion helper\`: \`bash .cclaw/hooks/stage-complete.sh ${schema.stage}\`
+- Record mandatory delegation completion/waiver in \`${RUNTIME_ROOT}/state/delegation-log.json\` with rationale as needed.
+- Use the completion helper instead of raw \`flow-state.json\` edits (legacy direct edits trigger workflow-guard warnings or strict-mode blocks).
 
 Apply shared completion logic from:
 \`${COMPLETION_PROTOCOL_PATH}\`

package/dist/content/stages/design.js

@@ -42,6 +42,7 @@ export const DESIGN = {
         "If a section has no issues, say 'No issues found' and move on.",
         "Do not skip failure-mode mapping.",
         "For design baseline approval: present the full baseline. **STOP.** Do NOT proceed until user explicitly approves the design.",
+        "**STOP BEFORE ADVANCE.** Mandatory delegation `planner` must be marked completed or explicitly waived in `.cclaw/state/delegation-log.json`. Then close the stage via `bash .cclaw/hooks/stage-complete.sh design` (do not hand-edit `.cclaw/state/flow-state.json`).",
         "Take a firm position on every recommendation. Do NOT hedge with 'it depends' or 'you could do either'. State your opinion, then justify it.",
         "Use pushback patterns for weak framing: if the user says 'it's just a small change', respond with 'small changes to shared interfaces have outsized blast radius — let's map it'. If 'we'll refactor later', respond with 'later never comes — show me the refactor ticket or do it now'.",
         "When the user's proposed architecture is suboptimal, say so directly. Offer the alternative with concrete trade-offs, do not bury criticism in praise.",

package/dist/content/stages/plan.js

@@ -29,7 +29,7 @@ export const PLAN = {
         "Map scope Locked Decisions — every D-XX from scope is referenced by at least one plan task (or explicitly marked deferred with reason).",
         "Run anti-placeholder + anti-scope-reduction scans — block `TODO/TBD/...` and phrasing like `v1`, `for now`, `later` for locked boundaries.",
         "Define checkpoints — mark points where progress should be validated before continuing.",
-        "WAIT_FOR_CONFIRM — write plan artifact and explicitly pause. **STOP.** Do NOT proceed until user confirms. Then update `flow-state.json` and tell user to run `/cc-next`."
+        "WAIT_FOR_CONFIRM — write plan artifact and explicitly pause. **STOP.** Do NOT proceed until user confirms. Then close the stage with `bash .cclaw/hooks/stage-complete.sh plan` and tell user to run `/cc-next`."
     ],
     interactionProtocol: [
         "Plan in read-only mode relative to implementation.",
@@ -38,7 +38,8 @@ export const PLAN = {
         "Attach verification step to every task.",
         "Preserve locked scope boundaries: no silent scope reduction language in task rows.",
         "Enforce WAIT_FOR_CONFIRM: present the plan summary with options (A) Approve / (B) Revise / (C) Reject.",
-        "**STOP.** Do NOT proceed until user explicitly approves. Then update `flow-state.json` and tell user to run `/cc-next`."
+        "**STOP.** Do NOT proceed until user explicitly approves.",
+        "**STOP BEFORE ADVANCE.** Mandatory delegation `planner` must be marked completed or explicitly waived in `.cclaw/state/delegation-log.json`. Then close the stage via `bash .cclaw/hooks/stage-complete.sh plan` and tell the user to run `/cc-next`."
     ],
     process: [
         "Build dependency graph and ordered slices.",

package/dist/content/stages/scope.js

@@ -41,7 +41,8 @@ export const SCOPE = {
         "Record explicit in-scope and out-of-scope contract.",
         "Once the user accepts or rejects a recommendation, commit fully. Do not re-argue.",
         "Produce a clean scope summary after all issues are resolved.",
-        "**STOP.** Wait for explicit user approval of scope contract before advancing to design."
+        "**STOP.** Wait for explicit user approval of scope contract before advancing to design.",
+        "**STOP BEFORE ADVANCE.** Mandatory delegation `planner` must be marked completed or explicitly waived in `.cclaw/state/delegation-log.json`. Then close the stage via `bash .cclaw/hooks/stage-complete.sh scope` (do not hand-edit `.cclaw/state/flow-state.json`)."
     ],
     process: [
         "Run premise challenge and existing-solution leverage check.",

package/dist/content/stages/tdd.js

@@ -92,18 +92,11 @@ export const TDD = {
     ],
     commonRationalizations: [
         "Writing code before failing test",
-        "Asserting implementation details instead of behavior",
-        "Big-bang implementation across multiple slices",
         "Partial test runs presented as GREEN",
         "Skipping evidence capture",
         "Undocumented refactor changes",
-        "Adding features beyond what RED tests require",
-        "No failing test output (RED missing)",
-        "Implementation edits appear before RED evidence",
         "No full-suite GREEN evidence",
-        "No refactor notes",
-        "Multiple tasks implemented in one pass without justification",
-        "Files changed outside current slice scope"
+        "Multiple tasks implemented in one pass without justification"
     ],
     policyNeedles: ["RED", "GREEN", "REFACTOR", "failing test", "full test suite", "acceptance criteria", "traceable to plan slice"],
     artifactFile: "06-tdd.md",

package/dist/install.d.ts

@@ -9,13 +9,12 @@ export declare function syncCclaw(projectRoot: string): Promise<void>;
 /**
  * Refresh generated files in `.cclaw/` without touching user-authored
  * artifacts, state, or custom config keys. Only the `version` + `flowVersion`
- * stamps are rewritten so the on-disk config reflects the installed CLI;
- * `promptGuardMode`, `tddEnforcement`, `gitHookGuards`, `languageRulePacks`,
- * `trackHeuristics`, and `sliceReview` are preserved verbatim from the
- * existing config.
+ * stamps are rewritten so the on-disk config reflects the installed CLI.
  *
- * For an explicit reset, run `cclaw-cli uninstall && cclaw-cli init`
- * (after optionally archiving the current run via `/cc-ops archive`).
+ * Shape preservation: if the user previously hand-authored advanced keys
+ * (e.g. `tddTestGlobs`, `trackHeuristics`, `sliceReview`), those stay in the
+ * yaml. If their existing config is minimal, the upgrade keeps it minimal —
+ * advanced knobs are never silently added.
  */
 export declare function upgradeCclaw(projectRoot: string): Promise<void>;
 export declare function uninstallCclaw(projectRoot: string): Promise<void>;

package/dist/install.js

@@ -3,7 +3,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { promisify } from "node:util";
 import { CCLAW_VERSION, COMMAND_FILE_ORDER, FLOW_VERSION, REQUIRED_DIRS, RUNTIME_ROOT } from "./constants.js";
-import { writeConfig, createDefaultConfig, readConfig, configPath } from "./config.js";
+import { writeConfig, createDefaultConfig, readConfig, configPath, detectLanguageRulePacks, detectAdvancedKeys } from "./config.js";
 import { commandContract } from "./content/contracts.js";
 import { contextModeFiles, createInitialContextModeState } from "./content/contexts.js";
 import { learnSkillMarkdown, learnCommandContract } from "./content/learnings.js";
@@ -23,7 +23,7 @@ import { archiveCommandContract, archiveCommandSkillMarkdown } from "./content/a
 import { rewindCommandContract, rewindCommandSkillMarkdown } from "./content/rewind-command.js";
 import { subagentDrivenDevSkill, parallelAgentsSkill } from "./content/subagents.js";
 import { sessionHooksSkillMarkdown } from "./content/session-hooks.js";
-import { sessionStartScript, stopCheckpointScript, preCompactScript, opencodePluginJs, claudeHooksJson, codexHooksJson, cursorHooksJson } from "./content/hooks.js";
+import { sessionStartScript, stopCheckpointScript, stageCompleteScript, preCompactScript, opencodePluginJs, claudeHooksJson, codexHooksJson, cursorHooksJson } from "./content/hooks.js";
 import { contextMonitorScript, promptGuardScript, workflowGuardScript } from "./content/observe.js";
 import { META_SKILL_NAME, usingCclawSkillMarkdown } from "./content/meta-skill.js";
 import { decisionProtocolMarkdown, completionProtocolMarkdown, ethosProtocolMarkdown } from "./content/protocols.js";
@@ -616,11 +616,13 @@ async function writeHooks(projectRoot, config) {
     await ensureDir(hooksDir);
     await writeFileSafe(path.join(hooksDir, "session-start.sh"), sessionStartScript());
     await writeFileSafe(path.join(hooksDir, "stop-checkpoint.sh"), stopCheckpointScript());
+    await writeFileSafe(path.join(hooksDir, "stage-complete.sh"), stageCompleteScript());
     await writeFileSafe(path.join(hooksDir, "pre-compact.sh"), preCompactScript());
     await writeFileSafe(path.join(hooksDir, "prompt-guard.sh"), promptGuardScript({
         strictMode: config.promptGuardMode === "strict"
     }));
     await writeFileSafe(path.join(hooksDir, "workflow-guard.sh"), workflowGuardScript({
+        workflowGuardMode: config.strictness ?? "advisory",
         tddEnforcementMode: config.tddEnforcement ?? "advisory",
         tddTestGlobs: config.tddTestGlobs
     }));
@@ -631,6 +633,7 @@ async function writeHooks(projectRoot, config) {
         for (const script of [
             "session-start.sh",
             "stop-checkpoint.sh",
+            "stage-complete.sh",
             "pre-compact.sh",
             "prompt-guard.sh",
             "workflow-guard.sh",
@@ -1156,13 +1159,24 @@ async function materializeRuntime(projectRoot, config, forceStateReset) {
     await ensureGitignore(projectRoot);
 }
 export async function initCclaw(options) {
-    const config = createDefaultConfig(options.harnesses, options.track);
-    await writeConfig(options.projectRoot, config);
+    const baseConfig = createDefaultConfig(options.harnesses, options.track);
+    // Best-effort auto-detect: a Node project gets `typescript`, a Go module
+    // gets `go`, etc. Skipped entirely when the project root has no manifests.
+    const detectedPacks = await detectLanguageRulePacks(options.projectRoot);
+    const config = {
+        ...baseConfig,
+        languageRulePacks: detectedPacks
+    };
+    // Write a minimal `config.yaml` — advanced knobs live in docs/config.md
+    // and only appear in the on-disk file when the user sets them explicitly
+    // or a non-default value was detected (e.g. languageRulePacks).
+    await writeConfig(options.projectRoot, config, { mode: "minimal" });
     await materializeRuntime(options.projectRoot, config, true);
 }
 export async function syncCclaw(projectRoot) {
+    const configExists = await exists(configPath(projectRoot));
     const config = await readConfig(projectRoot);
-    if (!(await exists(configPath(projectRoot)))) {
+    if (!configExists) {
         await writeConfig(projectRoot, createDefaultConfig(config.harnesses));
     }
     await materializeRuntime(projectRoot, config, false);
@@ -1170,22 +1184,25 @@ export async function syncCclaw(projectRoot) {
 /**
  * Refresh generated files in `.cclaw/` without touching user-authored
  * artifacts, state, or custom config keys. Only the `version` + `flowVersion`
- * stamps are rewritten so the on-disk config reflects the installed CLI;
- * `promptGuardMode`, `tddEnforcement`, `gitHookGuards`, `languageRulePacks`,
- * `trackHeuristics`, and `sliceReview` are preserved verbatim from the
- * existing config.
+ * stamps are rewritten so the on-disk config reflects the installed CLI.
  *
- * For an explicit reset, run `cclaw-cli uninstall && cclaw-cli init`
- * (after optionally archiving the current run via `/cc-ops archive`).
+ * Shape preservation: if the user previously hand-authored advanced keys
+ * (e.g. `tddTestGlobs`, `trackHeuristics`, `sliceReview`), those stay in the
+ * yaml. If their existing config is minimal, the upgrade keeps it minimal —
+ * advanced knobs are never silently added.
  */
 export async function upgradeCclaw(projectRoot) {
+    const advancedKeysPresent = await detectAdvancedKeys(projectRoot);
     const existing = await readConfig(projectRoot);
     const upgraded = {
         ...existing,
         version: CCLAW_VERSION,
         flowVersion: FLOW_VERSION
     };
-    await writeConfig(projectRoot, upgraded);
+    await writeConfig(projectRoot, upgraded, {
+        mode: "minimal",
+        advancedKeysPresent
+    });
     await materializeRuntime(projectRoot, upgraded, false);
 }
 function stripManagedHookCommands(value) {
@@ -1246,7 +1263,12 @@ function stripManagedHookCommands(value) {
 }
 function isManagedRuntimeHookCommand(command) {
     const normalized = command.trim().replace(/\s+/gu, " ");
-    return /(^|\s)(?:bash\s+)?(?:\.\/)?\.cclaw\/hooks\/(?:session-start|stop-checkpoint|pre-compact|prompt-guard|workflow-guard|context-monitor)\.sh(?:\s|$)/u.test(normalized);
+    if (/(^|\s)(?:bash\s+)?(?:\.\/)?\.cclaw\/hooks\/(?:session-start|stop-checkpoint|pre-compact|prompt-guard|workflow-guard|context-monitor)\.sh(?:\s|$)/u.test(normalized)) {
+        return true;
+    }
+    // Codex UserPromptSubmit non-blocking state nudge:
+    // bash -lc '... cclaw internal verify-current-state --quiet ...'
+    return /internal verify-current-state --quiet/u.test(normalized);
 }
 async function removeManagedHookEntries(hookFilePath) {
     if (!(await exists(hookFilePath)))

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

@@ -0,0 +1,7 @@
+import type { Writable } from "node:stream";
+interface InternalIo {
+    stdout: Writable;
+    stderr: Writable;
+}
+export declare function runInternalCommand(projectRoot: string, argv: string[], io: InternalIo): Promise<number>;
+export {};