@cloverleaf/reference-impl 0.6.3 → 0.6.5

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "cloverleaf",
-  "description": "Cloverleaf reference implementation — Claude Code skills for task scaffolding and the Delivery pipeline (implementer, documenter, reviewer, UI reviewer with multi-viewport visual diff, QA, merge).",
-  "version": "0.6.0",
+  "description": "Cloverleaf reference implementation — Claude Code skills for task scaffolding and the Delivery pipeline (implementer, documenter, reviewer, UI reviewer with multi-viewport visual diff, QA, merge, release).",
+  "version": "0.6.5",
   "author": {
     "name": "Renato D'Arrigo",
     "email": "renato.darrigo@gmail.com"
@@ -14,5 +14,11 @@
     "methodology",
     "ai-first",
     "reference-implementation"
+  ],
+  "skills": [
+    {
+      "name": "cloverleaf-release",
+      "description": "Publish a new @cloverleaf/reference-impl release. Runs pre-flight checks then executes git tag, git push, npm publish, gh release create. Accepts [--dry-run] [--yes] flags."
+    }
   ]
 }

package/README.md

@@ -45,6 +45,7 @@ v0.2 implements both paths of the Delivery track:
 - `/cloverleaf-qa` — run QA *(new in v0.2)*
 - `/cloverleaf-merge` — human gate (branches on state)
 - `/cloverleaf-run` — orchestrator (dispatches by `risk_class`)
+- `/cloverleaf-release` — publish a new `@cloverleaf/reference-impl` release; runs pre-flight checks then executes `git tag -a` / `git push origin main` / `git push origin <tag>` / `npm publish` / `gh release create`; accepts `[--dry-run] [--yes]` *(new in CLV-63)*
 
 ### Configuration
 
@@ -152,7 +153,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]`. `lib/release-preflight.ts` exports `runPreflightChecks(repoRoot)` — runs six blocking checks and two warnings, returning `{ checks, version, tag, notes }`; exposed via `cloverleaf-cli release-preflight <repoRoot> [--json]`.
 - `skills/` — Claude Code skill markdown files.
 - `prompts/` — Implementer/Reviewer subagent system prompts.
 - `examples/toy-repo/` — standalone demo repo.

package/dist/cli.mjs

@@ -34,10 +34,13 @@
  *   dag-detect-cycle <repoRoot> <planId>
  *   walk-state-read <repoRoot> <planId>
  *   walk-state-write <repoRoot> <walkStateJsonPath>
+ *   walker-default-concurrency [--explain]
+ *   release-preflight <repoRoot> [--json]
  */
 import { readFileSync, mkdirSync, copyFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { execSync } from 'node:child_process';
+import { runPreflightChecks } from './release-preflight.mjs';
 import { loadTask } from './task.mjs';
 import { advanceStatus } from './task.mjs';
 import { emitGateDecision } from './events.mjs';
@@ -58,6 +61,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 +99,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 +490,57 @@ 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);
+        }
+        case 'release-preflight': {
+            const positional = rest.filter((a) => !a.startsWith('--'));
+            const flags = rest.filter((a) => a.startsWith('--'));
+            const [repoRoot] = positional;
+            if (!repoRoot)
+                usage('release-preflight requires <repoRoot>');
+            const jsonMode = flags.includes('--json');
+            const result = runPreflightChecks(repoRoot);
+            if (jsonMode) {
+                process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+                process.exit(0);
+            }
+            else {
+                // Plain human-readable mode
+                for (const check of result.checks) {
+                    let prefix;
+                    if (check.status === 'pass') {
+                        prefix = '✓';
+                    }
+                    else if (check.level === 'warning') {
+                        prefix = '⚠';
+                    }
+                    else {
+                        prefix = '✗';
+                    }
+                    process.stdout.write(`${prefix} ${check.id}: ${check.message}\n`);
+                }
+                const blockingFailed = result.checks.some((c) => c.level === 'blocking' && c.status === 'fail');
+                process.exit(blockingFailed ? 1 : 0);
+            }
+        }
         default:
             usage(`Unknown command: ${command}`);
     }

package/dist/release-preflight.mjs

@@ -0,0 +1,123 @@
+import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+function shell(cmd, cwd) {
+    try {
+        const out = execSync(cmd, { cwd, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+        return { out: out.trim(), ok: true };
+    }
+    catch (err) {
+        const e = err;
+        const msg = (e.stderr ?? e.stdout ?? e.message ?? String(err)).trim();
+        return { out: msg, ok: false };
+    }
+}
+/**
+ * Run all pre-flight checks for a release from the given repo root.
+ * Never throws — all errors are captured into per-check `message` fields.
+ */
+export function runPreflightChecks(repoRoot) {
+    const checks = [];
+    // Helper to add a check result
+    function addCheck(id, level, pass, failMsg, passMsg = 'ok') {
+        checks.push({ id, level, status: pass ? 'pass' : 'fail', message: pass ? passMsg : failMsg });
+    }
+    // ── Blocking checks ────────────────────────────────────────────────────────
+    // 1. on-main: current branch must be main
+    const branch = shell('git rev-parse --abbrev-ref HEAD', repoRoot);
+    const isOnMain = branch.ok && branch.out === 'main';
+    addCheck('on-main', 'blocking', isOnMain, `not on main (current: ${branch.out})`);
+    // 2. clean-tree: no uncommitted changes
+    const status = shell('git status --porcelain', repoRoot);
+    const isClean = status.ok && status.out === '';
+    addCheck('clean-tree', 'blocking', isClean, `working tree is dirty: ${status.out || status.out}`);
+    // 3. in-sync-with-origin: no commits behind origin/main
+    // Fetch quietly first so we can compare
+    shell('git fetch origin main --quiet', repoRoot);
+    const behind = shell('git rev-list --count HEAD..origin/main', repoRoot);
+    const isSynced = behind.ok && behind.out === '0';
+    addCheck('in-sync-with-origin', 'blocking', isSynced, behind.ok ? `${behind.out} commit(s) behind origin/main` : `could not check sync: ${behind.out}`);
+    // 4. valid-version: reference-impl/package.json has a valid semver
+    let version = '';
+    try {
+        const pkgPath = join(repoRoot, 'reference-impl', 'package.json');
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        version = pkg.version ?? '';
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        addCheck('valid-version', 'blocking', false, `could not read package.json: ${msg}`);
+        version = '';
+    }
+    if (version !== '') {
+        const semverRe = /^\d+\.\d+\.\d+(-[\w.]+)?(\+[\w.]+)?$/;
+        const isValidSemver = semverRe.test(version);
+        addCheck('valid-version', 'blocking', isValidSemver, `invalid semver: '${version}'`, `${version}`);
+    }
+    // 5. changelog-section: CHANGELOG.md has a section for this version
+    const tag = version ? `reference-impl-v${version}` : 'reference-impl-v<unknown>';
+    let changelogPass = false;
+    let changelogMsg = 'no version resolved';
+    if (version) {
+        try {
+            const changelogPath = join(repoRoot, 'reference-impl', 'CHANGELOG.md');
+            const changelog = readFileSync(changelogPath, 'utf-8');
+            // Look for a heading like "## 0.6.5" or "## [0.6.5]"
+            const pattern = new RegExp(`^##\\s+\\[?${version.replace(/\./g, '\\.')}`, 'm');
+            changelogPass = pattern.test(changelog);
+            changelogMsg = changelogPass
+                ? `section for ${version} found`
+                : `no ## ${version} section found in CHANGELOG.md`;
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            changelogMsg = `could not read CHANGELOG.md: ${msg}`;
+        }
+    }
+    addCheck('changelog-section', 'blocking', changelogPass, changelogMsg, changelogMsg);
+    // 6. tag-absent: the release tag must not already exist
+    let tagAbsent = false;
+    let tagMsg = 'no version resolved';
+    if (version) {
+        const localTag = shell(`git tag -l "${tag}"`, repoRoot);
+        const remoteTag = shell(`git ls-remote --tags origin "${tag}"`, repoRoot);
+        const existsLocally = localTag.ok && localTag.out !== '';
+        const existsRemotely = remoteTag.ok && remoteTag.out !== '';
+        tagAbsent = !existsLocally && !existsRemotely;
+        if (existsLocally && existsRemotely) {
+            tagMsg = `tag ${tag} already exists locally and on origin`;
+        }
+        else if (existsLocally) {
+            tagMsg = `tag ${tag} already exists locally`;
+        }
+        else if (existsRemotely) {
+            tagMsg = `tag ${tag} already exists on origin`;
+        }
+        else {
+            tagMsg = `tag ${tag} is absent (ok)`;
+        }
+    }
+    addCheck('tag-absent', 'blocking', tagAbsent, tagMsg, tagMsg);
+    // ── Warning checks ─────────────────────────────────────────────────────────
+    // 7. npm-authenticated: `npm whoami` must exit 0
+    const npmAuth = shell('npm whoami', repoRoot);
+    addCheck('npm-authenticated', 'warning', npmAuth.ok, `npm not authenticated: ${npmAuth.out}`, `logged in as ${npmAuth.out}`);
+    // 8. gh-authenticated: `gh auth status` must exit 0
+    const ghAuth = shell('gh auth status', repoRoot);
+    addCheck('gh-authenticated', 'warning', ghAuth.ok, `gh not authenticated: ${ghAuth.out}`, 'gh CLI authenticated');
+    // Derive release notes from CHANGELOG section
+    let notes = '';
+    if (version) {
+        try {
+            const changelogPath = join(repoRoot, 'reference-impl', 'CHANGELOG.md');
+            const changelog = readFileSync(changelogPath, 'utf-8');
+            const pattern = new RegExp(`^##\\s+\\[?${version.replace(/\./g, '\\.')}[^\\n]*\\n([\\s\\S]*?)(?=^##\\s|$)`, 'm');
+            const m = changelog.match(pattern);
+            notes = m ? m[1].trim() : '';
+        }
+        catch {
+            notes = '';
+        }
+    }
+    return { checks, version, tag, notes };
+}

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,11 +34,14 @@
  *   dag-detect-cycle <repoRoot> <planId>
  *   walk-state-read <repoRoot> <planId>
  *   walk-state-write <repoRoot> <walkStateJsonPath>
+ *   walker-default-concurrency [--explain]
+ *   release-preflight <repoRoot> [--json]
  */
 
 import { readFileSync, mkdirSync, copyFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { execSync } from 'node:child_process';
+import { runPreflightChecks } from './release-preflight.js';
 import { loadTask } from './task.js';
 import { advanceStatus } from './task.js';
 import { emitGateDecision } from './events.js';
@@ -60,6 +63,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 +103,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 +504,56 @@ 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);
+    }
+
+    case 'release-preflight': {
+      const positional = rest.filter((a) => !a.startsWith('--'));
+      const flags = rest.filter((a) => a.startsWith('--'));
+      const [repoRoot] = positional;
+      if (!repoRoot) usage('release-preflight requires <repoRoot>');
+      const jsonMode = flags.includes('--json');
+      const result = runPreflightChecks(repoRoot);
+      if (jsonMode) {
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+        process.exit(0);
+      } else {
+        // Plain human-readable mode
+        for (const check of result.checks) {
+          let prefix: string;
+          if (check.status === 'pass') {
+            prefix = '✓';
+          } else if (check.level === 'warning') {
+            prefix = '⚠';
+          } else {
+            prefix = '✗';
+          }
+          process.stdout.write(`${prefix} ${check.id}: ${check.message}\n`);
+        }
+        const blockingFailed = result.checks.some(
+          (c) => c.level === 'blocking' && c.status === 'fail',
+        );
+        process.exit(blockingFailed ? 1 : 0);
+      }
+    }
+
     default:
       usage(`Unknown command: ${command}`);
   }

package/lib/release-preflight.ts

@@ -0,0 +1,171 @@
+import { execSync } from 'node:child_process';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export type CheckLevel = 'blocking' | 'warning';
+export type CheckStatus = 'pass' | 'fail';
+
+export interface PreflightCheck {
+  id: string;
+  level: CheckLevel;
+  status: CheckStatus;
+  message: string;
+}
+
+export interface PreflightResult {
+  checks: PreflightCheck[];
+  version: string;
+  tag: string;
+  notes: string;
+}
+
+function shell(cmd: string, cwd: string): { out: string; ok: boolean } {
+  try {
+    const out = execSync(cmd, { cwd, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+    return { out: out.trim(), ok: true };
+  } catch (err: unknown) {
+    const e = err as { stdout?: string; stderr?: string; message?: string };
+    const msg = (e.stderr ?? e.stdout ?? e.message ?? String(err)).trim();
+    return { out: msg, ok: false };
+  }
+}
+
+/**
+ * Run all pre-flight checks for a release from the given repo root.
+ * Never throws — all errors are captured into per-check `message` fields.
+ */
+export function runPreflightChecks(repoRoot: string): PreflightResult {
+  const checks: PreflightCheck[] = [];
+
+  // Helper to add a check result
+  function addCheck(
+    id: string,
+    level: CheckLevel,
+    pass: boolean,
+    failMsg: string,
+    passMsg = 'ok',
+  ): void {
+    checks.push({ id, level, status: pass ? 'pass' : 'fail', message: pass ? passMsg : failMsg });
+  }
+
+  // ── Blocking checks ────────────────────────────────────────────────────────
+
+  // 1. on-main: current branch must be main
+  const branch = shell('git rev-parse --abbrev-ref HEAD', repoRoot);
+  const isOnMain = branch.ok && branch.out === 'main';
+  addCheck('on-main', 'blocking', isOnMain, `not on main (current: ${branch.out})`);
+
+  // 2. clean-tree: no uncommitted changes
+  const status = shell('git status --porcelain', repoRoot);
+  const isClean = status.ok && status.out === '';
+  addCheck('clean-tree', 'blocking', isClean, `working tree is dirty: ${status.out || status.out}`);
+
+  // 3. in-sync-with-origin: no commits behind origin/main
+  // Fetch quietly first so we can compare
+  shell('git fetch origin main --quiet', repoRoot);
+  const behind = shell('git rev-list --count HEAD..origin/main', repoRoot);
+  const isSynced = behind.ok && behind.out === '0';
+  addCheck(
+    'in-sync-with-origin',
+    'blocking',
+    isSynced,
+    behind.ok ? `${behind.out} commit(s) behind origin/main` : `could not check sync: ${behind.out}`,
+  );
+
+  // 4. valid-version: reference-impl/package.json has a valid semver
+  let version = '';
+  try {
+    const pkgPath = join(repoRoot, 'reference-impl', 'package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8')) as { version?: string };
+    version = pkg.version ?? '';
+  } catch (e: unknown) {
+    const msg = e instanceof Error ? e.message : String(e);
+    addCheck('valid-version', 'blocking', false, `could not read package.json: ${msg}`);
+    version = '';
+  }
+  if (version !== '') {
+    const semverRe = /^\d+\.\d+\.\d+(-[\w.]+)?(\+[\w.]+)?$/;
+    const isValidSemver = semverRe.test(version);
+    addCheck('valid-version', 'blocking', isValidSemver, `invalid semver: '${version}'`, `${version}`);
+  }
+
+  // 5. changelog-section: CHANGELOG.md has a section for this version
+  const tag = version ? `reference-impl-v${version}` : 'reference-impl-v<unknown>';
+  let changelogPass = false;
+  let changelogMsg = 'no version resolved';
+  if (version) {
+    try {
+      const changelogPath = join(repoRoot, 'reference-impl', 'CHANGELOG.md');
+      const changelog = readFileSync(changelogPath, 'utf-8');
+      // Look for a heading like "## 0.6.5" or "## [0.6.5]"
+      const pattern = new RegExp(`^##\\s+\\[?${version.replace(/\./g, '\\.')}`, 'm');
+      changelogPass = pattern.test(changelog);
+      changelogMsg = changelogPass
+        ? `section for ${version} found`
+        : `no ## ${version} section found in CHANGELOG.md`;
+    } catch (e: unknown) {
+      const msg = e instanceof Error ? e.message : String(e);
+      changelogMsg = `could not read CHANGELOG.md: ${msg}`;
+    }
+  }
+  addCheck('changelog-section', 'blocking', changelogPass, changelogMsg, changelogMsg);
+
+  // 6. tag-absent: the release tag must not already exist
+  let tagAbsent = false;
+  let tagMsg = 'no version resolved';
+  if (version) {
+    const localTag = shell(`git tag -l "${tag}"`, repoRoot);
+    const remoteTag = shell(`git ls-remote --tags origin "${tag}"`, repoRoot);
+    const existsLocally = localTag.ok && localTag.out !== '';
+    const existsRemotely = remoteTag.ok && remoteTag.out !== '';
+    tagAbsent = !existsLocally && !existsRemotely;
+    if (existsLocally && existsRemotely) {
+      tagMsg = `tag ${tag} already exists locally and on origin`;
+    } else if (existsLocally) {
+      tagMsg = `tag ${tag} already exists locally`;
+    } else if (existsRemotely) {
+      tagMsg = `tag ${tag} already exists on origin`;
+    } else {
+      tagMsg = `tag ${tag} is absent (ok)`;
+    }
+  }
+  addCheck('tag-absent', 'blocking', tagAbsent, tagMsg, tagMsg);
+
+  // ── Warning checks ─────────────────────────────────────────────────────────
+
+  // 7. npm-authenticated: `npm whoami` must exit 0
+  const npmAuth = shell('npm whoami', repoRoot);
+  addCheck(
+    'npm-authenticated',
+    'warning',
+    npmAuth.ok,
+    `npm not authenticated: ${npmAuth.out}`,
+    `logged in as ${npmAuth.out}`,
+  );
+
+  // 8. gh-authenticated: `gh auth status` must exit 0
+  const ghAuth = shell('gh auth status', repoRoot);
+  addCheck(
+    'gh-authenticated',
+    'warning',
+    ghAuth.ok,
+    `gh not authenticated: ${ghAuth.out}`,
+    'gh CLI authenticated',
+  );
+
+  // Derive release notes from CHANGELOG section
+  let notes = '';
+  if (version) {
+    try {
+      const changelogPath = join(repoRoot, 'reference-impl', 'CHANGELOG.md');
+      const changelog = readFileSync(changelogPath, 'utf-8');
+      const pattern = new RegExp(`^##\\s+\\[?${version.replace(/\./g, '\\.')}[^\\n]*\\n([\\s\\S]*?)(?=^##\\s|$)`, 'm');
+      const m = changelog.match(pattern);
+      notes = m ? m[1].trim() : '';
+    } catch {
+      notes = '';
+    }
+  }
+
+  return { checks, version, tag, notes };
+}

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.5",
   "description": "Reference implementation of the Cloverleaf methodology as Claude Code skills. Implements the Tight Loop (Implementer + Reviewer).",
   "type": "module",
   "license": "MIT",

package/prompts/qa.md

@@ -77,7 +77,7 @@ The Standard's QA contract requires a `preview_uri`. You were passed the sentine
 
 After executing all matched QA rules, write an HTML report summarizing each run to `<repoRoot>/.cloverleaf/runs/{taskId}/qa/report.html` (substitute `{taskId}` with the `id` field from the task input, e.g., `{{task.id}}`).
 
-Use `renderQaReport(runs)` from `lib/qa-report.ts` to produce the HTML. Ensure the directory exists first (`mkdir -p`).
+Use `renderQaReport(runs)` from `lib/qa-report.ts` to produce the HTML. The compiled artifact is at `<repoRoot>/reference-impl/dist/qa-report.mjs` — invoke via `node --input-type=module` or import from there. Ensure the output directory exists first (`mkdir -p`).
 
 In the feedback you emit, include the report as an attachment on a single info-level finding (or on whichever summary finding you already emit):
 

package/skills/cloverleaf-release/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: cloverleaf-release
+description: Publish a new @cloverleaf/reference-impl release. Runs pre-flight checks, displays the 5-command release plan, and executes git tag -a / git push origin main / git push origin <tag> / npm publish / gh release create. Accepts [--dry-run] [--yes] flags.
+---
+
+# Cloverleaf — release
+
+The user has invoked this skill, optionally with `--dry-run` and/or `--yes`.
+
+## Args
+
+- `--dry-run` — print the pre-flight check list and the 5-command release plan, then exit 0 without executing any release command.
+- `--yes` — skip the interactive `y/N` prompt and execute the 5 commands unattended.
+
+## Steps
+
+1. **Parse flags.** Extract `--dry-run` and `--yes` from the invocation arguments if present.
+
+2. **Capture the repo root.**
+
+   ```bash
+   REPO_ROOT=$(git rev-parse --show-toplevel)
+   ```
+
+3. **Run pre-flight checks.**
+
+   ```bash
+   PREFLIGHT=$(cloverleaf-cli release-preflight "$REPO_ROOT" --json)
+   ```
+
+   Parse the JSON. Extract `version`, `tag`, and `notes`.
+
+4. **Display pre-flight check list.** For each check in `checks[]`:
+
+   - Status `pass` → prefix `✓`
+   - Status `fail` and level `warning` → prefix `⚠`
+   - Status `fail` and level `blocking` → prefix `✗`
+
+   Print one line per check: `<prefix> <id>: <message>`
+
+5. **Bail on any blocking failure.**
+
+   If any check has `level === "blocking"` and `status === "fail"`, print:
+
+   ```
+   ✗ Pre-flight failed — fix the issues above before releasing.
+   ```
+
+   And exit 1.
+
+6. **Display release plan.**
+
+   Print:
+
+   ```
+   Release plan for <tag>:
+     1. git tag -a <tag> -m "Release <tag>"
+     2. git push origin main
+     3. git push origin <tag>
+     4. cd reference-impl && npm publish --access public
+     5. gh release create <tag> --notes-file /tmp/release-notes-$VERSION.md
+
+   Version: <version>
+   Notes preview:
+   <notes (first 10 lines or "(no notes)" if empty)>
+   ```
+
+7. **If `--dry-run`:** Print `Dry run complete — no release commands executed.` and exit 0.
+
+8. **If not `--yes`:** Prompt:
+
+   ```
+   Proceed with release of <tag>? (y/N)
+   ```
+
+   Read a single line from the user. If the response is not `y` or `Y`, print `Aborted.` and exit 0.
+
+9. **Write the release notes file.**
+
+   ```bash
+   VERSION=<version>
+   printf '%s' "$NOTES" > /tmp/release-notes-$VERSION.md
+   ```
+
+10. **Execute the 5 release commands sequentially, bail-fast on first non-zero exit.**
+
+    ```bash
+    git tag -a "reference-impl-v$VERSION" -m "Release reference-impl-v$VERSION"
+    git push origin main
+    git push origin "reference-impl-v$VERSION"
+    cd reference-impl && npm publish --access public
+    gh release create "reference-impl-v$VERSION" --notes-file "/tmp/release-notes-$VERSION.md"
+    ```
+
+    If any command fails, print `✗ Release failed at step N: <command>` and exit 1.
+
+11. **Report success.**
+
+    ```
+    ✓ Released reference-impl-v<version>
+    ```
+
+## Rules
+
+- Never skip pre-flight checks, even with `--yes`.
+- Warning-level check failures (`⚠`) do not block execution — they are informational only.
+- Do NOT modify `.cloverleaf/` — this skill only releases, it does not change task state.
+- The skill's working directory is the consumer's repo root.
+- Do not use hardcoded plugin paths — use `cloverleaf-cli` for all CLI invocations.

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
@@ -81,6 +99,7 @@ description: Autonomous DAG walker for Cloverleaf Plans. Given a PLAN-ID in stat
       mkdir -p "$(dirname "$WT")"
       rm -rf "$WT"  # idempotent: clean any leftover from a prior run
       git -C <repo_root> worktree add "$WT" -b cloverleaf/<TASK-ID> main
+      cloverleaf-cli prep-worktree <repo_root> "$WT"
       ```
 
       Then `mcp__claw-drive__start_session` with:
@@ -92,7 +111,7 @@ description: Autonomous DAG walker for Cloverleaf Plans. Given a PLAN-ID in stat
 
       Record the returned `session_id`, `worktree_path`, and `branch_name` in walk-state with `state: "running"`, `started_at: <now>`, `last_seq: 0`. Persist via `walk-state-write`.
 
-   c. **Monitor live sessions.** Start `claw-drive watch <session_id> --since <last_seq>` for each running session. Merge the streams into a single notification feed (e.g., the Monitor tool, or `claw-drive watch` run per-session in the background with a filter).
+   c. **Monitor live sessions.** Start `claw-drive watch <session_id> --since <last_seq> --idle-after 600` for each running session. Merge the streams into a single notification feed (e.g., the Monitor tool, or `claw-drive watch` run per-session in the background with a filter). The `--idle-after 600` flag instructs claw-drive to emit a synthetic `idle` event if a session produces no output for 600 seconds (10 minutes), enabling the walker to detect stalled sessions without polling.
 
    d. **Handle events.**
 
@@ -103,7 +122,12 @@ description: Autonomous DAG walker for Cloverleaf Plans. Given a PLAN-ID in stat
         > To unstick: read feedback at `.cloverleaf/feedback/<TASK-ID>-*.json`, fix the issue, and run `/cloverleaf-run <TASK-ID>` manually. The walker will re-check on its next tick — when the task reaches `merged`, it'll pick up descendants automatically.
         Mark the task `state: "escalated"` in walk-state; do NOT queue it behind final-gate approvals; continue other branches.
       - **session_stopped** → reconcile as in step 4.
-      - **Per-session idle > 30 min** → surface to user for inspection; do NOT auto-kill.
+      - **idle** (`silent_for_ms >= 600000`) → the session has been silent for 10 minutes. For each child session emitting this event, check whether it has reached a terminal state:
+        ```bash
+        claw-drive status <child_session_id>
+        ```
+        Read `last_token` from the status response. If `last_token` is `[DONE]` **or** the on-disk task status (`.cloverleaf/tasks/<TASK-ID>.json`) is `final-gate` or `automated-gates`, treat the session as terminal and proceed with drain (same as `session_stopped` → stopped cleanly). If neither condition is met, surface to the user for inspection; do NOT auto-kill.
+      - **Per-session idle > 30 min** (no `idle` event received, wall-clock elapsed) → surface to user for inspection; do NOT auto-kill.
 
    e. **Drain the final-gate queue serially and merge on main.** Session B does NOT invoke `/cloverleaf-merge` — it stops at automated-gates (fast lane) or final-gate (full pipeline) and reports. The walker performs the merge on main in the primary repo. For each queued task: