@cloverleaf/reference-impl 0.6.3 → 0.6.4

package/README.md

@@ -152,7 +152,7 @@ The Reviewer never switches branches. It reads files via `git show` and runs tes
 
 ## Package layout
 
-- `lib/` — TypeScript library used by the CLI. State, events, feedback, IDs, paths. Includes `buildBaselinePath(repoRoot, browser, slug, viewport)` (`lib/visual-diff.ts`) for constructing canonical baseline paths under `.cloverleaf/baselines/{browser}/`. `lib/ui-browser.ts` exports `buildBrowserEscalationFinding` and `applyMaxCombinationsCap` (used by the UI Reviewer prompt for per-engine escalation and combination-count capping). `lib/ui-review-state.ts` exports `readUiReviewState`, `writeUiReviewState`, and `uiReviewStatePath` — the baseline-approval sidecar API for `.cloverleaf/runs/{taskId}/ui-review/state.json`. The CLI exposes `write-baseline <repoRoot> <taskId> <browser> <slug> <viewport> <sourceFile>` as the safe write path for baselines; it enforces the `baselines_pending` guard and uses `buildBaselinePath` internally.
+- `lib/` — TypeScript library used by the CLI. State, events, feedback, IDs, paths. Includes `buildBaselinePath(repoRoot, browser, slug, viewport)` (`lib/visual-diff.ts`) for constructing canonical baseline paths under `.cloverleaf/baselines/{browser}/`. `lib/ui-browser.ts` exports `buildBrowserEscalationFinding` and `applyMaxCombinationsCap` (used by the UI Reviewer prompt for per-engine escalation and combination-count capping). `lib/ui-review-state.ts` exports `readUiReviewState`, `writeUiReviewState`, and `uiReviewStatePath` — the baseline-approval sidecar API for `.cloverleaf/runs/{taskId}/ui-review/state.json`. The CLI exposes `write-baseline <repoRoot> <taskId> <browser> <slug> <viewport> <sourceFile>` as the safe write path for baselines; it enforces the `baselines_pending` guard and uses `buildBaselinePath` internally. `lib/walker-config.ts` exports `loadWalkerConfig()` — reads `~/.config/cloverleaf/walker.json` (XDG-aware) for the user-level `max_concurrent` override; exposed via `cloverleaf-cli walker-default-concurrency [--explain]`.
 - `skills/` — Claude Code skill markdown files.
 - `prompts/` — Implementer/Reviewer subagent system prompts.
 - `examples/toy-repo/` — standalone demo repo.

package/dist/cli.mjs

@@ -34,6 +34,7 @@
  *   dag-detect-cycle <repoRoot> <planId>
  *   walk-state-read <repoRoot> <planId>
  *   walk-state-write <repoRoot> <walkStateJsonPath>
+ *   walker-default-concurrency [--explain]
  */
 import { readFileSync, mkdirSync, copyFileSync } from 'node:fs';
 import { dirname } from 'node:path';
@@ -58,6 +59,7 @@ import { readUiReviewState, writeUiReviewState } from './ui-review-state.mjs';
 import { buildBaselinePath } from './visual-diff.mjs';
 import { computeReadyTasks, detectCycle } from './dag-walker.mjs';
 import { readWalkState, writeWalkState, walkStatePath } from './walk-state.mjs';
+import { loadWalkerConfig } from './walker-config.mjs';
 function die(msg, code = 1) {
     process.stderr.write(msg + '\n');
     process.exit(code);
@@ -95,7 +97,8 @@ function usage(msg) {
         '  dag-ready-tasks <repoRoot> <planId> <maxConcurrent>\n' +
         '  dag-detect-cycle <repoRoot> <planId>\n' +
         '  walk-state-read <repoRoot> <planId>\n' +
-        '  walk-state-write <repoRoot> <walkStateJsonPath>\n');
+        '  walk-state-write <repoRoot> <walkStateJsonPath>\n' +
+        '  walker-default-concurrency [--explain]\n');
     process.exit(2);
 }
 const [, , command, ...rest] = process.argv;
@@ -485,6 +488,26 @@ try {
             writeWalkState(repoRoot, state);
             break;
         }
+        case 'walker-default-concurrency': {
+            const explain = rest.includes('--explain');
+            let cfg;
+            try {
+                cfg = loadWalkerConfig();
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                process.stderr.write(msg + '\n');
+                process.exit(1);
+            }
+            if (explain) {
+                const location = cfg.source === 'user' ? `from ${cfg.path}` : 'default';
+                process.stdout.write(`max_concurrent=${cfg.maxConcurrent} (${location})\n`);
+            }
+            else {
+                process.stdout.write(`${cfg.maxConcurrent}\n`);
+            }
+            process.exit(0);
+        }
         default:
             usage(`Unknown command: ${command}`);
     }

package/dist/walker-config.mjs

@@ -0,0 +1,63 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * Resolve the absolute path to the walker config file.
+ * Respects XDG_CONFIG_HOME if set; otherwise falls back to $HOME/.config.
+ */
+export function walkerConfigPath() {
+    const xdgConfigHome = process.env['XDG_CONFIG_HOME'] ?? join(homedir(), '.config');
+    return join(xdgConfigHome, 'cloverleaf', 'walker.json');
+}
+/**
+ * Load and validate the walker configuration.
+ *
+ * Resolution rules:
+ * - File absent (ENOENT) → { maxConcurrent: 3, source: 'default' }
+ * - File present, no max_concurrent field → { maxConcurrent: 3, source: 'default' }
+ * - File present, valid positive integer → { maxConcurrent: N, source: 'user' }
+ * - Malformed JSON → throws with file path and parser detail
+ * - Invalid max_concurrent (0, negative, float, string, null) → throws with field path and actual value
+ *
+ * No AJV dependency — hand-rolled validation.
+ */
+export function loadWalkerConfig() {
+    const configPath = walkerConfigPath();
+    let raw;
+    try {
+        raw = readFileSync(configPath, 'utf-8');
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === 'ENOENT') {
+            return { maxConcurrent: 3, source: 'default', path: configPath };
+        }
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new Error(`walker config at ${configPath} contains malformed JSON: ${detail}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`walker config at ${configPath}: expected a JSON object, got ${JSON.stringify(parsed)}`);
+    }
+    const doc = parsed;
+    if (!('max_concurrent' in doc)) {
+        return { maxConcurrent: 3, source: 'default', path: configPath };
+    }
+    const value = doc['max_concurrent'];
+    if (typeof value !== 'number') {
+        throw new Error(`walker config at ${configPath}: max_concurrent must be a positive integer, got ${JSON.stringify(value)}`);
+    }
+    if (!Number.isInteger(value)) {
+        throw new Error(`walker config at ${configPath}: max_concurrent must be a positive integer (no floats), got ${value}`);
+    }
+    if (value <= 0) {
+        throw new Error(`walker config at ${configPath}: max_concurrent must be a positive integer (> 0), got ${value}`);
+    }
+    return { maxConcurrent: value, source: 'user', path: configPath };
+}

package/lib/cli.ts

@@ -34,6 +34,7 @@
  *   dag-detect-cycle <repoRoot> <planId>
  *   walk-state-read <repoRoot> <planId>
  *   walk-state-write <repoRoot> <walkStateJsonPath>
+ *   walker-default-concurrency [--explain]
  */
 
 import { readFileSync, mkdirSync, copyFileSync } from 'node:fs';
@@ -60,6 +61,7 @@ import { readUiReviewState, writeUiReviewState } from './ui-review-state.js';
 import { buildBaselinePath } from './visual-diff.js';
 import { computeReadyTasks, detectCycle } from './dag-walker.js';
 import { readWalkState, writeWalkState, walkStatePath } from './walk-state.js';
+import { loadWalkerConfig } from './walker-config.js';
 
 function die(msg: string, code = 1): never {
   process.stderr.write(msg + '\n');
@@ -99,7 +101,8 @@ function usage(msg?: string): never {
       '  dag-ready-tasks <repoRoot> <planId> <maxConcurrent>\n' +
       '  dag-detect-cycle <repoRoot> <planId>\n' +
       '  walk-state-read <repoRoot> <planId>\n' +
-      '  walk-state-write <repoRoot> <walkStateJsonPath>\n'
+      '  walk-state-write <repoRoot> <walkStateJsonPath>\n' +
+      '  walker-default-concurrency [--explain]\n'
   );
   process.exit(2);
 }
@@ -499,6 +502,26 @@ try {
       break;
     }
 
+    case 'walker-default-concurrency': {
+      const explain = rest.includes('--explain');
+      let cfg: { maxConcurrent: number; source: 'user' | 'default'; path: string };
+      try {
+        cfg = loadWalkerConfig();
+      } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(msg + '\n');
+        process.exit(1);
+      }
+      if (explain) {
+        const location =
+          cfg.source === 'user' ? `from ${cfg.path}` : 'default';
+        process.stdout.write(`max_concurrent=${cfg.maxConcurrent} (${location})\n`);
+      } else {
+        process.stdout.write(`${cfg.maxConcurrent}\n`);
+      }
+      process.exit(0);
+    }
+
     default:
       usage(`Unknown command: ${command}`);
   }

package/lib/walker-config.ts

@@ -0,0 +1,90 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export interface WalkerConfig {
+  maxConcurrent: number;
+  source: 'user' | 'default';
+  /** Absolute resolved path to the walker.json file (whether it exists or not). */
+  path: string;
+}
+
+/**
+ * Resolve the absolute path to the walker config file.
+ * Respects XDG_CONFIG_HOME if set; otherwise falls back to $HOME/.config.
+ */
+export function walkerConfigPath(): string {
+  const xdgConfigHome = process.env['XDG_CONFIG_HOME'] ?? join(homedir(), '.config');
+  return join(xdgConfigHome, 'cloverleaf', 'walker.json');
+}
+
+/**
+ * Load and validate the walker configuration.
+ *
+ * Resolution rules:
+ * - File absent (ENOENT) → { maxConcurrent: 3, source: 'default' }
+ * - File present, no max_concurrent field → { maxConcurrent: 3, source: 'default' }
+ * - File present, valid positive integer → { maxConcurrent: N, source: 'user' }
+ * - Malformed JSON → throws with file path and parser detail
+ * - Invalid max_concurrent (0, negative, float, string, null) → throws with field path and actual value
+ *
+ * No AJV dependency — hand-rolled validation.
+ */
+export function loadWalkerConfig(): WalkerConfig {
+  const configPath = walkerConfigPath();
+
+  let raw: string;
+  try {
+    raw = readFileSync(configPath, 'utf-8');
+  } catch (err: unknown) {
+    const e = err as NodeJS.ErrnoException;
+    if (e.code === 'ENOENT') {
+      return { maxConcurrent: 3, source: 'default', path: configPath };
+    }
+    throw err;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err: unknown) {
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `walker config at ${configPath} contains malformed JSON: ${detail}`
+    );
+  }
+
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new Error(
+      `walker config at ${configPath}: expected a JSON object, got ${JSON.stringify(parsed)}`
+    );
+  }
+
+  const doc = parsed as Record<string, unknown>;
+
+  if (!('max_concurrent' in doc)) {
+    return { maxConcurrent: 3, source: 'default', path: configPath };
+  }
+
+  const value = doc['max_concurrent'];
+
+  if (typeof value !== 'number') {
+    throw new Error(
+      `walker config at ${configPath}: max_concurrent must be a positive integer, got ${JSON.stringify(value)}`
+    );
+  }
+
+  if (!Number.isInteger(value)) {
+    throw new Error(
+      `walker config at ${configPath}: max_concurrent must be a positive integer (no floats), got ${value}`
+    );
+  }
+
+  if (value <= 0) {
+    throw new Error(
+      `walker config at ${configPath}: max_concurrent must be a positive integer (> 0), got ${value}`
+    );
+  }
+
+  return { maxConcurrent: value, source: 'user', path: configPath };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloverleaf/reference-impl",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "Reference implementation of the Cloverleaf methodology as Claude Code skills. Implements the Tight Loop (Implementer + Reviewer).",
   "type": "module",
   "license": "MIT",

package/skills/cloverleaf-run-plan/SKILL.md

@@ -20,9 +20,27 @@ description: Autonomous DAG walker for Cloverleaf Plans. Given a PLAN-ID in stat
 
 1. Capture the `<PLAN-ID>` argument and optional flags:
 
-   - `--max-concurrent=N` — cap simultaneous sessions. Default `3`. Setting `--max-concurrent=1` yields serial behaviour.
+   - `--max-concurrent=N` — cap simultaneous sessions. Default `3` (resolved via `cloverleaf-cli walker-default-concurrency`). Setting `--max-concurrent=1` yields serial behaviour.
    - `--reset` — wipe `.cloverleaf/runs/plan/<PLAN-ID>/walk-state.json` and start fresh.
 
+   Resolve `MAX` and print exactly one startup info line:
+
+   ```bash
+   if [ -n "$MAX_FLAG" ]; then
+     MAX="$MAX_FLAG"
+     echo "max_concurrent=$MAX (from --max-concurrent flag)"
+   else
+     if ! MAX=$(cloverleaf-cli walker-default-concurrency); then
+       echo "ERROR: cloverleaf-cli walker-default-concurrency failed."
+       echo "Fix or remove \`~/.config/cloverleaf/walker.json\` and retry."
+       exit 1
+     fi
+     cloverleaf-cli walker-default-concurrency --explain
+   fi
+   ```
+
+   If `cloverleaf-cli walker-default-concurrency` exits non-zero (e.g. malformed `${XDG_CONFIG_HOME:-$HOME/.config}/cloverleaf/walker.json`), the walker stops and reports the error: **Fix or remove `~/.config/cloverleaf/walker.json` and retry.** This mirrors the step-0 uncommitted-changes stop-and-report pattern.
+
 2. **Guard against cycles.**
 
    ```bash