create-claude-cabinet 0.31.1 → 0.33.0

package/lib/cli.js

@@ -485,7 +485,7 @@ const MODULES = {
     mandatory: false,
     default: true,
     lean: true,
-    templates: ['skills/plan', 'skills/execute', 'skills/generate-plan-groups', 'skills/execute-group', 'workflows/execute-group.js', 'skills/investigate', 'cabinet/checkpoint-protocol.md'],
+    templates: ['skills/plan', 'skills/execute', 'skills/generate-plan-groups', 'skills/execute-group', 'workflows/execute-group-implement.js', 'workflows/execute-group-complete.js', 'skills/investigate', 'cabinet/checkpoint-protocol.md'],
   },
   'compliance': {
     name: 'Compliance Stack (rules + enforcement)',
@@ -582,7 +582,7 @@ const MODULES = {
   },
   'site-audit': {
     name: 'Site Audit (deployed-site quality)',
-    description: '15-check audit for deployed websites: performance, accessibility (3 engines), security, SEO, DNS, privacy, sustainability. Standalone HTML report + comparison mode.',
+    description: '14-check audit for deployed websites: performance, accessibility (3 engines), security, SEO, DNS, privacy, sustainability. Standalone HTML report + comparison mode.',
     mandatory: false,
     default: false,
     lean: false,
@@ -592,20 +592,24 @@ const MODULES = {
     ],
     postInstall: 'site-audit-setup',
   },
-  handoff: {
-    name: 'Handoff (secure credential collection)',
-    description: 'Skill-based credential handoff for consulting engagements. Encrypted credential capture via OS dialog, pluggable transport (email/MCP/file), bidirectional messaging. Six skills across consultant and client sides.',
+  engagement: {
+    name: 'Engagement management (with secure credential handoff)',
+    description: 'Ongoing client-engagement management built on pib-db: per-recipient packets (rendered projections of the work backlog), role-gated billing, client feedback flowing back as events, and secure credential handoff (encrypted capture via OS dialog, pluggable email/MCP/file transport). Seven skills across consultant and client sides. Requires work-tracking (the pib-db adapter is the engine\'s data source).',
     mandatory: false,
     default: false,
     lean: false,
+    requires: ['work-tracking'],
     templates: [
-      'skills/handoff',
-      'skills/handoff-progress',
-      'skills/handoff-ask',
-      'skills/handoff-create',
-      'skills/handoff-add',
-      'skills/handoff-status',
-      'handoff',
+      'skills/engagement',
+      'skills/engagement-progress',
+      'skills/engagement-help',
+      'skills/engagement-message',
+      'skills/engagement-create',
+      'skills/engagement-edit',
+      'skills/engagement-add',
+      'skills/engagement-status',
+      'skills/engagement-sync',
+      'engagement',
     ],
   },
 };
@@ -1016,6 +1020,31 @@ async function run() {
     }
   }
 
+  // --- Enforce module prerequisites (requires:[...]) ---
+  // A selected module may declare hard prerequisites. Auto-include them (same
+  // posture as mandatory modules) with a notice, rather than failing — a
+  // missing prerequisite would surface as a confusing runtime error. e.g.
+  // engagement's pib-db adapter cannot function without work-tracking.
+  for (const key of [...selectedModules]) {
+    for (const req of MODULES[key]?.requires || []) {
+      if (!selectedModules.includes(req)) {
+        selectedModules.push(req);
+        delete skippedModules[req];
+        console.log(`  + Added '${req}' — required by '${key}'.`);
+        // The required module's own DB needs initializing too, unless the
+        // operator explicitly opted out with --no-db (respect that flag, but
+        // warn that the dependent module won't function without it).
+        if (req === 'work-tracking') {
+          if (flags.noDb) {
+            console.log(`    ⚠ --no-db is set, so pib-db won't be initialized — '${key}' will not function until it is.`);
+          } else {
+            includeDb = true;
+          }
+        }
+      }
+    }
+  }
+
   console.log('  Assembling your cabinet...\n');
 
   // --- Copy template files ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-claude-cabinet",
-  "version": "0.31.1",
+  "version": "0.33.0",
   "description": "Claude Cabinet — opinionated process scaffolding for Claude Code projects",
   "bin": {
     "create-claude-cabinet": "bin/create-claude-cabinet.js"
@@ -24,7 +24,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node --test test/**/*.test.js",
+    "test": "node --test test/**/*.test.js templates/**/__tests__/*.test.mjs",
     "prepublishOnly": "node -e \"if (!process.env.CC_ALLOW_PUBLISH) { console.error('\\n\\u2717 Use /cc-publish (which runs the mandatory consumer-walk), not raw npm publish.\\n  Raw npm publish on v0.27.1 left every consumer stale on v0.26.\\n  To publish manually anyway, set CC_ALLOW_PUBLISH=1.\\n'); process.exit(1); }\""
   },
   "dependencies": {

package/templates/README.md

@@ -40,7 +40,7 @@ templates, see [EXTENSIONS.md](EXTENSIONS.md).
 | `skills/debrief-quick/` | Quick debrief variant — core phases only, skip presentation. |
 | `skills/execute/` | Execute a plan with cabinet member checkpoints. 3-checkpoint protocol (pre-implementation, per-file-group, pre-commit). 5 phase files. |
 | `skills/generate-plan-groups/` | Scheduler: find plans with surface-area declarations, build a conflict graph, persist conflict-free parallel groups as pib-db `grp:` tags. Does not execute — hands each group to /execute-group. |
-| `skills/execute-group/` | Runner: execute one generated group via the `execute-group.js` workflow — cabinet pre-review, parallel worktree implementation, sequential merge with per-plan review, integration, informed final review, completion report. |
+| `skills/execute-group/` | Runner: execute one generated group as a 3-stage pipeline — interactive cabinet pre-review (CP1) the operator decides on, then the `execute-group-implement.js` workflow (parallel worktree implementation + sequential merge) and the `execute-group-complete.js` workflow (advisory review + integration + completion report), with operator checkpoints between stages. |
 | `skills/cc-extract/` | Analyze project artifacts and propose upstream extraction candidates for Claude Cabinet. |
 | `skills/investigate/` | Structured codebase exploration: frame, observe, hypothesize, test, conclude. |
 | `skills/cc-link/` | Set up local development linking for Claude Cabinet source repo work. |

package/templates/cabinet/checkpoint-protocol.md

@@ -27,6 +27,36 @@ set of conflict-free plans implemented concurrently in separate worktrees,
 then merged together. `/execute` never exercises that scope — it runs one
 plan at a time and uses only the first three.
 
+## Checkpoint modes — who acts on the verdict
+
+The scope says *what* is reviewed. The **mode** says *what happens to the
+verdict*. This distinction is load-bearing: an autonomous gate that reverts
+or halts on a false-positive `stop` is fragile and expensive. The default for
+high-stakes reviews is to put judgment in front of the operator.
+
+| Mode | Where it runs | What a `stop`/`pause` does | Used by |
+|------|---------------|----------------------------|---------|
+| **Interactive CP** | Main session (skill level) | Surfaced to the operator, who decides (proceed / drop / override / abort). Never automatic. | `/execute-group` CP1 |
+| **Advisory CP** | Workflow | Recorded in the Completion Report as a concern. Never halts or reverts. The only automatic gate alongside it is `/validate`. | `/execute-group` CP3 |
+| **Full CP** | Main session or workflow | Halts on `stop`, escalates 3+ `pause` to a halt, requires explicit override. The classic gate. | `/execute` CP1/CP2/CP3 |
+
+**Why Interactive and Advisory exist.** `/execute-group` once ran CP1 and CP3
+as autonomous gates inside a single workflow: a cabinet `stop` halted the run
+or reverted a merge with no human in the loop. False positives there cost real
+money (a CP1 halted twice consecutively — 1.6M+ tokens — on concerns the plan
+text already addressed). Moving CP1 to interactive (operator decides) and CP3
+to advisory (concerns recorded, `/validate` is the only hard gate) keeps the
+review signal while removing the destructive autonomous action.
+
+### Interactive CP adds a required `addressed_by_plan` field
+
+At Interactive CP (`/execute-group` CP1, `pre-impl` scope), each agent's
+verdict carries one extra **required** field, `addressed_by_plan` — the list
+of risks the plan already handles. The agent must enumerate these *first*,
+before raising any concern. This forces the plan-first discipline structurally:
+a risk listed in `addressed_by_plan` cannot also be raised as a concern. It is
+the direct fix for the false-positive halts.
+
 ## Step 1 — Select which members to spawn
 
 Spawn one Agent per cabinet member that matches **either**:
@@ -107,8 +137,26 @@ Each agent returns exactly this shape:
 }
 ```
 
+At **Interactive CP** (`/execute-group` CP1), add the required
+`addressed_by_plan` array described above:
+
+```json
+{
+  "cabinet_member": "name",
+  "addressed_by_plan": ["risks the plan already handles"],
+  "verdict": "continue" | "pause" | "stop",
+  "concerns": [ ... ]
+}
+```
+
 ## Step 4 — Apply escalation
 
+The escalation below is **Full CP** behavior (used by `/execute`). For
+**Interactive CP** the verdicts are surfaced to the operator severity-first
+and the operator decides — no automatic halt. For **Advisory CP** the concerns
+are recorded in the Completion Report and nothing halts or reverts; `/validate`
+is the only automatic gate. See "Checkpoint modes" above.
+
 Collect every verdict, then:
 
 - **Any `stop`** → halt. Show the concern. Require an explicit override

package/templates/cabinet/pib-db-access.md

@@ -36,6 +36,9 @@ Check: are pib_* MCP tools available?
 | pib_defer_with_trigger     | defer-with-trigger fid --trigger "<text>"       | Defer with a return condition  |
 | pib_list_triggered         | list-triggered [--include-done]                 | List items waiting on triggers |
 | pib_mark_trigger_checked   | mark-trigger-checked fid --result <value>       | Record a trigger evaluation    |
+| pib_add_engagement_event   | add-event --engagement prj:X --kind K --author A --allowed-authors "..." | Append an engagement event |
+| pib_list_engagement_events | list-events [--engagement prj:X] [--unaddressed-only]                    | List engagement events     |
+| pib_mark_event_addressed   | mark-event-addressed id                         | Mark an engagement event addressed |
 | pib_ingest_findings        | ingest-findings run-dir                         | Ingest audit findings          |
 | pib_triage                 | triage finding-id status [notes]                | Triage a finding               |
 | pib_triage_history         | triage-history                                  | Get suppression list           |
@@ -52,6 +55,29 @@ session and surfaces items whose conditions have become true. See
 result vocabulary, cascade semantics for projects, migration
 guarantees, and known limitations.
 
+## Engagement events
+
+The `engagement_events` table (schema v5) is an append-only log for
+consulting engagements managed by the **engagement** module. Each row
+records one event — client feedback, an approval, a status push, a
+delegation, a note, or a packet-sent marker — scoped to an engagement
+(a pib-db project) and optionally to a specific action.
+
+All writes route through `pib_add_engagement_event` (or the CLI
+`add-event`); there is no raw-INSERT path. The caller must pass
+`allowedAuthors` — the engagement's recipient ids plus `"consultant"`,
+derived from `engagement.yaml`. The library itself never reads config;
+the author allowlist is enforced **fail-closed** (an empty or omitted
+allowlist rejects every author). `client_feedback` and `approval`
+events must carry a meaningful verdict (`approve`/`object`/`comment`);
+`none` and null are rejected for those kinds.
+
+See [../engagement/engagement-schema.md](../engagement/engagement-schema.md)
+for the full contract: event kinds, dedup semantics, action tag
+conventions, the client-facing copy block, packet schema and lifecycle,
+the consultant-side `_refmap`, the `item_feedback` envelope, and the
+timelog/billing format.
+
 ## Surface Area Validation
 
 `pib_create_action` (and the CLI `create-action`) require that notes

package/templates/engagement/OVERVIEW.md

@@ -0,0 +1,161 @@
+# The Engagement System — How It Works
+
+A plain-language guide to Claude Cabinet's engagement module for managing
+ongoing client relationships.
+
+**Don't know where to start?** Run **`/engagement-help`** — it detects
+whether you're the consultant or the client, shows you exactly what you
+can do right now, and offers to run the next step for you. No need to
+memorize skill names.
+
+---
+
+## What is it?
+
+The engagement system turns your pib-db work backlog into a communication
+layer with your clients. Instead of emailing status updates manually or
+hoping the client remembers what you discussed on a call, you run one
+command (`/engagement-sync`) and each person on the engagement gets a
+personalized update showing exactly what needs their attention, what's in
+progress, and what's done — formatted for their role.
+
+It grew out of the handoff module (which handled one-time credential
+collection) into something broader: an ongoing engagement loop where work
+flows out as updates, and client feedback flows back as events on a
+timeline you can review at your own pace.
+
+---
+
+## Getting started
+
+Run **`/engagement-help`**. It detects your role automatically — you
+don't need to know which of the 9 skills to use. It reads the engagement
+config, checks what state things are in (fresh? mid-flight? feedback
+waiting?), and tells you exactly what's relevant right now. It also
+offers to run the next step for you, so it works as a launchpad.
+
+---
+
+## How the pieces fit together
+
+### Who sees what
+
+An engagement has **recipients** — the people you're working with. Each
+has a **role**:
+
+- A **principal** sees everything: all client-visible work items, the
+  billing running total, and all messages. They get the full picture.
+- A **delegate** sees only the items specifically assigned to them. No
+  billing, no items outside their scope. They get a focused, relevant
+  view — usually as a plain email rather than the full interactive
+  experience.
+
+You control what appears in anyone's view using **tags** on your pib-db
+actions:
+
+| Tag | What it does |
+|-----|-------------|
+| `client-visible` | Opt-in. Without this, the action is internal and invisible to everyone. |
+| `audience:ed` | Only the named recipient(s) can see it — narrows even a principal. |
+| `scope:marketing` | Only recipients whose scope includes this topic (or the wildcard "all"). |
+| `assignee:sydney` | The sole basis for what a delegate sees. |
+| `needs:decision` | This item requires the client to choose from options. |
+| `needs:credential` | This item requires a secure credential capture. |
+
+Each client-visible action also carries a **client-facing copy block** —
+a title and explanation written for the client, separate from your
+internal notes. The client never sees the raw action text or your working
+notes.
+
+### The trust boundary
+
+The client never sees your internal identifiers. Every item in a
+client's update is referenced by an opaque code (a hash). The mapping
+back to your real action IDs stays on your machine in a gitignored file
+that's never transmitted. When a client responds, their feedback comes
+back keyed by the opaque code — you resolve it locally.
+
+The system enforces this structurally. The update your client receives is
+built from scratch without internal IDs ever being added to it. A
+separate invariant check runs on every update before it can leave your
+machine — if anything leaked through, it throws and the update doesn't
+send.
+
+### Previewing before sending
+
+`/engagement-sync` shows you a summary of what each recipient is about
+to receive **before** anything is dispatched:
+
+```
+Ready to send:
+  Ed (principal, plugin) — 2 need response, 4 in progress, 7 done, $4,417.50 billed
+  Sydney (delegate, email) — 1 assigned item (marketing)
+
+  Blocked (not client-ready): 1 — "DNS cutover" (no client-facing copy)
+```
+
+You can drill into any recipient's full packet to read exactly what
+they'll see, then send, or cancel. Nothing goes out without your
+explicit confirmation.
+
+`/engagement-status` serves as a separate dry-run preview anytime — it
+renders what each recipient *would* receive right now, without
+dispatching anything.
+
+### The feedback loop
+
+Client feedback flows back as events on the engagement timeline. When a
+client approves a decision, you see it and are *offered* (never forced)
+the option to update the action's status. When they object or ask a
+question, it shows up in your inbox. Neutral acknowledgment receipts are
+queued for your review before they reach the client.
+
+### Billing
+
+If enabled, the engagement tracks billable hours from a markdown
+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.
+
+### Credential handoff
+
+When a client needs to provide a secret (API key, token, password):
+
+1. A secure OS dialog appears on their screen (not in the conversation).
+2. They type it — it's encrypted immediately with the consultant's
+   public key.
+3. The encrypted envelope is sent back.
+4. The consultant decrypts it on their machine via `/engagement-status`,
+   which writes the plaintext to a private file they open in their own
+   terminal. The decrypted value never enters Claude's context.
+
+---
+
+## All 9 skills at a glance
+
+| Skill | Who runs it | What it does |
+|-------|------------|-------------|
+| `/engagement-help` | Either | Detects your role and shows you what to do next |
+| `/engagement-create` | Consultant | Set up a new engagement (recipients, roles, billing, credentials, deploy) |
+| `/engagement-edit` | Consultant | Fix or update the config after creation |
+| `/engagement-add` | Consultant | Add a client-visible work item with tags + client-facing copy |
+| `/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 |
+| `/engagement` | Client | Review the latest update and respond |
+| `/engagement-progress` | Client | Quick glance — what's new, counts, read-only |
+
+---
+
+## Known limitations
+
+- **Single machine.** The engagement store (pib.db + the
+  `engagement-packets/` archive) is local. Running sync from two
+  different machines without syncing those files can produce inconsistent
+  updates.
+- **No terminal state.** An engagement never "completes" — a credential
+  checklist can finish without ending the engagement. Sync is
+  re-runnable indefinitely.
+- **Credential decryption requires a desktop.** On Linux without
+  `zenity`, the secure dialog can't appear and the system refuses rather
+  than showing the secret on screen.