create-claude-cabinet 0.32.0 → 0.33.1

package/lib/cli.js

@@ -9,6 +9,7 @@ const { create: createMetadata, read: readMetadata } = require('./metadata');
 const { setupDb } = require('./db-setup');
 const { setupVerifyRuntime } = require('./verify-setup');
 const { setupSiteAuditRuntime } = require('./site-audit-setup');
+const { setupEngagement } = require('./engagement-setup');
 const { reset } = require('./reset');
 
 const VERSION = require('../package.json').version;
@@ -485,7 +486,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)',
@@ -599,6 +600,7 @@ const MODULES = {
     default: false,
     lean: false,
     requires: ['work-tracking'],
+    postInstall: 'engagement-setup',
     templates: [
       'skills/engagement',
       'skills/engagement-progress',
@@ -1269,6 +1271,7 @@ async function run() {
   const POST_INSTALL_HANDLERS = {
     'verify-setup': setupVerifyRuntime,
     'site-audit-setup': setupSiteAuditRuntime,
+    'engagement-setup': setupEngagement,
   };
   for (const moduleKey of selectedModules) {
     const mod = MODULES[moduleKey];
@@ -1280,7 +1283,7 @@ async function run() {
     }
     try {
       console.log('');
-      const result = handler({ dryRun: !!flags.dryRun });
+      const result = handler({ dryRun: !!flags.dryRun, projectDir });
       for (const r of result.results || []) console.log(`  📋 ${r}`);
     } catch (err) {
       console.log(`  ⚠ ${mod.postInstall} failed: ${err.message}`);

package/lib/engagement-setup.js

@@ -0,0 +1,61 @@
+/**
+ * engagement-setup.js — extend pib-db files with engagement schema v5
+ * when the engagement module is installed.
+ *
+ * Dispatched from cli.js's postInstall pipeline. Idempotent: skips
+ * files that already contain the engagement code (detected by marker).
+ *
+ * The base pib-db templates (owned by work-tracking) ship schema v1-v4.
+ * The engagement module stores the complete engagement-inclusive versions
+ * of the pib-db files in templates/engagement/pib-db-patches/. When
+ * engagement is selected, this handler copies those over the base
+ * versions, keeping the base templates clean for consumers who don't
+ * opt into engagement.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const MARKER = 'ENGAGEMENT_EVENT_KINDS';
+const FILES = ['pib-db-lib.mjs', 'pib-db-mcp-server.mjs', 'pib-db-schema.sql', 'pib-db.mjs'];
+
+function setupEngagement({ dryRun, projectDir } = {}) {
+  const results = [];
+  const scriptsDir = path.join(projectDir, 'scripts');
+  const patchDir = path.join(projectDir, '.claude', 'engagement', 'pib-db-patches');
+
+  if (!fs.existsSync(patchDir)) {
+    results.push('engagement-setup: patch dir not found — skipping (templates not yet copied)');
+    return { results };
+  }
+
+  for (const file of FILES) {
+    const target = path.join(scriptsDir, file);
+    const source = path.join(patchDir, file);
+
+    if (!fs.existsSync(source)) {
+      results.push(`${file}: engagement patch not found — skipped`);
+      continue;
+    }
+
+    if (!fs.existsSync(target)) {
+      results.push(`${file}: target not found (work-tracking not installed?) — skipped`);
+      continue;
+    }
+
+    const existing = fs.readFileSync(target, 'utf8');
+    if (existing.includes(MARKER)) {
+      results.push(`${file}: already has engagement code — skipped`);
+      continue;
+    }
+
+    if (!dryRun) {
+      fs.copyFileSync(source, target);
+    }
+    results.push(`${file}: applied engagement-inclusive version`);
+  }
+
+  return { results };
+}
+
+module.exports = { setupEngagement };

package/package.json

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

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