create-claude-cabinet 0.42.0 → 0.43.0

package/lib/cli.js

@@ -609,15 +609,8 @@ const MODULES = {
     templates: [
       'skills/collab-client',
       'skills/collab-consultant',
-      'skills/engagement',
-      'skills/engagement-progress',
       'skills/engagement-help',
-      'skills/engagement-message',
       'skills/engagement-create',
-      'skills/engagement-edit',
-      'skills/engagement-add',
-      'skills/engagement-status',
-      'skills/engagement-sync',
       'skills/setup-accounts',
       'skills/guide',
       'engagement',
@@ -635,7 +628,6 @@ const MODULES = {
       'scripts/watchtower-lib.mjs',
       'scripts/watchtower-queue.mjs',
       'skills/inbox',
-      'skills/decisions',
       'hooks/watchtower-session-start.sh',
       'scripts/watchtower-build-context.mjs',
       'scripts/watchtower-ring1.mjs',
@@ -657,6 +649,7 @@ const MODULES = {
       'scripts/watchtower-status.sh',
       'skills/briefing',
       'skills/threads',
+      'skills/qa-handoff',
     ],
   },
   mux: {
@@ -666,7 +659,7 @@ const MODULES = {
     default: false,
     lean: false,
     postInstall: 'mux-setup',
-    templates: ['skills/orient/phases/dx-captures.md'],
+    templates: ['skills/orient/phases/dx-captures.md', 'skills/dx-feedback'],
   },
   'engagement-server': {
     name: 'Engagement Server',

package/lib/engagement-setup.js

@@ -177,7 +177,7 @@ function setupEngagement({ dryRun, projectDir } = {}) {
           target_fid    TEXT,
           packet_id     TEXT,
           kind          TEXT NOT NULL
-                          CHECK(kind IN ('client_feedback','status_push','delegation','approval','note','packet_sent')),
+                          CHECK(kind IN ('client_feedback','status_push','delegation','approval','note','packet_sent','packet_opened')),
           author        TEXT NOT NULL,
           verdict       TEXT CHECK(verdict IS NULL OR verdict IN ('approve','object','comment','none')),
           body          TEXT CHECK(body IS NULL OR length(body) <= 10000),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-claude-cabinet",
-  "version": "0.42.0",
+  "version": "0.43.0",
   "description": "Claude Cabinet — opinionated process scaffolding for Claude Code projects",
   "bin": {
     "create-claude-cabinet": "bin/create-claude-cabinet.js"

package/templates/engagement/pib-db-patches/pib-db-schema.sql

@@ -114,7 +114,7 @@ CREATE TABLE IF NOT EXISTS engagement_events (
   target_fid    TEXT,
   packet_id     TEXT,
   kind          TEXT NOT NULL
-                  CHECK(kind IN ('client_feedback','status_push','delegation','approval','note','packet_sent')),
+                  CHECK(kind IN ('client_feedback','status_push','delegation','approval','note','packet_sent','packet_opened')),
   author        TEXT NOT NULL,
   verdict       TEXT CHECK(verdict IS NULL OR verdict IN ('approve','object','comment','none')),
   body          TEXT CHECK(body IS NULL OR length(body) <= 10000),

package/templates/mux/bin/mux

@@ -227,19 +227,37 @@ create_worktree() {
     }
   }
 
-  # Copy .claude/ into worktree so CC sees worktree-local paths in its
-  # system context. A symlink here causes CC to resolve through to the
-  # main repo path, leaking it into every Read/Edit/Write call.
-  git -C "$wt_path" ls-files .claude/ 2>/dev/null | while IFS= read -r f; do
-    git -C "$wt_path" update-index --assume-unchanged "$f" 2>/dev/null || true
-  done
+  # Copy .claude/ infra into the worktree so CC sees worktree-local paths in
+  # its system context (a symlink makes CC resolve through to the main repo
+  # path, leaking it into every Read/Edit/Write). EXCEPT the authored project
+  # record — .claude/plans/ and .claude/methodology/ — which is real work that
+  # must commit from the worktree. Those stay as normal git-tracked files,
+  # left exactly as `git worktree add` checked them out from HEAD. See
+  # .claude/rules/artifacts-of-thought.md.
+  git -C "$wt_path" ls-files .claude/ 2>/dev/null \
+    | grep -vE '^\.claude/(plans|methodology)/' \
+    | while IFS= read -r f; do
+        git -C "$wt_path" update-index --assume-unchanged "$f" 2>/dev/null || true
+      done
   if [[ -d "$proj_path/.claude" ]]; then
-    rm -rf "$wt_path/.claude"
-    cp -R "$proj_path/.claude" "$wt_path/.claude"
-    # Exclude copied .claude/ from worktree's git status (it's infra, not work)
+    # Refresh infra subdirs from main, one top-level entry at a time, never
+    # the authored-record dirs (leave the worktree's HEAD-checked-out copies).
+    local entry name
+    for entry in "$proj_path"/.claude/*; do
+      [[ -e "$entry" ]] || continue
+      name=$(basename "$entry")
+      [[ "$name" == "plans" || "$name" == "methodology" ]] && continue
+      rm -rf "$wt_path/.claude/$name"
+      cp -R "$entry" "$wt_path/.claude/$name"
+    done
+    # Hide infra from the worktree's git status, but keep authored records
+    # visible so new design docs created in a worktree show up and commit.
     local wt_gitdir
     wt_gitdir=$(git -C "$wt_path" rev-parse --git-dir 2>/dev/null)
-    [[ -n "$wt_gitdir" ]] && mkdir -p "$wt_gitdir/info" && echo '.claude/' >> "$wt_gitdir/info/exclude"
+    if [[ -n "$wt_gitdir" ]]; then
+      mkdir -p "$wt_gitdir/info"
+      { echo '.claude/*'; echo '!.claude/plans/'; echo '!.claude/methodology/'; } >> "$wt_gitdir/info/exclude"
+    fi
   fi
   for f in .mcp.json .claudeignore; do
     [[ -f "$proj_path/$f" ]] && ln -sf "$proj_path/$f" "$wt_path/$f"

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

@@ -22,27 +22,78 @@ 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
+# .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.
 exclude_claude_dir() {
-  local wp="$1"
-  local gd
-  gd=$(git -C "$wp" rev-parse --git-dir 2>/dev/null)
-  [[ -n "$gd" ]] && mkdir -p "$gd/info" && grep -q '^\.claude/$' "$gd/info/exclude" 2>/dev/null || echo '.claude/' >> "$gd/info/exclude"
+  local wp="$1" gd
+  gd=$(git -C "$wp" rev-parse --git-dir 2>/dev/null) || return 0
+  [[ -n "$gd" ]] || return 0
+  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"
+}
+
+# Clear git's assume-unchanged bit on authored records so worktree edits to
+# plans/methodology actually commit (mux historically set it wholesale).
+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
 }
 
-# 1. .claude/ must be a local copy, not a symlink
+# 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).
+sync_claude_infra() {
+  local sp="$1" wp="$2" entry name
+  mkdir -p "$wp/.claude"
+  for entry in "$sp/.claude"/*; do
+    [[ -e "$entry" ]] || continue
+    name=$(basename "$entry")
+    [[ "$name" == "plans" || "$name" == "methodology" ]] && continue
+    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.
 if [[ -L "$wt_path/.claude" ]]; then
   if [[ -d "$proj_path/.claude" ]]; then
     rm -f "$wt_path/.claude"
-    cp -R "$proj_path/.claude" "$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
+    sync_claude_infra "$proj_path" "$wt_path"
     exclude_claude_dir "$wt_path"
     passes+=("✓ .claude/ auto-fixed: was symlink, now local copy (path isolation restored)")
   else
     fails+=("⚠ .claude/ is a symlink and main repo has no .claude/ to copy from")
   fi
 elif [[ -d "$wt_path/.claude" ]]; then
+  # Heal existing worktrees: un-freeze authored records + migrate the exclude.
+  unprotect_authored_records "$wt_path"
+  exclude_claude_dir "$wt_path"
   passes+=("✓ .claude/ is a local copy (path isolation intact)")
 elif [[ -d "$proj_path/.claude" ]]; then
-  cp -R "$proj_path/.claude" "$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
+  sync_claude_infra "$proj_path" "$wt_path"
   exclude_claude_dir "$wt_path"
   passes+=("✓ .claude/ auto-fixed: was missing, copied from main repo")
 else
@@ -71,14 +122,17 @@ else
   fails+=("⚠ Identity link missing and main project identity not found")
 fi
 
-# 4. .claude/ freshness — any file in main newer than the worktree copy
+# 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.
 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" 2>/dev/null | wc -l | tr -d ' ')
+  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
-    rm -rf "$wt_path/.claude"
-    cp -R "$proj_path/.claude" "$wt_path/.claude"
+    sync_claude_infra "$proj_path" "$wt_path"
     exclude_claude_dir "$wt_path"
-    passes+=("✓ .claude/ auto-refreshed ($stale_count file(s) updated from main repo)")
+    unprotect_authored_records "$wt_path"
+    passes+=("✓ .claude/ infra auto-refreshed ($stale_count file(s) updated; records preserved)")
   else
     passes+=("✓ .claude/ current with main repo")
   fi

package/templates/scripts/watchtower-build-context.mjs

@@ -12,6 +12,7 @@
 
 import { readFileSync, readdirSync, existsSync, statSync, mkdirSync } from 'fs';
 import { join, resolve, basename } from 'path';
+import { currentCursor } from './watchtower-lib.mjs';
 
 const WATCHTOWER_DIR = process.env.WATCHTOWER_DIR
   || join(process.env.HOME, '.claude-cabinet', 'watchtower');
@@ -143,7 +144,7 @@ function renderFocalZoom(threads, projectSlug) {
   // Cursor level: primary thread for this project, full detail
   if (projectThreads.length > 0) {
     const primary = projectThreads[0];
-    const c = primary.cursor || {};
+    const c = currentCursor(primary);
     lines.push(`**${primary.thread}** (primary)`);
     if (c.what) lines.push(`  What: ${c.what}`);
     if (c.why) lines.push(`  Why: ${c.why}`);
@@ -160,7 +161,7 @@ function renderFocalZoom(threads, projectSlug) {
 
   // Thread level: other project threads, one line each
   for (const t of projectThreads.slice(1)) {
-    const what = t.cursor?.what || '';
+    const what = currentCursor(t).what || '';
     const age = t.last_updated?.slice(0, 10) || '?';
     lines.push(`${t.thread}: ${what} (${age})`);
   }
@@ -170,7 +171,7 @@ function renderFocalZoom(threads, projectSlug) {
     lines.push('');
     lines.push('Other active threads:');
     for (const t of otherThreads.slice(0, 5)) {
-      const what = t.cursor?.what || '';
+      const what = currentCursor(t).what || '';
       const proj = t.sessions?.[t.sessions.length - 1]?.project || '?';
       lines.push(`  ${t.thread} [${proj}]: ${what}`);
     }

package/templates/scripts/watchtower-lib.mjs

@@ -66,6 +66,60 @@ export function slugify(text) {
   return text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
 }
 
+// ---------------------------------------------------------------------------
+// Thread cursor history (schema v2)
+// ---------------------------------------------------------------------------
+// A thread's cursor is no longer a single overwritten object; it is an
+// append-only `cursor_history` array of point-in-time snapshots, one per
+// session that advanced the thread. Each entry is
+//   { date, session_id, cursor: { what, why, where_left_off, open_questions,
+//     next_steps } }
+// The "current" cursor is always the last entry. Overwriting threw away the
+// journey (symptom → diagnosis → solution → abstraction); the history keeps it.
+// `cursor_history` is the thread's first sibling timeline — the QA-handoff
+// protocol (.claude/plans/qa-handoff-protocol.md) adds a parallel
+// point-in-time event sibling rather than nesting inside the cursor.
+
+// migrateThreadCursor — convert a legacy (schema v1) thread object that has a
+// single `cursor` field into the v2 `cursor_history` shape, in place.
+// Idempotent: a thread already carrying `cursor_history` is left alone (beyond
+// stripping any stale `cursor` field and bumping the version). The single
+// migrated entry inherits the date/session_id of the thread's most recent
+// session, since the legacy cursor reflected the latest understanding.
+export function migrateThreadCursor(threadData) {
+  if (!threadData || typeof threadData !== 'object') return threadData;
+  if (threadData.schema_version === undefined) threadData.schema_version = 1;
+
+  if (Array.isArray(threadData.cursor_history)) {
+    delete threadData.cursor; // drop any stale legacy field
+    if (threadData.schema_version < 2) threadData.schema_version = 2;
+    return threadData;
+  }
+
+  const legacy = threadData.cursor;
+  const sessions = Array.isArray(threadData.sessions) ? threadData.sessions : [];
+  const last = sessions.length ? sessions[sessions.length - 1] : null;
+  threadData.cursor_history = legacy
+    ? [{
+        date: last?.date || (threadData.last_updated || '').slice(0, 10) || null,
+        session_id: last?.id || null,
+        cursor: legacy,
+      }]
+    : [];
+  delete threadData.cursor;
+  threadData.schema_version = 2;
+  return threadData;
+}
+
+// currentCursor — the most recent cursor snapshot for a thread. Reads the last
+// `cursor_history` entry, falling back to a legacy `cursor` field so consumers
+// stay correct against any un-migrated thread file. Always returns an object.
+export function currentCursor(thread) {
+  const hist = thread?.cursor_history;
+  if (Array.isArray(hist) && hist.length) return hist[hist.length - 1].cursor || {};
+  return thread?.cursor || {};
+}
+
 // ---------------------------------------------------------------------------
 // loadBetterSqlite3 — resolve better-sqlite3 from wherever it actually lives
 // ---------------------------------------------------------------------------

package/templates/scripts/watchtower-ring1.mjs

@@ -396,10 +396,30 @@ function countRealUncommitted(wtPath) {
     if (/(?:^|[\s/])yarn\.lock$/.test(l)) return false;
     if (/(?:^|[\s/])pnpm-lock\.yaml$/.test(l)) return false;
     if (/(?:^|[\s/])bun\.lockb$/.test(l)) return false;
+    if (isMainShadow(l, wtPath)) return false;
     return true;
   }).length;
 }
 
+// A worktree whose HEAD predates a file committed to main shows that file as
+// untracked ("?? path") even though main already owns it — a stale-worktree
+// shadow, not work to lose. (The mux/devex false-alarm: scripts/skill-usage.mjs
+// was added to main after devex branched, so it counted as a "real" uncommitted
+// change and blocked the merged branch from ever auto-resolving.) Exclude an
+// untracked file only when main holds the SAME path with byte-identical content
+// — a genuinely new untracked file, or a modified shadow, still counts, so real
+// work-to-lose still alarms.
+function isMainShadow(porcelainLine, wtPath) {
+  const m = porcelainLine.match(/^\?\?\s+(.+)$/);
+  if (!m) return false;
+  let p = m[1].trim();
+  if (p.startsWith('"') && p.endsWith('"')) p = p.slice(1, -1);
+  const mainBlob = safeExec(`git rev-parse --verify --quiet "main:${p}"`, { cwd: wtPath });
+  if (!mainBlob) return false;
+  const wtBlob = safeExec(`git hash-object "${p}"`, { cwd: wtPath });
+  return !!wtBlob && wtBlob === mainBlob;
+}
+
 // Does a worktree-unmerged item belong to this project? Can't trust
 // item.project_path alone — Ring 3 historically attributed items to the
 // worktree path rather than the project root. Resolve ownership through

package/templates/scripts/watchtower-ring2.mjs

@@ -1048,8 +1048,9 @@ async function absorbThreadSessions(config) {
       continue;
     }
 
-    // Prune old session detail files that are already captured in the thread cursor.
-    // The session entry in the thread's sessions array (with transcript pointer) survives.
+    // Prune old session detail files that are already captured in the thread's
+    // cursor_history. The session entry in the thread's sessions array (with
+    // transcript pointer) survives.
     if (!thread.sessions || thread.sessions.length === 0) continue;
 
     const projects = config.projects || {};

package/templates/scripts/watchtower-ring3-close.mjs

@@ -34,6 +34,7 @@ import {
   atomicWrite, loadConfig, slugify,
   log as _log, logError as _logError,
   getWatchtowerDir, createItem, listPending, loadBetterSqlite3,
+  migrateThreadCursor, currentCursor,
 } from './watchtower-lib.mjs';
 
 const require = createRequire(import.meta.url);
@@ -398,7 +399,7 @@ async function threadCapture(compressed, projectSlug, sessionId, summary, transc
         if (thread.status === 'active') {
           existingThreads.push({
             id: thread.thread,
-            what: thread.cursor?.what || '',
+            what: currentCursor(thread).what || '',
           });
         }
       } catch { /* skip malformed */ }
@@ -475,12 +476,19 @@ Rules:
     threadIds.push(threadSlug);
     const threadPath = join(threadsDir, `${threadSlug}.json`);
 
+    // One cursor snapshot per session that advanced this thread — appended,
+    // never overwritten (see migrateThreadCursor / cursor_history in
+    // watchtower-lib.mjs). The qa_handoff payload is a future SIBLING of this
+    // history, not a field inside the cursor (qa-handoff-protocol.md).
+    const cursorEntry = { date, session_id: sessionId, cursor: t.cursor };
+
     let threadData;
     if (existsSync(threadPath) && !t.is_new) {
       threadData = JSON.parse(readFileSync(threadPath, 'utf8'));
-      // Heal pre-versioning thread files (watchtower-contracts.md §Schema Versioning)
-      if (threadData.schema_version === undefined) threadData.schema_version = 1;
-      threadData.cursor = t.cursor;
+      // Heal pre-versioning + legacy single-cursor files into cursor_history
+      // (watchtower-contracts.md §Schema Versioning).
+      migrateThreadCursor(threadData);
+      threadData.cursor_history.push(cursorEntry);
       if (t.display_name) threadData.display_name = t.display_name;
       threadData.last_updated = now;
       threadData.sessions.push({
@@ -493,10 +501,10 @@ Rules:
       });
     } else {
       threadData = {
-        schema_version: 1,
+        schema_version: 2,
         thread: threadSlug,
         display_name: t.display_name || threadSlug,
-        cursor: t.cursor,
+        cursor_history: [cursorEntry],
         sessions: [{
           id: sessionId,
           contribution: t.contribution || '',

package/templates/scripts/watchtower-status.sh

@@ -21,6 +21,15 @@ json_field() {
   node -p "try{JSON.parse(require('fs').readFileSync('$file','utf8'))${field}}catch{}" 2>/dev/null
 }
 
+# Read a field off a thread's CURRENT cursor (last cursor_history entry),
+# falling back to a legacy single `cursor` field for un-migrated thread files.
+# Mirrors currentCursor() in watchtower-lib.mjs. Returns '' when absent.
+current_cursor_field() {
+  local file="$1" sub="$2"
+  [ -f "$file" ] || return 1
+  node -p "try{const t=JSON.parse(require('fs').readFileSync('$file','utf8'));const h=t.cursor_history;const c=(Array.isArray(h)&&h.length?h[h.length-1].cursor:t.cursor)||{};c['$sub']??''}catch{}" 2>/dev/null
+}
+
 ts_to_epoch() {
   local ts="${1%%.*}"
   ts="${ts%%Z}"
@@ -226,9 +235,9 @@ if [ "$VERBOSE" = "--verbose" ] || [ "$VERBOSE" = "-v" ]; then
       status=$(json_field "$f" ".status")
       [ "$status" != "active" ] && continue
       slug=$(json_field "$f" ".thread")
-      what=$(json_field "$f" ".cursor?.what" 2>/dev/null || echo "")
+      what=$(current_cursor_field "$f" "what" 2>/dev/null || echo "")
       [ "$what" = "undefined" ] && what=""
-      left_off=$(json_field "$f" ".cursor?.where_left_off" 2>/dev/null || echo "")
+      left_off=$(current_cursor_field "$f" "where_left_off" 2>/dev/null || echo "")
       [ "$left_off" = "undefined" ] && left_off=""
       echo "  $slug"
       [ -n "$what" ] && echo "    $what"

package/templates/scripts/watchtower-validate.mjs

@@ -54,6 +54,7 @@ const VALID_CATEGORIES = [
   'deferred-trigger', 'routing-decision', 'knowledge-extraction', 'methodology-capture',
   'upstream-friction', 'project-completion', 'completion-review', 'branch-diverged',
   'stale-project', 'pattern-promotion', 'watchtower-health', 'worktree-unmerged',
+  'qa-handoff',
 ];
 const VALID_ENRICHMENT = ['bare', 'in-progress', 'complete'];
 const VALID_URGENCY = ['urgent', 'normal', 'low'];

package/templates/skills/briefing/SKILL.md

@@ -94,7 +94,11 @@ project's file.
 ### 1e. Active Threads
 
 Read `state/threads/*.json`. For each thread file, parse the JSON and
-collect threads with `status: "active"`. For each active thread, extract:
+collect threads with `status: "active"`. The **current cursor** is the
+last entry of the `cursor_history` array
+(`cursor_history[length-1].cursor`); older thread files may instead carry
+a single `cursor` object — treat that lone object as the current cursor.
+For each active thread, extract from the current cursor:
 - `thread` (slug name)
 - `cursor.what` (one-line description)
 - `cursor.where_left_off` (current state)

package/templates/skills/debrief/phases/methodology-capture.md

@@ -140,6 +140,19 @@ Structure (flexible — adapt to what the work is):
 Format so it could be pasted into a pitch deck section, an about page,
 an investor update, a collaborator email, or a customer FAQ.
 
+### 3c. Index the new artifacts (required)
+
+These records are version-controlled **project thought-record**, not
+ephemera (see `.claude/rules/artifacts-of-thought.md`). In the same
+change that writes a doc, add an index line for it to
+`.claude/methodology/README.md` — date, title, one-line hook, and a
+link. Create that index file if it doesn't exist yet. An unindexed
+record is an invisible record, and the `/validate`
+`artifacts-of-thought` check fails on any methodology doc git isn't
+tracking — so a doc left unindexed-and-uncommitted will break
+validation. If the project routes output to a custom location (see
+Path override), index it there instead.
+
 ### 4. Integration with the debrief report
 
 At the end of the report phase, surface any methodology artifacts

package/templates/skills/inbox/SKILL.md

@@ -147,6 +147,12 @@ Based on the chosen action:
   - `knowledge-extraction` -- run `/cc-remember` to capture the knowledge
   - `methodology-capture` -- run `/cc-remember` to capture the methodology
   - `completion-review` -- close the action in pib-db if confirmed
+  - `qa-handoff` -- the post-merge QA work for a merged branch. Read
+    `evidence.verification.runtime_needed` and run those named checks on
+    main (e2e, manual flow, deploy smoke); if `evidence.publish.needed`,
+    prepare the publish/deploy command and stop for the operator. Resolve
+    only after the runtime checks pass — never flip a handoff to verified
+    on a static claim.
   - `pattern-promotion` -- item has pre-authored options (write/promote/dismiss):
     - **write**: Read `evidence.target_member`, `evidence.target_project_path`,
       and `evidence.pattern_text` from the item. Write the pattern to

package/templates/skills/qa-handoff/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: qa-handoff
+description: |
+  Package a just-merged worktree session into a QA handoff — the bridge
+  between "worktree work is done" and the post-merge work that can only
+  happen on main (e2e tests against a live server, npm publish, deploy).
+  Writes an operator-level handoff (what merged, what the worktree could
+  NOT verify, what hangs on the next step) to the watchtower inbox so it
+  surfaces and ages until QA happens. Stage 1 of the QA-handoff protocol:
+  this PACKAGES the handoff; it does not yet dispatch it to window 1.
+  Use when: "qa-handoff", "/qa-handoff", "hand off to QA", "package the
+  handoff", or right after merging a worktree branch into main.
+argument-hint: "optional branch — e.g., (none = most recent merge), 'mux/my-branch'"
+---
+
+# /qa-handoff — Package a merge for post-merge QA
+
+Working in a worktree exposes a real gap: a worktree can't do anything
+that depends on the main checkout — e2e tests need a live dev server
+bound to one checkout, `npm publish` needs the main branch, deploy needs
+main. These are all **post-merge** activities, and there's no bridge
+between "the worktree work is merged" and "QA / publish / deploy runs on
+main." This skill builds the handoff that crosses that gap.
+
+Full design: `.claude/plans/qa-handoff-protocol.md`. This skill is
+**stage 1** — it packages a merge into a durable, surfaced handoff. The
+dispatch half (mux poking window 1, pane-state detection, the on-disk
+queue) is a later stage; for now the handoff lands in the inbox and is
+surfaced by `/briefing` until the operator runs QA.
+
+## The verification contract this enforces
+
+A worktree session **cannot** runtime-verify e2e — the dev stack only
+runs from main. So a handoff records two honest states, never one
+overclaimed `verified`:
+
+1. **`statically-validated`** — what the worktree DID check without a
+   live stack: `node -c` / type-check, unit tests, `cucumber --dry-run`,
+   duplicate-step scans, a clean build. Real, but not runtime.
+2. **`runtime-needed`** — what only post-merge QA on main can confirm:
+   e2e scenarios against the live server, a manual flow, a deploy smoke
+   test. The handoff names these; it never claims them done.
+
+The flip to `runtime-verified` is owned by the post-merge QA session
+citing named checks that passed — not by this skill.
+
+## When to run
+
+Right after you merge a worktree branch into main (this repo's
+convention: Claude merges worktree → main). Run it from the main
+checkout or the worktree you just merged from.
+
+## Step 1: Identify what merged
+
+Resolve the merge being handed off:
+
+- **No argument:** the most recent merge into `main`. Find it with
+  `git log --merges -1 --format='%H %s' main`, and the work range with
+  `git log main@{1}..main` if a reflog entry exists, else the merged
+  branch's commits.
+- **`<branch>` argument:** that branch's contribution —
+  `git log --oneline main..<branch>` won't help post-merge (it's 0), so
+  use `git log <branch> --not $(git merge-base main <branch>)~1` or the
+  merge commit's `^1..^2` range.
+
+Collect: the merge/HEAD commit SHA on main, a `--stat` of the diff, and
+the list of changed files. Keep the file list — capability detection and
+the verification split both key off it.
+
+## Step 2: Pull the acceptance criteria
+
+The handoff's value is naming what still needs checking. Gather the AC
+from the work:
+
+1. Scan the merged commit messages for `act:` / `prj:` fids.
+2. For each, read the action from pib-db (`pib_get_action` MCP, or
+   `node scripts/pib-db.mjs get <fid>`) and extract its Acceptance
+   Criteria / Verify Plan.
+3. Mark each AC `statically-validated` (the worktree proved it without a
+   live stack) or `runtime-needed` (only post-merge QA can confirm).
+   When unsure, default to `runtime-needed` — overclaiming is the
+   failure this protocol exists to prevent.
+
+If no fids are referenced, derive the criteria from the diff itself —
+what a reviewer on main would want to confirm still works.
+
+## Step 3: Detect capabilities (what post-merge work this project supports)
+
+The handoff degrades to what the project can actually do. Detect from
+the repo root:
+
+- **e2e:** an `e2e/` dir, `cucumber.*`/`*.feature` files, a Playwright
+  config, or `cabinet-verify` in package.json → e2e applies.
+- **publish:** a publishable npm package (package.json, not `private:
+  true`) or a `/cc-publish` skill present → publish applies.
+- **deploy:** `railway.toml` → Railway; `fly.toml` → Fly; `vercel.json`
+  / `.vercel/` → Vercel; `netlify.toml` → Netlify; else none.
+
+A project with none of these gets a handoff that's purely "here's what
+merged, here's what to eyeball" — that's fine; silence is better than a
+fake gate.
+
+## Step 4: Compose the handoff payload
+
+Build one operator-level object. Reuse the thread-cursor's voice (plain
+English, what a colleague needs to pick this up) — this is the QA
+sibling of the cursor, a point-in-time event, not a field on it:
+
+```json
+{
+  "merged_branch": "mux/<branch>",
+  "merged_commit": "<sha on main>",
+  "merged_into": "main",
+  "date": "YYYY-MM-DD",
+  "session_id": "<this session's id, if known>",
+  "what": "One line: what this work was.",
+  "why": "Why it happened — the motivation.",
+  "what_merged": ["The substantive changes, a few bullets."],
+  "could_not_verify": [
+    "What the worktree could not runtime-verify and post-merge QA must — be specific (which e2e scenario, which flow)."
+  ],
+  "hangs_on": [
+    "What the next step depends on — a publish decision, a deploy, a follow-up act: fid."
+  ],
+  "acceptance_criteria": [
+    {"fid": "act:xxxxxxxx", "text": "...", "state": "statically-validated | runtime-needed"}
+  ],
+  "capabilities": {"e2e": true, "publish": true, "deploy": "railway | fly | vercel | netlify | none"},
+  "verification": {
+    "statically_validated": ["What the worktree DID verify."],
+    "runtime_needed": ["What main must verify, by name."]
+  },
+  "publish": {"needed": true, "command": "the exact publish/deploy command, prepared not run"}
+}
+```
+
+Keep `could_not_verify` and `hangs_on` honest and short. An empty
+`runtime_needed` with `publish.needed: false` is a valid handoff — it
+just says "merged, nothing hangs on it."
+
+## Step 5: File the handoff to the inbox
+
+File it as a `qa-handoff` inbox item. Urgency is `normal` by default —
+reserve `urgent` for a handoff that genuinely blocks (a publish the
+operator is waiting on). Better dark than wrong: a wall of urgent
+handoffs trains the operator to ignore them.
+
+Write the payload to a temp file, then file via the installed queue API:
+
+```bash
+WT="${WATCHTOWER_DIR:-$HOME/.claude-cabinet/watchtower}"
+# 1. Write the createItem args to /tmp/qa-handoff-item.json:
+#    { project, project_path, category: "qa-handoff", urgency,
+#      title, summary, context_anchor, evidence: <the payload above>,
+#      thread_ids: [<linked thread slugs, if known>],
+#      filed_by: "manual" }
+node --input-type=module -e '
+import { readFileSync } from "fs";
+import { createItem } from "'"$WT"'/scripts/watchtower-queue.mjs";
+const args = JSON.parse(readFileSync(process.argv[1], "utf8"));
+console.log("Filed qa-handoff item:", createItem(args));
+' /tmp/qa-handoff-item.json
+```
+
+- `title`: `QA handoff: <what>, merged <short-sha>`
+- `summary`: one line — what merged and what QA must confirm.
+- `context_anchor`: `git show <merged_commit>` (so QA can reconstruct).
+- `thread_ids`: the thread slug(s) this work advanced, if you know them
+  (links the handoff to its cursor history — the sibling relationship).
+  Ring 3 mints threads at session close, so a fresh thread may not exist
+  yet; leave `[]` rather than guessing.
+
+## Step 6: Report to the operator
+
+Tell the operator, plainly:
+- What was handed off (the `what` + merged commit).
+- What QA on main needs to do — the `runtime_needed` list, named.
+- Whether a publish/deploy is staged and waiting on their go.
+- That it's in the inbox and `/briefing` will resurface it until acted
+  on.
+
+Do **not** run the publish or deploy. This skill prepares and stops;
+promotion is an explicit operator decision (and, later, a dispatched
+window-1 step).
+
+## Scope boundary (stage 1)
+
+This skill does NOT poke window 1, detect pane state, or auto-run QA.
+Those are the dispatch stages in `.claude/plans/qa-handoff-protocol.md`.
+What it guarantees today: every merge can be packaged into one honest,
+surfaced, ageable handoff that names what could not be verified from the
+worktree — so nothing silently ships unverified.

package/templates/skills/threads/SKILL.md

@@ -50,11 +50,15 @@ Pure filesystem — no API calls. Read every `*.json` under:
 ```
 
 Ignore any `threads-test/` directory (fixtures). For each thread, you have:
-`thread` (slug), `display_name` (optional, falls back to slug), `cursor`
-(`what`, `why`, `where_left_off`, `open_questions`, `next_steps`),
-`sessions` (append-only log, each with `id`, `date`, `project`, `summary`,
+`thread` (slug), `display_name` (optional, falls back to slug),
+`cursor_history` (append-only array of `{date, session_id, cursor}`
+snapshots — the CURRENT cursor is the last entry's `cursor`, carrying
+`what`, `why`, `where_left_off`, `open_questions`, `next_steps`; the
+earlier entries are the trail of how understanding evolved), `sessions`
+(append-only log, each with `id`, `date`, `project`, `summary`,
 `transcript`), `related_fids`, `lineage` (optional), `last_updated`,
-`status`.
+`status`. Older thread files may still carry a single `cursor` object
+instead of `cursor_history` — treat that lone object as the current cursor.
 
 If the directory is missing or empty, say so plainly ("No threads
 captured yet — watchtower's Ring 3 writes these at session close") and
@@ -87,9 +91,11 @@ in the output. (This is the house style — see the memory
 ### Arc mode (`arc <slug>`)
 
 Tell the story of one thread across its `sessions` in order: how the
-framing (`what`) evolved, the turning points, where it stands now, and
-its `lineage` if present (what it grew out of, what it merged into). End
-with the open questions and next steps.
+framing (`what`) evolved — `cursor_history` records this directly, one
+snapshot per session, so walk the entries in sequence rather than
+inferring the arc — the turning points, where it stands now, and its
+`lineage` if present (what it grew out of, what it merged into). End
+with the current cursor's open questions and next steps.
 
 ### Connections mode
 
@@ -124,7 +130,7 @@ any of these smells:
 - **Drift** — a `display_name`/`what` that no longer matches what the
   recent sessions are actually about.
 - **Orphans** — sessions referenced but missing transcripts, or threads
-  with an empty cursor.
+  with an empty `cursor_history`.
 
 If the threads look well-segmented, say so in one line. If they don't,
 name the specific threads and suggest the fix is a re-sort

package/templates/skills/validate/phases/validators.md

@@ -147,6 +147,40 @@ values (must be high|moderate|info), invalid tags (must be run|review).
 Exits 0 silently if qa-dimensions.yaml doesn't exist (the checklist
 engine is opt-in).
 
+### artifacts-of-thought
+
+```bash
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || { echo "not a git work tree — skipping"; exit 0; }
+untracked=0
+for dir in .claude/methodology .claude/plans; do
+  [ -d "$dir" ] || continue
+  for f in "$dir"/*.md; do
+    [ -e "$f" ] || continue
+    if ! git ls-files --error-unmatch "$f" >/dev/null 2>&1; then
+      echo "UNTRACKED: $f"
+      untracked=$((untracked + 1))
+    fi
+  done
+done
+if [ "$untracked" -gt 0 ]; then
+  echo ""
+  echo "$untracked design record(s)/plan(s) are not tracked by git."
+  echo "These are project thought-record, not ephemera. Commit them, or if"
+  echo "one is genuinely disposable, move it out of these dirs. Never resolve"
+  echo "this by gitignoring the directory — see .claude/rules/artifacts-of-thought.md."
+  exit 1
+fi
+echo "All methodology records and plans are tracked."
+```
+
+Catches the silent-loss failure mode: a design record in
+`.claude/methodology/` or a plan in `.claude/plans/` that git isn't
+tracking — because it was just written and not committed, or because the
+directory was gitignored (which un-tracks every *new* doc while older
+committed ones survive, masking the problem). `README.md` indexes are
+tracked, so they don't flag. Skips silently outside a git work tree or
+when neither directory exists.
+
 ## Example Validators (commented — enable for your project)
 
 <!--

package/templates/watchtower/queue/items/item.json.schema

@@ -33,7 +33,8 @@
       "enum": [
         "deferred-trigger", "routing-decision", "knowledge-extraction", "methodology-capture",
         "upstream-friction", "project-completion", "completion-review", "branch-diverged",
-        "stale-project", "pattern-promotion", "watchtower-health", "worktree-unmerged"
+        "stale-project", "pattern-promotion", "watchtower-health", "worktree-unmerged",
+        "qa-handoff"
       ]
     },
     "urgency": {

package/templates/skills/decisions/SKILL.md

@@ -1,13 +0,0 @@
----
-name: decisions
-description: "Redirect: use /inbox instead"
----
-
-# /decisions → /inbox
-
-This skill has been renamed to `/inbox`. Run `/inbox` instead.
-
-The watchtower inbox holds items that background rings noticed and want
-your attention on — knowledge to route, completion candidates, methodology,
-and friction reports. `/decisions` was misleading because the items aren't
-decisions awaiting judgment; they're incoming signals awaiting triage.

package/templates/skills/engagement/SKILL.md

@@ -1,9 +0,0 @@
----
-name: engagement
-description: "Moved to /collab-client. Use that instead."
-manual: true
----
-
-This skill has moved to `/collab-client`. Please run `/collab-client` instead.
-
-For a quick status glance, use `/collab-client progress`.

package/templates/skills/engagement-add/SKILL.md

@@ -1,7 +0,0 @@
----
-name: engagement-add
-description: "Moved to /collab-consultant add. Use that instead."
-manual: true
----
-
-This skill has moved to `/collab-consultant add`. Please run `/collab-consultant add` instead.

package/templates/skills/engagement-edit/SKILL.md

@@ -1,7 +0,0 @@
----
-name: engagement-edit
-description: "Moved to /collab-consultant edit. Use that instead."
-manual: true
----
-
-This skill has moved to `/collab-consultant edit`. Please run `/collab-consultant edit` instead.

package/templates/skills/engagement-message/SKILL.md

@@ -1,7 +0,0 @@
----
-name: engagement-message
-description: "Moved to /collab-consultant message. Use that instead."
-manual: true
----
-
-This skill has moved to `/collab-consultant message <who>`. Please run `/collab-consultant message <who>` instead.

package/templates/skills/engagement-progress/SKILL.md

@@ -1,7 +0,0 @@
----
-name: engagement-progress
-description: "Moved to /collab-client progress. Use that instead."
-manual: true
----
-
-This skill has moved to `/collab-client progress`. Please run `/collab-client progress` instead.

package/templates/skills/engagement-status/SKILL.md

@@ -1,7 +0,0 @@
----
-name: engagement-status
-description: "Moved to /collab-consultant. Use that instead."
-manual: true
----
-
-This skill has moved to `/collab-consultant` (the default subcommand is the dashboard). Please run `/collab-consultant` instead.

package/templates/skills/engagement-sync/SKILL.md

@@ -1,7 +0,0 @@
----
-name: engagement-sync
-description: "Moved to /collab-consultant sync. Use that instead."
-manual: true
----
-
-This skill has moved to `/collab-consultant sync`. Please run `/collab-consultant sync` instead.