create-claude-cabinet 0.44.0 → 0.45.0

package/templates/mux/config/worktree-dirty-check.sh

@@ -0,0 +1,128 @@
+#!/bin/bash
+# worktree-dirty-check.sh — shared dirty-worktree detection.
+#
+# Single source of truth for "does this worktree have real changes?"
+# (one implementation, callers delegate — see .claude/rules/maintainability.md).
+#
+# Callers:
+#   - bin/mux worktree_cleanup()   (interactive `mux worktree cleanup`)
+#   - worktree-cleanup.sh          (fire-and-forget tmux pane-exited hook,
+#                                   which SILENTLY DELETES clean worktrees)
+#
+# Usage:
+#   worktree-dirty-check.sh <wt_path> <proj_path>
+#
+# stdout (single line, space-separated key=value):
+#   commits=<n|?> uncommitted=<n|?> verdict=<clean|dirty>
+#
+# Exit code: 0 whenever a verdict line was printed (even verdict=dirty), so
+# `set -e` callers can command-substitute safely; 2 only on usage error.
+#
+# FAIL-DIRTY SEMANTICS: any count that cannot be determined is reported as
+# "?" and forces verdict=dirty. A worktree is never classified clean — and
+# therefore never deleted — on the strength of a failed check. Callers must
+# apply the same rule when this helper itself is missing or its output is
+# unparseable: degrade to dirty, never abort silently and never delete.
+#
+# EXCLUSION CONTRACT (shell side) ---------------------------------------------
+# The dirty verdict ignores ONLY known CC-infrastructure churn that mux
+# itself manufactures in every worktree:
+#
+#   1. Untracked .claude/ infra — mux copies .claude/ (skills, agents,
+#      settings) into each worktree; git-exclude rules hide most of it, but
+#      an untracked `.claude/` dir or stray infra file is still churn.
+#      EXCEPTION: untracked files under any top-level .claude/ entry that
+#      holds TRACKED files (plans/, methodology/, rules/, cabinet/, …) are
+#      AUTHORED PROJECT RECORD (.claude/rules/artifacts-of-thought.md) and
+#      always count as dirty. The authored set is derived from the worktree's
+#      index at run time; if it can't be read, the static plans/methodology
+#      floor applies (fail-dirty, never fail-clean).
+#
+#   2. .mcp.json / .claudeignore typechange (` T`) — mux replaces these
+#      tracked files with symlinks to the main repo. A genuinely MODIFIED
+#      tracked .mcp.json (` M`) is real work and counts as dirty (the old
+#      cleanup-hook regex matched any line containing `.mcp.json`, which let
+#      a worktree with a real .mcp.json edit be silently deleted).
+#
+#   3. Untracked `node_modules` SYMLINK churn — mux symlinks node_modules
+#      from the main checkout into each worktree (MCP servers need it). The
+#      project's `.gitignore` typically reads `node_modules/` (trailing
+#      slash), which matches only DIRECTORIES — a symlink shows up as
+#      `?? node_modules` and made every mux-created worktree permanently
+#      dirty, so auto-cleanup never fired (found live 2026-06-11, QA pass).
+#      Excluding any untracked node_modules entry is safe: its contents are
+#      never project record, so there is no work to lose.
+#
+#   4. Lockfile MODIFICATION — package-lock.json (and yarn/pnpm/bun lockfiles)
+#      show modified in worktrees because npm rewrites `file:` dependency
+#      paths to the worktree's directory depth (memory:
+#      lesson_worktree_lockfile_false_dirty). Only modified-in-place lockfile
+#      lines are excluded; added/deleted/renamed lockfiles count as dirty.
+#      TRADEOFF (documented, accepted): an intentional, uncommitted,
+#      lockfile-ONLY edit is mechanically indistinguishable from this churn
+#      and classifies as clean (deletable). In practice intentional dependency
+#      changes also touch package.json (which counts as dirty); without this
+#      exclusion every npm-touching worktree is immortal.
+#
+# JS-SIDE PARALLEL: the watchtower ring scripts (.mjs) carry their own
+# porcelain dirty checks with their own exclusion sets. They are a parallel
+# implementation owned by a separate plan and intentionally NOT consolidated
+# here yet. When the JS side converges, this header is the canonical
+# exclusion contract to cite.
+#
+# Matching is regex against whole porcelain lines — never positional column
+# slicing (memory: lesson_worktree_dirty_detection_artifacts).
+# -----------------------------------------------------------------------------
+
+set -uo pipefail  # deliberately NOT -e: every failure degrades to fail-DIRTY
+
+wt_path="${1:-}"
+proj_path="${2:-}"
+if [[ -z "$wt_path" || -z "$proj_path" ]]; then
+  echo "usage: worktree-dirty-check.sh <wt_path> <proj_path>" >&2
+  exit 2
+fi
+
+# Known CC-infrastructure churn (see EXCLUSION CONTRACT above).
+INFRA_CHURN_RE='^\?\? \.claude/?$|^\?\? \.claude/|^.T \.mcp\.json$|^.T \.claudeignore$|^\?\? node_modules/?$|^[M ][M ] (.*/)?(package-lock\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lockb)$'
+# Authored records re-included after the untracked-.claude exclusion
+# (ERE has no negative lookahead, so this is a second counting pass).
+# Any top-level .claude/ entry holding tracked files is authored; the static
+# plans/methodology pair is the fallback floor when the index can't be read.
+AUTHORED_RECORD_RE='^\?\? \.claude/(plans|methodology)/'
+if [[ -n "$wt_path" ]] && authored_dirs=$(git -C "$wt_path" ls-files '.claude/' 2>/dev/null \
+    | cut -d/ -f2 | sort -u | paste -sd'|' -) && [[ -n "$authored_dirs" ]]; then
+  AUTHORED_RECORD_RE="^\\?\\? \\.claude/(${authored_dirs})(/|\$)"
+fi
+
+commits="?"
+uncommitted="?"
+
+if [[ -d "$wt_path" ]] && git -C "$wt_path" rev-parse --git-dir >/dev/null 2>&1; then
+  main_head=$(git -C "$proj_path" rev-parse HEAD 2>/dev/null) || main_head=""
+  if [[ -n "$main_head" ]]; then
+    base=$(git -C "$wt_path" merge-base HEAD "$main_head" 2>/dev/null) || base=""
+    if [[ -n "$base" ]]; then
+      c=$(git -C "$wt_path" rev-list --count "${base}..HEAD" 2>/dev/null) && commits="$c"
+    fi
+  fi
+  # --untracked-files=all: without it, a fully-untracked .claude/ collapses
+  # to a single '?? .claude/' line, hiding any authored .claude/plans/ or
+  # .claude/methodology/ doc inside it from AUTHORED_RECORD_RE — a brand-new
+  # uncommitted design record would be invisible and the worktree deletable.
+  if porcelain=$(git -C "$wt_path" status --porcelain --untracked-files=all 2>/dev/null); then
+    if [[ -z "$porcelain" ]]; then
+      uncommitted=0
+    else
+      non_churn=$(grep -cvE "$INFRA_CHURN_RE" <<<"$porcelain") || true
+      authored=$(grep -cE "$AUTHORED_RECORD_RE" <<<"$porcelain") || true
+      uncommitted=$(( ${non_churn:-0} + ${authored:-0} ))
+    fi
+  fi
+fi
+
+verdict="dirty"
+[[ "$commits" == "0" && "$uncommitted" == "0" ]] && verdict="clean"
+
+printf 'commits=%s uncommitted=%s verdict=%s\n' "$commits" "$uncommitted" "$verdict"
+exit 0

package/templates/mux/config/worktree-session-health.sh

@@ -1,15 +1,20 @@
 #!/bin/bash
 # Worktree health check — single source of truth.
 #
-# Called two ways:
+# Called three ways:
 #   1. CC SessionStart hook (no args) — uses $PWD, exits silently outside worktrees
 #   2. mux worktree health (args: proj_path wt_path) — checks a specific worktree
+#   3. mux worktree refresh (args: proj_path wt_path --refresh) — forces an
+#      infra re-sync even when nothing is stale. Refresh delegates here so
+#      the authored-record carve-out (sync_claude_infra) lives in exactly
+#      one place — never a wholesale rm -rf of .claude/.
 #
 # Self-heals all fixable issues. Positive confirmation for every check.
 # Exit codes: 0 = healthy (possibly after auto-fix), 1 = unfixable issue
 
 proj_path="${1:-}"
 wt_path="${2:-}"
+force_refresh="${3:-}"
 
 if [[ -z "$wt_path" ]]; then
   # SessionStart mode — detect from environment
@@ -22,14 +27,18 @@ fi
 passes=()
 fails=()
 
-# .claude/plans/ and .claude/methodology/ are authored project record — real
-# work that must commit from a worktree. Everything else under .claude/ is
-# regenerated infra (skills, agents, settings) that's copied per worktree and
-# must NOT churn or commit. The helpers below keep that line. See
+# Any git-TRACKED file under .claude/ is authored project record — plans,
+# methodology, rules, cabinet docs, anything committed — real work that must
+# commit from a worktree. Only gitignored infra (installed skills, agents,
+# settings copies) is disposable: copied per worktree, refreshed from main,
+# and hidden from status. The helpers below keep that line. See
 # .claude/rules/artifacts-of-thought.md.
 
-# Hide .claude/ infra from the worktree's git status, but keep authored records
-# visible so new design docs / plan specs created in a worktree show and commit.
+# Hide untracked .claude/ infra from the worktree's git status, but negate
+# every top-level entry that holds tracked (authored) files so new docs
+# created beside them stay visible and commit. The managed lines are rebuilt
+# on every run, so the negation set follows what's actually committed (and
+# the old static plans/methodology pair migrates automatically).
 exclude_claude_dir() {
   local wp="$1" gd
   gd=$(git -C "$wp" rev-parse --git-dir 2>/dev/null) || return 0
@@ -37,47 +46,62 @@ exclude_claude_dir() {
   mkdir -p "$gd/info"
   local ex="$gd/info/exclude"
   touch "$ex"
-  # Migrate the old wholesale rule, which hid authored records too.
-  if grep -qxF '.claude/' "$ex" 2>/dev/null; then
-    sed -i.bak '/^\.claude\/$/d' "$ex" && rm -f "$ex.bak"
-  fi
-  grep -qxF '.claude/*' "$ex" 2>/dev/null \
-    || printf '%s\n' '.claude/*' '!.claude/plans/' '!.claude/methodology/' >> "$ex"
+  { grep -vE '^(\.claude/\*?|!\.claude/.*)$' "$ex" 2>/dev/null || true; } > "$ex.tmp"
+  echo '.claude/*' >> "$ex.tmp"
+  git -C "$wp" ls-files '.claude/' 2>/dev/null \
+    | awk -F/ 'NF>2 {print "!.claude/" $2 "/"} NF==2 {print "!" $0}' \
+    | sort -u >> "$ex.tmp"
+  mv "$ex.tmp" "$ex"
 }
 
-# Clear git's assume-unchanged bit on authored records so worktree edits to
-# plans/methodology actually commit (mux historically set it wholesale).
+# Clear git's assume-unchanged bit on every tracked .claude/ file — tracked
+# means authored, and authored work must commit from the worktree (mux
+# historically froze all of .claude/, then everything outside plans/ and
+# methodology/; both left edits to tracked files invisible to git).
 unprotect_authored_records() {
-  local wp="$1" f
-  git -C "$wp" ls-files .claude/plans .claude/methodology 2>/dev/null | while IFS= read -r f; do
-    git -C "$wp" update-index --no-assume-unchanged "$f" 2>/dev/null || true
-  done
+  local wp="$1"
+  git -C "$wp" ls-files -z '.claude/' 2>/dev/null \
+    | xargs -0 git -C "$wp" update-index --no-assume-unchanged -- 2>/dev/null || true
 }
 
-# Refresh .claude/ INFRA from main, one top-level entry at a time, never
-# touching the authored-record dirs (preserve the worktree's own tracked
-# plans/ and methodology/, including uncommitted edits).
+# Refresh .claude/ INFRA from main without touching authored record. Authored
+# = tracked in main's index; it syncs via git (merge main), never a file copy
+# that could clobber uncommitted worktree edits. A pure-infra entry (no
+# tracked files) is replaced wholesale so deletions in main reconcile; an
+# entry holding tracked files gets a per-file copy of only the untracked
+# infra inside it — no deletes, tracked files never overwritten.
 sync_claude_infra() {
-  local sp="$1" wp="$2" entry name
+  local sp="$1" wp="$2" entry name rel entry_tracked
   mkdir -p "$wp/.claude"
   for entry in "$sp/.claude"/*; do
     [[ -e "$entry" ]] || continue
     name=$(basename "$entry")
-    [[ "$name" == "plans" || "$name" == "methodology" ]] && continue
+    entry_tracked=$(git -C "$sp" ls-files ".claude/$name" 2>/dev/null)
+    if [[ -n "$entry_tracked" ]]; then
+      if [[ -d "$entry" ]]; then
+        (cd "$sp" && find ".claude/$name" -type f 2>/dev/null) | while IFS= read -r rel; do
+          grep -qxF "$rel" <<<"$entry_tracked" && continue
+          mkdir -p "$wp/$(dirname "$rel")"
+          cp "$sp/$rel" "$wp/$rel"
+        done
+      fi
+      continue
+    fi
     rm -rf "$wp/.claude/$name"
     cp -R "$entry" "$wp/.claude/$name"
   done
 }
 
 # 1. .claude/ must be a local copy, not a symlink. Infra is refreshed from
-#    main; authored records (plans/methodology) stay as the worktree's own
-#    git-tracked files, restored from HEAD if a prior wipe lost them.
+#    main; authored records (all tracked .claude/ files) stay as the
+#    worktree's own git-tracked files, restored from HEAD if a prior wipe
+#    lost them.
 if [[ -L "$wt_path/.claude" ]]; then
   if [[ -d "$proj_path/.claude" ]]; then
     rm -f "$wt_path/.claude"
     mkdir -p "$wt_path/.claude"
     unprotect_authored_records "$wt_path"
-    git -C "$wt_path" checkout -- .claude/plans .claude/methodology 2>/dev/null || true
+    git -C "$wt_path" checkout -- .claude/ 2>/dev/null || true
     sync_claude_infra "$proj_path" "$wt_path"
     exclude_claude_dir "$wt_path"
     passes+=("✓ .claude/ auto-fixed: was symlink, now local copy (path isolation restored)")
@@ -92,7 +116,7 @@ elif [[ -d "$wt_path/.claude" ]]; then
 elif [[ -d "$proj_path/.claude" ]]; then
   mkdir -p "$wt_path/.claude"
   unprotect_authored_records "$wt_path"
-  git -C "$wt_path" checkout -- .claude/plans .claude/methodology 2>/dev/null || true
+  git -C "$wt_path" checkout -- .claude/ 2>/dev/null || true
   sync_claude_infra "$proj_path" "$wt_path"
   exclude_claude_dir "$wt_path"
   passes+=("✓ .claude/ auto-fixed: was missing, copied from main repo")
@@ -122,17 +146,20 @@ else
   fails+=("⚠ Identity link missing and main project identity not found")
 fi
 
-# 4. .claude/ INFRA freshness — any infra file in main newer than the worktree
-#    copy. Authored records are excluded: they sync via git (merge main), never
-#    a file copy that could clobber uncommitted worktree edits.
+# 4. .claude/ INFRA freshness — any untracked (infra) file in main newer than
+#    the worktree copy. Tracked files are excluded: they're authored record,
+#    synced via git (merge main), never a file copy that could clobber
+#    uncommitted worktree edits.
 if [[ -d "$proj_path/.claude" ]] && [[ -d "$wt_path/.claude" ]] && [[ ! -L "$wt_path/.claude" ]]; then
-  stale_count=$(find "$proj_path/.claude" -type f -newer "$wt_path/.claude" \
-    -not -path '*/.claude/plans/*' -not -path '*/.claude/methodology/*' 2>/dev/null | wc -l | tr -d ' ')
-  if [[ "$stale_count" -gt 0 ]]; then
+  stale_count=$( (cd "$proj_path" && find .claude -type f -newer "$wt_path/.claude" 2>/dev/null) \
+    | while IFS= read -r rel; do
+        git -C "$proj_path" ls-files --error-unmatch "$rel" >/dev/null 2>&1 || echo "$rel"
+      done | wc -l | tr -d ' ')
+  if [[ "$stale_count" -gt 0 || "$force_refresh" == "--refresh" ]]; then
     sync_claude_infra "$proj_path" "$wt_path"
     exclude_claude_dir "$wt_path"
     unprotect_authored_records "$wt_path"
-    passes+=("✓ .claude/ infra auto-refreshed ($stale_count file(s) updated; records preserved)")
+    passes+=("✓ .claude/ infra refreshed ($stale_count stale file(s); authored records preserved)")
   else
     passes+=("✓ .claude/ current with main repo")
   fi

package/templates/scripts/__tests__/qa-handoff-aging.e2e.test.mjs

@@ -0,0 +1,108 @@
+// Ring 2 [AGING] fall-through — end-to-end against escalateQueueItems.
+//
+// The recipient gate exempts qa-handoff items from expiry at every terminal
+// (expireItem THROWS on them; runExpiry skips them); ring2's escalation loop
+// must route a 30d+ qa-handoff item to the [AGING] title path instead of
+// expiring it. This is the e2e the gate handoff confessed as verified-by-
+// reading-only (dec-51a67f01 / act:d20df77d).
+//
+// True end-to-end: spawns `watchtower-ring2.mjs --fast` as a subprocess
+// against a hermetic WATCHTOWER_DIR (ANTHROPIC_API_KEY stripped — the
+// enrichment phase degrades via its phase-level catch; escalation is pure
+// local). Differential controls prove the test is sensitive, not vacuous:
+// an equally-aged non-qa item DOES expire, and a fresh qa-handoff item is
+// untouched. QA_AGING_RING2 overrides the script under test for mutation
+// runs (red-then-green verification).
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { tmpdir } from 'node:os';
+import { spawnSync } from 'node:child_process';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const RING2 = process.env.QA_AGING_RING2 || join(here, '..', 'watchtower-ring2.mjs');
+
+const root = mkdtempSync(join(tmpdir(), 'qa-aging-'));
+// Set BEFORE the dynamic import — the lib reads WATCHTOWER_DIR into a module
+// const at load; a static import would silently target the LIVE inbox.
+process.env.WATCHTOWER_DIR = root;
+for (const d of [join('queue', 'items'), 'state', 'logs']) {
+  mkdirSync(join(root, d), { recursive: true });
+}
+writeFileSync(join(root, 'config.json'), '{"schema_version":1,"projects":[]}\n');
+
+const q = await import('../watchtower-queue.mjs');
+
+test.after(() => rmSync(root, { recursive: true, force: true }));
+
+const itemFile = (id) => join(root, 'queue', 'items', `${id}.json`);
+const readBack = (id) => JSON.parse(readFileSync(itemFile(id), 'utf8'));
+
+function makeItem(category, title, agedDays) {
+  // createItem returns the new item's id (a string), not the item object.
+  const id = q.createItem({
+    project: 'test-proj',
+    project_path: '/tmp/test-proj',
+    category,
+    title,
+    summary: 'aging e2e fixture',
+    context_anchor: 'git show abc1234',
+  });
+  if (agedDays > 0) {
+    const j = readBack(id);
+    j.filed_at = new Date(Date.now() - agedDays * 24 * 60 * 60 * 1000).toISOString();
+    writeFileSync(itemFile(id), JSON.stringify(j, null, 2) + '\n');
+  }
+  return id;
+}
+
+function runRing2Fast() {
+  const env = { ...process.env, WATCHTOWER_DIR: root };
+  delete env.ANTHROPIC_API_KEY; // enrichment must degrade, never be exercised
+  return spawnSync(process.execPath, [RING2, '--fast'], {
+    env,
+    encoding: 'utf8',
+    timeout: 60_000,
+  });
+}
+
+test('aged qa-handoff gets [AGING] and never expires; aged non-qa expires; fresh qa untouched; re-run idempotent', () => {
+  const agedQa = makeItem('qa-handoff', 'QA handoff: aged merge', 31);
+  const agedOther = makeItem('knowledge-extraction', 'old knowledge', 31);
+  const freshQa = makeItem('qa-handoff', 'QA handoff: fresh merge', 0);
+
+  const run = runRing2Fast();
+  assert.equal(
+    run.status, 0,
+    `ring2 --fast exited ${run.status}\nstdout: ${run.stdout}\nstderr: ${run.stderr}`
+  );
+  // ring2 exits 0 even on a fatal setup error (the error lands in ring
+  // health) — assert on health too, or a config-rejected run that touched
+  // nothing would masquerade as green.
+  const health = JSON.parse(readFileSync(join(root, 'state', 'ring2-fast-health.json'), 'utf8'));
+  assert.equal(health.status, 'success', `ring2 health: ${health.status} (${health.error})`);
+
+  const qa = readBack(agedQa);
+  assert.equal(qa.status, 'pending', 'aged qa-handoff must NOT expire (QA debt stays surfaced)');
+  assert.ok(qa.title.startsWith('[AGING] '), `aged qa-handoff gets the [AGING] prefix (got: ${qa.title})`);
+
+  // Differential control: same age, non-qa category — expiry path is alive,
+  // so the qa-handoff survival above is the exemption, not a dead loop.
+  const other = readBack(agedOther);
+  assert.equal(other.status, 'expired', 'equally-aged non-qa item expires');
+
+  const fresh = readBack(freshQa);
+  assert.equal(fresh.status, 'pending', 'fresh qa-handoff stays pending');
+  assert.ok(!fresh.title.startsWith('[AGING]'), 'fresh qa-handoff gets no prefix');
+
+  // Idempotency: a second tick must not stack prefixes.
+  const run2 = runRing2Fast();
+  assert.equal(run2.status, 0, `second ring2 run exited ${run2.status}\nstderr: ${run2.stderr}`);
+  assert.ok(
+    !readBack(agedQa).title.startsWith('[AGING] [AGING]'),
+    'no double [AGING] prefix on re-run'
+  );
+});