create-claude-cabinet 0.46.0 → 0.47.0

package/templates/engagement/OVERVIEW.md

@@ -117,6 +117,17 @@ timelog. The running total appears only in a principal's update — never
 in a delegate's. Billing can be scoped by period: the full engagement
 total, the current month, or only hours since the last sync.
 
+**Invoicing.** `/collab-consultant invoice [YYYY-MM]` renders a clean
+invoice document from a month's tracked hours (defaults to the last full
+calendar month; `--itemized` for one line per timelog row instead of a
+single consolidated line). The document is built for upload to the
+operator's bank (Relay), whose "Create Invoice → Autofill from document"
+extracts the customer, line items, and total — so the document carries
+no invoice number and no From/bank block (Relay supplies those). It's
+written to `invoices/<YYYY-MM>.html` with a best-effort PDF conversion.
+Relay defaults the due date to today, so the skill reminds you to set the
+Net-30 due date by hand after autofill.
+
 ### Credential handoff
 
 When a client needs to provide a secret (API key, token, password):
@@ -142,6 +153,7 @@ When a client needs to provide a secret (API key, token, password):
 | `/engagement-message` | Consultant | Send a free-text note to a recipient |
 | `/engagement-sync` | Consultant | Push updates to recipients (with preview + confirm) + pull feedback |
 | `/engagement-status` | Consultant | Dashboard: previews, feedback inbox, billing, tag warnings |
+| `/collab-consultant invoice` | Consultant | Render a month's invoice document for upload to Relay's autofill |
 | `/engagement` | Client | Review the latest update and respond |
 | `/engagement-progress` | Client | Quick glance — what's new, counts, read-only |
 

package/templates/engagement/__tests__/engagement.test.mjs

@@ -27,6 +27,8 @@ import {
   validateFeedbackEnvelope,
   mapResponseToEvent,
   resolveFeedbackRef,
+  decisionFid,
+  normalizeOption,
 } from '../engagement.mjs';
 
 // --- Fixtures ---------------------------------------------------------------
@@ -1106,7 +1108,7 @@ test('2D: options declared in notes but NOT client_body do not reach the client
   assert.deepStrictEqual(item.options, [], 'notes-based options must not leak to the client');
 });
 
-test('2D: options declared in client_body DO reach the client packet', () => {
+test('2D: options declared in client_body DO reach the client packet (structured §5.1)', () => {
   const a = action({
     fid: 'act:00000011',
     tags: 'client-visible, audience:ed, needs:decision',
@@ -1115,7 +1117,9 @@ test('2D: options declared in client_body DO reach the client packet', () => {
   });
   const { packet } = renderPacket({ ...CONFIG, __now: '2026-05-31T12:00:00Z' }, [a], [], null, ED);
   const item = packet.needs_you.find(i => i.title === 'Pick a vendor');
-  assert.deepStrictEqual(item.options, ['Acme', 'Globex']);
+  // Structured options objects (comma-safe value field), not a string array.
+  assert.deepStrictEqual(item.options, [{ value: 'Acme', label: 'Acme' }, { value: 'Globex', label: 'Globex' }]);
+  assert.strictEqual(item.decision_type, 'choice');
 });
 
 // --- Plan 2B: status fallback never leaks raw enum --------------------------
@@ -1171,3 +1175,174 @@ test('2C: renderPacket still works with a plain array (not double-unwrapped)', (
   const { packet } = renderPacket({ ...CONFIG, __now: '2026-05-31T12:00:00Z' }, [a], [], null, ED);
   assert.ok(packet.in_flight.find(i => i.title === 'Plain'));
 });
+
+// ===========================================================================
+// §5.1 — internalized decision projection: structured options, free-text,
+// fail-closed, dedup, deterministic fid. (P1.1 + P1.2)
+// ===========================================================================
+
+// A config carrying `decide` sections, principal=ed, delegate=sydney.
+function decideConfig(items, over = {}) {
+  return loadEngagement({
+    engagement: { slug: 'maginnis', title: 'Maginnis', project_fid: 'prj:11111111', consultant: 'Oren' },
+    recipients: [
+      { id: 'ed', name: 'Ed', email: 'ed@x.com', role: 'principal', scopes: ['all'] },
+      { id: 'sydney', name: 'Sydney', email: 'syd@x.com', role: 'delegate', scopes: ['marketing'] },
+    ],
+    roles: { principal: { sees: 'all', billing: true }, delegate: { sees: 'assigned', billing: false } },
+    transport: { type: 'email', consultant: 'oren@x.com' },
+    sections: [{ key: 'go_live', title: 'Go-Live', items }],
+    ...over,
+  });
+}
+const EDR = { id: 'ed', name: 'Ed', email: 'ed@x.com', role: 'principal', scopes: ['all'], has_claude_code: true };
+const SYDR = { id: 'sydney', name: 'Sydney', email: 'syd@x.com', role: 'delegate', scopes: ['marketing'], has_claude_code: false };
+
+test('§5.1 decisionFid: deterministic and FID_PATTERN-valid (act:<8hex> — passes ingest validateFid)', () => {
+  assert.strictEqual(decisionFid('maginnis', 'go_live', 'domain'), decisionFid('maginnis', 'go_live', 'domain'));
+  assert.notStrictEqual(decisionFid('maginnis', 'go_live', 'domain'), decisionFid('maginnis', 'go_live', 'mail_from'));
+  assert.notStrictEqual(decisionFid('maginnis', 'go_live', 'domain'), decisionFid('other', 'go_live', 'domain'));
+  // Must match the pib-db FID_PATTERN so addEngagementEvent accepts it as a
+  // target_fid (the production answer-ingest path the loop test can't reach).
+  assert.ok(/^act:[0-9a-f]{8}$/.test(decisionFid('maginnis', 'go_live', 'domain')), 'matches act:<8 lowercase hex>');
+});
+
+test('§5.1 normalizeOption: string ⇒ {value,label}; object passes through; comma-safe; empties drop', () => {
+  assert.deepStrictEqual(normalizeOption('Acme'), { value: 'Acme', label: 'Acme' });
+  assert.deepStrictEqual(normalizeOption({ value: 'B', label: 'Option B' }), { value: 'B', label: 'Option B' });
+  assert.deepStrictEqual(normalizeOption({ value: 'B' }), { value: 'B', label: 'B' });
+  assert.deepStrictEqual(normalizeOption('A, B, and C together'), { value: 'A, B, and C together', label: 'A, B, and C together' });
+  assert.strictEqual(normalizeOption('   '), null);
+  assert.strictEqual(normalizeOption(null), null);
+});
+
+test('§5.1 synthesis: a yaml decide item renders into needs_you with structured options + kind=decision', () => {
+  const cfg = decideConfig([
+    { key: 'domain', kind: 'decide', prompt: 'Which domain?', help: 'Pick one', tradeoff: 'Keystone', options: ['holdthemtoit.com', 'A different domain'] },
+  ]);
+  const { packet, refmap } = renderPacket({ ...cfg, __now: '2026-06-18T00:00:00Z' }, [], [], null, EDR);
+  assert.strictEqual(packet.needs_you.length, 1);
+  const d = packet.needs_you[0];
+  assert.strictEqual(d.kind, 'decision');
+  assert.strictEqual(d.decision_type, 'choice');
+  assert.strictEqual(d.title, 'Which domain?');
+  assert.ok(/Pick one/.test(d.why) && /Trade-off: Keystone/.test(d.why), 'why merges help + tradeoff');
+  assert.deepStrictEqual(d.options, [
+    { value: 'holdthemtoit.com', label: 'holdthemtoit.com' },
+    { value: 'A different domain', label: 'A different domain' },
+  ]);
+  assert.strictEqual(refmap[d.ref], decisionFid('maginnis', 'go_live', 'domain'), 'ref resolves to the deterministic fid');
+});
+
+test('§5.1 synthesis: a comma-bearing option survives intact (no comma-split damage)', () => {
+  const cfg = decideConfig([
+    { key: 'k', kind: 'decide', prompt: 'P', options: ['Marriott uses AAA, Hilton uses NAF', 'One forum per theory'] },
+  ]);
+  const { packet } = renderPacket({ ...cfg, __now: '2026-06-18T00:00:00Z' }, [], [], null, EDR);
+  assert.deepStrictEqual(packet.needs_you[0].options.map(o => o.value), [
+    'Marriott uses AAA, Hilton uses NAF', 'One forum per theory',
+  ]);
+});
+
+test('§5.1 synthesis: a decide item with no options is free_text (exempt from fail-closed)', () => {
+  const cfg = decideConfig([{ key: 'mail_from', kind: 'decide', prompt: 'Which From address?', help: 'open' }]);
+  const { packet } = renderPacket({ ...cfg, __now: '2026-06-18T00:00:00Z' }, [], [], null, EDR);
+  assert.strictEqual(packet.needs_you[0].decision_type, 'free_text');
+  assert.deepStrictEqual(packet.needs_you[0].options, []);
+});
+
+test('§5.1 synthesis: free_text:true forces free-text even with options present', () => {
+  const cfg = decideConfig([{ key: 'k', kind: 'decide', prompt: 'P', free_text: true, options: ['a', 'b'] }]);
+  const { packet } = renderPacket({ ...cfg, __now: '2026-06-18T00:00:00Z' }, [], [], null, EDR);
+  assert.strictEqual(packet.needs_you[0].decision_type, 'free_text');
+  assert.deepStrictEqual(packet.needs_you[0].options, []);
+});
+
+test('§5.1 fail-closed: a choice decision with <2 options throws at render', () => {
+  const cfg = decideConfig([{ key: 'k', kind: 'decide', prompt: 'P', options: ['only one'] }]);
+  assert.throws(
+    () => renderPacket({ ...cfg, __now: '2026-06-18T00:00:00Z' }, [], [], null, EDR),
+    /choice with 1 option/,
+  );
+});
+
+test('§5.1 audience: a no-audience decision reaches the principal but not the delegate', () => {
+  const cfg = decideConfig([{ key: 'k', kind: 'decide', prompt: 'P', options: ['a', 'b'] }]);
+  const ed = renderPacket({ ...cfg, __now: '2026-06-18T00:00:00Z' }, [], [], null, EDR).packet;
+  const syd = renderPacket({ ...cfg, __now: '2026-06-18T00:00:00Z' }, [], [], null, SYDR).packet;
+  assert.strictEqual(ed.needs_you.length, 1);
+  assert.strictEqual(syd.needs_you.length, 0, 'delegate sees only assigned items');
+});
+
+test('§5.1 audience: audience:[sydney] narrows a decision to that recipient only', () => {
+  const cfg = decideConfig([{ key: 'k', kind: 'decide', prompt: 'P', audience: ['sydney'], options: ['a', 'b'] }]);
+  const ed = renderPacket({ ...cfg, __now: '2026-06-18T00:00:00Z' }, [], [], null, EDR).packet;
+  // sydney is a delegate; audience alone does not grant a delegate visibility
+  // (assignee is the sole delegate key), so audience narrows the principal out:
+  assert.strictEqual(ed.needs_you.length, 0, 'audience:sydney narrows ed (principal) out');
+});
+
+test('§5.1 dedup: a live needs:decision action carrying the engagement_key marker renders the decision once', () => {
+  const cfg = decideConfig([{ key: 'domain', kind: 'decide', prompt: 'Which domain?', options: ['a', 'b'] }]);
+  // A surviving projected action for the SAME key (transition state).
+  const projected = action({
+    fid: 'act:abc12345',
+    tags: 'client-visible, audience:ed, needs:decision',
+    client_title: 'Which domain? (projected)',
+    client_body: 'why\nOptions: a, b',
+    notes: 'engagement_key: domain\ntier: blocks_launch',
+  });
+  const { packet } = renderPacket({ ...cfg, __now: '2026-06-18T00:00:00Z' }, [projected], [], null, EDR);
+  const domainItems = packet.needs_you.filter(i => /domain/i.test(i.title));
+  assert.strictEqual(domainItems.length, 1, 'exactly one render — synthesis skipped the covered key');
+  assert.strictEqual(domainItems[0].title, 'Which domain? (projected)', 'the live action rendered it, not the synthesis');
+});
+
+test('§5.1 cross-render: the same decide key keeps the same ref across re-renders', () => {
+  const cfg = decideConfig([{ key: 'domain', kind: 'decide', prompt: 'Which domain?', options: ['a', 'b'] }]);
+  const p1 = renderPacket({ ...cfg, __now: '2026-06-18T09:00:00Z' }, [], [], null, EDR).packet;
+  const p2 = renderPacket({ ...cfg, __now: '2026-06-18T15:00:00Z' }, [], [], null, EDR).packet;
+  assert.strictEqual(p1.needs_you[0].ref, p2.needs_you[0].ref, 'deterministic fid ⇒ stable ref');
+});
+
+test('§5.1 synthesized decision passes the leak gate (no fid/notes/tags on the item)', () => {
+  const cfg = decideConfig([{ key: 'k', kind: 'decide', prompt: 'P', options: ['a', 'b'] }]);
+  const { packet } = renderPacket({ ...cfg, __now: '2026-06-18T00:00:00Z' }, [], [], null, EDR);
+  // renderPacket already runs assertPacketInvariants; re-assert explicitly.
+  assert.doesNotThrow(() => assertPacketInvariants(packet, EDR, cfg.roles));
+  for (const k of ['action_fid', 'fid', 'notes', 'tags']) {
+    assert.ok(!(k in packet.needs_you[0]), `synthesized item must not carry ${k}`);
+  }
+});
+
+test('§5.1 checklist_summary: a type-less section labels by key, never the literal "unknown"', () => {
+  const cfg = decideConfig([], { sections: [{ key: 'misc', items: [{ key: 'k1', kind: 'confirm' }] }] });
+  const { packet } = renderPacket({ ...cfg, __now: '2026-06-18T00:00:00Z' }, [], [], null, EDR);
+  assert.ok(Array.isArray(packet.checklist_summary));
+  assert.strictEqual(packet.checklist_summary[0].type, 'misc');
+  assert.notStrictEqual(packet.checklist_summary[0].type, 'unknown');
+  assert.strictEqual(packet.checklist_summary[0].count, 1);
+});
+
+test('§5.1 dedup: a marker-bearing projected action with NO client copy does not suppress synthesis', () => {
+  const cfg = decideConfig([{ key: 'domain', kind: 'decide', prompt: 'Which domain?', options: ['a', 'b'] }]);
+  const noCopy = action({
+    fid: 'act:abc12399',
+    tags: 'client-visible, audience:ed, needs:decision',
+    notes: 'engagement_key: domain', // marker present, but NO client copy
+  });
+  const { packet, notClientReady } = renderPacket({ ...cfg, __now: '2026-06-18T00:00:00Z' }, [noCopy], [], null, EDR);
+  const domainItems = packet.needs_you.filter((i) => /domain/i.test(i.title));
+  assert.strictEqual(domainItems.length, 1, 'synthesis fills the gap when the projected action lacks copy');
+  assert.ok(notClientReady.includes('act:abc12399'), 'the no-copy action is reported, not silently swallowed');
+});
+
+test('§5.1 fail-closed: a REAL action with exactly 1 option throws (not only yaml decide items)', () => {
+  const a = action({
+    fid: 'act:00000091',
+    tags: 'client-visible, audience:ed, needs:decision',
+    client_title: 'Pick one',
+    client_body: 'why\nOptions: OnlyChoice',
+  });
+  assert.throws(() => renderPacket({ ...CONFIG, __now: '2026-06-18T00:00:00Z' }, [a], [], null, ED), /choice with 1 option/);
+});

package/templates/engagement/__tests__/invoice-doc.test.mjs

@@ -0,0 +1,195 @@
+// Unit tests for renderInvoiceDoc — the pure invoice-document renderer that
+// backs `/collab-consultant invoice`. The document is uploaded to Relay's
+// "Create Invoice → Autofill from document"; these tests pin the ground-truth
+// constraints from the live Relay experiment (2026-06-16):
+//   - line items are Description / Quantity (hrs) / Unit price / Amount
+//   - NO invoice number, NO From/remit/bank block (Relay supplies them)
+//   - Total due is billingResult.total VERBATIM (never a re-sum)
+//   - terms live in a memo footer (Relay defaults the due date to today)
+// Run: node --test templates/engagement/__tests__/invoice-doc.test.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert';
+import { renderInvoiceDoc, loadEngagement, renderBilling } from '../engagement.mjs';
+
+// --- Fixtures ---------------------------------------------------------------
+const CONFIG = loadEngagement({
+  engagement: { slug: 'maginnis', title: 'Maginnis Howard', project_fid: 'prj:11111111' },
+  billing: { enabled: true, rate: 190, currency: 'USD' },
+  invoicing: { mode: 'consolidated', scope_label: 'Consulting services', terms_days: 30 },
+  recipients: [
+    { id: 'ed', name: 'Ed Maginnis', org: 'Maginnis Howard', email: 'ed@example.com', role: 'principal', scopes: ['all'] },
+  ],
+});
+const ED = CONFIG.recipients.find(r => r.id === 'ed');
+
+// A hand-built billingResult (the shape renderBilling returns) — keeps the
+// unit test independent of timelog parsing.
+function billing(over = {}) {
+  return {
+    hours: 7.25,
+    rate: 190,
+    currency: 'USD',
+    period: 'month',
+    total: 1377.5,
+    lineItems: [
+      { date: '2026-05-02', hours: 2.5, work: 'Platform setup' },
+      { date: '2026-05-10', hours: 1.75, work: 'Campaign config' },
+      { date: '2026-05-20', hours: 3, work: 'Pipeline review' },
+    ],
+    ...over,
+  };
+}
+
+const OPTS = { mode: 'consolidated', invoiceDate: '2026-06-01', dueDate: '2026-07-01', period: '2026-05' };
+
+// Count <tr> rows inside the line-item <tbody> only (excludes thead + totals).
+function tbodyRowCount(html) {
+  const m = html.match(/<tbody>([\s\S]*?)<\/tbody>/);
+  if (!m) return 0;
+  return (m[1].match(/<tr>/g) || []).length;
+}
+
+// (a) consolidated mode → exactly one line, Quantity = total hours, Total verbatim
+test('consolidated mode: one line item, quantity = total hours, total verbatim', () => {
+  const bill = billing();
+  const html = renderInvoiceDoc(CONFIG, ED, bill, OPTS);
+  assert.strictEqual(tbodyRowCount(html), 1, 'consolidated renders exactly one line');
+  // Quantity column shows the total hours
+  assert.match(html, /7\.25/);
+  // The stated Total === billingResult.total EXACTLY ($1,377.50)
+  assert.ok(html.includes('Total due'));
+  assert.ok(html.includes('$1,377.50'), 'total rendered verbatim');
+  // consolidated description = "<scope_label> — <Month YYYY>"
+  assert.ok(html.includes('Consulting services — May 2026'));
+});
+
+// (b) itemized mode from a 3-row fixture → 3 line rows, Total verbatim
+test('itemized mode: one line per row, total verbatim (not a re-sum)', () => {
+  const bill = billing();
+  const html = renderInvoiceDoc(CONFIG, ED, bill, { ...OPTS, mode: 'itemized' });
+  assert.strictEqual(tbodyRowCount(html), 3, 'itemized renders one row per lineItem');
+  assert.ok(html.includes('Platform setup'));
+  assert.ok(html.includes('Campaign config'));
+  assert.ok(html.includes('Pipeline review'));
+  // Total is billingResult.total verbatim, NOT a re-sum of per-line amounts.
+  assert.ok(html.includes('$1,377.50'), 'total is the honest billingResult.total');
+});
+
+// (b2) itemized total stays verbatim even when per-line rounding would diverge
+test('itemized mode: total is billingResult.total even if per-line amounts re-sum differently', () => {
+  // 3 rows of 0.333h × 190 = 63.27 each → re-sum 189.81; but billingResult.total
+  // is the authoritative figure (here deliberately 190.00).
+  const bill = billing({
+    hours: 0.999,
+    total: 190.0,
+    lineItems: [
+      { date: '2026-05-02', hours: 0.333, work: 'A' },
+      { date: '2026-05-03', hours: 0.333, work: 'B' },
+      { date: '2026-05-04', hours: 0.333, work: 'C' },
+    ],
+  });
+  const html = renderInvoiceDoc(CONFIG, ED, bill, { ...OPTS, mode: 'itemized' });
+  assert.ok(html.includes('Total due'));
+  assert.ok(html.includes('$190.00'), 'stated total is the verbatim billingResult.total');
+});
+
+// (b3) itemized: empty work falls back to the row date
+test('itemized mode: empty work falls back to the row date', () => {
+  const bill = billing({
+    hours: 1,
+    total: 190,
+    lineItems: [{ date: '2026-05-09', hours: 1, work: '' }],
+  });
+  const html = renderInvoiceDoc(CONFIG, ED, bill, { ...OPTS, mode: 'itemized' });
+  assert.ok(html.includes('2026-05-09'), 'falls back to the date when work is empty');
+});
+
+// (c) due date = invoiceDate + terms_days (rendered Net N in the memo)
+test('memo reflects the passed due date (Net N — due <dueDate>)', () => {
+  const bill = billing();
+  // invoiceDate 2026-06-01, dueDate 2026-07-01 → 30 days
+  const html = renderInvoiceDoc(CONFIG, ED, bill, OPTS);
+  assert.match(html, /Payment terms: Net 30 — due 2026-07-01\./);
+  // A shorter term renders the right N.
+  const html15 = renderInvoiceDoc(CONFIG, ED, bill, { ...OPTS, dueDate: '2026-06-16' });
+  assert.match(html15, /Net 15 — due 2026-06-16/);
+});
+
+// (d) period label renders "Month YYYY"
+test('period label renders the right Month YYYY', () => {
+  const bill = billing();
+  const html = renderInvoiceDoc(CONFIG, ED, bill, OPTS);
+  assert.ok(html.includes('May 2026'), 'period 2026-05 → "May 2026"');
+  assert.ok(html.includes('Period: May 2026.'), 'memo carries the period label too');
+});
+
+// (e) NO invoice number, NO bank/From block
+test('document carries no invoice number and no bank/From/remit block', () => {
+  const bill = billing();
+  const html = renderInvoiceDoc(CONFIG, ED, bill, OPTS);
+  assert.ok(!/Invoice\s*#|Invoice\s*No\.?\b/i.test(html), 'no "Invoice #" / "Invoice No" sender-number label');
+  assert.ok(!/routing/i.test(html), 'no routing number');
+  assert.ok(!/account\s*(number|no\.?)/i.test(html), 'no account number');
+  assert.ok(!/\bACH\b/i.test(html), 'no ACH details');
+  assert.ok(!/\bremit\b/i.test(html), 'no remit-to block');
+  // No "From:" sender block — Relay pulls the sender from the account.
+  assert.ok(!/>\s*From\b/i.test(html), 'no From sender block');
+});
+
+// (f) bill-to shows the recipient name + email (and org when present)
+test('bill-to shows recipient name, org, and email', () => {
+  const bill = billing();
+  const html = renderInvoiceDoc(CONFIG, ED, bill, OPTS);
+  assert.ok(html.includes('Bill to'));
+  assert.ok(html.includes('Ed Maginnis'), 'bill-to name');
+  assert.ok(html.includes('Maginnis Howard'), 'bill-to org');
+  assert.ok(html.includes('ed@example.com'), 'bill-to email');
+});
+
+// (g) refuses on empty lineItems / zero hours
+test('throws on empty lineItems', () => {
+  assert.throws(
+    () => renderInvoiceDoc(CONFIG, ED, billing({ lineItems: [], hours: 0, total: 0 }), OPTS),
+    /no lineItems/,
+  );
+});
+test('throws on zero hours even with a stray line', () => {
+  assert.throws(
+    () => renderInvoiceDoc(CONFIG, ED, billing({ hours: 0, total: 0, lineItems: [{ date: '2026-05-01', hours: 0, work: 'x' }] }), OPTS),
+    /zero hours/,
+  );
+});
+
+// --- integration with renderBilling -----------------------------------------
+test('renderBilling → renderInvoiceDoc end to end (month period, consolidated)', () => {
+  const timelog = [
+    '| Date       | Hours | Work            |',
+    '| ---------- | ----- | --------------- |',
+    '| 2026-05-02 | 2.5   | Platform setup  |',
+    '| 2026-04-30 | 9     | (prior month)   |',
+    '| 2026-05-20 | 3     | Pipeline review |',
+  ].join('\n');
+  const bill = renderBilling(timelog, 190, 'USD', 'month', { monthCutoff: '2026-05-01' });
+  assert.strictEqual(bill.period, 'month');
+  // Only the two May rows count: 5.5h × 190 = 1045.00 (the April row is excluded).
+  assert.strictEqual(bill.hours, 5.5);
+  assert.strictEqual(bill.total, 1045);
+  const html = renderInvoiceDoc(CONFIG, ED, bill, OPTS);
+  assert.strictEqual(tbodyRowCount(html), 1);
+  assert.ok(html.includes('$1,045.00'));
+  assert.ok(!html.includes('(prior month)'), 'April row excluded by the month filter');
+});
+
+// --- mode default + __now seam ----------------------------------------------
+test('mode defaults to consolidated and dates default via config.__now', () => {
+  const cfg = loadEngagement({
+    engagement: {}, billing: { enabled: true, rate: 190 }, invoicing: {},
+    recipients: [{ id: 'ed', name: 'Ed', role: 'principal' }],
+  });
+  cfg.__now = '2026-06-16T10:00:00.000Z';
+  const html = renderInvoiceDoc(cfg, cfg.recipients[0], billing(), {});
+  assert.strictEqual(tbodyRowCount(html), 1, 'default mode is consolidated (one line)');
+  assert.ok(html.includes('2026-06-16'), 'issued date defaults from config.__now');
+  assert.match(html, /Net 0 — due 2026-06-16/, 'due defaults to issued when not passed');
+});

package/templates/engagement/engagement-preview.mjs

@@ -0,0 +1,100 @@
+// READ-ONLY dispatch preview — renders EXACTLY what `/collab-consultant sync`
+// would send to a recipient, WITHOUT generating copy, writing pib-db, or POSTing
+// anything. The guarded `--dry-run` half of sync, upstreamed (P1.3). It drives
+// the same render path the real sync uses (loadEngagement → renderPacket) against
+// the live pib-db, so the leak gate (assertPacketInvariants, run inside
+// renderPacket) is exercised before any real dispatch.
+//
+//   node .claude/engagement/engagement-preview.mjs [recipientId]
+//
+// recipientId defaults to the first principal (a role that `sees: all`). The
+// command makes ZERO writes and ZERO network calls — safe to run any time.
+// PIB_DB_PATH (if set) is inherited by the pib-db query, so it is correct from
+// a worktree too.
+import { readFileSync, existsSync } from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createRequire } from 'node:module'
+import { loadEngagement, renderPacket, renderBilling } from './engagement.mjs'
+import { toAbstractActions, toAbstractProjects, toEvents } from './pibdb-adapter.mjs'
+
+// .claude/engagement/ → project root is two levels up.
+const root = join(dirname(fileURLToPath(import.meta.url)), '..', '..')
+const require = createRequire(import.meta.url)
+
+// YAML is needed only to parse engagement.yaml. Resolve it through node's own
+// module resolution (walks up node_modules) rather than a brittle deep path,
+// and degrade with a clear message if the consumer hasn't installed it — the
+// engagement module deliberately adds no hard dependency.
+let parseYaml
+try {
+  parseYaml = require('yaml').parse
+} catch {
+  console.error('engagement-preview needs the `yaml` package to read engagement.yaml.\n  Install it in this project:  npm install yaml');
+  process.exit(2)
+}
+
+const pib = (sql) => JSON.parse(execFileSync('node', [join(root, 'scripts/pib-db.mjs'), 'query', sql], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 }))
+
+const config = loadEngagement(parseYaml(readFileSync(join(root, 'engagement.yaml'), 'utf8')))
+const wantId = process.argv[2]
+const recipient = (config.recipients || []).find((r) => r.id === wantId)
+  || (config.recipients || []).find((r) => config.roles?.[r.role]?.sees === 'all')
+  || (config.recipients || [])[0]
+if (!recipient) {
+  console.error('engagement-preview: no recipients in engagement.yaml');
+  process.exit(2)
+}
+
+const actions = toAbstractActions(pib('SELECT * FROM actions WHERE deleted_at IS NULL'))
+const projects = toAbstractProjects(pib('SELECT * FROM projects WHERE deleted_at IS NULL'))
+let events = []
+try { events = toEvents(pib(`SELECT * FROM engagement_events WHERE engagement = '${config.engagement.project_fid}'`)) } catch { events = [] }
+const billing = renderBilling(readFileSync(join(root, 'timelog.md'), 'utf8'), config.billing?.rate || 190, config.billing?.currency || 'USD', 'engagement')
+const prevPath = join(root, 'engagement-packets', `${recipient.id}-sent.json`)
+const prevPacket = existsSync(prevPath) ? JSON.parse(readFileSync(prevPath, 'utf8')) : null
+
+let out
+try {
+  out = renderPacket(config, actions, events, billing, recipient, prevPacket, projects)
+} catch (e) {
+  console.error('LEAK GATE / RENDER FAILED:', e.message)
+  process.exit(1)
+}
+const { packet, notClientReady, allDropped } = out
+
+const B = '\x1b[1m', X = '\x1b[0m', C = '\x1b[36m', Y = '\x1b[33m', G = '\x1b[32m'
+console.log(`\n${B}══════ DISPATCH PREVIEW — what ${recipient.name || recipient.id} would receive ══════${X}`)
+console.log(`${B}${packet.generated_label || packet.packet_id}${X}   (prev packet: ${prevPacket ? prevPacket.generated_label || prevPacket.packet_id : 'none'})`)
+console.log(`\nBuckets:  needs_you ${C}${(packet.needs_you || []).length}${X} · in_flight ${C}${(packet.in_flight || []).length}${X} · shipped ${C}${(packet.shipped || []).length}${X} · delegated ${C}${(packet.delegated || []).length}${X} · messages ${C}${(packet.messages || []).length}${X}`)
+console.log(`New since last: ${C}${(packet.new_since_last || []).length}${X}   Checklist: ${JSON.stringify(packet.checklist_summary)}`)
+console.log(`Billing: ${G}${packet.billing ? packet.billing.hours + 'h  $' + packet.billing.total : '(not included)'}${X}`)
+console.log(`${G}✓ leak gate (assertPacketInvariants) passed — no _refmap / internal fid in projection${X}`)
+
+console.log(`\n${B}── NEEDS YOU (${(packet.needs_you || []).length}) — decisions/requests answered in /collab-client ──${X}`)
+for (const it of packet.needs_you || []) {
+  if (it.kind === 'decision') {
+    const detail = it.decision_type === 'free_text'
+      ? `  ${C}[free-text answer]${X}`
+      : ((it.options || []).length ? `  ${C}[${it.options.map((o) => o.value).join(' · ')}]${X}` : `  ${Y}[NO OPTIONS]${X}`)
+    console.log(`  • ${(it.title || '').slice(0, 90)}  (decision)${detail}`)
+  } else {
+    console.log(`  • ${(it.title || '').slice(0, 90)}  (${it.kind || 'item'})`)
+  }
+}
+
+console.log(`\n${B}── IN FLIGHT (${(packet.in_flight || []).length}) ──${X}`)
+for (const it of packet.in_flight || []) console.log(`  • ${(it.title || '').slice(0, 90)}  — ${it.status || ''}`)
+
+console.log(`\n${B}── SHIPPED (${(packet.shipped || []).length}) ──${X}`)
+for (const it of packet.shipped || []) console.log(`  ✓ ${(it.title || '').slice(0, 90)}`)
+
+console.log(`\n${B}── MESSAGES FEED (${(packet.messages || []).length}) ──${X}`)
+for (const m of packet.messages || []) console.log(`  » ${(m.body || m.text || JSON.stringify(m)).slice(0, 100)}`)
+
+console.log(`\n${B}── MISSING CLIENT COPY (would be auto-generated by sync step 6) ──${X}`)
+if (!notClientReady || notClientReady.length === 0) console.log(`  ${G}none — every client-visible item/project already has copy${X}`)
+else { console.log(`  ${Y}${notClientReady.length} item(s)/project(s) lack copy:${X}`); for (const fid of notClientReady) console.log(`    - ${fid}`) }
+if (allDropped) console.log(`  ${Y}⚠ allDropped=true — every visible item lacked copy${X}`)
+console.log(`\n${G}(read-only preview — no pib-db writes, no network calls)${X}\n`)