create-claude-cabinet 0.45.0 → 0.47.0

package/templates/skills/briefing/SKILL.md

@@ -1,31 +1,83 @@
 ---
 name: briefing
 description: |
-  CEO-style briefing. Your cabinet walks you through the landscape —
-  what watchtower did, what changed across the portfolio, what deserves
-  attention. Progressive disclosure: top-level summaries, drill into
-  anything. Also handles /recap (factual-only mode).
+  The one daily surface. A portfolio-wide curator: walks the landscape
+  project by project — plain-English state, what deserves attention,
+  and the project's pending inbox items batched into proposed
+  dispositions you approve in-conversation. Decisions are chunked by
+  project, never interleaved. Also handles /recap (factual-only mode)
+  and a per-project decision-lineage drill-down ("why is this project
+  the way it is — what still constrains it").
   Use when: "briefing", "brief me", "/briefing", "what's the landscape",
-  "recap", "/recap", "what happened", "what did I do yesterday".
-argument-hint: "scope — e.g., 'today', 'this week', 'maginnis only', 'recap'"
+  "recap", "/recap", "what happened", "what did I do yesterday",
+  "decision lineage", "why is this the way it is".
+argument-hint: "scope — e.g., 'today', 'this week', 'maginnis only', 'recap', 'lineage'"
 ---
 
-# /briefing — Portfolio Briefing
+# /briefing — The Daily Surface
+
+One run, from any desk, covers the whole portfolio. The briefing is a
+**curator**, not a dashboard: it reads everything watchtower knows,
+selects what actually matters, narrates it in plain English, and lets
+the operator disposition pending inbox items in bulk without leaving
+the conversation. The success test: the operator runs this daily
+because it is pleasant, and the inbox drains through batch decisions
+here instead of item-by-item `/inbox` walks.
+
+Tone contract for every section below — **non-negotiable, every run**:
+plain English, conversational, concept-first. No insider jargon, no
+fid/jargon walls. Say "the background system files one note when the
+same mistake keeps happening" — not "Ring 2 emitPatternPromotion
+dedups by failure class." Name the thing in words the operator would
+use, then add the id only as a trailing reference. Item ids and `act:`
+fids appear on request or in disposition confirmations — never as the
+narrative spine. Lead with what matters; counts and mechanics trail.
+This recurred live (2026-06-14): a briefing slipped into "Ring 2
+meta-critiques / generator leak" and the operator could not act on it
+until it was re-said plainly. If you catch yourself writing a term a
+non-author wouldn't recognize, rewrite the sentence. See also the
+decision/context structure rule under Step 3c.
+
+## The Anti-Accretion Invariant (structural rule)
+
+Every "the briefing should show X" duty — present and future — routes
+through the curator's top-N selection inside the owning project's
+chunk. **No duty may append its own always-rendered section.** This is
+how the briefing stays a pleasure for years: new signal classes (QA
+filed gaps, advisor findings, hygiene nudges, DX captures, verify
+warnings, whatever ships next) become candidates the curator weighs,
+not permanent real estate. A duty that earns attention today may
+earn one line tomorrow and silence next week. When editing this skill,
+reject any change that adds an unconditional section — give the new
+signal a candidate class in Step 3b instead.
+
+Two narrow floors temper curation — both are "never silently dropped"
+rules, not sections:
+
+1. **Gated items are never curated out.** A pending item in a gated
+   category (`GATED_CATEGORIES` in `scripts/watchtower-queue.mjs`;
+   today: `qa-handoff`) always appears in its project's chunk. The
+   queue lib already guarantees these cannot leave the queue silently;
+   the briefing must not hide what the gate keeps alive.
+2. **Open QA filed-gaps get at least a one-line roll-up** in the
+   cross-portfolio close (Step 4) while any remain open. "Filed" must
+   not become "forgotten" — the qa-handoff contract promises this
+   re-surfacing.
 
 ## Mode Detection
 
-Determine the briefing mode from how the skill was invoked:
-
 - If `$ARGUMENTS` contains the word "recap", or the skill was invoked
-  as `/recap`: **Factual mode.** No drill-down, no cabinet members.
-  Deliver the summary and stop.
-- Otherwise: **Full mode.** Summary followed by progressive disclosure
-  and optional cabinet lens.
+  as `/recap`: **Factual mode.** Deliver Step 2's summary, write the
+  timestamp (Step 5), and stop. No walk, no dispositions, no cabinet.
+- If `$ARGUMENTS` contains "lineage", "why is", or "decision history":
+  **Lineage mode.** Render THIS desk's project decision lineage (see
+  "Lineage Mode" below), then stop. No walk, no dispositions, no cabinet.
+- Otherwise: **Full mode.** Summary, then the project walk with batch
+  dispositions, then the cross-portfolio close.
 
 ## Scope Detection
 
-Parse the arguments (bound in Mode Detection above) to determine the
-time window and project filter:
+Parse the arguments to determine the time window and project filter:
 
 | Input | Scope |
 |-------|-------|
@@ -39,214 +91,498 @@ time window and project filter:
 
 When a project name is provided, match against project directory names
 in `state/projects/`. Use fuzzy prefix matching — "maginnis" matches
-"maginnis-howard". If multiple projects match, list them and ask the
-user to clarify.
+"maginnis-howard". If multiple projects match, list them and ask.
+The time window scopes the NARRATIVE (sessions, threads, what
+happened); pending inbox items are always loaded in full — old pending
+items are exactly what batch dispositions exist to drain.
+
+## Lineage Mode: Decision-Lineage Drill-Down (act:a2efc0ce)
+
+On-demand, read-only. Answers "why is THIS desk's project the way it is —
+what past decisions still constrain it, and what's safely reversible?"
+This is a **projection** over existing stores (the inbox, threads, memory
+`decision_*.md`, `.claude/methodology/`, pib-db), never a new store, and
+it **writes nothing**. It is current-project-scoped in Stage 1: it reads
+the project the current desk's cwd belongs to (worktree-aware). If the
+operator named a *different* project, say plainly that lineage is
+per-desk for now — run it from that project's desk — then either run it
+for the current project or stop. (Cross-project lineage is deferred.)
+
+Distinct from `/threads arc <slug>`, which tells **one work thread's**
+evolution. Lineage tells the **whole project's decision causality**.
+
+**L1 — corpus (inbox + threads).** Run the read-only helper (it lives
+beside the queue lib, in the project-root `scripts/` dir):
+```bash
+node scripts/watchtower-narrative-corpus.mjs --corpus --project-path "$(pwd)"
+```
+It returns `project_identity`, `inbox_decisions` (knowledge-extraction
+items, captured-to-memory duplicates already dropped, `superseded`
+included), `thread_cursors` (full `cursor_history` timelines),
+`per_store_counts`, and `skipped_unresolved`. If `reason` is
+`project-unresolved`, say the desk isn't a watchtower project and stop.
+
+**L2 — memory decisions + recorded edges.** Resolve the project's
+built-in memory dir the way orient does (prefer
+`node -e "console.log(require('./scripts/project-context.cjs').resolveMemoryDir())"`
+when that script exists; else `~/.claude/projects/<dashified-cwd>/memory`),
+then have the SAME helper parse the decision files (the consumer resolves
+the path; the helper owns the edge rule):
+```bash
+node scripts/watchtower-narrative-corpus.mjs --memory "<memory-dir>"
+```
+Each entry carries `supersedes` (RECORDED, directional edges) and
+`see_also` (undirected wikilinks — **never** render a see-also as a
+supersession).
+
+**L3 — methodology "why" (richest substrate).** If `.claude/methodology/`
+exists in the cwd, read its `README.md` index and the `-internal.md`
+bodies relevant to the load-bearing decisions — these carry the
+Claim→Evidence→Skeptic→Counter reasoning the other stores summarize away.
+
+**L4 — pib-db design rationale.** `pib_list_actions` for the current
+project (resolve the `prj:` fid via `pib_list_projects`; if the name is
+ambiguous, ask — never guess). Action notes carry `absorbs act:…` /
+`Supersedes …` prose — these are **inferred** edges (prose, not a
+structural field), mark them so.
+
+**L5 — synthesize, ANSWER-FIRST** (plain English, concept-first; the tone
+contract above applies in full):
+
+1. **What still constrains this project right now** — lead with this. The
+   decisions/constraints from earlier that later work still depends on;
+   for the ones the operator might want to revisit, say whether anything
+   still hangs on them (reversible vs load-bearing). This is the answer
+   the drill-down exists to give.
+2. **Supersession chains** — what replaced what, with **provenance**:
+   *recorded* (a parsed `**Supersedes:**` block or a pib `absorbs act:`
+   marker — citable) vs *inferred* (read from prose) — labeled, never
+   conflated. A narrative is a trust surface: do not present an inferred
+   link as recorded history, and never render a `[[wikilink]]` as a
+   supersede.
+3. **The causal timeline** — OPTIONAL deep-read, placed **below** the
+   answer. Chapter by causal **pivot / phase transition** (the moments
+   direction changed — a constraint discovered, an approach superseded),
+   not by raw time gaps. Skip this entirely when the corpus is sparse.
+
+**Honesty footer.** Report `per_store_counts` and `skipped_unresolved` in
+plain words when either is notable: "history may be incomplete — N inbox
+items couldn't be attributed to a project and may belong here." Never
+present a silently-truncated history as complete.
+
+**Sparse / empty.** If the combined decision count (inbox_kept + memory
+decisions) is under ~3, say "not enough decision history to narrate yet
+(N found)" and stop — a story needs enough points to have an arc.
+
+Lineage mode renders inline and stops. It writes nothing — no state file,
+no inbox item, no memory write.
 
 ## Step 1: Gather Data
 
-No Claude API calls in this step — pure filesystem reads. All paths
-are under `~/.claude-cabinet/watchtower/`.
-
-### 1a. Ring Health
-
-Read health files for each ring:
-
-- `state/ring1-health.json` — Ring 1 (mechanical cron): last run time,
-  success/fail, projects scanned
-- `state/ring2-fast-health.json` — Ring 2 fast tier: last run time,
-  success/fail, items enriched
-- `state/ring2-slow-health.json` — Ring 2 slow tier: last run time,
-  success/fail, synthesis results
-- `state/ring3-health.json` — Ring 3 (session-aware): last processed
-  session, backlog count
-
-If a health file is missing, note the ring as "not yet active" rather
-than erroring. Watchtower rings are deployed incrementally — a missing
-file means the ring hasn't run, not that something is broken.
-
-### 1b. Sessions Processed
-
-Scan `ring3/processed/` for session files (`.json`) within the scope
-window. For each, extract: project name, session date, duration,
-summary snippet. Count total sessions processed.
-
-If the directory is empty or missing, report "No sessions processed
-yet" — Ring 3 may not have run.
-
-### 1c. Queue Activity
-
-List `queue/items/*.json`. For each item, read `status`, `category`,
-`urgency`, `filed_at`, and `title`. Compute:
-
-- Total items by status (pending, resolved, expired, superseded, dismissed)
-- Pending items by urgency (urgent, normal, low)
-- Oldest pending item (age in hours/days)
-- Category distribution of pending items
-
-If no items exist, report "Queue empty."
-
-**QA debt (filed gaps):** while scanning, also collect RESOLVED
-`qa-handoff` items whose `qa_verdict.filed_gaps` is non-empty (the
-`verified · N gaps filed` verdicts). For each, check whether the filed
-`act:` fids are still open in pib-db (`pib_get_action`, or
-`node scripts/pib-db.mjs get <fid>`); drop entries whose fids are all
-closed. Surviving gaps are unretired QA debt — "filed" must not mean
-"forgotten."
-
-### 1d. Portfolio State
-
-Read project state files from `state/projects/*.md`. For each project
-within scope, extract the key sections: Active Plans, Last Session,
-Standing Issues. If a project filter was specified, only read that
-project's file.
-
-### 1e. Active Threads
-
-Read `state/threads/*.json`. For each thread file, parse the JSON and
-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)
-- `last_updated` (timestamp)
-- `sessions` array length (how many sessions have touched it)
-
-If a project filter is active, filter to threads whose `sessions` array
-contains at least one entry with a matching `project` slug. If no thread
-files exist, skip silently — threads accumulate over time.
-
-Sort by `last_updated` descending (most recent first).
-
-### 1f. Last Briefing Timestamp
-
-Read `state/last-briefing.json` if it exists. Use this to determine
-what's "new since last briefing" for the default scope. If the file
-doesn't exist, fall back to "last 24 hours."
-
-## Step 2: Top-Level Brief
-
-Present a scannable summary in **10 lines or fewer.** This is the
-executive view — the user should know the state of everything in one
-glance.
-
-Format:
-
+No Claude API calls — pure filesystem reads plus the queue lib. State
+paths are under `~/.claude-cabinet/watchtower/`; the queue lib is the
+project-root `scripts/watchtower-queue.mjs` (any watchtower-installed
+project's copy operates on the shared global queue — this is what
+makes "run from any desk" work).
+
+### 1a. Ring health
+
+Read `state/ring1-health.json`, `state/ring2-fast-health.json`,
+`state/ring2-slow-health.json`, `state/ring3-health.json`. A missing
+file means "not yet active", not an error. Thresholds: **ok** — last
+success within expected cadence (Ring 1: 5 min, Ring 2 fast: 15 min,
+Ring 2 slow: 6 hours, Ring 3: since last session end); **stale** —
+exceeded 2x cadence; **down** — missing after previously running, or
+last run failed.
+
+### 1b. Sessions processed
+
+Scan `ring3/processed/` for session files within the scope window:
+project, date, duration, summary snippet.
+
+### 1c. The inbox, in full
+
+Run `runExpiry()` first (warn 14d, expire 30d — the mechanical decay
+floor; gated categories never expire, they warn). Then load ALL
+pending items via `listPending()` and group by `item.project`. Items
+carrying `project_unresolved: true` form their own group (see Step 3).
+Collect per project: counts by category and urgency, age distribution,
+and titles. Also collect resolved `qa-handoff` items whose
+`qa_verdict.filed_gaps` is non-empty; check each filed `act:` fid in
+pib-db (`pib_get_action` or `node scripts/pib-db.mjs get <fid>`) and
+keep only still-open ones — these are the open QA debts for Step 4.
+
+### 1d. Cross-ring portfolio view (state, threads, git attention, resolution history)
+
+Run the cross-ring reader — ONE gather call that replaces the old
+per-store reads (state files + threads) and adds two signals nothing
+here consulted before: the inbox **resolution history** (with
+`resolution_mix` ratios — what the operator's past decisions actually
+engaged vs discarded, per project) and the structured **git-attention
+facts**:
+
+```bash
+XRING="$(mktemp)"
+node scripts/watchtower-cross-ring-reader.mjs --portfolio > "$XRING"
+# with a project filter active: --project "<name or slug>" instead
+# (config-key name preferred; a unique slug match also resolves)
 ```
-## Briefing — [scope description]
 
-**Sessions:** N processed since [time]. Last: [project] ([when]).
-**Queue:** N pending (M urgent). Oldest: [age]. [N resolved since last briefing.]
-**Health:** Ring 1 [ok/stale/down]. Ring 2 fast [ok/stale/down]. Ring 2 slow [ok/stale/down]. Ring 3 [ok/stale/down].
-**Threads:** N active. Most recent: [thread-slug] — [cursor.what].
-**Portfolio:** N projects tracked. [1-2 line highlight of what's active or needs attention.]
+**Consume by Reading the file, never by echoing it through Bash** — a
+live portfolio view runs to a few hundred KB and Bash tool output
+truncates long before that (a truncated JSON parse is the failure this
+instruction exists to prevent). Read the envelope's top (counts +
+honesty fields) for Step 2, then Read each project's view slice as you
+walk that chunk in Step 3; the JSON is pretty-printed, so each
+project's view is one contiguous block.
+
+Per project it returns the parsed Ring 1 state sections (Active Plans,
+Last Session, Standing Issues, Tech Stack), git-attention facts, recent
+session summaries, thread cursor timelines (capped to the newest 3
+snapshots with `history_total` — the full evolution is lineage mode's
+job; a legacy lone-`cursor` file arrives as a single-entry history;
+current cursor = the LAST history entry), pending counts by
+category/urgency, and the resolution history (`resolution_mix` carries
+full counts; the event list is capped with `resolution_events_total`).
+Every cap reports its total — "3 of 85" is signal, not truncation. The
+envelope's honesty fields (`unattributed_items`, `orphan_threads`,
+`orphaned_state_files`) are real signal — surface them in plain words
+in Step 4 when notable. Pending COUNTS here are a narration snapshot;
+1c's live `listPending()` load stays the disposition source of truth.
+
+**Fallback (script absent — a consumer that hasn't reinstalled since
+the reader shipped):** read the raw stores directly as 1e describes,
+and proceed without the resolution-history/git-attention signals.
+
+### 1e. Active threads (fallback path only)
+
+Normally covered by the 1d view. When the 1d fallback is in effect,
+read `state/threads/*.json`; collect `status: "active"` threads. The
+current cursor is `cursor_history[last].cursor` (older files may carry
+a lone `cursor` object — treat it as current). Extract `what`,
+`where_left_off`, `next_steps`, `last_updated`, session count. Sort by
+`last_updated` descending. (Also read `state/projects/*.md` — Active
+Plans, Last Session, Standing Issues per project, scope-filtered if a
+project filter is active.)
+
+### 1f. Last briefing timestamp
+
+Read `state/last-briefing.json` if present — it anchors "new since
+last briefing" for the default scope.
+
+### 1g. Spawn the live advisor panel (full mode only)
+
+The standing session advisors hold their start-side seat here — this is
+where intent exists, the thing background runs are blind to. Discover
+the panel from `.claude/skills/_index.json`: entries whose
+`standingMandate` includes `"briefing"`, each with a
+`directives.briefing` scoped task (a mandate without a directive is a
+data error — skip that member, say so). Spawn all members in parallel
+NOW, right after the Step 1 reads, so they work while you compose Step
+2. Each agent gets: its SKILL.md (from the index `path`), the
+portfolio data gathered above (state summaries, active threads, pending
+counts), and its `directives.briefing` as the task — constrained to a
+**one-to-few-line observation**. The constraint is load-bearing.
+
+Collect results before Step 3. Route them through the curation seam —
+never as their own section: an observation about a specific project
+becomes a Step 3b candidate in that project's chunk; a portfolio-level
+observation is Step 4 close material. Include only members who said
+something; silence is fine and is the common case. In recap mode, skip
+the panel entirely — it spawns only on full-mode invocation.
+
+### 1h. Unprocessed DX captures (mux's global capture list)
+
+Read mux's global DX-capture store — `~/.local/share/mux/dx.json` — the
+single cross-project list where `mux dx "..."` and `/dx-feedback` drop
+developer-experience ideas and friction. A pure filesystem read with no
+ordering dependency on the panel spawn. If the file is absent or
+unparseable (mux not installed, or no captures yet), skip silently — it
+is a mux-owned store and its absence is normal, not an error.
+
+An item is **active** (unprocessed) only when BOTH `done` is false AND
+`filed` is false. `done` items were cleared; `filed` items already live
+in pib-db (an action or feedback) — resurfacing either is exactly the
+write-only-telemetry bug this duty exists to kill. Collect each active
+item's `text`, `created_at`, `origin`, and its **global active-list
+position** (1-based index among active items — the position
+`manage-dx.py` addresses when draining). Resolve each item's `origin` to
+a walk project where you can: labels like `"claude-cabinet"` or `"flow"`
+map to a project chunk; labels like `"session-observation"` or
+`"unknown"` do not — those are portfolio-level (Step 4). If there are
+zero active items, skip silently. (This was orient's job; post-orient
+nothing reads these unless the briefing does — see
+`lesson_write_only_telemetry_wire_a_reader`.)
+
+## Step 2: Top Brief
+
+Ten lines or fewer — the whole portfolio in one glance, curated. Not a
+fixed template: lead with the one or two things that genuinely matter
+today (a gate waiting, an urgent item, a fresh advisor finding from
+last session's close, a thread left mid-flight, a ring down), then the
+compact vitals:
 
-[If any urgent queue items exist, list them here — one line each.]
-[If any resolved qa-handoff verdicts carry still-open filed_gaps, add:
-**QA debt:** N gaps filed by past QA verdicts still open — act:fid (gap), one line each.]
 ```
+## Briefing — [scope, in words]
 
-Health status thresholds:
-- **ok** — last successful run within expected cadence (Ring 1: 5 min,
-  Ring 2 fast: 15 min, Ring 2 slow: 6 hours, Ring 3: since last session end)
-- **stale** — last run exceeded 2x expected cadence
-- **down** — health file missing or last run was a failure
-
-## Step 3: Progressive Disclosure (Full mode only)
-
-In **factual/recap mode, STOP here.** The summary is the deliverable.
-
-In **full mode**, offer drill-down using `AskUserQuestion`:
-
-- `header`: `"Briefing"`
-- `question`: `"What would you like to drill into?"`
-- `options`:
-  - Sessions — "Review processed sessions in detail"
-  - Queue — "Walk through pending inbox items"
-  - Threads — "Active work threads and their cursors"
-  - Health — "Ring health details and diagnostics"
-  - Portfolio — "Per-project deep dive"
-  - Looks good — "Nothing to drill into, move on"
-- `multiSelect: false`
-
-### Sessions drill-down
-
-List each session processed within scope: project, date, duration, and
-the Ring 3 summary. Group by project if multiple projects are in scope.
-
-### Threads drill-down
-
-Present all active threads sorted by `last_updated` (most recent first).
-For each thread, show:
-
-- Thread slug and `cursor.what`
-- `cursor.where_left_off` (the understanding that survives across sessions)
-- `cursor.open_questions` if any
-- `cursor.next_steps` if any
-- Session count and last updated date
-
-If a project filter is active, show only threads touching that project,
-with the primary thread (most recently touched by a session in that
-project) expanded with full cursor detail, and other threads as one-line
-summaries.
-
-If there are dormant threads (status: "dormant"), mention the count but
-don't list them unless the user asks.
-
-### Queue drill-down
-
-Present pending queue items sorted by urgency (urgent first), then by
-age (oldest first). For each item, show: id, title, category, urgency,
-age, summary. If the item has enrichment (`enrichment_status: complete`),
-note that enrichment is available.
-
-After presenting, offer to open the `/inbox` skill if the user
-wants to act on queue items.
-
-### Health drill-down
-
-For each ring, show: last run timestamp, success/failure history,
-items processed, any error messages from the health file. If a ring
-is stale or down, suggest diagnostic steps.
-
-### Portfolio drill-down
-
-Present the full project state file for each project in scope. If the
-user specified a project filter, show only that project. Otherwise,
-list projects and let the user pick one.
-
-After any drill-down completes, offer the drill-down menu again (loop)
-until the user selects "Looks good."
-
-## Step 4: Cabinet Lens
-
-**Only activates** when the user selects "Portfolio" drill-down with
-scope "all" — meaning they want the broadest view.
-
-Discover cabinet members with `standing-mandate` that includes `orient`
-(same discovery mechanism as /orient's cabinet consultation phase: read
-`.claude/skills/_index.json`, filter by `standingMandate` containing
-`"orient"`).
-
-Spawn each matching member with a constrained task: **ONE LINE
-observation** about the portfolio state gathered in Step 1. No full
-audit, no detailed analysis. The constraint is load-bearing — without
-it, cabinet members produce pages of analysis that bury the briefing's
-signal.
-
-Collect responses and present them after the portfolio detail:
+[1-3 curated headline lines — what actually deserves attention today.]
 
+**Since [last briefing/time]:** N sessions across M projects. Last: [project] ([when]).
+**Inbox:** N pending across M projects ([K urgent, G gated]). [Expiry note if items expired.]
+**Health:** one line — "all rings ok" when true; name only the stale/down ones otherwise.
 ```
-### Cabinet Observations
-- **[member-name]:** [one-line observation]
-- **[member-name]:** [one-line observation]
+
+In **factual/recap mode, stop here** (after Step 5's timestamp). The
+summary is the deliverable.
+
+In **full mode**, continue straight into the walk — no menu, no
+ceremony. One transition sentence: name the chunk order and why
+("Three projects have items waiting; starting with X — it has the
+gate.").
+
+## Step 3: The Project Walk
+
+One project at a time, in curated order: lead with the chunks the
+operator can actually act on from this session — the current desk and
+any project with dispositionable (ungated, this-desk) items — then
+projects with pending gated items, then urgent items, then by thread
+recency and pending count; quiet projects last (and a project with
+nothing to say gets one line or silence — absence of news is news the
+operator doesn't need). A project filter scopes the walk to that
+project. **Why actionable-first:** a cross-desk gated item can only be
+"left queued for its own desk" from here — it is read-only from this
+session, so surfacing it (and a wall of another desk's state) before
+the operator's own decisions just front-loads context they must hold.
+Surface it, but later. A gated item is never dropped (floor #1); it is
+only re-ordered.
+
+**Decisions are never interleaved.** Each project's chunk completes —
+narrative, attention items, dispositions executed — before the next
+project is named. Cross-project observations wait for Step 4.
+
+Items in the `project_unresolved` group form a final chunk of their
+own, presented explicitly as "unresolved project" with each item's
+stored fallback `project` value inline — never blended into real
+project chunks, never silently dropped (fail-loud contract shared
+with `/inbox`).
+
+Each chunk has three movements:
+
+### 3a. State, in plain English
+
+Two to four sentences synthesized from the project's threads, Last
+Session, and standing issues — all already in hand from the Step 1d
+cross-ring view (no second read; its parsed sections, session bullets,
+and cursor timelines are the input). Concept-first — "the publish
+pipeline is built but has never run against a live tag" — not file
+paths and fids. This
+is the operator-facing register (`cabinet/skill-output-conventions.md`
+§9) as the briefing's whole default; keep it that way. Offer nothing
+here; drill-down happens by the operator asking.
+
+### 3b. Curated attention (top-N selection)
+
+Select **at most five** attention items for this project. This selection
+step is where ALL "briefing should show X" duties land — see the
+invariant. The weighable **candidate classes** (source · freshness/decay ·
+floor-or-not) — a new duty adds an entry here, never a section:
+
+- **Gated items** (`qa-handoff`) · pending in queue · **floor #1, always
+  included** (specific handling below).
+- **Urgent-urgency items** · pending · weigh high.
+- **Moment-is-now items** · a `routine` still within `stale_after_hours`,
+  a deferred trigger that fired · weigh high while fresh (handling below).
+- **Open QA filed-gaps** belonging to this project · until the `act:` fid
+  closes · floor in Step 4, weighable here.
+- **Advisor signals** · fresh `advisor-finding` items + live panel
+  observations · weigh fresh near the top, then decay (sources below).
+- **Backlog-hygiene nudge** · the per-project state file's Standing Issues
+  shows ≥3 stale project(s) OR ≥2 completion candidate(s) (Ring 1 renders
+  these counts) · one line max, "backlog showing cruft — consider
+  /spring-clean" · decays once the counts fall; never its own section.
+- **Environment advisories** · `suggested` entries in
+  `.claude/cabinet/advisories-state.json` (the watchtower context builder's
+  advisory pass already wrote them) for this chunk's project · one line
+  each, weigh low — they self-quiet after two surfacings · no probe here,
+  just read the surfacing state.
+- **Verify signals** · shipped-uncovered warnings · weigh as they arrive.
+- **State-file flags** · anything in Standing Issues that needs a human.
+- **Unprocessed DX captures** · active items in mux's global `dx.json`
+  (1h) whose `origin` resolves to this chunk's project · weigh fresh,
+  then decay like any aged item — one line each, with a process/dismiss
+  path so the list actually drains (handling below) · not a floor:
+  captures are freely drainable and dismissable. Captures whose origin
+  resolves to no walk project go to the Step 4 close — never silently
+  dropped.
+
+Everything else stays in the batch counts below.
+
+Advisor signals come from two sources, both weighed here:
+
+- **Fresh close-pass findings** — pending `advisor-finding` items filed
+  since the last briefing (Ring 3's session advisor pass, or an
+  /orient / /debrief consultation that persisted an actionable
+  finding — same channel). These are
+  the re-surfacing path the close pass promises: weigh a fresh one near
+  the top of this project's selection so it surfaces at the briefing
+  after the session that produced it, then let it decay into batch
+  fodder like anything else. Stale advisor findings are ordinary
+  ungated items — legal batch material in 3c.
+- **Live panel observations** (Step 1g) that named this project.
+
+Three categories get specific handling when selected:
+
+- **Gated items (`qa-handoff`):** present what merged and what hangs
+  on it, then offer exactly two paths — run the recipient gate now in
+  this session (the qa-handoff skill's "The recipient gate" section is
+  the playbook; the stamped verdict is the only exit), or leave it
+  queued for its desk's QA station. Never fold a gated item into any
+  batch; never dismiss it to tidy the count (the lib will throw, by
+  design).
+- **Routine items:** a declared routine fired and wasn't picked up at
+  its desk. If its moment is still live (within `stale_after_hours`),
+  offer to run its `evidence.script` conversation here and resolve
+  `acted-on`. If the moment passed (yesterday's morning briefing),
+  propose it for the stale batch below — routine items are dispatched
+  but not gated, and the engine supersedes stale ones anyway.
+- **DX captures:** write-only until something drains them. Surface each
+  active capture as one plain line (the idea · when · where it came
+  from) and offer exactly two paths, one decision at a time — **process**
+  it (act on it now, or file it to pib-db as an action or feedback, then
+  mark it filed) or **dismiss** it as no-longer-relevant. Both paths
+  drain the list through mux's own tooling — single source of truth,
+  never hand-edit `dx.json`:
+
+  ```bash
+  # dismiss (clear) a capture — n is its position in the active list
+  python3 ~/.config/mux/manage-dx.py done <origin> <n>
+  # after filing a capture to pib-db, mark it filed (drops it from the panel)
+  python3 ~/.config/mux/manage-dx.py mark-filed <origin> <n>
+  ```
+
+  `<n>` is the global active-list position, and positions renumber as
+  items leave — when draining several, clear from the **highest position
+  down** (or re-read positions between marks) so an earlier removal can't
+  shift the index out from under you. `<origin>` is context only; the
+  number addresses the global active list regardless of origin.
+
+### 3c. Batch dispositions
+
+**First, the sign-off batch — the SAVE direction (M4, act:ffae4eec).**
+Before any decay clustering, partition this project's ungated pending
+items with `partitionForBatchSignoff` (the lib owns the predicate). Its
+`signoff` set is the high-confidence pre-drafted knowledge-extraction
+items (non-empty `draft_artifact`, not urgent, not low-confidence) —
+work the rings already did that needs a nod, not a judgment. Offer the
+whole set as ONE sign-off decision ("the background system drafted these
+N memory entries; approving writes them to memory — sign off on all?").
+On approval, write each `draft_artifact` to memory (`/cc-remember` or a
+direct write), THEN one `applyBatch` resolve with
+`resolution_type: 'captured-to-memory'`. This is the throughput valve:
+M1/M2 raise inflow and success = filed × approval-rate (the M5 canary
+tracks it), so a fast sign-off keeps drafts from ageing out
+unadjudicated. Pulled-out items get per-item `/inbox` treatment after
+the walk; everything else falls to the decay flow below — still one
+decision at a time, the sign-off batch presented first.
+
+**Then, decay clustering.** Cluster this project's REMAINING pending
+items into **at most three
+proposed batches** by theme — category × age × thread is the usual
+axis. For each batch, propose a disposition in plain English with the
+reasoning visible. Decay lives here: the curator's default proposal
+for an aged, ungated cluster is dismissal-as-stale ("these 14 are
+knowledge-extraction drafts from May; the threads they fed have moved
+on — archive?"), always scoped to this project, never a global sweep.
+A batch proposal must name: what's in it (count + a few example
+titles), the proposed disposition, and the typed reason that will land
+on every item.
+
+Ask for approval **one decision at a time** — never a stack of
+questions under a wall of context, never a same-turn dialog. Two
+failure modes, both observed live: a same-turn dialog eclipses the
+reasoning above it, so the operator approves logic they cannot see
+(recurred 2026-06-13); and a long narrative followed by several
+questions at the end forces the operator to hold every batch's
+rationale in their head at once, which they cannot (recurred
+2026-06-14). **The decision/context structure rule:** the only thing
+that should require working memory is the single decision in front of
+the operator, with its reason immediately beside it.
+
+The shape: present **one batch** — what's in it (count + a few example
+titles), the proposed disposition, the typed reason — then a one-line
+question ("Dismiss these 14 as stale? y / n / show me") and the turn
+STOPS. The operator answers in prose. Apply it, confirm in one line,
+then present the next batch the same way. Pure read-only material —
+portfolio state for desks the operator isn't on, platform notes,
+anything needing no decision — is delivered AFTER all decisions are
+made; it costs nothing to hold, so it never sits above a decision.
+Reserve `AskUserQuestion` only for a self-contained choice whose
+options stand on their own inside the dialog (e.g. a layout pick with
+previews); batch dispositions never qualify.
+
+Execute approved batches immediately via the queue lib, then say what
+happened in one line each and move to the next project:
+
+```bash
+node --input-type=module -e "
+import { applyBatch, partitionForBatchSignoff, listPending } from './scripts/watchtower-queue.mjs';
+// Sign-off batch (M4): partitionForBatchSignoff(listPending({project})).signoff
+// → resolve 'captured-to-memory' (write each draft_artifact FIRST). Decay='dismiss'.
+const r = applyBatch([/* ids */], {
+  disposition: 'dismiss',            // or 'resolve' (the sign-off batch)
+  resolution_type: 'stale',          // typed reason — required ('captured-to-memory' for sign-off)
+  notes: '<the reason shown to the operator, verbatim>',
+});
+console.log(JSON.stringify(r));
+"
 ```
 
+`applyBatch` pre-validates the whole batch and throws before writing
+anything if a gated item slipped in — the carve-out is structural, not
+etiquette. Choose `resolution_type` honestly per batch: `stale`
+(overtaken by events), `noise` (shouldn't have been filed),
+`captured-to-memory` / `acted-on` for resolve batches — these feed the
+trust-ladder ratios. Items the operator pulls out of a batch get the
+`/inbox` per-item treatment (offer it after the walk, not mid-chunk).
+
+## Step 4: Cross-Portfolio Close
+
+The only non-project section, and it is curated like everything else:
+include a part only when it has signal.
+
+- **Cross-cutting synthesis** — patterns spanning projects (the same
+  friction filed from two desks, a theme across threads, a decision
+  made in one project that answers a question open in another). The
+  substrate is the Step 1d cross-ring portfolio view — synthesize from
+  its per-project views (git-attention facts across projects,
+  `resolution_mix` ratios, thread/session convergence) instead of
+  re-deriving from raw stores. Its honesty fields belong here too, in
+  plain words when notable: "N inbox items couldn't be attributed to
+  any project", "one active thread matches no configured project".
+  The synthesis itself stays live — the reader gathers, this session
+  thinks.
+- **Standing debts** — floor #2: while any QA filed-gaps remain open,
+  one roll-up line each ("X still owes the migration test filed by
+  last week's QA — act:fid"). Same treatment for unmerged-worktree
+  warnings surfaced by the state files.
+- **Advisor panel, portfolio-level** — the Step 1g observations that
+  span projects rather than belonging to one chunk land here (a
+  historian precedent that answers an open question, a platform delta
+  from the insider, a legibility flag from the user-advocate). One line
+  each, only members who said something — never a roll call.
+- **Unprocessed DX captures, portfolio-level** — active `dx.json`
+  captures (1h) whose `origin` resolved to no walk project land here,
+  one line each, with the same process/dismiss drain path as the
+  per-project handling (3b). Only when some exist; never a standing
+  section.
+
+Close with one sentence: dispositions applied this run (N resolved, M
+dismissed, across K projects), what remains pending, and — only if
+something is genuinely waiting on the operator — the single next thing.
+
 ## Step 5: Record Timestamp
 
-After the briefing completes (regardless of mode), write
+After the briefing completes (any mode), atomically write
 `~/.claude-cabinet/watchtower/state/last-briefing.json`:
 
 ```json
@@ -255,42 +591,54 @@ After the briefing completes (regardless of mode), write
   "scope": "<the scope that was used>",
   "mode": "full" | "recap",
   "sessions_covered": <count>,
-  "queue_pending_at_time": <count>
+  "queue_pending_at_time": <count>,
+  "dispositions": { "resolved": <n>, "dismissed": <n> }
 }
 ```
 
-Use atomic write (temp + rename) per watchtower contracts.
-
----
+## Edge Cases
+
+- No watchtower install (`~/.claude-cabinet/watchtower/` missing):
+  say so and point at `/watchtower install`. Don't improvise state.
+- Queue lib missing at `scripts/watchtower-queue.mjs` (project without
+  the watchtower module): deliver the read-only briefing from global
+  state and say dispositions need a watchtower-installed project.
+- Corrupt/unparseable item files: skip with a one-line warning count.
+- No mux DX store (`~/.local/share/mux/dx.json` missing, or mux not
+  installed): skip the DX-capture candidate silently — a mux-owned
+  store's absence is normal, not an error.
+- An `applyBatch` throw is a stop-and-show, not a retry loop: name the
+  item that tripped the gate, pull it into per-item handling, re-offer
+  the rest as a new batch.
 
 ## Calibration
 
-**Core failure this targets:** The user returns to their portfolio and
-has no idea what happened while they were away. Watchtower processed
-sessions, enriched queue items, detected issues — but none of that
-reaches the user unless they know where to look and which files to read.
+**Core failure this targets:** attention flow-control. The background
+rings file faster than item-by-item triage drains, so the inbox grows
+until the operator stops looking — and the things that DO need eyes
+(a QA gate, a fired routine, a dying ring) drown in batchable noise.
 
 ### Without Skill (Bad)
 
-The user starts a session after a day away. They know watchtower is
-running but don't know what it found. They manually check
-`~/.claude-cabinet/watchtower/state/summary.md` — it's a template with
-placeholders, or it was last updated hours ago. They `ls` the queue
-directory and count files. They open each project state file. They piece
-together a picture from raw artifacts across five directories.
-
-Twenty minutes of manual archaeology to answer "what happened while I
-was gone?" — and they still miss the urgent queue item filed by Ring 2
-because it was in a subdirectory they didn't check.
+The operator returns after a day. The inbox shows 174 pending. They
+open `/inbox`, review four items one at a time, lose patience, and
+close it. The qa-handoff filed yesterday sits unworked behind 50
+knowledge-extraction drafts. Next week the inbox shows 230 and the
+operator has stopped running anything at all — the surfaces produced
+signal but no decision throughput.
 
 ### With Skill (Good)
 
-The user says "/briefing" or "what's the landscape." Ten lines appear:
-3 sessions processed, 2 queue items pending (1 urgent), all rings
-healthy, the maginnis project has a stale branch. The urgent queue item
-is right there in the summary. The user drills into "Queue," reads the
-enrichment, opens `/inbox` to resolve it. Five minutes, full picture,
-nothing missed.
-
-Or the user just wants the facts — "/recap" delivers the summary and
-stops. No questions, no drill-down, no cabinet. Just the numbers.
+The operator says "/briefing". Ten lines: one gate waiting on
+claude-cabinet, two rings ok one stale, 174 pending of which ~150 are
+three stale batches. The walk starts with claude-cabinet: state in two
+sentences, the gate presented with its two paths, then "these 40
+knowledge drafts predate the threads they fed — archive?" Three
+plain-prose approvals later, 120 items are dispositioned with typed
+reasons, the gate is queued deliberately for the QA station, and the
+close notes one cross-project pattern worth a future action. Eight
+minutes, decisions made where the operator already was — and nothing
+gated or filed-as-debt was waved away in the bulk.
+
+Or the operator just wants the facts — "/recap" delivers the summary
+and stops.