create-claude-cabinet 0.46.0 → 0.47.0

package/templates/engagement/engagement-schema.md

@@ -238,9 +238,15 @@ billing:
   currency: USD
   period: since-last-sync          # engagement | month | since-last-sync
 
+invoicing:                         # optional — see §8.1
+  mode: consolidated               # consolidated | itemized
+  scope_label: "Consulting services"
+  terms_days: 30
+
 recipients:
   - id: ed
     name: "Ed Maginnis"
+    org: "Maginnis Howard"         # optional — shown in the invoice bill-to
     email: "ed@example.com"
     role: principal
     scopes: [all]
@@ -337,6 +343,186 @@ checklist_summary     # [ { type, count } ] when config has sections
 
 ---
 
+## 5.1. Decision items — the structured options & decision-type contract
+
+The single shared contract that the engine synthesis (`renderPacket`),
+the fail-closed validator (`assertPacketInvariants`), the client
+renderer (`/collab-client`), and the consultant inbox
+(`/collab-consultant`) all conform to. P1.1–P1.4 of the engagement
+upstream-fix program depend on this — pin it here, build to it.
+
+### Where a decision is authored (once)
+
+A decision is authored exactly once, in `engagement.yaml`, as a `decide`
+item inside a `sections[]` block:
+
+```yaml
+sections:
+  - key: go_live
+    items:
+      - key: arbitration_forum_model
+        kind: decide
+        tier: recommended            # optional priority hint (free text)
+        audience: [ed]               # optional; default = all principals
+        prompt: "Which forum model…" # the question  → client_title / title
+        help:  "Tracking per-company…" # the explanation → client_body / why
+        tradeoff: "Per-company is…"   # optional; appended to `why`
+        options:                      # omit / empty ⇒ free-text decision
+          - "A — forum per company, with an analysis notes field"
+          - value: "B — one forum per theory"
+            label: "One forum per theory"
+        free_text: false              # optional; forces a free-text answer
+```
+
+`engagement.yaml` stays the **authoritative authoring source** for
+decisions (Non-Goal: dropping it). The engine derives everything below
+from it.
+
+### The engine internalizes the projection (P1.1)
+
+`renderPacket`, given the parsed config, **ensures a backing decision
+per `decide` item and renders it into `needs_you` exactly as it renders
+a `needs:decision` action** — preserving the `ref` / `refmap` /
+`client_feedback` spine. The pure engine synthesizes the backing item
+**in-memory** from the yaml (it imports nothing — no DB, no fs); a
+pib-db row is materialized separately by `ensureDecisionActions` (below).
+
+- **Deterministic backing fid.** Each decide item gets a stable fid
+  `decisionFid(engagementSlug, sectionKey, itemKey)` → `act:<8 hex>`
+  (FNV-1a). Deterministic so the `ref` is stable across renders
+  (`new_since_last` stays a reliable diff) and so an inbound answer's
+  `target_fid` always resolves to the same decision — even across a
+  re-render (the cross-render gate). It **must satisfy the pib-db
+  `FID_PATTERN` (`act:<8 lowercase hex>`)** so the answer's `target_fid`
+  passes `addEngagementEvent`'s `validateFid` — the production ingest
+  path the loop test's in-memory refmap never exercises (so the loop
+  test alone would not catch a malformed fid; this is why the scheme is
+  fixed at design time, not later). A collision with a real
+  pib-db-generated fid is ~1e-6 and is hard-guarded in the synthesis (an
+  unrelated live-fid match throws loudly rather than mis-attributing the
+  answer).
+- **Same spine as an action.** `ref = stableRef(fid)`,
+  `refmap[ref] = fid`. The client answers `context_ref: <ref>`; the
+  consultant inbox resolves `ref → fid` and writes `client_feedback`
+  with `target_fid = fid`. A yaml section rendered *raw* (no fid) would
+  break this — hence synthesis, not raw rendering (loop-test step D).
+- **No row required to render or round-trip.** `target_fid` has no FK,
+  so the answer stores even if no pib-db row exists. The row exists so
+  the consultant can *apply* the answer against a real action — see
+  `ensureDecisionActions`.
+
+### Structural dedup (invariant #3)
+
+The engine must **never** emit a decision twice — once natively from the
+yaml and once from a surviving projected action. A backing/projected
+action declares which decide item it covers via an
+`engagement_key: <itemKey>` marker on its own line in `notes`. When
+synthesizing, the engine **skips any decide item whose key appears in
+the `engagement_key` marker of a live, visible `needs:decision`
+action** — that action renders it instead. The marker is the single
+dedup key, shared by the engine synthesis and `ensureDecisionActions`.
+After the Phase-2 cutover (projected actions tag-neutralized), every
+decide item renders natively.
+
+### The packet decision item (the structured shape — P1.2)
+
+Every decision `needs_you` item carries the fields below. **Note the
+`kind` value is `'decision'`, not `'needs:decision'`** — `parseActionTags`
+strips the `needs:` prefix, so the rendered item's `kind` is the
+post-colon token (`'decision'` / `'credential'`). The TAG is
+`needs:decision`; the item FIELD is `kind: 'decision'`.
+
+| Field | Type | Meaning |
+| ----- | ---- | ------- |
+| `ref` | string | opaque stable ref (`refmap` resolves it to the fid) |
+| `title` | string | the question (`prompt` / `client_title`) |
+| `why` | string | the explanation (`help` / `client_body`, + `tradeoff`) |
+| `kind` | `'decision'` | the needs token (the `needs:` prefix is stripped) |
+| `decision_type` | `'choice'` \| `'free_text'` | how it is answered |
+| `options` | `Array<{ value: string, label?: string }>` | the choices |
+
+- **`options` is an array of objects, never a comma-joined string.** The
+  `value` is the canonical, **comma-safe** answer text, round-tripped
+  verbatim — there is no `split(',')` on a value anywhere. `label` is an
+  optional short display string (defaults to `value`). This retires the
+  lossy `Options: A, B, C` line: a value that itself contains a comma
+  survives intact.
+- **Normalization.** A yaml option given as a bare string `"X"`
+  normalizes to `{ value: "X", label: "X" }`. An object option passes
+  through; a missing `label` defaults to `value`. Whitespace-only / empty
+  values are dropped.
+- **`decision_type: 'free_text'`** — an open-ended written answer. Set
+  when the decide item declares `free_text: true` OR has no `options`.
+  `options` is `[]`. The client collects free text instead of choices.
+- **`decision_type: 'choice'`** — pick from `options` (≥2 required).
+
+### Fail-closed (P1.2)
+
+`assertPacketInvariants` **throws** on any answerable `needs_you` item
+(`kind === 'decision'` carrying a `ref`) with `decision_type === 'choice'`
+and `options.length < 2`. An unanswerable choice decision can never ship —
+the failure is loud at render time, not a confusing empty dialog for the
+client. The gate is whole-packet (consistent with the leak gate): a
+misconfigured decision holds the entire packet until fixed. Free-text
+decisions legitimately carry zero options and are exempt. Display-only
+roll-ups (`feedbackable: false`, no `ref`) are exempt. A real (projected)
+action with exactly 1 option also trips this — fix by adding a second
+option or dropping the `needs:decision` tag (an action author has no
+`free_text` field).
+
+### Two stability caveats
+
+- **Decide keys must be unique across sections.** Dedup (and the legacy
+  workaround) match a projected action's `engagement_key: <key>` marker —
+  which carries no section — against a yaml decide key. If the same key
+  appears in two sections and one projected action covers it, both
+  sections' synthesis is suppressed and only one renders. Keep decide
+  keys unique within an engagement.
+- **A section/slug rename re-keys the ref.** The cross-render ref
+  stability holds only while `engagement.slug`, the section key, and the
+  item key are all unchanged (they seed `decisionFid`). Renaming any of
+  them changes the fid → ref and orphans an in-flight answer keyed to the
+  old ref. Don't rename a section or the slug while a decision packet is
+  out and unanswered (the refmap-continuity invariant, #5).
+
+### `ensureDecisionActions` — the persistent-row materialization (Phase-2 cutover)
+
+**Phase 1 ships the render synthesis above; the persistent-row
+materialization lands at the Phase-2 Maginnis cutover (P2.1), where it
+replaces the project-local `project-engagement-decisions.mjs`.** The
+synthesis alone closes the loop (render + refmap + answer round-trip;
+`target_fid` has no FK, so the answer stores without a row). The
+materialized row is what lets the consultant *apply* an answer against a
+tracked action.
+
+When built, it is the DB-side counterpart — living at the adapter/skill
+boundary (NOT in the pure engine), called at sync time before render:
+idempotently materializes one pib-db action per decide item, keyed to
+the **same deterministic fid** and carrying the `engagement_key:
+<itemKey>` marker, `client-visible,needs:decision` tags (+
+`audience:<id>` when declared), and the structured copy. Because the row
+carries the marker, the render's structural dedup skips re-synthesizing
+that key and renders the row instead — so in production every decision
+resolves to a real, ingest-valid fid, and the synthesis is the
+no-row / loop-test fallback.
+
+### Client render (P1.2 → `/collab-client`)
+
+A `choice` decision maps each `options[i]` to one AskUserQuestion option
+(`label: opt.label`, description from context); the chosen `value` is
+the answer text submitted as the `client_feedback` message. A
+`free_text` decision collects an open written answer (no option list).
+The client never sees the `decision_type` enum or verdict jargon.
+
+### Answer round-trip (unchanged spine)
+
+The answer is a `client_feedback` event with
+`target_fid = refmap[context_ref]` (§6). Because the backing fid is
+deterministic, an answer keyed to a prior packet's ref resolves to the
+same decision across re-renders.
+
+---
+
 ## 6. `item_feedback` envelope
 
 The contract for inbound client responses. **Keyed by `ref` only.**
@@ -448,6 +634,60 @@ Default rate **$190/hr**. `renderBilling` sums the `Hours` column;
 
 ---
 
+## 8.1. Invoicing (`invoicing` block + the `invoices/` output)
+
+`/collab-consultant invoice [YYYY-MM] [--itemized]` renders a clean,
+print-friendly invoice **document** (`renderInvoiceDoc`) from a month's
+tracked hours. It is local-only — no API, no pib-db mutation, no email.
+
+### Why a document, not an API
+
+The operator's bank (**Relay**) does the actual invoicing. Relay has no
+API but accepts an uploaded PDF/PNG via **Create Invoice → Autofill from
+document**. So the system's only job is to render the document; the
+operator uploads, reviews, and sends in Relay. Validated against Relay's
+autofill (live experiment):
+
+- Line items are **Description / Quantity / Unit price / Amount** and
+  Relay computes its own totals (Quantity = hours, Unit price = the rate).
+- Relay assigns its own invoice number and pulls the sender (From /
+  business name / address / email) from the operator's Relay account.
+  **The document therefore carries NO invoice number and NO From / remit
+  / bank / ACH block** — they are ignored or overridden.
+- Relay autofills the customer (bill-to name + email) and the line items
+  + total correctly.
+- Relay does **not** read a net-30 due date — it defaults the due date to
+  today. Terms only survive in Relay's free-text Memo, so they go in a
+  memo-friendly footer line and the skill tells the operator to set the
+  due date in Relay by hand.
+
+### The `invoicing:` config block (optional)
+
+| Field | Default | Meaning |
+| ----- | ------- | ------- |
+| `mode` | `consolidated` | `consolidated` (one line: scope label + month, Quantity = total hours) or `itemized` (one line per timelog row). `--itemized` on the command line overrides. |
+| `scope_label` | `"Consulting services"` | The line description in consolidated mode (rendered as `<scope_label> — <Month YYYY>`). |
+| `terms_days` | `30` | Net-N payment terms — `dueDate = invoiceDate + terms_days`, shown in the memo footer. |
+
+`loadEngagement` normalizes these defaults (mirrors how `billing` /
+`transport` defaults are filled), so downstream code can assume the
+shape. **No bank / remit / From fields are needed** — see above.
+
+The bill-to block reads `recipient.name`, optional `recipient.org`, and
+`recipient.email` (org rides through `normalizeRecipient`).
+
+### Output convention: `invoices/<YYYY-MM>.html` (+ best-effort `.pdf`)
+
+The rendered HTML is written to `invoices/<YYYY-MM>.html` in the working
+dir. The skill then attempts a best-effort PDF conversion using whatever
+tool is already on the machine (weasyprint → headless Chrome →
+wkhtmltopdf), **with no bundled dependency** — if none is available it
+tells the operator to open the HTML and use Cmd-P → Save as PDF. Relay
+needs a PDF or PNG, not HTML. The `invoices/` directory is local runtime
+output (gitignore alongside `engagement-packets/`).
+
+---
+
 ## 9. Scope model: multi-project engagements
 
 An engagement operates at the scope of **one `pib.db`** — all