create-claude-cabinet 0.34.1 → 0.36.0

package/package.json

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

package/templates/cabinet/skill-best-practices.md

@@ -40,6 +40,13 @@ slash commands for CC maintenance.
 
 These hold for every SKILL.md regardless of type.
 
+**Runtime output formatting lives in a sibling doc.** This doc covers
+*write-time* authoring. For *runtime* user-facing output — when a running
+skill should present choices via the native `AskUserQuestion` tool versus
+prose versus a markdown table, plus the AskUserQuestion schema facts
+authors must get right — see `skill-output-conventions.md`. Follow that
+pointer whenever a skill prompts the user to make a decision.
+
 ### Body under 500 lines
 
 The SKILL.md **body** — content after the closing `---` of

package/templates/cabinet/skill-output-conventions.md

@@ -0,0 +1,153 @@
+# Skill Output Conventions
+
+How skills format **user-facing output** and **interactive prompts** at
+runtime. The companion to `skill-best-practices.md`.
+
+## 1. Purpose & Scope
+
+`skill-best-practices.md` governs **write-time** authoring rules — file
+structure, naming, frontmatter, length. This doc governs **runtime**
+interaction: how a skill, while executing, presents choices and
+information to the user. `output-contract.md` is a third, separate
+concern — the JSON cabinet members emit during audits, not user-facing
+output.
+
+Stating the boundary keeps the three docs from drifting together: if a
+rule is about *how a SKILL.md is written*, it belongs in
+skill-best-practices; if it's about *what the running skill shows the
+user*, it belongs here.
+
+## 2. When to Use AskUserQuestion
+
+`AskUserQuestion` is the native interactive primitive — a structured
+menu of 2-4 options the user picks from. Use it when **all** of these
+hold:
+
+- The choice is among **discrete options** (not free text).
+- The answer **branches the skill's behavior** (it's a real decision).
+- There are **2-4 mutually-exclusive choices** (or a small set if
+  multiSelect).
+- It is **not an obvious-default confirm** — a yes/no where one answer
+  is plainly expected (see §5).
+- The item count is **bounded and small** — not a variable-length loop
+  (see §4).
+
+If any answer is "no," use prose (§5) or a table (§6) instead.
+
+## 3. Schema Facts Authors Must Get Right
+
+Verified against the live schema. Get these wrong and the call fails or
+behaves unexpectedly.
+
+- **1-4 questions per call; 2-4 options per question.** Outside this
+  range fails validation.
+- **`header` is REQUIRED** — a short chip/tag, **max 12 chars** (e.g.
+  `Branch`, `Verdict`, `Decision`). Omitting it fails validation. This
+  is the most common authoring mistake.
+- **Cost is per-session, not per-call.** AskUserQuestion is a deferred
+  tool: the first use in a session loads its schema (one ToolSearch
+  round-trip, ~200 tokens); every call after that is free. Don't
+  under-use it to "save" a cost that's already paid.
+- **`multiSelect` is required.** `false` for mutually-exclusive choices
+  (the norm — one answer). `true` only when the user may legitimately
+  pick more than one.
+- **"Other" is auto-added** by the harness. Never add an "Other" /
+  "Something else" option manually — it duplicates.
+- **No reliable preview/comparison field.** The official schema has no
+  dependable preview surface; don't build conventions on preview
+  behavior or expect side-by-side rendering.
+- **Unavailable in Task-spawned subagents.** Agents launched via the
+  Task tool (execute-group worktree agents, Workflow agents,
+  `context:fork`) cannot call AskUserQuestion — they must use prose.
+  This warning outlives any current wiring: a skill that runs in the
+  main session today may be called from a subagent tomorrow.
+- **Pre-specify each call site** in the SKILL.md prose — exact `header`,
+  `question`, and option labels/descriptions. In a long skill body the
+  model otherwise drifts to a prose question instead of emitting the
+  structured call. (This is an authoring practice — `skill-best-practices.md`
+  is the write-time home for it — surfaced here because it's what makes a
+  runtime AskUserQuestion call fire reliably.)
+
+## 4. Bounded-List Caveat
+
+AskUserQuestion is for **decisions**, not **batch processing**. A
+variable-length loop of homogeneous items — reviewing 12 copy edits,
+approving 30 line items — should not become 30 sequential dialogs. Past
+~5 items, prefer a single batch path (present all, take one combined
+response) over N prompts. The fatigue of N near-identical dialogs
+outweighs the structure they add.
+
+The test: are these **genuine, distinct decisions** (→ AskUserQuestion,
+one per item up to a small cap) or **homogeneous review items** (→ batch
+path)?
+
+## 5. When to Use Prose
+
+Use plain conversational prose for:
+
+- **Free-text gathering** — names, reasons, descriptions, anything not
+  a fixed menu.
+- **Clarifications and reasons** — "why did you defer this?"
+- **Obvious-default confirms** — a yes/no where one answer is plainly
+  expected and the other is rare. A structured menu over-formalizes it;
+  a prose "Want me to X? (I'll skip if not)" is lighter.
+
+## 6. When to Use Markdown Tables
+
+Use a table for **rosters, status, or any data with ≥2 columns** —
+where the value is in *comparing rows*, not *choosing one*. The `/menu`
+skill (skills × description) and `/cabinet` (member × domain) are
+canonical examples. A table presents; AskUserQuestion decides. Don't use
+a table to offer a choice, and don't use AskUserQuestion to display a
+list the user isn't picking from.
+
+## 7. Option-Block Format
+
+When presenting options as prose (subagent context, or >4 options), the
+canonical format is in `templates/skills/onboard/phases/options.md` —
+name, "what it is," "good for," "trade-off" per option. Do not duplicate
+that format here; reference it.
+
+## 8. Section Structure & Tone
+
+`options.md` is also canonical for tone: **present, don't prescribe.**
+"Here are your options" not "I recommend X." Ground choices in the
+user's actual situation. This applies whether the choice is rendered via
+AskUserQuestion or prose — the primitive changes, the posture doesn't.
+
+## 9. Calibration Examples
+
+**Before/after — engagement decision items** (the Tier 1 conversion):
+
+> Before: "Present the options conversationally and let the client
+> choose."
+> After: For each decision item, one AskUserQuestion call — `header:
+> "Decision"`, `question:` the item's client-facing prompt, `options:`
+> the item's own authored option list, `multiSelect: false`. One call
+> per item; never batched.
+
+Why: the items already carry discrete, consultant-authored options, and
+this is the consultant↔client boundary where ambiguity is most expensive
+and the client can't ask for real-time clarification.
+
+**Before/after — triage-audit fallback verdict:**
+
+> Before: a prose prompt listing "Fix / Defer / Reject / Question" and
+> asking the user to type one.
+> After: AskUserQuestion — `header: "Verdict"`, four options, one per
+> finding, `multiSelect: false`.
+
+Why: four discrete mutually-exclusive verdicts that branch behavior —
+this scores well on all five §2 criteria.
+
+**EXCLUDED — orient registry-orphan prompt** (do NOT convert):
+
+> "Your old project 'deal-v1' seems to have been deleted — want me to
+> remove it from the registry?"
+
+This looks like a Remove/Keep choice but is an **obvious-default
+confirm**: the path no longer exists, so removal is plainly expected and
+"keep" is the rare exception. A structured two-option menu over-formalizes
+a routine yes/no. Leave it prose. This is the boundary that stops
+AskUserQuestion from being applied to every binary question in the
+codebase.

package/templates/engagement/engagement-schema.md

@@ -187,6 +187,14 @@ One or more "why this matters" lines for the client.
 blocks dispatch until it is supplied (the internal `text` is never
 shown to a client verbatim).
 
+**Literal `\n` normalization.** When notes are written via MCP tools
+that JSON-encode the string, newlines sometimes arrive as literal
+two-character `\n` sequences (backslash + n) instead of real newlines.
+`parseClientCopy` normalizes these before parsing — titles won't contain
+stray `\n` characters. Status suffixes like "— complete" or "— shipped"
+are also stripped from titles since the bucket placement already
+communicates status.
+
 The copy block may be human-written or generated-then-approved.
 `/engagement-sync` step 3.5 can auto-draft copy from structured action
 metadata (via `buildGenerationSource`), with the consultant reviewing
@@ -240,6 +248,9 @@ transport:
   type: email                      # the CHANNEL (email | mcp | file)
   consultant: "oren@example.com"   # where client feedback is sent
 
+engagement_notes:                  # persistent notes shown at top of every packet
+  - "All email logic is built and tested on staging — real delivery activates once Postmark is configured."
+
 sections:                          # the credential checklist = one section
   - key: go_live
     title: "Go-Live Credentials"
@@ -274,8 +285,10 @@ A **packet** is a per-recipient projection of engagement state. Fields:
 engagement, packet_id, recipient, role, generated_at,
 needs_you: [ { ref, title, why, kind, options } ],
 in_flight, shipped, delegated,
-billing,            # present ONLY if roles[role].billing === true
-messages, new_since_last, generated_label
+billing,              # present ONLY if roles[role].billing === true
+messages, new_since_last, generated_label,
+engagement_notes,     # persistent consultant-authored notes (from config)
+checklist_summary     # [ { type, count } ] when engagement.yaml has sections
 ```
 
 - The client **never** sees `action_fid` — items are referenced by an
@@ -306,13 +319,15 @@ The pure render engine (`engagement.mjs`, imports nothing — the adapter
 boundary) pins these behaviors so Phase 3/4 can build on them without
 reopening Phase 1:
 
-- **`renderPacket` returns `{ packet, refmap, notClientReady }`.**
+- **`renderPacket` returns `{ packet, refmap, notClientReady, allDropped }`.**
   `packet` is the client projection, built without `action_fid`/`_refmap`
   ever added (leaking is impossible by construction, not by a strip step).
   `refmap` is the consultant-side `ref → action_fid` map. The caller writes
   `{ ...packet, _refmap: refmap }` to `<recipient>-sent.json` and delivers
   `packet` alone. `notClientReady` lists fids of client-visible actions
-  dropped because they lacked a client-facing copy block.
+  dropped because they lacked a client-facing copy block. `allDropped` is
+  `true` when ALL visible items were dropped (likely a missing-notes-column
+  query bug) — the caller should halt dispatch, not send an empty packet.
 - **Not-client-ready items are dropped, never rendered with internal text.**
   A `client-visible` action with no `<!-- client-facing -->` block is
   excluded from the packet (and reported in `notClientReady`) — the engine

package/templates/engagement/engagement.mjs

@@ -16,6 +16,9 @@
 const KNOWN_TAG_PREFIXES = ['audience', 'scope', 'assignee', 'needs'];
 const KNOWN_BARE_TAGS = ['client-visible'];
 
+// Trailing status phrases that are redundant with bucket placement.
+const STATUS_SUFFIX_RE = /\s*[—–-]\s*(?:complete|completed|shipped|done|planned|in progress|started|delivered)\s*(?:\(.*\))?\s*$/i;
+
 // pib-db status → plain English shown to clients (never the raw enum).
 const STATUS_LABELS = {
   open: 'Not started',
@@ -82,8 +85,9 @@ export function loadEngagement(config) {
 
   const transport = config.transport || { type: 'email', consultant: null };
   const sections = Array.isArray(config.sections) ? config.sections : [];
+  const engagement_notes = config.engagement_notes || null;
 
-  return { engagement, billing, recipients, roles, transport, sections };
+  return { engagement, billing, recipients, roles, transport, sections, engagement_notes };
 }
 
 export function normalizeRecipient(r) {
@@ -171,8 +175,11 @@ export function parseClientCopy(notes) {
   const close = notes.indexOf('-->', bodyStart);
   if (close === -1) return null;
 
-  const inner = notes.slice(bodyStart, close).trim();
-  if (!inner) return null;
+  const raw = notes.slice(bodyStart, close).trim();
+  if (!raw) return null;
+  // Normalize literal two-char \n sequences (from double-escaping during
+  // JSON-encoded MCP writes) to real newlines before splitting.
+  const inner = raw.replace(/\\n/g, '\n');
   const lines = inner.split('\n').map(l => l.trim()).filter(Boolean);
   if (lines.length === 0) return null;
 
@@ -361,7 +368,8 @@ export function renderPacket(config, actions, events, billing, recipient, prevPa
       throw new Error(`renderPacket: stableRef collision — ${refmap[ref]} and ${a.fid} both hash to ${ref}`);
     }
     refmap[ref] = a.fid;
-    const item = { ref, title: copy.client_title, why: copy.client_why };
+    const title = copy.client_title.replace(STATUS_SUFFIX_RE, '');
+    const item = { ref, title, why: copy.client_why };
 
     if (a.completed || a.status === 'done') {
       // Completed wins over needs: a done item is never shown as pending.
@@ -408,7 +416,8 @@ export function renderPacket(config, actions, events, billing, recipient, prevPa
     }
     // Construction-not-strip: explicit field listing only. Never spread from
     // project row. fid/project_fid/name/notes/tags are never assigned.
-    const rollupItem = { title: copy.client_title, why: copy.client_why, status: rollupStatus, feedbackable: false };
+    const rollupTitle = copy.client_title.replace(STATUS_SUFFIX_RE, '');
+    const rollupItem = { title: rollupTitle, why: copy.client_why, status: rollupStatus, feedbackable: false };
     const parsedProjectTags = parseActionTags(p.tags);
     if (p.status === 'done' || (children.length > 0 && children.every(c => c.completed || c.status === 'done'))) {
       shipped.push(rollupItem);
@@ -419,6 +428,29 @@ export function renderPacket(config, actions, events, billing, recipient, prevPa
     }
   }
 
+  // Silent-empty signal: if there were visible actions but ALL of them landed
+  // in notClientReady, the caller likely used a query that omits the notes
+  // column (e.g. pib_list_actions instead of pib_query). Signal so the
+  // caller can halt dispatch instead of silently sending an empty packet.
+  const allDropped = visible.length > 0 && notClientReady.length === visible.length;
+
+  // Checklist summary: sections parsed from engagement.yaml but NOT rendered as
+  // bucket items (those are interactive via /engagement). Include a summary so
+  // the preview shows checklist coverage.
+  const sections = config.sections || [];
+  const checklistSummary = sections.length > 0
+    ? sections.map(s => {
+        const items = Array.isArray(s.items) ? s.items : [];
+        return { type: s.type || s.label || 'unknown', count: items.length };
+      })
+    : null;
+
+  // Engagement-wide notes: persistent messages from the consultant that appear
+  // at the top of every packet (e.g. caveats, disclaimers, contextual notes).
+  const engagementNotes = Array.isArray(config.engagement_notes) ? config.engagement_notes
+    : typeof config.engagement_notes === 'string' ? [config.engagement_notes]
+    : null;
+
   // Messages: engagement-level events (target_fid null) plus events whose
   // target action is still live. Events for soft-deleted / unknown actions
   // are dropped (defensive — even if the caller passed them through).
@@ -452,6 +484,9 @@ export function renderPacket(config, actions, events, billing, recipient, prevPa
     new_since_last,
   };
 
+  if (engagementNotes) packet.engagement_notes = engagementNotes;
+  if (checklistSummary) packet.checklist_summary = checklistSummary;
+
   // billing only for roles configured to receive it, and only when billing is
   // actually enabled (a config.billing with enabled:false must not produce a
   // "$0.00" section; a computed renderBilling block has no `enabled` field, so
@@ -465,7 +500,7 @@ export function renderPacket(config, actions, events, billing, recipient, prevPa
   // roles, defined role). Defense-in-depth so the dispatch path can't skip it.
   assertPacketInvariants(packet, recipient, roles);
 
-  return { packet, refmap, notClientReady };
+  return { packet, refmap, notClientReady, allDropped };
 }
 
 function extractOptions(action) {

package/templates/skills/cabinet-roster-check/SKILL.md

@@ -321,6 +321,20 @@ information-design's mock output. This should be sequential: designer
 produces mock, then usability critiques the interaction model using the
 mock as input."
 
+**Good (output conventions — prose where AskUserQuestion fits):** "/triage-audit's
+CLI-fallback path prompts the user to type one of Fix / Defer / Reject /
+Question. These are four discrete, mutually-exclusive verdicts that branch
+behavior — the canonical case for the native `AskUserQuestion` tool per
+`skill-output-conventions.md` §2. Rendering them as a prose 'type one of…'
+prompt is a guidance-layer drift. Flag as a finding pointing to that doc."
+Do NOT raise this finding for: free-text gathering (names, reasons), open
+clarifying questions, obvious-default confirms (e.g. orient's "remove the
+deleted project from the registry?" — removal is plainly expected, so prose
+is correct), or variable-length per-item loops of homogeneous items (those
+prefer a batch path, not N dialogs). Match the finding to the doc's §2
+checklist; if any checklist item fails, prose is the right call and there is
+no finding.
+
 **Too narrow (belongs to another cabinet member):** "The deploy script has a
 race condition." That's technical-debt or architecture territory.
 

package/templates/skills/engagement/SKILL.md

@@ -66,7 +66,14 @@ note before anything else:
 Always show the `generated_label` ("as of <date>") as a header so
 staleness is visible even under the threshold.
 
-### 3. Messages first, then the work
+### 3. Engagement notes, messages, then work
+
+If the packet carries `engagement_notes` (persistent consultant-authored
+notes), render them first in a distinct block before any messages or items.
+
+If the packet carries `checklist_summary`, show a single summary line
+after engagement notes: "Plus N checklist items (X decisions, Y credentials,
+...) — these appear when you run `/engagement` interactively."
 
 Render the **messages** feed distinctly from action items — each with an
 explicit sender and timestamp, in order:
@@ -74,16 +81,23 @@ explicit sender and timestamp, in order:
 > **Oren · May 30** — "Quick note: the hosting migration is scheduled
 > for next week."
 
-Then render the work, **needs_you first**:
-- **Needs your attention** (`needs_you`) — lead with these.
-- **In progress** (`in_flight`).
-- **Done** (`shipped`).
+Then render the work with **visual structure**:
+
+- **Needs your attention (N)** (`needs_you`) — lead with these. Use a
+  clear heading with the count.
+- **In progress (N)** (`in_flight`) — each item gets an arrow indicator.
+- **Done (N)** (`shipped`) — each item gets a checkmark indicator.
 - **Handled for you** (`delegated`) — place LAST, collapsed to a one-line
   summary ("Sydney is handling 3 items (marketing)"); offer to expand on
   request. It's reassurance, not a to-do.
 
-Show `billing` only if the packet carries it (principals only). Highlight
-`new_since_last` items by title.
+**Formatting rules:**
+- Every section gets a header with a count: "**Done (12)**" not just a
+  bare list.
+- Items in `new_since_last` are marked with "(new)" after the title.
+- Show `billing` only if the packet carries it (principals only). Format
+  billing as a clear table (Date | Hours | Work), with rate and total at
+  the bottom — not a raw JSON dump.
 
 ### 4. Collect responses (respectful batch review)
 
@@ -109,9 +123,25 @@ in `needs_you` was resolved upstream; don't nag about it.)
 Then split `needs_you` into two groups:
 
 - **Decisions** — items with a populated `options` list (or
-  `kind === 'decision'`). These are **never** batch-approved. Walk each
-  one individually: present the options conversationally, let the client
-  choose. A real decision always gets explicit engagement.
+  `kind === 'decision'`). These are **never** batch-approved — walk each
+  one individually with exactly **one `AskUserQuestion` call per decision
+  item**. Never bundle two decisions into a single call. Pre-specify the
+  call this way:
+  - `header`: `"Decision"` (within the 12-char cap).
+  - `question`: the item's client-facing prompt/title.
+  - `options`: the item's own `options` list, one labeled choice each.
+    **If an item has more than 4 options**, AskUserQuestion can't hold
+    them — fall back to presenting that item's options as prose and let
+    the client answer in their own words.
+  - `multiSelect: false` — a single verdict per decision.
+  - Do **not** add an "Other" choice; the harness adds it automatically.
+    If the client picks "Other" or says something off-menu, handle it
+    conversationally and map to the right verdict (see the table below).
+
+  A real decision always gets explicit engagement. (AskUserQuestion is
+  available here because `/engagement` runs in the main session, not a
+  subagent. See `.claude/cabinet/skill-output-conventions.md` for the
+  conventions behind this.)
 - **Approvals / FYIs** — items with no options. These are eligible for
   the batch default.
 

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

@@ -32,8 +32,16 @@ Access pib-db via [pib-db-access.md](../../cabinet/pib-db-access.md).
    - "What's the item?" (internal `text`)
    - "Who should see it?" — map to `audience:<id>` (and, for a delegate,
      `assignee:<id>` — the **sole** basis for a delegate seeing it).
-   - "Is it a decision the client must make, or a credential they must
-     provide?" → `needs:decision` / `needs:credential` (or neither).
+   - Collect item type via `AskUserQuestion`:
+     - `header`: `"Item type"`
+     - `question`: "What kind of item is this?"
+     - `options`:
+       - Decision — "Client must choose among options you provide"
+       - Credential — "Client must hand over a secret (secure dialog)"
+       - Neither — "Informational or approval item, no special handling"
+     - `multiSelect: false`
+     Map: Decision → tag `needs:decision`. Credential → tag
+     `needs:credential`. Neither → no needs tag.
    - "What scope?" (optional `scope:<scope>`)
    - To make a **project itself** visible to clients as a roll-up
      (e.g., "E-signing: Done"), tag the project `client-visible` and author
@@ -50,6 +58,9 @@ Access pib-db via [pib-db-access.md](../../cabinet/pib-db-access.md).
    - Always include `client-visible` (an item with no `client-visible`
      tag appears in **no** packet).
 
+   (See `.claude/cabinet/skill-output-conventions.md` for when structured
+   choices apply.)
+
 3. **Prompt for the client-facing copy block** (optional — the
    consultant can write it now or let `/engagement-sync` draft it):
    - "Want to write the client-facing copy now, or let `/engagement-sync`

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

@@ -53,14 +53,24 @@ id, name, email, and their role."
 For each recipient, capture:
 - **id** — short handle (e.g. `ed`, `sydney`), used in tags
 - **name**, **email**
-- **role** — `principal` (sees everything, gets billing) or `delegate`
-  (sees only items assigned to them, no billing)
+- **role** — collect via `AskUserQuestion`:
+  - `header`: `"Role"`
+  - `question`: "What role for [name]?"
+  - `options`:
+    - Principal — "Sees everything, gets billing, defaults to interactive delivery"
+    - Delegate — "Sees only assigned items, no billing, defaults to email"
+  - `multiSelect: false`
 - **scopes** — topical areas they care about (e.g. `[marketing]`); a
   principal is usually `[all]`
-- **has_claude_code** — "Does [name] have Claude Code installed? If yes:
-  they get the interactive `/engagement` view with rich status updates.
-  If no: they get a formatted email summary instead. (Principals default
-  to yes, delegates default to no.)"
+- **has_claude_code** — collect via `AskUserQuestion`:
+  - `header`: `"Delivery"`
+  - `question`: "Does [name] have Claude Code installed?"
+  - `options`:
+    - Yes — "Interactive /engagement view with rich status"
+    - No — "Formatted email summary instead"
+  - `multiSelect: false`
+  (Principals default to yes, delegates default to no — use as the
+  pre-selected suggestion in the question phrasing.)
 
 The default `roles` block is:
 ```yaml
@@ -86,8 +96,17 @@ confirmation before proceeding.
 "Do you bill time on this engagement?" If yes:
 - **timelog** path (default `./timelog.md`)
 - **rate** (default `190`), **currency** (default `USD`)
-- **period** — `engagement` (running total), `month`, or
-  `since-last-sync` (only since the last packet) — default `engagement`
+- **period** — collect via `AskUserQuestion`:
+  - `header`: `"Billing"`
+  - `question`: "How should billing be calculated?"
+  - `options`:
+    - Running total — "Cumulative from engagement start (default)"
+    - Monthly — "Reset each calendar month"
+    - Since last sync — "Only time since the last packet was sent"
+  - `multiSelect: false`
+
+(See `.claude/cabinet/skill-output-conventions.md` for when structured
+choices apply.)
 
 Billing appears only in `principal`-role packets.
 

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

@@ -150,15 +150,33 @@ For every `client-visible` action or project **lacking** a `<!-- client-facing -
 summary: "N items need new copy (no block). M items have stale copy
 (status changed). Total: N+M items to review."
 
-**Batch option for large sets.** If more than 5 items need review, offer:
-"Review each individually, or review as a batch? (Batch shows all drafts
-at once — you confirm, edit by number, or skip any.)"
+**Batch option for large sets.** If more than 5 items need review,
+collect the choice via `AskUserQuestion`:
+- `header`: `"Review"`
+- `question`: "N items need copy review. How to proceed?"
+- `options`:
+  - Individual — "One at a time, decide each separately"
+  - Batch — "Show all drafts at once, confirm/edit by number"
+- `multiSelect: false`
 
 **Skip if block exists.** An existing block (hand-written or previously approved) is authoritative. Never overwrite it. Check: `parseClientCopy(notes) !== null → skip`.
 
 **Draft from structured data.** Call `buildGenerationSource(item)` (from `engagement.mjs`) to get the structured metadata — status, completion, needs, options. For projects, pre-compute `child_summary` via `computeChildSummary(actions, project.fid)` and attach it to the project object before calling. Claude drafts a `client_title` + `client_why` from this metadata. The internal `text` field is NEVER an input to generation.
 
-**Per-item review loop (not batch approve).** For each generated draft, show the consultant: the structured source data and the generated title + why. Consultant chooses **Accept / Edit / Skip** per item. Accepted or edited copy proceeds to write-back. Skipped items remain without copy (the dispatch gate drops them).
+**Per-item review loop (not batch approve).** For each generated draft,
+show the consultant the structured source data and the generated title +
+why, then collect the verdict via `AskUserQuestion`:
+- `header`: `"Copy"`
+- `question`: "[item title] — accept this draft?"
+- `options`:
+  - Accept — "Use this copy as-is"
+  - Edit — "I'll provide revised text"
+  - Skip — "Leave without copy (dispatch gate will drop it)"
+- `multiSelect: false`
+
+Accepted or edited copy proceeds to write-back. Skipped items remain
+without copy (the dispatch gate drops them). If "Edit" is chosen, ask
+for the revised text conversationally, then write back.
 
 **Write-back.** On approval, call `spliceClientCopy(notes, newBlock, markerLine)` (from `engagement.mjs`) to produce the updated notes. `newBlock` is the `<!-- client-facing ... -->` block. `markerLine` is `<!-- cc-generated:<ISO timestamp> status:<current status> -->` — placed OUTSIDE the copy block (never inside, or `parseClientCopy` would include it in `client_why`). Write via `pib_update_action({ fid, notes: splicedNotes })` or `pib_update_project({ fid, notes: splicedNotes })`.
 
@@ -180,12 +198,19 @@ For each recipient: load their previous packet from
 `engagement-packets/<recipient>-sent.json` (if any) as `prevPacket`,
 then:
 ```
-const { packet, refmap, notClientReady } = renderPacket(config, actions, events, billing, recipient, prevPacket, projects)
+const { packet, refmap, notClientReady, allDropped } = renderPacket(config, actions, events, billing, recipient, prevPacket, projects)
 ```
 `notClientReady` reconfirms (defensively) the not-client-ready items the
 engine dropped — they never reach the client (no internal text leaks).
 Fold these into the step-3 block report.
 
+**`allDropped` guard:** If `allDropped` is true, **STOP** — do not
+proceed to dispatch. Every visible item was dropped because it lacked
+client-facing copy. This almost always means the query used
+`pib_list_actions` (which omits `notes`) instead of `pib_query` with
+`SELECT *`. Surface: "Empty packet — all N client-visible items are
+missing client-facing copy. Did you use pib_query with SELECT *?"
+
 ### 5. Hard gate
 
 `assertPacketInvariants(packet, recipient, config.roles)`. If it throws
@@ -211,14 +236,23 @@ For project roll-ups, show: `E-signing (roll-up: 3 done, 1 in progress)`
 vs action items: `DNS cutover (action, needs:decision)`. For projects
 with individually-visible children, note the count.
 
-Then ask: **"Send these updates now, or review a recipient's packet in
-detail first?"**
-
-- **"Send"** → proceed to archive + dispatch (steps 7–9).
-- **"Show me Ed's"** → render Ed's full packet (needs_you titles, in_flight,
-  shipped, messages, billing) so the consultant can read exactly what Ed will
-  see. Then re-ask.
-- **"Cancel"** → abort the sync, nothing sent.
+Then collect the dispatch decision via `AskUserQuestion`:
+- `header`: `"Dispatch"`
+- `question`: "Ready to send to N recipients?"
+- `options`:
+  - Send — "Archive and dispatch all packets now"
+  - Review — "Show me a recipient's packet in detail first"
+  - Cancel — "Abort this sync, nothing sent"
+- `multiSelect: false`
+
+- **Send** → proceed to archive + dispatch (steps 7–9).
+- **Review** → ask which recipient, render their full packet (needs_you,
+  in_flight, shipped, messages, billing), then re-present this same
+  AskUserQuestion (loop until Send or Cancel).
+- **Cancel** → abort, nothing sent.
+
+(See `.claude/cabinet/skill-output-conventions.md` for when structured
+choices apply.)
 
 This confirmation step is the human-in-the-loop gate — the safety checks
 (assertPacketInvariants) catch structural violations, but only the

package/templates/skills/orient/SKILL.md

@@ -282,7 +282,19 @@ items are returned, skip silently. Otherwise:
    (`triggered | still-waiting | needs-info | condition-obsolete`)
    and brief reasoning in notes.
 4. Include any items that evaluated to `triggered` in the briefing's
-   **Attention Items** section. Do not auto-reopen — the user decides.
+   **Attention Items** section. For each, collect the user's decision
+   via `AskUserQuestion`:
+   - `header`: `"Triggered"`
+   - `question`: "[fid] appears triggered — [trigger summary]. What to do?"
+   - `options`:
+     - Reopen — "Change status back to open, ready to work"
+     - Leave deferred — "Keep it deferred, not ready yet"
+     - Mark obsolete — "Trigger condition no longer relevant"
+   - `multiSelect: false`
+
+   Map: Reopen → status to open; Leave deferred → no-op; Mark obsolete
+   → `pib_mark_trigger_checked` with `condition-obsolete`.
+   (See `skill-output-conventions.md`.)
 
 **Cost control:** Cap this phase at 30 seconds total. If N > 10 items,
 evaluate only the 5 least-recently-checked.
@@ -344,9 +356,18 @@ done
 Also check `git worktree list` for active worktrees whose branches
 have diverged from main.
 
-Surface as advisory:
-> ⚠ Branch `feature-x` has N commits ahead of main (last touched
-> [date]). Merge, continue working, or discard?
+Surface as advisory, then collect the decision via `AskUserQuestion`:
+- `header`: `"Branch"`
+- `question`: "Branch `[name]` has N commits ahead of main. What to do?"
+- `options`:
+  - Merge — "Merge into main now"
+  - Continue — "Leave it, still working on it"
+  - Discard — "Delete the branch (destructive)"
+- `multiSelect: false`
+
+Map: Merge → `git merge [branch]` (surface conflicts if any). Continue →
+no-op. Discard → warn "permanently deletes N commits" and require
+explicit second confirmation before `git branch -D`.
 
 **Known platform limitation:** The Claude Code Agent tool with
 `isolation: "worktree"` branches from the remote tracking ref, not

package/templates/skills/triage-audit/SKILL.md

@@ -136,8 +136,23 @@ assumption, evidence, question, and your commentary. The user needs to
 see everything to make good decisions.
 
 **Fallback (no browser available):** Present findings in the conversation
-grouped by cabinet member, severity-ordered within each group. Ask for
-verdicts one group at a time to avoid overwhelming.
+grouped by cabinet member, severity-ordered within each group. For each
+finding, show its full context (title, description, assumption, evidence,
+question, and your commentary), then collect the verdict via one
+`AskUserQuestion` call:
+
+- `header`: `"Verdict"`
+- `question`: the finding's title
+- `options`:
+  - Fix — "Real finding, approve for action"
+  - Defer — "Real but not now — revisit later"
+  - Reject — "Not a real problem for this project"
+  - Question — "Need more information before deciding"
+- `multiSelect: false`
+
+One call per finding, walked individually within each group. (See
+`.claude/cabinet/skill-output-conventions.md` for when this pattern
+applies.)
 
 ### 3. Apply Verdicts (core)