create-claude-cabinet 0.36.0 → 0.38.0

package/lib/cli.js

@@ -486,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-implement.js', 'workflows/execute-group-complete.js', 'skills/investigate', 'cabinet/checkpoint-protocol.md'],
+    templates: ['skills/plan', 'skills/execute', 'skills/execute/phases/post-impl-checklist.md', 'skills/debrief/phases/checklist-feedback.md', 'skills/checklist-discover', 'skills/generate-plan-groups', 'skills/execute-group', 'workflows/execute-group-implement.js', 'workflows/execute-group-complete.js', 'skills/investigate', 'cabinet/checkpoint-protocol.md', 'cabinet/qa-dimensions-template.yaml', 'scripts/qa-dimensions-validator.cjs', 'skills/orient/phases/checklist-status.md'],
   },
   'compliance': {
     name: 'Compliance Stack (rules + enforcement)',
@@ -595,13 +595,15 @@ const MODULES = {
   },
   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).',
+    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). Three primary skills across consultant and client sides, plus redirect stubs. Requires work-tracking (the pib-db adapter is the engine\'s data source).',
     mandatory: false,
     default: false,
     lean: false,
     requires: ['work-tracking'],
     postInstall: 'engagement-setup',
     templates: [
+      'skills/collab-client',
+      'skills/collab-consultant',
       'skills/engagement',
       'skills/engagement-progress',
       'skills/engagement-help',
@@ -611,6 +613,8 @@ const MODULES = {
       'skills/engagement-add',
       'skills/engagement-status',
       'skills/engagement-sync',
+      'skills/setup-accounts',
+      'skills/guide',
       'engagement',
     ],
   },

package/lib/engagement-setup.js

@@ -5,11 +5,16 @@
  * Dispatched from cli.js's postInstall pipeline. Two responsibilities:
  *
  * 1. FILE OVERLAY — copy the engagement-inclusive pib-db files over the
- *    base versions. Uses a version-aware check: parse SCHEMA_VERSION from
- *    the installed file and re-copy when below the patch's version. This
- *    replaces the old string-marker approach, which was version-blind and
- *    silently skipped upgrades (e.g., v5→v6 never landed because the v5
- *    marker already matched).
+ *    base versions. For pib-db-lib.mjs, the decision is marker-aware:
+ *    we check whether the installed file already contains engagement code
+ *    (not just its SCHEMA_VERSION number). This handles three cases:
+ *      a. Installed file has engagement code + version >= patch → skip
+ *      b. Installed file lacks engagement code + version <= patch → copy
+ *      c. Installed file lacks engagement code + version > patch → BASE
+ *         AHEAD: the base work-tracking module advanced past the patch
+ *         without a coordinated engagement patch bump. Copying stale
+ *         patch code over a newer base would drop base migrations.
+ *         Emit a warning and skip both overlay and schema-ensure.
  *
  * 2. SCHEMA ENSURE — after the overlay, open pib.db and call migrate()
  *    so existing DBs advance to the patch's schema version. Also runs an
@@ -18,8 +23,19 @@
  *    engagement — the v5 migration entry is gated out, so this direct
  *    exec is the only path to creating the table).
  *
- * The base pib-db templates (owned by work-tracking) ship schema v1-v5.
- * The engagement patch ships v1-v6 (v5=engagement_events, v6=projects.tags).
+ * SCHEMA VERSIONING COORDINATION RULES:
+ *   - The engagement patch's SCHEMA_VERSION must always be >= the base
+ *     work-tracking SCHEMA_VERSION (the patch is a superset).
+ *   - When base advances, the patch must advance in the same CC release.
+ *   - Migrations shared by both base and patch use column-existence
+ *     checks or IF NOT EXISTS to be idempotent.
+ *   - A base-ahead state (base version > patch version) is an error
+ *     indicating an uncoordinated upgrade. The overlay refuses to copy
+ *     and skips schema-ensure to avoid mismatched lib/DB state.
+ *
+ * The base pib-db templates (owned by work-tracking) ship schema v1-v6.
+ * The engagement patch ships v1-v8 (v5=engagement_events, v6=projects.tags,
+ * v7=client-facing copy columns, v8=engagement_events.visibility).
  */
 
 const fs = require('fs');
@@ -27,12 +43,17 @@ const path = require('path');
 
 const FILES = ['pib-db-lib.mjs', 'pib-db-mcp-server.mjs', 'pib-db-schema.sql', 'pib-db.mjs'];
 const VERSION_RE = /export const SCHEMA_VERSION\s*=\s*(\d+)/;
+const ENGAGEMENT_MARKER_RE = /engagement_events/;
 
 function parseSchemaVersion(content) {
   const m = content.match(VERSION_RE);
   return m ? parseInt(m[1], 10) : 0;
 }
 
+function hasEngagementCode(content) {
+  return ENGAGEMENT_MARKER_RE.test(content);
+}
+
 function setupEngagement({ dryRun, projectDir } = {}) {
   const results = [];
   const scriptsDir = path.join(projectDir, 'scripts');
@@ -43,7 +64,7 @@ function setupEngagement({ dryRun, projectDir } = {}) {
     return { results };
   }
 
-  // --- Step 1: File overlay (version-aware) ---
+  // --- Step 1: File overlay (marker-aware for pib-db-lib.mjs) ---
 
   const patchLibPath = path.join(patchDir, 'pib-db-lib.mjs');
   let patchVersion = 0;
@@ -52,6 +73,7 @@ function setupEngagement({ dryRun, projectDir } = {}) {
   }
 
   let filesUpdated = false;
+  let baseAhead = false;
   for (const file of FILES) {
     const target = path.join(scriptsDir, file);
     const source = path.join(patchDir, file);
@@ -67,9 +89,22 @@ function setupEngagement({ dryRun, projectDir } = {}) {
     }
 
     if (file === 'pib-db-lib.mjs') {
-      const installedVersion = parseSchemaVersion(fs.readFileSync(target, 'utf8'));
-      if (installedVersion >= patchVersion) {
-        results.push(`${file}: schema v${installedVersion} >= patch v${patchVersion} — skipped`);
+      const installedContent = fs.readFileSync(target, 'utf8');
+      const installedVersion = parseSchemaVersion(installedContent);
+      const isEngagementInclusive = hasEngagementCode(installedContent);
+
+      if (isEngagementInclusive && installedVersion >= patchVersion) {
+        results.push(`${file}: engagement-inclusive v${installedVersion} >= patch v${patchVersion} — skipped`);
+        continue;
+      }
+
+      if (!isEngagementInclusive && installedVersion > patchVersion) {
+        baseAhead = true;
+        results.push(
+          `${file}: BASE AHEAD — installed base v${installedVersion} > patch v${patchVersion}. ` +
+          `The engagement patch must be updated to match. Overlay skipped to avoid dropping base migrations. ` +
+          `Fix: bump the engagement patch SCHEMA_VERSION to >= ${installedVersion} in the same CC release.`
+        );
         continue;
       }
     } else {
@@ -89,6 +124,13 @@ function setupEngagement({ dryRun, projectDir } = {}) {
   }
 
   // --- Step 2: Schema ensure (migrate + idempotent engagement_events) ---
+  // Skipped entirely when base-ahead is detected — running migrations
+  // against a mismatched library/DB pair would under-migrate the DB.
+
+  if (baseAhead) {
+    results.push('schema-ensure: skipped — base-ahead state detected (see overlay warning above)');
+    return { results };
+  }
 
   const dbPath = path.join(projectDir, 'pib.db');
   if (!dryRun && fs.existsSync(dbPath) && fs.existsSync(path.join(scriptsDir, 'pib-db-lib.mjs'))) {
@@ -122,6 +164,12 @@ function setupEngagement({ dryRun, projectDir } = {}) {
       // later adds engagement. Their v5 migration entry (engagement_events)
       // is gated out by user_version, and the execSync migrate above won't
       // create it either. This direct exec is the only path.
+      //
+      // SOURCE OF TRUTH: templates/engagement/sql-constants.mjs
+      // This inline copy exists because engagement-setup.js is CJS and
+      // can't import() ESM synchronously. The drift-guard test
+      // (test/pib-db-engagement/sql-constants-drift.test.js) verifies
+      // this stays in sync with sql-constants.mjs.
       try {
         db.exec(`CREATE TABLE IF NOT EXISTS engagement_events (
           id            INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -133,6 +181,7 @@ function setupEngagement({ dryRun, projectDir } = {}) {
           author        TEXT NOT NULL,
           verdict       TEXT CHECK(verdict IS NULL OR verdict IN ('approve','object','comment','none')),
           body          TEXT CHECK(body IS NULL OR length(body) <= 10000),
+          visibility    TEXT NOT NULL DEFAULT 'internal' CHECK(visibility IN ('client','internal')),
           addressed     INTEGER NOT NULL DEFAULT 0 CHECK(addressed IN (0,1)),
           created_at    TEXT NOT NULL CHECK(created_at GLOB '????-??-??T*'),
           CHECK(kind NOT IN ('client_feedback','approval')
@@ -141,10 +190,69 @@ function setupEngagement({ dryRun, projectDir } = {}) {
         db.exec("CREATE INDEX IF NOT EXISTS idx_engagement_events_eng ON engagement_events(engagement, created_at DESC)");
         db.exec("CREATE INDEX IF NOT EXISTS idx_engagement_events_tgt ON engagement_events(target_fid, created_at DESC)");
         db.exec("CREATE INDEX IF NOT EXISTS idx_engagement_events_dedup ON engagement_events(packet_id, target_fid, verdict)");
+        // Defensive idempotent ALTER: an engagement_events table created by a
+        // prior install (before the visibility column existed) won't get the
+        // column from CREATE IF NOT EXISTS. Add it here; swallow "duplicate
+        // column" when it's already present.
+        try {
+          db.exec("ALTER TABLE engagement_events ADD COLUMN visibility TEXT NOT NULL DEFAULT 'internal' CHECK(visibility IN ('client','internal'))");
+        } catch (e) {
+          if (!/duplicate column/i.test(e.message || '')) throw e;
+        }
         results.push('schema-ensure: engagement_events table ensured (idempotent)');
       } catch (e) {
         results.push(`schema-ensure: engagement_events ensure failed — ${e.message}`);
       }
+
+      // Data migration — extract client-facing copy from notes into columns.
+      // Idempotent: skips rows where any client column is already populated.
+      // Uses synchronous DB operations (better-sqlite3) so no async needed.
+      try {
+        const hasClientCols = db.prepare("PRAGMA table_info(actions)").all()
+          .some(c => c.name === 'client_title');
+        if (hasClientCols) {
+          const actionRows = db.prepare(
+            "SELECT fid, notes FROM actions WHERE notes LIKE '%client-facing%' AND client_title IS NULL AND client_body IS NULL AND client_generated_at IS NULL"
+          ).all();
+          const projRows = db.prepare(
+            "SELECT fid, notes FROM projects WHERE notes LIKE '%client-facing%' AND client_title IS NULL AND client_body IS NULL AND client_generated_at IS NULL"
+          ).all();
+
+          const copyRe = /<!--\s*client-facing\s*\n([\s\S]*?)-->/;
+          const genRe = /<!--\s*cc-generated:(\S+)\s+status:(\S+)\s*-->/;
+          const updateA = db.prepare("UPDATE actions SET client_title = ?, client_body = ?, client_generated_at = ?, client_generated_status = ? WHERE fid = ?");
+          const updateP = db.prepare("UPDATE projects SET client_title = ?, client_body = ?, client_generated_at = ?, client_generated_status = ? WHERE fid = ?");
+
+          let migrated = 0;
+          for (const { fid, notes } of [...actionRows, ...projRows]) {
+            if (!notes) continue;
+            const copyMatch = notes.match(copyRe);
+            const genMatch = notes.match(genRe);
+            if (!copyMatch && !genMatch) continue;
+
+            let title = null, body = null, genAt = null, genStatus = null;
+            if (copyMatch) {
+              const lines = copyMatch[1].split('\n').map(l => l.trim()).filter(Boolean);
+              title = lines[0] || null;
+              body = lines.slice(1).join('\n').trim() || null;
+            }
+            if (genMatch) {
+              genAt = genMatch[1] || null;
+              genStatus = genMatch[2] || null;
+            }
+
+            const stmt = actionRows.some(r => r.fid === fid) ? updateA : updateP;
+            stmt.run(title, body, genAt, genStatus, fid);
+            migrated++;
+          }
+          if (migrated > 0) {
+            results.push(`data-migration: migrated client-facing copy for ${migrated} row(s)`);
+          }
+        }
+      } catch (e) {
+        results.push(`data-migration: client copy migration failed — ${e.message}`);
+      }
+
       db.close();
     } catch (e) {
       if (/Cannot find module|MODULE_NOT_FOUND/.test(e.message || '')) {

package/package.json

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

package/templates/cabinet/qa-dimensions-template.yaml

@@ -0,0 +1,103 @@
+# Change-Impact QA Dimensions — starter template.
+#
+# To ACTIVATE the change-impact checklist, copy this file to:
+#   .claude/cabinet/qa-dimensions.yaml
+# and customize the dimensions for your project. The /execute
+# post-impl-checklist phase looks for `qa-dimensions.yaml` (no
+# `-template` suffix) and stays silent until that file exists.
+#
+# How it works: after implementation, the phase reads the git diff,
+# matches each changed file against every dimension's `paths` globs,
+# and surfaces the matched dimensions' checks as context for the
+# pre-commit cabinet sweep (Checkpoint 3). QA is the primary consumer.
+#
+# ── Schema ────────────────────────────────────────────────────────
+# dimensions:                  # top-level map; keys are dimension names
+#   <dimension-name>:
+#     paths:                   # list of glob patterns (REQUIRED, >=1)
+#       - "glob/pattern/**"
+#     severity: high           # high | moderate | info (REQUIRED)
+#     checks:                  # list of checks (REQUIRED, >=1)
+#       - tag: run            # run | review
+#         check: "text"        # what to verify
+#
+# ── Glob matching rules (canonical — the phase follows these) ───────
+#   * A leading "./" is stripped from both pattern and path before
+#     matching. Diff paths are repo-relative with no "./".
+#   * "*" matches within ONE path segment (no "/"). "src/api/*"
+#     matches "src/api/foo.js" but NOT "src/api/v2/foo.js".
+#   * "**" matches across segments (subtree). "src/api/**" matches
+#     "src/api/foo.js" AND "src/api/v2/foo.js".
+#   * A trailing "/" means "this directory and below": "src/api/" is
+#     treated as "src/api/**".
+#   * A bare extension glob like "*.md" is UNROOTED — it matches that
+#     extension at any depth. For root-only, use an explicit prefix:
+#     "README.md" or "docs/*.md" instead of bare "*.md".
+#
+# ── severity meanings ───────────────────────────────────────────────
+#   high     — a miss here ships a real bug; sweep should treat as blocking
+#   moderate — worth checking; sweep treats as advisory
+#   info     — reminder/nudge; never blocking
+#
+# The examples below are illustrative. Delete or replace them.
+
+dimensions:
+  # ── Replace the example paths below with your project's real paths. ──
+  # The dimension *concepts* are broadly useful; the glob patterns are
+  # placeholders. Run /checklist-discover to auto-detect your project's
+  # paths and generate a tailored qa-dimensions.yaml.
+
+  data-coherence:
+    paths:
+      - "**/*schema*"
+      - "**/*migration*"
+      - "**/*.sql"
+      - "**/models/**"
+    severity: high
+    checks:
+      - tag: run
+        check: "Run schema validation if any schema or migration file changed."
+      - tag: review
+        check: "Verify referential integrity for any new foreign keys or cross-store references."
+      - tag: review
+        check: "Confirm any migration handles existing rows, not just fresh installs."
+
+  api-drift:
+    paths:
+      - "**/routes*"
+      - "**/api/**"
+      - "src/**"
+      - "**/index.mjs"
+    severity: high
+    checks:
+      - tag: run
+        check: "Grep the changed files for exported symbols; confirm the public surface is intentional."
+      - tag: review
+        check: "Check downstream consumers of any changed or removed export."
+
+  test-staleness:
+    paths:
+      - "**/test*/**"
+      - "**/*.test.*"
+      - "**/*.spec.*"
+      - "**/factories/**"
+      - "**/fixtures/**"
+    severity: high
+    checks:
+      - tag: run
+        check: "Run the test suite if any test, factory, or fixture file changed."
+      - tag: review
+        check: "If a model's validations or associations changed, verify factories still produce valid records."
+      - tag: review
+        check: "If behavior changed, check whether existing specs assert on the old behavior."
+
+  knowledge-layer:
+    paths:
+      - "**/docs/**"
+      - "**/*guide*"
+      - "**/README*"
+      - "**/CHANGELOG*"
+    severity: moderate
+    checks:
+      - tag: review
+        check: "If user-facing behavior or vocabulary changed, check whether docs or guides need updating."