create-claude-cabinet 0.45.0 → 0.47.0

package/templates/engagement/engagement.mjs

@@ -84,11 +84,24 @@ export function loadEngagement(config) {
     : { enabled: false, timelog: null, rate: 190, currency: 'USD', period: 'engagement' };
 
   const transport = config.transport || { type: 'email', consultant: null };
+
+  // invoicing: optional block controlling the local invoice document
+  // (`/collab-consultant invoice`). NO bank/remit/From fields live here —
+  // Relay supplies the sender from the operator's account and assigns the
+  // invoice number; the document only carries bill-to + line items + total.
+  const invoicing = config.invoicing
+    ? {
+        mode: config.invoicing.mode === 'itemized' ? 'itemized' : 'consolidated',
+        scope_label: config.invoicing.scope_label || 'Consulting services',
+        terms_days: Number.isFinite(config.invoicing.terms_days) ? config.invoicing.terms_days : 30,
+      }
+    : { mode: 'consolidated', scope_label: 'Consulting services', terms_days: 30 };
+
   const sections = Array.isArray(config.sections) ? config.sections : [];
   const engagement_notes = config.engagement_notes || null;
   const scoped_notes = Array.isArray(config.scoped_notes) ? config.scoped_notes : [];
 
-  return { engagement, billing, recipients, roles, transport, sections, engagement_notes, scoped_notes };
+  return { engagement, billing, recipients, roles, transport, invoicing, sections, engagement_notes, scoped_notes };
 }
 
 export function normalizeRecipient(r) {
@@ -112,6 +125,8 @@ export function normalizeRecipient(r) {
     id: r.id,
     name: r.name || r.id,
     email: r.email || null,
+    // org (optional) rides through so the invoice bill-to block can show it.
+    org: r.org || r.organization || null,
     role,
     scopes: Array.isArray(r.scopes) ? r.scopes : [],
     has_claude_code,
@@ -327,6 +342,217 @@ function extractDate(cell) {
   return m ? m[0] : null;
 }
 
+// ---------------------------------------------------------------------------
+// renderInvoiceDoc — PURE. A clean, print-friendly invoice HTML document
+// the operator uploads to Relay's "Create Invoice → Autofill from document".
+// ---------------------------------------------------------------------------
+// Relay (the operator's bank) does the actual invoicing — it has no API but
+// extracts fields from an uploaded PDF/PNG. So this is the ONLY job: render a
+// flat, self-contained invoice document. Validated against Relay's autofill
+// (live experiment, 2026-06-16):
+//   - Relay parses line items as Description / Quantity / Unit price / Amount
+//     and computes its OWN totals (Quantity = hours, Unit price = the rate).
+//   - Relay assigns its OWN invoice number and pulls the From/sender (business
+//     name, address, email) from the operator's account → the document must
+//     NOT include an invoice number or any From/remit/bank block (ignored or
+//     overridden). No bank/ACH details anywhere.
+//   - Relay autofills the customer (bill-to name + email) and the line items
+//     + total correctly.
+//   - Relay does NOT map a net-30 due date — it defaults the due date to
+//     today. The terms only survive in Relay's free-text Memo → terms go in a
+//     memo-friendly footer line, and the skill tells the operator to set the
+//     due date in Relay by hand.
+//
+// Signature: renderInvoiceDoc(config, recipient, billingResult,
+//   { mode, invoiceDate, dueDate, period }) → HTML string.
+//   - PURE: invoiceDate/dueDate/period are passed in. A default for missing
+//     dates uses the `config.__now` injectable-time seam (never new Date()).
+//   - mode 'consolidated' (default): ONE line item — description
+//     "<scope_label> — <Month YYYY>", Quantity = total hours, Unit price =
+//     rate, Amount = billingResult.total.
+//   - mode 'itemized': one line per billingResult.lineItems row.
+//   - Total due is billingResult.total VERBATIM (the honest figure; for
+//     itemized it is NOT a re-sum of the per-line amounts).
+export function renderInvoiceDoc(config, recipient, billingResult, { mode = 'consolidated', invoiceDate = null, dueDate = null, period = null } = {}) {
+  if (!billingResult || !Array.isArray(billingResult.lineItems) || billingResult.lineItems.length === 0) {
+    throw new Error('renderInvoiceDoc: billingResult has no lineItems (nothing to invoice)');
+  }
+  if (!(billingResult.hours > 0)) {
+    throw new Error('renderInvoiceDoc: billingResult has zero hours (nothing to invoice)');
+  }
+
+  const now = config?.__now || isoNow();
+  const issued = invoiceDate || now.slice(0, 10);
+  const due = dueDate || issued;
+  const rate = billingResult.rate;
+  const currency = billingResult.currency || 'USD';
+
+  // Period label: prefer the explicit period (YYYY-MM), else the issue month.
+  const periodMonth = (period || issued).slice(0, 7);
+  const periodLabel = formatMonthYear(periodMonth);
+
+  const invoicing = config?.invoicing || {};
+  const scopeLabel = invoicing.scope_label || 'Consulting services';
+
+  // Build the line rows. Each: { description, quantity (hours), unitPrice, amount }.
+  let rows;
+  if (mode === 'itemized') {
+    rows = billingResult.lineItems.map(li => {
+      const qty = Math.round((li.hours || 0) * 100) / 100;
+      return {
+        description: (li.work && li.work.trim()) || li.date || scopeLabel,
+        quantity: qty,
+        unitPrice: rate,
+        amount: Math.round(qty * rate * 100) / 100,
+      };
+    });
+  } else {
+    rows = [{
+      description: `${scopeLabel} — ${periodLabel}`,
+      quantity: billingResult.hours,
+      unitPrice: rate,
+      amount: billingResult.total,
+    }];
+  }
+
+  // The stated Total is billingResult.total VERBATIM — never a re-sum.
+  const total = billingResult.total;
+
+  // Bill-to from the recipient object (autofilled by Relay as the customer).
+  const billToName = recipient?.name || recipient?.id || '';
+  const billToOrg = recipient?.org || recipient?.organization || null;
+  const billToEmail = recipient?.email || null;
+
+  const billToLines = [esc(billToName)];
+  if (billToOrg) billToLines.push(esc(billToOrg));
+  if (billToEmail) billToLines.push(esc(billToEmail));
+
+  const rowHtml = rows.map(r => `        <tr>
+          <td class="desc">${esc(r.description)}</td>
+          <td class="num">${fmtQty(r.quantity)}</td>
+          <td class="num">${fmtMoney(r.unitPrice, currency)}</td>
+          <td class="num">${fmtMoney(r.amount, currency)}</td>
+        </tr>`).join('\n');
+
+  const memoLine = `Payment terms: Net ${daysBetween(issued, due)} — due ${due}. Period: ${periodLabel}.`;
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Invoice — ${esc(periodLabel)}</title>
+<style>
+  * { box-sizing: border-box; }
+  body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif; color: #1a1a1a; margin: 0; padding: 48px; font-size: 14px; line-height: 1.5; }
+  .invoice { max-width: 720px; margin: 0 auto; }
+  h1 { font-size: 28px; letter-spacing: 0.06em; margin: 0 0 24px; font-weight: 600; }
+  .meta { display: flex; justify-content: space-between; gap: 32px; margin-bottom: 32px; }
+  .meta .block { flex: 1; }
+  .label { text-transform: uppercase; font-size: 11px; letter-spacing: 0.08em; color: #888; margin-bottom: 4px; }
+  .billto-name { font-weight: 600; }
+  table { width: 100%; border-collapse: collapse; margin: 8px 0 0; }
+  thead th { text-align: left; border-bottom: 2px solid #1a1a1a; padding: 8px 10px; font-size: 11px; text-transform: uppercase; letter-spacing: 0.06em; color: #555; }
+  thead th.num { text-align: right; }
+  tbody td { padding: 10px; border-bottom: 1px solid #e2e2e2; vertical-align: top; }
+  tbody td.num { text-align: right; white-space: nowrap; }
+  tbody td.desc { width: 55%; }
+  .totals { margin-top: 16px; display: flex; justify-content: flex-end; }
+  .totals table { width: auto; min-width: 280px; }
+  .totals td { padding: 6px 10px; border: none; }
+  .totals td.num { text-align: right; white-space: nowrap; }
+  .totals tr.grand td { border-top: 2px solid #1a1a1a; font-weight: 700; font-size: 16px; padding-top: 12px; }
+  .memo { margin-top: 40px; padding-top: 16px; border-top: 1px solid #e2e2e2; color: #555; font-size: 13px; }
+  @media print { body { padding: 0; } }
+</style>
+</head>
+<body>
+  <div class="invoice">
+    <h1>INVOICE</h1>
+    <div class="meta">
+      <div class="block">
+        <div class="label">Bill to</div>
+        <div class="billto-name">${billToLines.join('</div>\n        <div>')}</div>
+      </div>
+      <div class="block">
+        <div class="label">Issued</div>
+        <div>${esc(issued)}</div>
+        <div class="label" style="margin-top:12px;">Period</div>
+        <div>${esc(periodLabel)}</div>
+      </div>
+    </div>
+    <table>
+      <thead>
+        <tr>
+          <th class="desc">Description</th>
+          <th class="num">Quantity (hrs)</th>
+          <th class="num">Unit price</th>
+          <th class="num">Amount</th>
+        </tr>
+      </thead>
+      <tbody>
+${rowHtml}
+      </tbody>
+    </table>
+    <div class="totals">
+      <table>
+        <tr class="grand">
+          <td>Total due</td>
+          <td class="num">${fmtMoney(total, currency)}</td>
+        </tr>
+      </table>
+    </div>
+    <div class="memo">${esc(memoLine)}</div>
+  </div>
+</body>
+</html>
+`;
+}
+
+// HTML-escape a value for safe interpolation into the invoice document.
+function esc(v) {
+  return String(v == null ? '' : v)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+// "2026-06" → "June 2026". Falls back to the raw input on a malformed value.
+function formatMonthYear(yyyymm) {
+  const m = String(yyyymm || '').match(/^(\d{4})-(\d{2})/);
+  if (!m) return String(yyyymm || '');
+  const months = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'];
+  const idx = parseInt(m[2], 10) - 1;
+  if (idx < 0 || idx > 11) return String(yyyymm);
+  return `${months[idx]} ${m[1]}`;
+}
+
+// Whole-day gap between two ISO dates (used to label the memo's "Net N").
+// Defaults to 30 if either date is unparseable.
+function daysBetween(fromIso, toIso) {
+  const a = Date.parse(`${fromIso}T00:00:00Z`);
+  const b = Date.parse(`${toIso}T00:00:00Z`);
+  if (!Number.isFinite(a) || !Number.isFinite(b)) return 30;
+  return Math.round((b - a) / 86400000);
+}
+
+function fmtQty(n) {
+  // Trim trailing zeros: 2.50 → "2.5", 3.00 → "3".
+  const r = Math.round((Number(n) || 0) * 100) / 100;
+  return String(r);
+}
+
+function fmtMoney(n, currency = 'USD') {
+  const amount = (Number(n) || 0).toFixed(2);
+  const symbols = { USD: '$', CAD: '$', AUD: '$', GBP: '£', EUR: '€' };
+  const sym = symbols[currency];
+  // Group thousands with commas.
+  const [whole, frac] = amount.split('.');
+  const grouped = whole.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+  return sym ? `${sym}${grouped}.${frac}` : `${grouped}.${frac} ${currency}`;
+}
+
 // ---------------------------------------------------------------------------
 // renderPacket — build a per-recipient projection + consultant-side refmap
 // ---------------------------------------------------------------------------
@@ -403,7 +629,14 @@ export function renderPacket(config, actions, events, billing, recipient, prevPa
       // Completed wins over needs: a done item is never shown as pending.
       shipped.push({ ...item, status: STATUS_LABELS.done });
     } else if (parsed.needs.length > 0) {
-      needs_you.push({ ...item, kind: parsed.needs[0], options: extractClientOptions(a) });
+      const kind = parsed.needs[0];
+      if (kind === 'decision') {
+        // Structured options + decision_type (§5.1). A real (projected) action
+        // declares free-text by carrying no options.
+        needs_you.push({ ...item, kind, ...buildDecisionFields(a) });
+      } else {
+        needs_you.push({ ...item, kind, options: extractClientOptions(a) });
+      }
     } else if (parsed.assignees.length > 0 && !parsed.assignees.includes(recipient.id)) {
       // Delegated = assigned to others and NOT to this recipient. An item the
       // recipient is also an assignee on is their own work (in_flight), not delegated.
@@ -458,22 +691,51 @@ export function renderPacket(config, actions, events, billing, recipient, prevPa
     }
   }
 
+  // Internalized decision projection (§5.1, P1.1): synthesize a needs_you
+  // decision per engagement.yaml `decide` item that no LIVE action already
+  // covers. The synthesized item carries a deterministic backing fid so its
+  // ref/refmap entry is stable and an inbound answer resolves to it — exactly
+  // as for a real action. Structural dedup (invariant #3): a live, visible
+  // needs:decision action declaring `engagement_key: <key>` in its notes
+  // renders that decision instead, so it is never emitted twice.
+  const coveredKeys = new Set();
+  for (const a of visible) {
+    // Only a projected action that ACTUALLY RENDERS as a decision (i.e. has
+    // client copy) covers its key. A marker-bearing action with no copy is
+    // dropped to notClientReady and renders nowhere; if it also suppressed the
+    // synthesis the decision would vanish silently. Require copy so synthesis
+    // still fills that gap.
+    if (parseActionTags(a.tags).needs.includes('decision') && parseClientCopy(a) !== null) {
+      const k = parseEngagementKey(a.notes);
+      if (k) coveredKeys.add(k);
+    }
+  }
+  for (const synth of synthesizeDecisions(config, recipient, roles, coveredKeys, refmap, liveFids)) {
+    needs_you.push(synth);
+  }
+
   // 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.
+  // Checklist summary: NON-decide checklist items only (credentials/confirms
+  // handled interactively via /setup-accounts). `decide` items now render as
+  // needs_you decisions (the internalized projection, §5.1), so counting them
+  // here too would double-surface every decision — they are EXCLUDED. The type
+  // label is derived from a real section field (type → kind → label → key),
+  // never the literal 'unknown'; a section with zero non-decide items is
+  // omitted entirely (no empty / 'unknown' rows leak into the packet).
   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;
+  const checklistRows = [];
+  for (const s of sections) {
+    const items = Array.isArray(s.items) ? s.items : [];
+    const nonDecide = items.filter(it => it && it.kind !== 'decide');
+    if (nonDecide.length === 0) continue;
+    checklistRows.push({ type: s.type || s.kind || s.label || s.key || 'checklist', count: nonDecide.length });
+  }
+  const checklistSummary = checklistRows.length > 0 ? checklistRows : null;
 
   // Engagement-wide notes: persistent messages from the consultant that appear
   // at the top of every packet (e.g. caveats, disclaimers, contextual notes).
@@ -553,6 +815,111 @@ export function extractClientOptions(item) {
   return extractOptions(item);
 }
 
+// ---------------------------------------------------------------------------
+// Decision items — structured options & the internalized projection (§5.1)
+// ---------------------------------------------------------------------------
+
+// Deterministic backing fid for a yaml-authored decision. MUST satisfy the
+// pib-db FID_PATTERN (`act:<8 lowercase hex>`) so an inbound answer's
+// target_fid passes addEngagementEvent's validateFid — the production ingest
+// path the loop test's in-memory refmap can't exercise. Deterministic FNV-1a
+// over (slug, section, key) → 8 hex: a stable ref across renders, the same
+// identity any materialized backing row derives. A collision with a real
+// pib-db-generated fid is ~1e-6 and is hard-guarded in synthesizeDecisions
+// (an unrelated live-fid match throws loudly rather than mis-attributing).
+export function decisionFid(engagementSlug, sectionKey, itemKey) {
+  let h = 0x811c9dc5;
+  const s = `${engagementSlug}${sectionKey}${itemKey}`;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return 'act:' + (h >>> 0).toString(16).padStart(8, '0');
+}
+
+// Normalize one option (yaml entry OR a legacy comma-split string) → { value,
+// label }. `value` is the canonical, comma-safe answer text; `label` defaults
+// to it. Empty/whitespace-only values drop out.
+export function normalizeOption(opt) {
+  if (opt == null) return null;
+  if (typeof opt === 'object' && !Array.isArray(opt)) {
+    const value = String(opt.value ?? '').trim();
+    if (!value) return null;
+    const lab = opt.label != null ? String(opt.label).trim() : '';
+    return { value, label: lab || value };
+  }
+  const value = String(opt).trim();
+  return value ? { value, label: value } : null;
+}
+
+// { decision_type, options } for a yaml decide item. free_text when the item
+// declares free_text:true OR carries no options. Choice options are the
+// structured array — never a comma-joined string.
+function decisionShape(item) {
+  const options = Array.isArray(item.options) ? item.options.map(normalizeOption).filter(Boolean) : [];
+  const freeText = item.free_text === true || options.length === 0;
+  return { decision_type: freeText ? 'free_text' : 'choice', options: freeText ? [] : options };
+}
+
+// { decision_type, options } for a REAL (projected) needs:decision action.
+// Sources options from the legacy comma-split path and normalizes them to the
+// structured shape so every decision item is uniform. No options ⇒ free_text.
+function buildDecisionFields(action) {
+  const options = (extractClientOptions(action) || []).map(normalizeOption).filter(Boolean);
+  const freeText = options.length === 0;
+  return { decision_type: freeText ? 'free_text' : 'choice', options: freeText ? [] : options };
+}
+
+// The dedup key: a backing/projected action declares which decide item it
+// covers with an `engagement_key: <itemKey>` marker on its own notes line.
+function parseEngagementKey(notes) {
+  const m = (notes || '').match(/^engagement_key:\s*(\S+)\s*$/m);
+  return m ? m[1] : null;
+}
+
+// Synthesize needs_you decision items from the config's `decide` sections,
+// skipping any key a live action already covers (coveredKeys). Pure: builds an
+// in-memory action shape per decide item and reuses visibleTo (audience-aware)
+// + stableRef, then emits the structured decision item and records its refmap
+// entry. Returns the items to append to needs_you.
+function synthesizeDecisions(config, recipient, roles, coveredKeys, refmap, liveFids) {
+  const out = [];
+  const slug = config.engagement?.slug || config.engagement?.project_fid || 'engagement';
+  for (const sec of config.sections || []) {
+    const sectionKey = sec.key || sec.label || 'section';
+    for (const it of (sec.items || [])) {
+      if (!it || it.kind !== 'decide' || !it.key) continue;
+      if (coveredKeys.has(it.key)) continue; // a live action renders this one
+      const audience = Array.isArray(it.audience) ? it.audience : (it.audience ? [it.audience] : []);
+      const tags = ['client-visible', 'needs:decision', ...audience.map(a => `audience:${a}`)].join(',');
+      const synthAction = { fid: decisionFid(slug, sectionKey, it.key), tags, status: 'open', notes: `engagement_key: ${it.key}` };
+      if (!visibleTo(synthAction, recipient, roles)) continue;
+      // Collision guard: this key was NOT covered by a marker-bearing action
+      // (coveredKeys skip above), so a live-fid match here is an UNRELATED
+      // action. Throw loudly rather than mis-attribute the answer to it.
+      if (liveFids && liveFids.has(synthAction.fid)) {
+        throw new Error(`renderPacket: synthesized decision fid ${synthAction.fid} (key "${it.key}") collides with an unrelated live action fid`);
+      }
+      const ref = stableRef(synthAction.fid);
+      if (refmap[ref] && refmap[ref] !== synthAction.fid) {
+        throw new Error(`renderPacket: stableRef collision (synthesized decision) — ${refmap[ref]} and ${synthAction.fid} both hash to ${ref}`);
+      }
+      refmap[ref] = synthAction.fid;
+      const title = String(it.prompt || it.key).replace(STATUS_SUFFIX_RE, '').trim();
+      const why = [it.help, it.tradeoff ? `Trade-off: ${it.tradeoff}` : '']
+        .map(x => (x == null ? '' : String(x).trim())).filter(Boolean).join('\n\n');
+      const { decision_type, options } = decisionShape(it);
+      const item = { ref, title, why, kind: 'decision', decision_type, options };
+      const itemTags = tags.split(',').map(t => t.trim()).filter(Boolean);
+      const scopedNotes = (config.scoped_notes || [])
+        .filter(sn => sn.tag && itemTags.includes(sn.tag)).map(sn => sn.note).filter(Boolean);
+      if (scopedNotes.length) item.context_notes = scopedNotes;
+      out.push(item);
+    }
+  }
+  return out;
+}
+
 function collectRefs(packet) {
   if (!packet) return [];
   const buckets = ['needs_you', 'in_flight', 'shipped', 'delegated'];
@@ -596,6 +963,19 @@ export function assertPacketInvariants(packet, recipient, roles) {
     }
   }
 
+  // Fail-closed (§5.1, P1.2): an answerable choice decision must carry >=2
+  // options. An unanswerable choice can never ship as an empty client dialog —
+  // the failure is loud at render time. free_text decisions (0 options) and
+  // display-only roll-ups (no ref) are exempt.
+  for (const item of packet.needs_you || []) {
+    if (item.kind === 'decision' && item.ref && item.decision_type === 'choice') {
+      const n = Array.isArray(item.options) ? item.options.length : 0;
+      if (n < 2) {
+        throw new Error(`assertPacketInvariants: decision "${item.title}" (${item.ref}) is a choice with ${n} option(s) — a choice decision needs >=2 options. Fix: add a second option; OR declare free_text (a yaml decide item); OR drop the needs:decision tag (a projected action). The whole packet is held until this is resolved.`);
+      }
+    }
+  }
+
   const hasBilling = Object.prototype.hasOwnProperty.call(packet, 'billing') && packet.billing != null;
   if (hasBilling && role.billing !== true) {
     throw new Error(`assertPacketInvariants: role "${recipient.role}" must not receive billing`);

package/templates/engagement/pib-db-patches/pib-db-lib.mjs

@@ -8,10 +8,19 @@
 // None of them do console.log — callers decide how to present output.
 
 import { existsSync, readFileSync } from 'node:fs';
-import { ENGAGEMENT_EVENTS_CREATE, ENGAGEMENT_EVENTS_INDEXES } from '../.claude/engagement/sql-constants.mjs';
 import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 
+// sql-constants lives in the installed engagement runtime (.claude/engagement/),
+// which is gitignored in the CC source repo — absent on every fresh checkout/CI,
+// where npm test must still pass (act:d64feaac). Fall back to the committed
+// template source of truth. Same code in template and installed copies — no fork.
+const { ENGAGEMENT_EVENTS_CREATE, ENGAGEMENT_EVENTS_INDEXES } =
+  await import('../.claude/engagement/sql-constants.mjs').catch((err) => {
+    if (err.code !== 'ERR_MODULE_NOT_FOUND') throw err;
+    return import('../templates/engagement/sql-constants.mjs');
+  });
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------

package/templates/engagement/pib-db-patches/pib-db-mcp-server.mjs

@@ -5,59 +5,20 @@
 // for Claude Code to call directly instead of shelling out to the CLI.
 //
 // Environment:
-//   PIB_DB_PATH  — path to SQLite file (default: ./pib.db)
+//   PIB_DB_PATH  — path to SQLite file. Overrides everything. Otherwise the
+//                  path resolver (pib-db-path.mjs) picks main's pib.db when in
+//                  a linked worktree, else cwd/pib.db.
 
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
 import { createInterface } from 'node:readline';
-import { existsSync, readFileSync, statSync } from 'node:fs';
 import * as lib from './pib-db-lib.mjs';
+import { resolvePibDbPath } from './pib-db-path.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-// Resolve pib.db path, handling git worktrees where cwd may not contain
-// the canonical database. Worktrees have a .git *file* (not directory)
-// pointing to the main repo's .git/worktrees/<name>/ directory.
-function resolveDbPath() {
-  if (process.env.PIB_DB_PATH) return process.env.PIB_DB_PATH;
-
-  const cwd = process.cwd();
-  const localDb = join(cwd, 'pib.db');
-
-  // If local pib.db exists and is non-trivial (>8KB), use it
-  if (existsSync(localDb)) {
-    try {
-      const stats = statSync(localDb);
-      if (stats.size > 8192) return localDb;
-    } catch { /* fall through to worktree detection */ }
-  }
-
-  // Check if we're in a git worktree (.git is a file, not a directory)
-  const gitPath = join(cwd, '.git');
-  if (existsSync(gitPath)) {
-    try {
-      const stats = statSync(gitPath);
-      if (stats.isFile()) {
-        // .git file contains: "gitdir: /path/to/main/.git/worktrees/<name>"
-        const content = readFileSync(gitPath, 'utf-8').trim();
-        const match = content.match(/^gitdir:\s*(.+)/);
-        if (match) {
-          // Walk up from .git/worktrees/<name> to find the main repo
-          const gitdir = match[1];
-          const mainGitDir = join(gitdir, '..', '..');
-          const mainRepoDir = dirname(mainGitDir);
-          const mainDb = join(mainRepoDir, 'pib.db');
-          if (existsSync(mainDb)) return mainDb;
-        }
-      }
-    } catch { /* fall through to default */ }
-  }
-
-  return localDb;
-}
-
-const DB_PATH = resolveDbPath();
+const DB_PATH = resolvePibDbPath();
 
 // ---------------------------------------------------------------------------
 // SQLite setup

package/templates/engagement/pib-db-patches/pib-db.mjs

@@ -24,15 +24,18 @@
 //   node scripts/pib-db.mjs triage-history              # Suppression list JSON
 //
 // Environment:
-//   PIB_DB_PATH  — path to SQLite file (default: ./pib.db)
+//   PIB_DB_PATH  — path to SQLite file. Overrides everything. Otherwise the
+//                  path resolver (pib-db-path.mjs) picks main's pib.db when in
+//                  a linked worktree, else cwd/pib.db.
 
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
 import * as lib from './pib-db-lib.mjs';
+import { resolvePibDbPath } from './pib-db-path.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const DB_PATH = process.env.PIB_DB_PATH || join(process.cwd(), 'pib.db');
+const DB_PATH = resolvePibDbPath();
 
 // ---------------------------------------------------------------------------
 // SQLite setup — try better-sqlite3

package/templates/hooks/action-completion-gate.sh

@@ -68,10 +68,16 @@ fi
 #
 # Tag lookup is best-effort: if pib.db can't be read, GRP_LABEL is empty and
 # this gate is skipped — the base breadcrumb gate above still applies.
-# Same worktree resolution for the db: a worktree without its own pib.db
-# falls back to the main checkout's, so the grp gate doesn't silently skip.
+# Worktree resolution mirrors scripts/pib-db-path.mjs (the JS resolver) and the
+# VERIFY_DIR logic above: an explicit PIB_DB_PATH wins; otherwise, in a linked
+# worktree whose main checkout HAS a pib.db, ALWAYS use main's db — never the
+# worktree's own copy (work-tracking is project-level; one main db is the
+# source of truth). Earlier this only redirected when the local pib.db was
+# absent, which silently read a stale/empty worktree-local db whenever one
+# existed (the symlink mux creates usually hid it) — diverging from the JS
+# resolver that dropped exactly that "local db wins" heuristic. Keep in step.
 DB_PATH="${PIB_DB_PATH:-pib.db}"
-if [ ! -f "$DB_PATH" ] && [ -z "$PIB_DB_PATH" ] && [ -n "$MAIN_CHECKOUT" ] && [ -f "$MAIN_CHECKOUT/pib.db" ]; then
+if [ -z "$PIB_DB_PATH" ] && [ -n "$MAIN_CHECKOUT" ] && [ -f "$MAIN_CHECKOUT/pib.db" ]; then
   DB_PATH="$MAIN_CHECKOUT/pib.db"
 fi
 TAGS=$(python3 -c "

package/templates/hooks/memory-index-guard.sh

@@ -5,9 +5,14 @@
 # Triggers: PostToolUse on Write/Edit when the target path is under
 # ~/.claude/projects/*/memory/*.md (Claude Code's auto-memory dir).
 #
-# Behavior: runs scripts/validate-memory.mjs against the memory dir.
-# If the validator reports orphan files (memory file written but not
-# indexed), emits a system reminder pointing Claude at /cc-remember.
+# Behavior: runs scripts/validate-memory.mjs in --check-file mode against
+# the file just written. If THAT file is not reachable from MEMORY.md
+# (no index line and no region pointer covers it — i.e. it was written
+# straight to disk and isn't in the working set), emits a system reminder
+# pointing Claude at /cc-remember. Keys on the written file's reachability,
+# NOT on the whole-dir validation — so an unrelated pre-existing violation
+# (e.g. a stale region pointer) never makes the guard cry wolf on every
+# write, and the relaxed enumeration rule doesn't silently retire it.
 #
 # This is the post-omega-winddown replacement for omega-memory-guard.sh.
 # Where the omega guard BLOCKED markdown writes (redirecting them to
@@ -45,8 +50,9 @@ if [ ! -f "$VALIDATOR" ]; then
   exit 0
 fi
 
-# Run validator quietly. If it reports orphans, emit guidance.
-OUTPUT=$(node "$VALIDATOR" --memory-dir "$MEMORY_DIR" --quiet 2>&1)
+# Check only THIS file's reachability. Exits non-zero with a one-line
+# message when the just-written file isn't reachable from MEMORY.md.
+OUTPUT=$(node "$VALIDATOR" --memory-dir "$MEMORY_DIR" --check-file "$FILE_PATH" --quiet 2>&1)
 STATUS=$?
 
 if [ $STATUS -eq 0 ]; then
@@ -56,15 +62,15 @@ fi
 # Print the failure to stdout so it surfaces back to Claude as
 # additional context. Frame as a suggestion, not a block.
 cat <<REMINDER
-[memory-index-guard] $(basename "$FILE_PATH") was written to a memory directory,
-but validate-memory.mjs reports an issue:
+[memory-index-guard] $(basename "$FILE_PATH") was written to a memory directory
+but is not reachable from MEMORY.md:
 
 $OUTPUT
 
-To fix the most common case (orphan memory file not indexed in
-MEMORY.md), use /cc-remember next time — it updates MEMORY.md
-automatically. Or manually add this file to MEMORY.md's
-"## Curated entries (hand-authored)" section.
+The file is on disk but nothing makes it findable next session — it has no
+working-set index line and no region pointer covers it. Use /cc-remember
+(it indexes into the working set automatically), or add a covering region
+pointer in MEMORY.md, or add a "## Curated entries (hand-authored)" line.
 REMINDER
 
 exit 0