create-claude-cabinet 0.52.0 → 0.53.0

package/lib/cli.js

@@ -1832,8 +1832,8 @@ async function run() {
   console.log('\n  ✅ Cabinet assembled!\n');
   console.log('  Next steps:');
   console.log('  1. Run /onboard in Claude Code — Claude will interview you and prepare the briefings');
-  console.log('  2. Start each session with /orient — get briefed');
-  console.log('  3. End each session with /debrief — close the loop for next time');
+  console.log('  2. Run /watchtower install to start the background rings — sessions then open pre-briefed');
+  console.log('  3. /briefing is your daily surface; end sessions with /close (or /session-handoff)');
   const skippedKeys = Object.keys(skippedModules);
   if (skippedKeys.length > 0) {
     console.log(`\n  Skipped modules: ${skippedKeys.join(', ')}`);

package/package.json

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

package/templates/CLAUDE.md

@@ -319,9 +319,22 @@ consumes the registry stays in cli.js).
   ring-filed inbox category to `{reconciler}` or `{exempt}` (exactly
   one), enforced by the structural filing-site test
   `__tests__/detector-registry.test.mjs`: it scans `category:` literals
-  at createItem sites across ring1 + ring2 + ring3-close (read-only
-  source scan) and fails on an unregistered category or a non-literal
-  category value inside a filing owner (act:4d11fd53).
+  at createItem sites across ring1 + ring2 + ring3-close + **ring4 +
+  routines** (read-only source scan) and fails on an unregistered
+  category or a non-literal category value inside a filing owner
+  (act:4d11fd53; act:ea23b3a5 added the last two scripts and their
+  `doc-drift` / `routine` entries, closing the gap act:c2f06955 item 5
+  named — the contract's "maps every ring-filed category" claim was
+  false while ring4 and the routine engine sat outside the scan). Census
+  at 2026-07-26: 27 filing sites, 20 distinct categories, 20 registry
+  entries. **The census binds a `category:` literal to its NEAREST
+  PRECEDING call opener and recognises only `createItem(` and `file(` as
+  filing owners** — an injectable filing dep under any other name reads
+  as a query filter and its category silently drops out of the census.
+  That is not hypothetical: act:ea23b3a5's ring2 memory-budget dep, first
+  written as `createItemFn`, dropped `watchtower-health` out of the
+  filing set and the suite caught it. Name an injected filing seam
+  `file`.
   `GENERATED_STATE_PATTERNS`/`generatedStateIsDisposable` — the JS SSOT
   for machine-written generated state (UNTRACKED `??` lines only:
   `.claude/verification/`, advisories-state.json, checklist-stats.json,
@@ -376,15 +389,43 @@ consumes the registry stays in cli.js).
   to the lib's `resolveProjectFromTranscriptSlug` (feature-detected by
   name on the namespace import) and then to `project_unresolved: true` —
   inbox filing proceeds, but no state-file or thread key is minted from
-  a raw slug. Phase 2c's `completionReviewEmitGuard` adds the
-  create-vs-complete filter (act:9eebbac4): an action whose db `created`
-  date falls inside the session's day window (+1 for past-midnight
-  spill) with confidence below `high` is not a completion candidate (an
-  action born this session whose only evidence is its own creation);
-  mechanical (db row, the same prepared statement as the status
-  re-check) and FAIL-OPEN in every gap — no sessionDate, an unparseable
-  sessionDate (windowEnd is a required conjunct), a missing `created`
-  column, or a thrown lookup all emit. coverage-warning is now a
+  a raw slug. Phase 2c's `completionReviewEmitGuard` was **rebuilt on
+  measurement** (act:ea23b3a5): act:9eebbac4's create-vs-complete
+  day-window filter is DELETED and the model's `confidence: 'high'` is
+  SUPPRESSED instead. Over all 223 items this category had ever filed,
+  each joined against the cited action's OWN project db, `high` scored
+  30% precision (12 acted-on / 28 dismissed-noise) against 60% for
+  medium+low (48 / 32) — the model rates high when a session *talks
+  about* an action (files it, plans it, discusses it), not when it
+  quietly finishes one. The deleted filter exempted `high` from its
+  born-this-session skip, so it suppressed the BEST cohort (same-day
+  creation + medium/low: 74%) and passed the worst (same-day + high:
+  33%); split at its 2026-07-12 ship date the category went **0-for-23**
+  — zero acted-on, 19 dismissed as noise. A **calibration fence** sits on
+  the check: the result holds for the Phase 2c confidence rubric AS
+  WRITTEN, so rewording that rubric requires re-running the measurement.
+  The per-fid dedup corpus gained `expired` + `superseded`, load-bearing
+  because the category's 14-day expiry equals
+  `COMPLETION_REVIEW_DEDUP_DAYS` (without them a fid leaves every corpus
+  exactly when its item expires and refiles forever). A
+  quoted-completion-evidence check (`verifyCompletionQuote` +
+  `decodeTranscriptText`) ships as **INSTRUMENTATION ONLY** — stamped to
+  `evidence.quote_verified`, counted per session, gating nothing: the
+  haystack is `preprocessTranscript`'s JSON-serialized output, so a
+  substring gate rejects ordinary multi-line prose (a newline is the two
+  characters `\` + `n`) and reliably ACCEPTS serialized TodoWrite
+  arguments; `decodeTranscriptText` drops `tool_use` blocks for exactly
+  that reason, and even decoded, containment proves a span EXISTS, never
+  that it means the work is done. Phase 2g (upstream friction) gained a
+  **three-arm actionability gate** (act:ea23b3a5, Phase 2f's
+  verification-gate shape): a named route from the closed vocabulary
+  `cc-feedback | project-tracker | config-change` with a non-empty detail
+  files `upstream-friction`; a durable no-route platform constraint files
+  `knowledge-extraction` (4 of the 5 friction items the operator KEPT
+  exited `captured-to-memory`, so a two-arm gate would have discarded the
+  useful half of the lens); anything else files nothing and is COUNTED.
+  Contract in `watchtower-contracts.md` ("Upstream-Friction
+  Actionability"). coverage-warning is now a
   STANDING-DEBT aggregation (act:e888dd63): ONE pending item per
   (project, debt-class — `COVERAGE_DEBT_CLASS`) whose evidence APPENDS
   per session (session-id union, so a reprocess replay can't inflate
@@ -394,7 +435,17 @@ consumes the registry stays in cli.js).
   at 5, urgent at 15); resolving closes the accumulated view and a
   persisting debt refiles FRESH next session. The `## Last Session`
   block names its authoritative per-session record (`appendRecordPointer`
-  → `<slug>/sessions/<date>-<sessionId>.md`; act:8c076580).
+  → `<slug>/sessions/<date>-<sessionId>.md`; act:8c076580). Phase 2d
+  classifies non-durable facts AT extraction (act:471dd701 N2 +
+  act:a69c21f8): `derivable` (recomputable from a live source → home
+  `derivation`, the recompute instruction visible) and its twin
+  `perishable` (true-at-a-moment, will become false, NOT recomputable —
+  `perishes_when` names what falsifies it → home `session-record`);
+  both ALWAYS FILED to acknowledge/dismiss, never memory, never
+  dropped; derivable wins when both apply; the type/home vocabulary is
+  the exported `KNOWLEDGE_EXTRACTION_TYPES`/`_HOMES` consts
+  (watchtower-queue) with createItem boundary checks + a prompt-parity
+  test (`__tests__/extraction-classification.test.mjs`).
 - `watchtower-queue.mjs` — inbox queue CRUD library (atomic temp+rename,
   no-index convention); also home of the staff-QA recipient gate
   (2026-06-11): every terminal exit on a `qa-handoff` item is structural —
@@ -405,7 +456,19 @@ consumes the registry stays in cli.js).
   exempts the category). `emitPatternPromotion` files one deduplicated
   pattern-promotion inbox item at >=3 sweep instances of a failure class.
   `listItems()` exposes filtered item listing (project/category/status/since)
-  for the Ring 3 dedup corpora. Terminal exits on any dispatched-category
+  for the Ring 3 dedup corpora. **Category expiry is single-sourced here**
+  (act:ea23b3a5): `expiryDaysFor` / `categoryNeverExpires` /
+  `CATEGORY_EXPIRE_DAYS` / `DEFAULT_EXPIRE_DAYS`, with
+  `categoryNeverExpires` sitting beside `expireItem`'s throw because the
+  qa-handoff carve-out is STRUCTURAL (returning anything but null for it
+  crashes the caller's loop). There are TWO expiry engines — Ring 2's
+  `escalateQueueItems` cron and `runExpiry`, which `/inbox` and
+  `/briefing` call — and each previously hardcoded 30 days with its own
+  inlined carve-out, so a per-category policy set in one was silently
+  violated by whichever reached the item first. Both now delegate.
+  completion-review is the first override at 14 days; note that a
+  shortened expiry can open a refile loop when it meets its filing site's
+  dedup window (see the "Category Expiry" contract). Terminal exits on any dispatched-category
   item (`qa-handoff`, `routine` — the DISPATCHED_CATEGORIES set; resolve /
   typed dismiss / supersede / expire) also clear the matching mux
   dispatch-queue descriptor — queued AND in-flight, across all desk dirs —
@@ -491,6 +554,23 @@ consumes the registry stays in cli.js).
   descriptor through `mux qa dispatch` — the SAME hardened desk-dispatch path
   as qa-handoffs, never a fork. Pending-item dedup blocks refiring; stale
   pending firings (default 24h) are superseded + redispatched.
+  `sweepExpiredMoments` (act:ea23b3a5) adds **end-of-day moment expiry for
+  `time-of-day` triggers**: Ring 1's tick supersedes a pending item once
+  the calendar day it was FILED on has ended, instead of waiting 24h for
+  the next firing. End-of-day rather than a fixed window is a measured
+  choice — the portfolio's one time-of-day routine had 10 real pickups in
+  six weeks, 8 within four hours and 2 after (4.4h, 8.6h), so a 4h window
+  would have destroyed two genuine pickups to clear one stale item.
+  Scoped to Ring 1's PORTFOLIO tick (Ring 3's single-project
+  session-close call would otherwise sweep every other project's items,
+  once per replayed session during a reprocess drain), classified from
+  `item.evidence.trigger` rather than config (so a de-registered routine
+  still classifies instead of rotting), and an unparseable `filed_at`
+  ABSTAINS loudly rather than sweeping (the `stale_after_hours` path
+  treats the same input as stale — two mechanisms disagreeing silently is
+  worse than one abstaining out loud). For time-of-day the moment sweep
+  now pre-empts the `stale_after_hours` supersede; interval /
+  path-nonempty / session-close have no moment and are untouched.
   `buildPickupPrompt` (the dispatch pickup-prompt wording, including the
   resolve-on-run that clears the badge) is exported and reused by the
   build-context missed-routine re-delivery (act:4b4fa7d9), so the wording is
@@ -911,7 +991,17 @@ summary attention aggregates portfolio-wide pib errors into ONE line (almost
 always a single system-level fault; Ring 2's `openPibDb` logs instead of
 silently nulling); the memory-integrity check delegates to
 `checkMemoryReachability` (watchtower-lib) — reachability, never
-filename-substring (act:49cb1c27). Ring 1's worktree-unmerged +
+filename-substring (act:49cb1c27). Standing Issues also renders the
+**cabinet-roster ambient lines** (act:ea23b3a5, `readRosterMetrics` +
+`renderRosterEntries`): dormant-skill and stale-briefing counts stopped
+being `advisor-finding` queue items and became a Ring 2 measurement that
+Ring 1 renders — the same relationship as the recall canary (the
+measurement is Ring 2's, the render is Ring 1's, because Ring 1 owns the
+per-project state file). Rendered ON CHANGE only and carrying skill
+NAMES, because ambient state has no dismiss verb and a number that never
+moves is furniture by the third read; the count itself had to be fixed
+first, since `ROSTER_DORMANT_LIST_CAP` saturated it and every project
+ever measured reported exactly "12 dead". Ring 1's worktree-unmerged +
 branch-diverged detectors flag on CONTENT, not ahead-count (act:a152cf6c): a
 squash-merge leaves a branch a non-ancestor of main with phantom "ahead"
 commits but an IDENTICAL tree, so the old ancestry/`aheadCount` gates flagged
@@ -959,11 +1049,60 @@ knowledge-extraction drafts with freshness (cited `act:` fids positively
 CLOSED in the item's own project pib-db — parameter-bound lookups via
 `openPibDb`, now `timeout: 5000` for lock parity with Ring 3) and fold
 proposals (the watchtower-queue recipe), demoting them out of batch
-sign-off, never dismissing; unreadable dbs and out-of-config drafts are
-counted LOUDLY (`skipped_projects`/`unscanned_items`) and every run
-writes the positive-confirmation sidecar
+sign-off, never dismissing; act:09184ad7 added a SECOND fold corpus —
+pending pattern-promotion items, grouped per `evidence.target_member`
+(cross-member similarity is never a duplicate), so near-duplicate
+pattern variants arrive pre-annotated for the next consolidation pass
+(`pattern_items_scanned`/`pattern_fold_annotated`/
+`unscanned_pattern_items` counters); act:ea23b3a5 added a THIRD corpus —
+pending `raised-unhandled` loose ends, grouped per project
+(`loose_end_items_scanned`/`loose_end_fold_annotated`). That third corpus
+is where the spec's "aggregate recurring loose ends into ONE item"
+landed after measurement refused the merge: `proposeFolds` scores with
+`overlapCoefficient` (act:421a8ab2 retired `unigramJaccard`), whose
+`min()` denominator lets two three-token titles sharing ONE word clear
+`FOLD_SIMILARITY_THRESHOLD = 0.22` — four false folds in fifteen pairs
+against the six live titles — and the five timelog specimens were
+resolved `deferred` (real work the operator postponed, across two
+projects and three date ranges), so merging would have buried which gaps
+remain. The threshold was calibrated for ADVISORY retrieval, not a
+destructive merge: **a lexical matcher may propose, never silently
+suppress.** Unreadable dbs and out-of-config
+items are counted LOUDLY (`skipped_projects`/`unscanned_items`) and
+every run writes the positive-confirmation sidecar
 `state/draft-annotations-health.json`, so "no annotations" is
-distinguishable from "never ran"), Ring 3 (session close, transcript
+distinguishable from "never ran". The slow tier also owns the
+**memory-budget standing debt + its retraction** (act:ea23b3a5):
+`surfacePersistentViolations` files ONE accumulating `watchtower-health`
+item per project instead of a fresh one every 7 days — keyed by CALENDAR
+DAY (a per-run key would count ~48 cron ticks a day and make the replay
+guard dead code), appended via `annotateItemEvidence` so `filed_at` is
+never bumped, carrying `session_count` because that is the spelling
+`itemSessionWeight` already reads — and `retractClearedMemoryBudgetItems`
+retracts on the SAME pass over the `passProjects` `runMemoryHygiene`
+already computes. Deliberately not in Ring 1: a second memory-health
+producer is forbidden by name in `watchtower-contracts.md`, and at a
+30-minute throttle against ring2's 30-minute cadence it would buy zero
+freshness. Both selectors match the LEGACY `{violations, streak}` title
+shape as well as the new `debt_class`, because every item on disk when
+this shipped carried the former. The cabinet-roster review now files only
+`uncovered-tech` (a proposed cabinet seat is a decision); `dormant-skill`
+and `stale-briefing` became ambient metrics in `state/roster-review.json`
+(`parseDormantSkills` reports TRUE counts — the cap bounds the NAME list
+only) and `retireRosterFindingItems` supersedes any of the two retired
+kinds still pending, since the filing site was the only code that ever
+touched them. The slow tier's `scanAuditPatterns`
+(the pattern-promotion filing site) now runs the act:09184ad7
+emission-quality SHAPE GATE — `patternHasRequiredShape` requires the
+`**Evidence:**` + `**Gap:**` blocks Phase 2e's prompt mandates, rejecting
+document echoes (wave ledgers, dependency graphs, recipes, transcript
+fragments — 17/144 items in the 2026-07-26 consolidation) BEFORE the
+routing Claude call; rejections are counted loudly
+(`rejected_malformed_total`/`last_scan_rejected` in
+`state/pattern-detection.json`) and their hashes marked processed, never
+retried. Calibrated against the consolidation corpus: 120/120 legitimate
+bodies pass, 17/17 fragments fail; hermetic suite in
+`__tests__/ring2-pattern-gate.test.mjs`), Ring 3 (session close, transcript
 processing; fires session-close routines as Phase 2j2; runs the standing
 session advisors as Phase 2m — see
 below; runs three session-close extraction lenses (act:4ff2cfb3) — Phase 2n
@@ -971,7 +1110,12 @@ raised-but-unhandled (loose ends the session raised but neither did nor filed
 → inbox category `raised-unhandled`), Phase 2o skill-candidate (a manual
 procedure repeated by hand → `skill-candidate` inbox item), Phase 2p
 checklist-catch (a surfaced change-impact check that caught a real bug →
-`checklist-stats.json`); its Phase 2h feedback "flush" was deleted 2026-06-12
+`checklist-stats.json`); its Phase 2e quality-pattern prompt is the exported
+`QUALITY_PATTERN_SYSTEM_PROMPT` carrying the act:09184ad7 generation-side
+exclusions — no-gap positives, transcript-artifact observations, document
+echoes are never patterns — the prompt half of ring2's mechanical shape
+gate, guarded by `__tests__/ring2-pattern-gate.test.mjs`; its Phase 2h
+feedback "flush" was deleted 2026-06-12
 — it marked without delivering), Ring 4 (periodic truth reconciliation,
 act:36dae795 — stage-1 BUILT, weekly cadence; cron/launchd registration is a
 deferred `/watchtower install` follow-up). Ring 4 mechanically compares

package/templates/cabinet/watchtower-contracts.md

@@ -208,6 +208,81 @@ mux descriptor; routine items resolve normally (no QA gate, normal
 expiry — expiry also clears the descriptor). A pending routine item
 blocks refiring of the same routine until resolved or stale.
 
+**Moment expiry for `time-of-day` routines (act:ea23b3a5).** A daily
+routine's value is bound to its day: a morning briefing delivered
+tomorrow is not a briefing. `stale_after_hours` only supersedes at the
+NEXT due firing, which for a daily routine is 24 hours later, so a
+missed firing held a queue slot and a lit desk badge all day. Ring 1's
+tick now supersedes a pending `time-of-day` item once the calendar day
+it was FILED on has ended.
+
+End of day, not a fixed number of hours, and the difference is
+measured rather than tasteful: across six weeks the portfolio's one
+time-of-day routine had ten real pickups — eight within four hours and
+two after, at 4.4h and 8.6h. A four-hour window would have destroyed two
+genuine pickups to clear one stale item. End-of-day preserves all ten,
+needs no tuning constant, and matches what a daily routine means to a
+person: you can still want your morning briefing at 4pm; you do not want
+it tomorrow.
+
+Three scoping rules, each load-bearing:
+
+- **Ring 1's portfolio tick only.** Ring 3 also calls `runRoutinePass`,
+  with a single-project `session-close` event. An unscoped sweep there
+  would have every session close in any project superseding every OTHER
+  project's routine items — and one portfolio sweep per replayed session
+  during a `--reprocess-failed` drain.
+- **Classify from the ITEM, not from config.** `dispatchRoutine`
+  persists `evidence.trigger` at filing, so a routine whose declaration
+  was later removed still classifies. A config lookup would find nothing
+  and leave it pending forever.
+- **An unparseable `filed_at` abstains, loudly.** The `stale_after_hours`
+  path treats the same input as stale (NaN comparisons fall through to
+  supersede); this one refuses and logs. Two mechanisms disagreeing
+  silently is worse than one abstaining out loud.
+
+Consequences, named rather than discovered later: for a `time-of-day`
+trigger the moment sweep pre-empts the `stale_after_hours` supersede
+(same outcome, more honest reason), a missed briefing is no longer
+re-delivered by the SessionStart missed-routine section on a LATER day,
+and the sweep has no in-flight awareness — a routine picked up by `mux
+qa drain` very close to midnight could be superseded mid-run, which
+end-of-day narrows to minutes where a fixed-hour window would have
+opened it to hours. `interval`, `path-nonempty`, and `session-close`
+routines have no moment and are untouched.
+
+## Upstream-Friction Actionability (Phase 2g)
+
+A friction report with no party who could act on it is not a report.
+Five of the 2026-07-26 dismissals were observations like "Claude made
+iterative browser tweaks without writing to file" — true, and addressed
+to nobody, aging in the queue for weeks.
+
+Phase 2g now classifies each finding into three arms (act:ea23b3a5),
+copying Phase 2f's verification-gate shape (which files a methodology
+capture only when the claimed artifact verifiably exists on disk, after
+11 of 11 unverified captures were dismissed over three weeks):
+
+1. **A named route** — `evidence.route.type` from the CLOSED vocabulary
+   `cc-feedback | project-tracker | config-change`, plus a non-empty
+   `detail` naming who acts and how ⇒ files `upstream-friction`, with the
+   route rendered into the summary so the operator sees it without
+   opening the evidence.
+2. **Durable, no route** — a platform constraint or environment quirk
+   nobody can fix, whose WORKAROUND is worth remembering ⇒ files
+   `knowledge-extraction`. This arm is not theory: of the five friction
+   items the operator KEPT, four exited as `captured-to-memory`. A
+   two-arm gate would have discarded the useful half of the lens.
+3. **Neither** — a transient incident or a general observation about
+   Claude's behavior ⇒ files nothing, and is COUNTED. All three counts
+   are logged every run; silence would be indistinguishable from a lens
+   that never ran, and the drop count is the number this change exists to
+   move.
+
+An invented route type or an empty `detail` falls to arm 3. The
+vocabulary is closed precisely so "someone should fix this" cannot
+become an escape hatch.
+
 ## Session Advisor Pass (re-homed standing advisors)
 
 The standing session advisors (historian, system-advocate,
@@ -523,16 +598,133 @@ branch-diverged item for it — the branch stays visible on the attention
 line / git-attention sidecar / summary / Standing Issues (the exclusion
 gates filing ONLY), and the consumer overrides the list in config.
 
-**Standing-debt aggregation (coverage-warning first):** a detector
-whose finding is a STANDING condition (recurs while a debt persists)
-files ONE item per (project, debt-class) and APPENDS evidence to the
-pending item (path union + per-path counts + session count), carrying
-`evidence.first_seen` (oldest evidence date) so aging reads the debt's
-true age, with an urgency escalation at a session-count threshold.
-Resolving the item closes the accumulated view; if the debt persists,
-the next tick files FRESH — post-disposition recurrence is a new
-signal, not a refile loop (act:e888dd63; 49 identical coverage-warning
-items for one month-old debt was the live specimen).
+**Standing-debt aggregation (coverage-warning, memory-budget):** a
+detector whose finding is a STANDING condition (recurs while a debt
+persists) files ONE item per (project, debt-class) and APPENDS evidence
+to the pending item, carrying `evidence.first_seen` (oldest evidence
+date) so aging reads the debt's true age. Resolving the item closes the
+accumulated view; if the debt persists, the next tick files FRESH —
+post-disposition recurrence is a new signal, not a refile loop
+(act:e888dd63; 49 identical coverage-warning items for one month-old
+debt was the live specimen).
+
+Three rules the second adopter (memory-budget, act:ea23b3a5) added, each
+learned from a live failure mode:
+
+1. **The occurrence key must be the operator's unit of time, not the
+   ring's.** coverage-warning keys on the session; memory-budget keys on
+   the CALENDAR DAY, because Ring 2 slow runs ~48 times a day. A per-run
+   key makes the replay guard dead code, grows the key list by ~17,500
+   entries a year inside one JSON file, renders a count no human can
+   read, and — because the backlog-rot reader weighs standing debt by
+   that count — poisons the `keeping` / `losing` / `not-consumed` verdict
+   `/inbox` and `/briefing` lead with.
+2. **Reuse an evidence spelling the readers already know.** The rot
+   weigher (`itemSessionWeight`, watchtower-inbox-assessment) accepts
+   `session_count` / `session_ids` / `sessions` and silently weighs
+   everything else as 1. A new adopter that invents a fifth spelling
+   reintroduces the blind spot the fourth was added to fix. memory-budget
+   writes `session_count`.
+3. **Prefer `annotateItemEvidence` over a direct item write, and do not
+   bump `filed_at` without a reason.** The append gets a fresh read, a
+   pending fence checked at write time, and a deep-equal skip for free.
+   Bumping `filed_at` has three side effects worth choosing
+   deliberately: it strips an `[AGING]` prefix the escalation pass added
+   (and prevents its return), it re-escalates urgency the decay pass
+   de-escalated, and — since `listPending` sorts by `filed_at` — it pins
+   the item to the top of every pending list permanently. coverage-warning
+   bumps on purpose (its expiry clock should measure the last
+   recurrence); memory-budget does not.
+
+**What does NOT aggregate.** `doc-drift` carries a per-claim,
+mutually-exclusive fix-doc / fix-code decision, so N claims folded into
+one item pose a question the operator cannot answer, and any reconciler
+over the aggregate could only fire when every claim cleared.
+`raised-unhandled` is free text: recognizing "this loose end restates
+that one" needs a similarity matcher, and `proposeFolds`'
+`overlapCoefficient` at `FOLD_SIMILARITY_THRESHOLD = 0.22` folds two
+three-token titles that share ONE word — calibrated for advisory
+retrieval, not for a destructive merge. Both instead route through Ring
+2's `runDraftAnnotationSweep`, which annotates both sides with
+`possible_duplicate_of` and demotes them out of batch sign-off. **A
+lexical matcher may propose; it may never silently suppress.**
+
+## Category Expiry
+
+Every pending item ages out on a per-category policy. The table and its
+helpers live in `watchtower-queue.mjs` (`expiryDaysFor`,
+`categoryNeverExpires`, `CATEGORY_EXPIRE_DAYS`) — read the constants
+there for the numbers; mirroring them into this document would be a
+count claim that drifts, in a repo whose Ring 4 files `doc-drift` items
+for exactly that.
+
+**There are TWO expiry engines and both must delegate.** Ring 2's
+`escalateQueueItems` runs on the 5-minute cron; `runExpiry` is called by
+`/inbox` and `/briefing`. Before act:ea23b3a5 each hardcoded 30 days and
+inlined its own qa-handoff carve-out, so a per-category policy set in one
+would be silently violated by whichever engine reached an item first.
+
+**The qa-handoff exemption is structural, not a preference.**
+`expireItem` THROWS on a qa-handoff by the recipient-gate contract, so
+`categoryNeverExpires` lives beside that throw: returning anything but
+null for it would crash the caller's loop. One fact, one place.
+
+**A shortened expiry can open a refile loop.** completion-review expires
+at 14 days, which equals `COMPLETION_REVIEW_DEDUP_DAYS`. An item
+therefore leaves the dedup window at exactly the moment it expires — so
+Phase 2c's dedup corpus must include `expired` and `superseded`, or the
+fid is in no corpus at all and the next session refiles it forever. That
+is Detector Symmetry §2's named failure, reached from the other
+direction: **when you shorten a category's expiry, check what its filing
+site dedups against.**
+
+## Queue Items Require a Decision; Ambient State Describes Conditions
+
+A queue item asks the operator to decide something. A per-project state
+file describes a condition. Filing a condition as an item spends the
+operator's scarcest resource — a triage slot — on something they can
+only acknowledge.
+
+**The axis is who is judging, not whether the value is recomputable.**
+Recomputability is the wrong test and would contradict a rule this
+system already ships: derivable and perishable facts (act:471dd701,
+act:a69c21f8) are recomputable *by definition*, and they are **always
+filed** — routed to their derivation or the session record, never
+dropped — because that routing is a per-item MODEL judgment, and
+dropping one would be silent model auto-suppression. A deterministic
+ring measurement is different in kind: the operator routes it once, by
+category, and the routing holds.
+
+**The functional test: does waiting cost something irreversible?**
+`worktree-unmerged` is the calibrating counter-example. Ring 1
+recomputes it from git every five minutes, so by a recomputability rule
+it would be pure ambient state — and it must stay in the queue, because
+the worktree gets cleaned up and the work is gone. A recomputable
+condition with decay belongs in the queue; a recomputable condition that
+is stable belongs in ambient state.
+
+**The calibrating pair (act:ea23b3a5).** The cabinet-roster review
+produces three signals. `uncovered-tech` names a specific per-project
+gap and proposes adding a cabinet seat — a decision, so it stays a queue
+item. `dormant-skill` and `stale-briefing` are measurements, so they
+moved to `state/roster-review.json` and render in Ring 1's Standing
+Issues.
+
+Three obligations come with moving something to ambient state:
+
+- **Fix the measurement first.** The dormant-skill count was a saturated
+  display cap: every project ever measured reported exactly "12 dead",
+  because the title was built from an array already sliced to
+  `ROSTER_DORMANT_LIST_CAP`. Moving that into seven state files would
+  have given a constant the authority of a fact.
+- **Render on change, or give it a firing threshold.** Ambient state has
+  no dismiss verb — the queue item at least had one. A number that never
+  moves in a file read at every briefing is furniture by the third read.
+  The precedent is the recall canary, which Ring 1 renders only on alert.
+- **Retire what is already filed.** The filing site was usually the only
+  code that ever touched those items. Removing it without a one-shot
+  supersede leaves them displaying a stale count for weeks beside a live
+  ambient line saying something different — dual existence.
 
 **Known limitation (named, not hidden):** reconcilers run per
 configured project — items whose project was deleted or de-registered

package/templates/mux/bin/mux

@@ -28,6 +28,11 @@ in_tmux() { [[ -n "${TMUX:-}" ]]; }
 
 slugify() {
   local input="$*"
+  # Flatten to one line FIRST — sed/cut below process input line-by-line,
+  # so a multi-paragraph prompt would otherwise yield a multi-line "slug"
+  # (one line per input line) that mangles or empties out every caller's
+  # branch/directory name instead of collapsing to a single slug.
+  input="${input//$'\n'/ }"
   # If prompt has "name. rest", use only the name part
   if [[ "$input" == *". "* ]]; then
     input="${input%%". "*}"

package/templates/mux/config/mux-server.py

@@ -2,6 +2,7 @@
 """MCP server for mux — lets Claude manage desks, windows, and notes."""
 
 import json
+import shlex
 import subprocess
 import sys
 import os
@@ -192,11 +193,12 @@ def handle_tool(name, args):
     elif name == "mux_new":
         prompt = args.get("prompt", "")
         if prompt:
-            out, _, _ = run(f'{os.path.expanduser("~/.local/bin/mux")} new "{prompt}" 2>&1')
-            return out or f"New window '{prompt}' created."
+            out, _, rc = run(f'{os.path.expanduser("~/.local/bin/mux")} new {shlex.quote(prompt)} 2>&1')
         else:
-            out, _, _ = run(f'{os.path.expanduser("~/.local/bin/mux")} new 2>&1')
-            return out or "New window created."
+            out, _, rc = run(f'{os.path.expanduser("~/.local/bin/mux")} new 2>&1')
+        if rc != 0:
+            return f"Failed to open new window: {out or '(no output — check tmux/mux state)'}"
+        return out or (f"New window '{prompt}' created." if prompt else "New window created.")
 
     elif name == "mux_note_add":
         text = args["text"]
@@ -236,7 +238,7 @@ def handle_tool(name, args):
     elif name == "mux_status":
         project = args.get("project", "")
         if project:
-            out, _, _ = run(f'{os.path.expanduser("~/.local/bin/mux")} status "{project}" 2>&1')
+            out, _, _ = run(f'{os.path.expanduser("~/.local/bin/mux")} status {shlex.quote(project)} 2>&1')
         else:
             out, _, _ = run(f'{os.path.expanduser("~/.local/bin/mux")} status 2>&1')
         return out or "No desks open."