create-claude-cabinet 0.44.0 → 0.45.0

package/templates/scripts/watchtower-migrate-keys.mjs

@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+
+// Watchtower project-key migration — one-time repair for the phantom-key era.
+//
+// Before the canonical resolver landed, Ring 3 filed everything under
+// basename(cwd) — for mux worktree sessions that's a phantom key like
+// "cabinet-continue" that /inbox and the rings never look up — and the mux
+// pane-close filer keyed items by desk name ("cabinet" vs the config key
+// "claude-cabinet"). The damage lives in THREE stores that must move
+// together, with one shared resolution, or they end up inconsistently
+// half-right (worse than consistently wrong):
+//
+//   1. queue/items/*.json      — the `project` field (ALL statuses, not just
+//                                pending: threads reference terminal items)
+//   2. state/projects/<slug>/  — per-phantom-slug session dirs, MERGED into
+//                                the config-slug dir (collisions suffixed)
+//   3. state/threads/*.json    — sessions[].project slug values
+//
+// Resolution, per phantom key: (a) any live project_path resolves via the
+// canonical resolver (git walks a worktree back to its main repo); (b) an
+// alias map for deleted worktrees, where no tool can derive the project
+// ("maginnis-*" shares no prefix with "claudeconsult-maginnis" — the
+// operator has to say it); (c) neither → the items get project_unresolved
+// and land in the residue report. The dry-run recomputes everything from
+// the files — it never asserts prior counts.
+//
+// Safety: dry-run is the default; --apply backs up all three stores first;
+// re-running --apply rewrites 0 items (idempotent); items already keyed to
+// a config project are never touched.
+//
+// Usage:
+//   watchtower-migrate-keys.mjs                       dry-run report
+//   watchtower-migrate-keys.mjs --apply               backup, then rewrite
+//   watchtower-migrate-keys.mjs --alias maginnis-=claudeconsult-maginnis
+//                                                     (repeatable; prefix=key)
+
+import {
+  readFileSync, readdirSync, existsSync, mkdirSync, renameSync,
+  cpSync, statSync, rmdirSync,
+} from 'fs';
+import { join, basename } from 'path';
+import {
+  getWatchtowerDir, loadConfig, slugify, atomicWrite,
+  resolveProjectIdentity,
+} from './watchtower-lib.mjs';
+
+const WATCHTOWER_DIR = getWatchtowerDir();
+const QUEUE_DIR = join(WATCHTOWER_DIR, 'queue', 'items');
+const PROJECTS_DIR = join(WATCHTOWER_DIR, 'state', 'projects');
+const THREADS_DIR = join(WATCHTOWER_DIR, 'state', 'threads');
+
+// ---------------------------------------------------------------------------
+// Alias map — operator-confirmed prefix → config key, for phantom keys whose
+// worktrees no longer exist on disk (nothing mechanical can recover those).
+// Extend via --alias prefix=key. Longest matching prefix wins.
+// ---------------------------------------------------------------------------
+const DEFAULT_ALIASES = {
+  'cabinet-': 'claude-cabinet',
+  'maginnis-': 'claudeconsult-maginnis',
+  'flow-': 'flow',
+};
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const parsed = { apply: false, aliases: { ...DEFAULT_ALIASES } };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--apply') parsed.apply = true;
+    else if (args[i] === '--alias' && args[i + 1]) {
+      const [prefix, key] = args[++i].split('=');
+      if (prefix && key) parsed.aliases[prefix] = key;
+    } else if (args[i] === '--help' || args[i] === '-h') {
+      console.log('usage: watchtower-migrate-keys.mjs [--apply] [--alias prefix=configKey]...');
+      process.exit(0);
+    }
+  }
+  return parsed;
+}
+
+function readJSON(fp) {
+  try {
+    return JSON.parse(readFileSync(fp, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function aliasTarget(phantomKey, aliases, configKeys) {
+  let best = null;
+  for (const [prefix, key] of Object.entries(aliases)) {
+    if (phantomKey.startsWith(prefix) && configKeys.has(key)) {
+      if (!best || prefix.length > best.prefix.length) best = { prefix, key };
+    }
+  }
+  return best?.key || null;
+}
+
+function main() {
+  const { apply, aliases } = parseArgs();
+  const config = loadConfig();
+  const configKeys = new Set(Object.keys(config.projects || {}));
+  const configSlugs = new Map(
+    [...configKeys].map(k => [slugify(k), k])
+  );
+
+  // --- Pass 0: scan queue items, build the phantom-key → target mapping ---
+  // Strictly *.json — 430 legacy extension-less dec-* files share this dir.
+  const itemFiles = existsSync(QUEUE_DIR)
+    ? readdirSync(QUEUE_DIR).filter(f => f.endsWith('.json'))
+    : [];
+  const items = [];
+  for (const f of itemFiles) {
+    const item = readJSON(join(QUEUE_DIR, f));
+    if (item && item.project) items.push({ file: f, item });
+  }
+
+  // mapping: phantomName -> { name, slug, path } | null (unresolvable)
+  const mapping = new Map();
+  const ensureMapped = (phantomKey, projectPath) => {
+    if (configKeys.has(phantomKey)) return; // already a real key — untouched
+    const existing = mapping.get(phantomKey);
+    if (existing) return;
+    // (a) live path: the resolver walks worktrees back to their main repo
+    if (projectPath) {
+      const id = resolveProjectIdentity(projectPath, config);
+      if (id?.registered) {
+        mapping.set(phantomKey, id);
+        return;
+      }
+    }
+    // (b) operator alias for dead worktrees
+    const aliased = aliasTarget(phantomKey, aliases, configKeys);
+    if (aliased) {
+      const path = config.projects[aliased]?.path || null;
+      mapping.set(phantomKey, { name: aliased, slug: slugify(aliased), path });
+      return;
+    }
+    // (c) unresolvable — recorded so all three stores treat it identically
+    mapping.set(phantomKey, null);
+  };
+
+  for (const { item } of items) ensureMapped(item.project, item.project_path);
+
+  // Phantom slugs can also appear in stores without a matching queue item
+  // (state dirs, thread sessions). Map those through the same rules.
+  const threadFiles = existsSync(THREADS_DIR)
+    ? readdirSync(THREADS_DIR).filter(f => f.endsWith('.json'))
+    : [];
+  const threads = threadFiles
+    .map(f => ({ file: f, thread: readJSON(join(THREADS_DIR, f)) }))
+    .filter(t => t.thread);
+  for (const { thread } of threads) {
+    for (const s of thread.sessions || []) {
+      if (s.project && !configSlugs.has(s.project)) ensureMapped(s.project, null);
+    }
+  }
+  const stateDirs = existsSync(PROJECTS_DIR)
+    ? readdirSync(PROJECTS_DIR).filter(d => {
+        try { return statSync(join(PROJECTS_DIR, d)).isDirectory(); } catch { return false; }
+      })
+    : [];
+  for (const d of stateDirs) {
+    if (!configSlugs.has(d)) ensureMapped(d, null);
+  }
+
+  // --- Report: recomputed ground truth, grouped by filed_by and phantom key ---
+  const planned = { items: [], threads: [], dirs: [], residue: [] };
+  const byFiler = {};
+  const byKey = {};
+
+  for (const { file, item } of items) {
+    if (configKeys.has(item.project)) continue; // already correct: untouched
+    const target = mapping.get(item.project);
+    if (target) {
+      planned.items.push({ file, item, target });
+      byFiler[item.filed_by || '?'] = (byFiler[item.filed_by || '?'] || 0) + 1;
+      byKey[`${item.project} → ${target.name}`] =
+        (byKey[`${item.project} → ${target.name}`] || 0) + 1;
+    } else if (!item.project_unresolved) {
+      planned.residue.push({ file, item });
+    }
+  }
+
+  for (const { file, thread } of threads) {
+    const rewrites = (thread.sessions || []).filter(s =>
+      s.project && !configSlugs.has(s.project) && mapping.get(s.project)
+    ).length;
+    const unresolvable = (thread.sessions || []).filter(s =>
+      s.project && !configSlugs.has(s.project) && !mapping.get(s.project) && !s.project_unresolved
+    ).length;
+    if (rewrites || unresolvable) planned.threads.push({ file, thread, rewrites, unresolvable });
+  }
+
+  for (const d of stateDirs) {
+    if (configSlugs.has(d)) continue;
+    const target = mapping.get(d);
+    if (target) planned.dirs.push({ dir: d, target });
+  }
+
+  console.log(`Watchtower project-key migration — ${apply ? 'APPLY' : 'dry-run'}`);
+  console.log(`Config keys: ${[...configKeys].join(', ')}\n`);
+  console.log(`Queue items scanned: ${items.length} (${itemFiles.length} .json files)`);
+  console.log(`Items to re-key: ${planned.items.length}`);
+  for (const [k, n] of Object.entries(byKey).sort((a, b) => b[1] - a[1])) {
+    console.log(`  ${k}: ${n}`);
+  }
+  console.log('By filer (cross-registry desk renames listed separately from ring3 basenames):');
+  for (const [k, n] of Object.entries(byFiler)) console.log(`  ${k}: ${n}`);
+  console.log(`Thread files to rewrite: ${planned.threads.length} (of ${threads.length})`);
+  console.log(`State dirs to merge: ${planned.dirs.length}${planned.dirs.length ? ' — ' + planned.dirs.map(d => `${d.dir} → ${d.target.slug}`).join(', ') : ''}`);
+  const unresolvableDirs = stateDirs.filter(d => !configSlugs.has(d) && !mapping.get(d));
+  if (unresolvableDirs.length) {
+    console.log(`State dirs unresolvable: ${unresolvableDirs.length} — left in place: ${unresolvableDirs.join(', ')}`);
+  }
+  if (planned.residue.length) {
+    console.log(`\nRESIDUE — unresolvable, will be flagged project_unresolved (add --alias to map):`);
+    for (const { item } of planned.residue) {
+      console.log(`  [${item.status}] ${item.project} (${item.project_path || 'no path'}) — ${item.title?.slice(0, 60)}`);
+    }
+  }
+
+  if (!apply) {
+    console.log('\nDry-run only. Re-run with --apply to migrate (a backup is taken first).');
+    return;
+  }
+
+  // --- Backup all three stores before any write ---
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupDir = join(WATCHTOWER_DIR, `migration-backup-${stamp}`);
+  mkdirSync(backupDir, { recursive: true });
+  for (const [src, name] of [[QUEUE_DIR, 'queue-items'], [PROJECTS_DIR, 'state-projects'], [THREADS_DIR, 'state-threads']]) {
+    if (existsSync(src)) cpSync(src, join(backupDir, name), { recursive: true });
+  }
+  console.log(`\nBackup: ${backupDir}`);
+
+  // --- Store 1: queue items ---
+  let rewritten = 0;
+  for (const { file, item, target } of planned.items) {
+    item.project = target.name;
+    if (target.path) item.project_path = target.path;
+    delete item.project_unresolved;
+    atomicWrite(join(QUEUE_DIR, file), item);
+    rewritten++;
+  }
+  let flagged = 0;
+  for (const { file, item } of planned.residue) {
+    item.project_unresolved = true;
+    atomicWrite(join(QUEUE_DIR, file), item);
+    flagged++;
+  }
+
+  // --- Store 2: thread files (same mapping, slug values) ---
+  let threadsRewritten = 0;
+  for (const { file, thread } of planned.threads) {
+    for (const s of thread.sessions || []) {
+      if (!s.project || configSlugs.has(s.project)) continue;
+      const target = mapping.get(s.project);
+      if (target) {
+        s.project = target.slug;
+        delete s.project_unresolved;
+      } else if (!s.project_unresolved) {
+        s.project_unresolved = true;
+      }
+    }
+    atomicWrite(join(THREADS_DIR, file), thread);
+    threadsRewritten++;
+  }
+
+  // --- Store 3: state/projects dir merges (collision → keep both, suffix) ---
+  let dirsMerged = 0;
+  for (const { dir, target } of planned.dirs) {
+    const srcDir = join(PROJECTS_DIR, dir);
+    const dstDir = join(PROJECTS_DIR, target.slug);
+    const walk = (rel) => {
+      const abs = join(srcDir, rel);
+      for (const entry of readdirSync(abs, { withFileTypes: true })) {
+        const childRel = join(rel, entry.name);
+        if (entry.isDirectory()) {
+          mkdirSync(join(dstDir, childRel), { recursive: true });
+          walk(childRel);
+          try { rmdirSync(join(srcDir, childRel)); } catch { /* not empty */ }
+        } else {
+          let dest = join(dstDir, childRel);
+          if (existsSync(dest)) {
+            const dot = entry.name.lastIndexOf('.');
+            const suffixed = dot > 0
+              ? `${entry.name.slice(0, dot)}.from-${dir}${entry.name.slice(dot)}`
+              : `${entry.name}.from-${dir}`;
+            dest = join(dstDir, join(childRel, '..'), suffixed);
+          }
+          mkdirSync(join(dest, '..'), { recursive: true });
+          renameSync(join(srcDir, childRel), dest);
+        }
+      }
+    };
+    mkdirSync(dstDir, { recursive: true });
+    walk('');
+    try { rmdirSync(srcDir); } catch { /* leftovers stay; report below */ }
+    dirsMerged++;
+  }
+
+  console.log(`Applied: ${rewritten} items re-keyed, ${flagged} flagged unresolved, ${threadsRewritten} thread files rewritten, ${dirsMerged} state dirs merged.`);
+  console.log('Verify idempotency: re-run with --apply — it should rewrite 0 items.');
+}
+
+main();

package/templates/scripts/watchtower-queue.mjs

@@ -45,6 +45,199 @@ function generateId() {
 // Urgency sort order: urgent < normal < low (urgent first)
 const URGENCY_ORDER = { urgent: 0, normal: 1, low: 2 };
 
+// --- qa-handoff category contract (the staff-QA recipient gate) ---
+//
+// A qa-handoff item cannot leave the queue silently: resolution requires a
+// structured, field-validated qa_verdict; dismissal/supersession require a
+// typed reason; expiry never applies. The gate's playbook, tiers, and the
+// verdict shape are defined ONCE in the qa-handoff skill (SKILL.md, "The
+// recipient gate") — this section validates the SHAPE at the API so the one
+// sin, a silent stamp with no coverage look, is impossible rather than
+// discouraged. Keep all qa-handoff domain knowledge fenced here; the CRUD
+// functions below only call into it.
+
+const QA_CATEGORY = 'qa-handoff';
+const QA_TERMINAL_VERDICTS = ['runtime-verified', 'blocked'];
+// The parameterized token. Canonical form uses U+00B7 (·); input tolerates
+// common separator drift (-, –, —, *, •) because sessions retype labels.
+const QA_GAPS_TOKEN_RE = /^verified\s*[·•*\-–—]\s*(\d+)\s+gaps?\s+filed$/;
+const QA_COVERAGE_ASSESSMENTS = ['adequate', 'extended', 'gap-filed'];
+
+/**
+ * Normalize a qa-handoff verdict token to canonical form.
+ * Returns 'runtime-verified' | 'blocked' | 'verified · N gaps filed' (N >= 1),
+ * or null when the input is not a legal token (including bare 'verified').
+ * @param {string} raw
+ * @returns {string|null}
+ */
+export function normalizeQaVerdictToken(raw) {
+  if (typeof raw !== 'string') return null;
+  const t = raw.normalize('NFKC').trim().replace(/\s+/g, ' ');
+  if (QA_TERMINAL_VERDICTS.includes(t)) return t;
+  const m = t.match(QA_GAPS_TOKEN_RE);
+  if (m) {
+    const n = parseInt(m[1], 10);
+    if (Number.isSafeInteger(n) && n >= 1) return `verified · ${n} gaps filed`;
+  }
+  return null;
+}
+
+function gateError(item, message) {
+  // Never echo resolution/notes content back — name fields only.
+  return new Error(`qa-handoff gate: cannot close ${item.id} — ${message}`);
+}
+
+/**
+ * Validate the structured verdict for a qa-handoff item. Throws naming the
+ * missing/invalid field; returns the canonical verdict token on success.
+ * Validates the RESOLUTION shape only — legacy items (no risk_surface /
+ * tier_hint, absent or non-array could_not_verify) stay resolvable.
+ * @param {object} item
+ * @param {object} qa_verdict
+ * @returns {string} canonical verdict token
+ */
+export function validateQaVerdict(item, qa_verdict) {
+  if (!qa_verdict || typeof qa_verdict !== 'object' || Array.isArray(qa_verdict)) {
+    throw gateError(item, "missing structured qa_verdict object (pass qa_verdict to resolveItem; shape: see 'The recipient gate' in the qa-handoff skill)");
+  }
+  if (typeof qa_verdict.commit_tested !== 'string' || !qa_verdict.commit_tested.trim()) {
+    throw gateError(item, 'qa_verdict.commit_tested is required (the main commit the QA ran against)');
+  }
+  if (qa_verdict.tier !== 'narrow' && qa_verdict.tier !== 'full') {
+    throw gateError(item, "qa_verdict.tier is required ('narrow' | 'full')");
+  }
+
+  const posture = qa_verdict.coverage_posture;
+  if (!posture || typeof posture !== 'object' || Array.isArray(posture)) {
+    throw gateError(item, 'qa_verdict.coverage_posture is required (the coverage look, separate from check results)');
+  }
+  if (!QA_COVERAGE_ASSESSMENTS.includes(posture.assessment)) {
+    throw gateError(item, `qa_verdict.coverage_posture.assessment must be one of: ${QA_COVERAGE_ASSESSMENTS.join(' | ')}`);
+  }
+  if (posture.assessment === 'gap-filed') {
+    const filed = posture.gap_filed;
+    if (!Array.isArray(filed) || filed.length === 0
+        || filed.some((g) => !g || typeof g.filed_as !== 'string' || !g.filed_as.trim())) {
+      throw gateError(item, "coverage_posture.assessment is 'gap-filed' but coverage_posture.gap_filed is not a non-empty array of {gap, filed_as}");
+    }
+  }
+
+  const verdict = normalizeQaVerdictToken(qa_verdict.verdict);
+  if (!verdict) {
+    throw gateError(item, "qa_verdict.verdict is not a legal token — use 'runtime-verified', 'blocked', or 'verified · N gaps filed' (N >= 1; bare 'verified' is illegal: the label may not out-run its substance)");
+  }
+
+  // The gaps-bearing label must match its substance, and a clean label may
+  // not hide filed gaps. ('blocked' + filed_gaps is deliberately legal — a
+  // blocked QA can still file follow-ups; the block itself is the headline.)
+  const gapsMatch = verdict.match(QA_GAPS_TOKEN_RE);
+  const filedGaps = Array.isArray(qa_verdict.filed_gaps) ? qa_verdict.filed_gaps : [];
+  if (gapsMatch) {
+    const n = parseInt(gapsMatch[1], 10);
+    if (filedGaps.length !== n
+        || filedGaps.some((g) => !g || typeof g.filed_as !== 'string' || !g.filed_as.trim())) {
+      throw gateError(item, `verdict claims ${n} gaps filed but qa_verdict.filed_gaps has ${filedGaps.length} entries with a filed_as fid — the count in the label must equal the gaps actually filed`);
+    }
+  } else if (verdict === 'runtime-verified' && filedGaps.length > 0) {
+    throw gateError(item, `verdict 'runtime-verified' with ${filedGaps.length} filed_gaps — use 'verified · ${filedGaps.length} gaps filed'`);
+  }
+
+  // Confessed gaps cannot be laundered: every could_not_verify entry must be
+  // discharged as fixed-in-session or an explicitly typed deferral. Absent /
+  // non-array / empty confession lists demand nothing (legacy compatibility).
+  const confessed = Array.isArray(item.evidence?.could_not_verify)
+    ? item.evidence.could_not_verify : [];
+  if (confessed.length > 0) {
+    const cg = qa_verdict.confessed_gap;
+    if (!cg || typeof cg !== 'object' || Array.isArray(cg)) {
+      throw gateError(item, `this handoff confessed ${confessed.length} could_not_verify entr${confessed.length === 1 ? 'y' : 'ies'} — qa_verdict.confessed_gap {written_and_run, deferred} is required to discharge them`);
+    }
+    const written = Array.isArray(cg.written_and_run) ? cg.written_and_run : [];
+    const deferred = Array.isArray(cg.deferred) ? cg.deferred : [];
+    written.forEach((w, i) => {
+      if (typeof w !== 'string' || !w.trim()) {
+        throw gateError(item, `confessed_gap.written_and_run[${i}] must be a non-empty string naming the test written and run`);
+      }
+    });
+    deferred.forEach((d, i) => {
+      if (!d || typeof d !== 'object'
+          || typeof d.gap !== 'string' || !d.gap.trim()
+          || typeof d.filed_as !== 'string' || !d.filed_as.trim()
+          || typeof d.justification !== 'string' || !d.justification.trim()) {
+        throw gateError(item, `confessed_gap.deferred[${i}] must be a typed deferral {gap, filed_as, justification} — a confessed gap is fixed in-session or explicitly deferred, never folded into 'filed'`);
+      }
+    });
+    if (written.length + deferred.length < confessed.length) {
+      throw gateError(item, `${confessed.length} confessed could_not_verify entr${confessed.length === 1 ? 'y' : 'ies'} but only ${written.length + deferred.length} dispositioned (written_and_run + typed deferrals) — every confessed gap must be discharged`);
+    }
+  }
+
+  return verdict;
+}
+
+/**
+ * Emit a pattern-promotion inbox item from a qa-gate class sweep.
+ * Threshold-gated (default >= 3 instances), deduplicated against pending
+ * pattern-promotion items by (source_item_id, failure_class), and refuses
+ * to file into a directory that is not a real watchtower install.
+ * @param {object} params
+ * @returns {string|null} The item id (existing id when deduplicated),
+ *   or null when instance_count is below threshold.
+ */
+export function emitPatternPromotion({
+  project,
+  project_path,
+  source_item_id,
+  failure_class,
+  instance_count,
+  pattern_text,
+  population = null,
+  desk = null,
+  threshold = 3,
+}) {
+  if (typeof failure_class !== 'string' || !failure_class.trim()) {
+    throw new Error('emitPatternPromotion: failure_class is required');
+  }
+  if (typeof source_item_id !== 'string' || !source_item_id.trim()) {
+    throw new Error('emitPatternPromotion: source_item_id is required (the qa-handoff item the sweep ran for — it is half the dedup key)');
+  }
+  if (!Number.isInteger(threshold) || threshold < 1) {
+    throw new Error('emitPatternPromotion: threshold must be a positive integer');
+  }
+  if (!Number.isInteger(instance_count) || instance_count < threshold) return null;
+  if (!existsSync(join(WATCHTOWER_DIR, 'config.json'))) {
+    throw new Error(`emitPatternPromotion: no watchtower install at ${WATCHTOWER_DIR} (config.json missing) — refusing to file into a phantom queue; record the promotion candidate in the stamped verdict instead`);
+  }
+  const existing = listPending({ category: 'pattern-promotion' }).find(
+    (i) => i.evidence?.source_item_id === source_item_id
+        && i.evidence?.failure_class === failure_class,
+  );
+  if (existing) return existing.id;
+  return createItem({
+    project,
+    project_path,
+    category: 'pattern-promotion',
+    urgency: 'normal',
+    title: `Pattern promotion: ${failure_class}`,
+    summary: `qa-gate class sweep found ${instance_count} instances${population ? ` (${population})` : ''} — recurring failure class, promotion candidate`,
+    context_anchor: `qa-handoff item ${source_item_id}`,
+    evidence: {
+      source: 'qa-gate-sweep',
+      source_item_id,
+      failure_class,
+      instance_count,
+      population,
+      pattern_text,
+    },
+    options: [
+      { value: 'write', label: 'Write pattern', description: 'Capture to the project pattern dir for later promotion review' },
+      { value: 'dismiss', label: 'Dismiss', description: 'Not a recurring class worth capturing' },
+    ],
+    filed_by: 'qa-gate',
+    desk,
+  });
+}
+
 // --- Exports ---
 
 /**
@@ -68,6 +261,8 @@ export function createItem({
   plan_fid = null,
   thread_ids = [],
   confidence = null,
+  project_unresolved = false,
+  desk = null,
 }) {
   ensureDir(QUEUE_DIR);
   const id = generateId();
@@ -76,6 +271,11 @@ export function createItem({
     id,
     project,
     project_path,
+    // Additive fields, present only when meaningful (older readers and items
+    // omit them): project_unresolved marks a basename-fallback identity,
+    // desk preserves the mux desk name as display metadata.
+    ...(project_unresolved ? { project_unresolved: true } : {}),
+    ...(desk ? { desk } : {}),
     filed_at: new Date().toISOString(),
     filed_by,
     status: 'pending',
@@ -104,14 +304,22 @@ export function createItem({
 
 /**
  * Resolve an inbox item.
+ * For qa-handoff items, a structured `qa_verdict` is REQUIRED and validated
+ * (validateQaVerdict) — invalid shapes THROW naming the missing field; the
+ * bare-null return remains reserved for "not pending". The validated verdict
+ * is stamped onto the item with its token canonicalized.
  * @param {string} id
  * @param {object} params
  * @returns {object} The updated item
  */
-export function resolveItem(id, { resolution, resolution_notes = null, resolution_type = null }) {
+export function resolveItem(id, { resolution, resolution_notes = null, resolution_type = null, qa_verdict = null }) {
   const fp = itemPath(id);
   const item = readItem(fp);
   if (item.status !== 'pending') return null;
+  if (item.category === QA_CATEGORY) {
+    const verdict = validateQaVerdict(item, qa_verdict);
+    item.qa_verdict = { ...qa_verdict, verdict };
+  }
   item.status = 'resolved';
   item.resolved_at = new Date().toISOString();
   item.resolution = resolution;
@@ -131,6 +339,11 @@ export function dismissItem(id, { notes = null, resolution_type = null } = {}) {
   const fp = itemPath(id);
   const item = readItem(fp);
   if (item.status !== 'pending') return null;
+  if (item.category === QA_CATEGORY
+      && (typeof resolution_type !== 'string' || !resolution_type.trim()
+          || typeof notes !== 'string' || !notes.trim())) {
+    throw gateError(item, 'dismissing a qa-handoff item requires a typed resolution_type AND notes naming why post-merge QA is being waived — dismissal is an audited escape hatch, not a bypass of the recipient gate');
+  }
   item.status = 'dismissed';
   item.resolved_at = new Date().toISOString();
   item.resolution_type = resolution_type;
@@ -149,6 +362,9 @@ export function supersedeItem(id, { reason = null } = {}) {
   const fp = itemPath(id);
   const item = readItem(fp);
   if (item.status !== 'pending') return null;
+  if (item.category === QA_CATEGORY && (typeof reason !== 'string' || !reason.trim())) {
+    throw gateError(item, 'superseding a qa-handoff item requires a reason naming what replaces it (e.g. the newer handoff covering the same merge)');
+  }
   item.status = 'superseded';
   item.resolution_notes = reason;
   atomicWrite(fp, item);
@@ -164,6 +380,9 @@ export function expireItem(id) {
   const fp = itemPath(id);
   const item = readItem(fp);
   if (item.status !== 'pending') return null;
+  if (item.category === QA_CATEGORY) {
+    throw gateError(item, 'qa-handoff items never expire — QA debt stays surfaced until a stamped verdict resolves it (or a typed dismissal waives it)');
+  }
   item.status = 'expired';
   item.resolution_notes = 'Auto-expired by age policy';
   atomicWrite(fp, item);
@@ -261,6 +480,12 @@ export function runExpiry({ warnDays = 14, expireDays = 30 } = {}) {
 
   for (const item of pending) {
     const age = now - new Date(item.filed_at).getTime();
+    // qa-handoff items never auto-expire: an expired handoff is exactly the
+    // silent QA gap the recipient gate forbids. They warn (by item) instead.
+    if (item.category === QA_CATEGORY) {
+      if (age >= warnMs) warned.push(item);
+      continue;
+    }
     if (age >= expireMs) {
       item.status = 'expired';
       item.resolution_notes = `Auto-expired after ${expireDays} days. If still relevant, re-file with updated context.`;

package/templates/scripts/watchtower-ring1.mjs

@@ -26,6 +26,7 @@ import { homedir } from 'os';
 import {
   atomicWrite, loadConfig, slugify, log as _log, logError as _logError,
   getWatchtowerDir, createItem, listPending, resolveItem, loadBetterSqlite3,
+  preserveRing3LastSession,
 } from './watchtower-lib.mjs';
 
 const WATCHTOWER_DIR = getWatchtowerDir();
@@ -917,11 +918,26 @@ function main() {
     const summary = assembleSummary(projectStates, config);
     atomicWrite(join(stateDir, 'summary.md'), summary);
 
-    // Write per-project state files
+    // Write per-project state files.
+    // Section ownership (watchtower-contracts.md §Project State Section
+    // Ownership): Ring 3 owns "## Last Session" once it has authored a rich
+    // session summary there (marked by its `_<date> (<session-id>)_`
+    // attribution line). Ring 1 rebuilds every OTHER section from scratch,
+    // but must carry a Ring 3-authored Last Session forward verbatim —
+    // otherwise this rebuild deterministically clobbers Ring 3's summary
+    // within one cron tick.
     for (const ps of projectStates) {
       const slug = slugify(ps.name);
-      const projectMd = assembleProjectState(ps);
-      atomicWrite(join(projectsDir, `${slug}.md`), projectMd);
+      const statePath = join(projectsDir, `${slug}.md`);
+      let projectMd = assembleProjectState(ps);
+      if (existsSync(statePath)) {
+        try {
+          projectMd = preserveRing3LastSession(projectMd, readFileSync(statePath, 'utf8'));
+        } catch (e) {
+          logError(`could not merge existing state for ${slug}: ${e.message} — writing fresh`);
+        }
+      }
+      atomicWrite(statePath, projectMd);
     }
 
     log(`collected state for ${projectStates.length} project(s)`);

package/templates/scripts/watchtower-ring2.mjs

@@ -479,8 +479,10 @@ async function escalateQueueItems() {
     const ageMs = now - new Date(item.filed_at).getTime();
     const ageDays = ageMs / (24 * 60 * 60 * 1000);
 
-    if (ageDays >= ESCALATION_EXPIRE_DAYS) {
-      // 30+ days: expire
+    if (ageDays >= ESCALATION_EXPIRE_DAYS && item.category !== 'qa-handoff') {
+      // 30+ days: expire. qa-handoff items are exempt — they never expire
+      // (recipient-gate contract: expireItem THROWS on them); they fall
+      // through to the [AGING] path below and stay surfaced as QA debt.
       expireItem(item.id);
       expired++;
       log(`Fast: expired queue item ${item.id} (${Math.floor(ageDays)}d old)`);