create-claude-cabinet 0.34.1 → 0.35.0

package/package.json

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

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/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)
 

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

@@ -180,12 +180,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