create-claude-cabinet 0.35.0 → 0.37.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'],
   },
   'compliance': {
     name: 'Compliance Stack (rules + enforcement)',
@@ -602,6 +602,8 @@ const MODULES = {
     requires: ['work-tracking'],
     postInstall: 'engagement-setup',
     templates: [
+      'skills/collab-client',
+      'skills/collab-consultant',
       'skills/engagement',
       'skills/engagement-progress',
       'skills/engagement-help',
@@ -611,6 +613,7 @@ const MODULES = {
       'skills/engagement-add',
       'skills/engagement-status',
       'skills/engagement-sync',
+      '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.35.0",
+  "version": "0.37.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,77 @@
+# 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:
+  data-coherence:
+    paths:
+      - "**/pib-db*.mjs"
+      - "**/*schema*"
+      - "**/*migration*"
+    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:
+      - "**/index.mjs"
+      - "lib/*.js"
+    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."
+
+  knowledge-layer:
+    paths:
+      - "templates/skills/**"
+      - "templates/engagement/**"
+    severity: moderate
+    checks:
+      - tag: review
+        check: "If user-facing behavior or vocabulary changed, check whether app-guide.md needs updating."

package/templates/cabinet/skill-best-practices.md

@@ -40,6 +40,13 @@ slash commands for CC maintenance.
 
 These hold for every SKILL.md regardless of type.
 
+**Runtime output formatting lives in a sibling doc.** This doc covers
+*write-time* authoring. For *runtime* user-facing output — when a running
+skill should present choices via the native `AskUserQuestion` tool versus
+prose versus a markdown table, plus the AskUserQuestion schema facts
+authors must get right — see `skill-output-conventions.md`. Follow that
+pointer whenever a skill prompts the user to make a decision.
+
 ### Body under 500 lines
 
 The SKILL.md **body** — content after the closing `---` of

package/templates/cabinet/skill-output-conventions.md

@@ -0,0 +1,153 @@
+# Skill Output Conventions
+
+How skills format **user-facing output** and **interactive prompts** at
+runtime. The companion to `skill-best-practices.md`.
+
+## 1. Purpose & Scope
+
+`skill-best-practices.md` governs **write-time** authoring rules — file
+structure, naming, frontmatter, length. This doc governs **runtime**
+interaction: how a skill, while executing, presents choices and
+information to the user. `output-contract.md` is a third, separate
+concern — the JSON cabinet members emit during audits, not user-facing
+output.
+
+Stating the boundary keeps the three docs from drifting together: if a
+rule is about *how a SKILL.md is written*, it belongs in
+skill-best-practices; if it's about *what the running skill shows the
+user*, it belongs here.
+
+## 2. When to Use AskUserQuestion
+
+`AskUserQuestion` is the native interactive primitive — a structured
+menu of 2-4 options the user picks from. Use it when **all** of these
+hold:
+
+- The choice is among **discrete options** (not free text).
+- The answer **branches the skill's behavior** (it's a real decision).
+- There are **2-4 mutually-exclusive choices** (or a small set if
+  multiSelect).
+- It is **not an obvious-default confirm** — a yes/no where one answer
+  is plainly expected (see §5).
+- The item count is **bounded and small** — not a variable-length loop
+  (see §4).
+
+If any answer is "no," use prose (§5) or a table (§6) instead.
+
+## 3. Schema Facts Authors Must Get Right
+
+Verified against the live schema. Get these wrong and the call fails or
+behaves unexpectedly.
+
+- **1-4 questions per call; 2-4 options per question.** Outside this
+  range fails validation.
+- **`header` is REQUIRED** — a short chip/tag, **max 12 chars** (e.g.
+  `Branch`, `Verdict`, `Decision`). Omitting it fails validation. This
+  is the most common authoring mistake.
+- **Cost is per-session, not per-call.** AskUserQuestion is a deferred
+  tool: the first use in a session loads its schema (one ToolSearch
+  round-trip, ~200 tokens); every call after that is free. Don't
+  under-use it to "save" a cost that's already paid.
+- **`multiSelect` is required.** `false` for mutually-exclusive choices
+  (the norm — one answer). `true` only when the user may legitimately
+  pick more than one.
+- **"Other" is auto-added** by the harness. Never add an "Other" /
+  "Something else" option manually — it duplicates.
+- **No reliable preview/comparison field.** The official schema has no
+  dependable preview surface; don't build conventions on preview
+  behavior or expect side-by-side rendering.
+- **Unavailable in Task-spawned subagents.** Agents launched via the
+  Task tool (execute-group worktree agents, Workflow agents,
+  `context:fork`) cannot call AskUserQuestion — they must use prose.
+  This warning outlives any current wiring: a skill that runs in the
+  main session today may be called from a subagent tomorrow.
+- **Pre-specify each call site** in the SKILL.md prose — exact `header`,
+  `question`, and option labels/descriptions. In a long skill body the
+  model otherwise drifts to a prose question instead of emitting the
+  structured call. (This is an authoring practice — `skill-best-practices.md`
+  is the write-time home for it — surfaced here because it's what makes a
+  runtime AskUserQuestion call fire reliably.)
+
+## 4. Bounded-List Caveat
+
+AskUserQuestion is for **decisions**, not **batch processing**. A
+variable-length loop of homogeneous items — reviewing 12 copy edits,
+approving 30 line items — should not become 30 sequential dialogs. Past
+~5 items, prefer a single batch path (present all, take one combined
+response) over N prompts. The fatigue of N near-identical dialogs
+outweighs the structure they add.
+
+The test: are these **genuine, distinct decisions** (→ AskUserQuestion,
+one per item up to a small cap) or **homogeneous review items** (→ batch
+path)?
+
+## 5. When to Use Prose
+
+Use plain conversational prose for:
+
+- **Free-text gathering** — names, reasons, descriptions, anything not
+  a fixed menu.
+- **Clarifications and reasons** — "why did you defer this?"
+- **Obvious-default confirms** — a yes/no where one answer is plainly
+  expected and the other is rare. A structured menu over-formalizes it;
+  a prose "Want me to X? (I'll skip if not)" is lighter.
+
+## 6. When to Use Markdown Tables
+
+Use a table for **rosters, status, or any data with ≥2 columns** —
+where the value is in *comparing rows*, not *choosing one*. The `/menu`
+skill (skills × description) and `/cabinet` (member × domain) are
+canonical examples. A table presents; AskUserQuestion decides. Don't use
+a table to offer a choice, and don't use AskUserQuestion to display a
+list the user isn't picking from.
+
+## 7. Option-Block Format
+
+When presenting options as prose (subagent context, or >4 options), the
+canonical format is in `templates/skills/onboard/phases/options.md` —
+name, "what it is," "good for," "trade-off" per option. Do not duplicate
+that format here; reference it.
+
+## 8. Section Structure & Tone
+
+`options.md` is also canonical for tone: **present, don't prescribe.**
+"Here are your options" not "I recommend X." Ground choices in the
+user's actual situation. This applies whether the choice is rendered via
+AskUserQuestion or prose — the primitive changes, the posture doesn't.
+
+## 9. Calibration Examples
+
+**Before/after — engagement decision items** (the Tier 1 conversion):
+
+> Before: "Present the options conversationally and let the client
+> choose."
+> After: For each decision item, one AskUserQuestion call — `header:
+> "Decision"`, `question:` the item's client-facing prompt, `options:`
+> the item's own authored option list, `multiSelect: false`. One call
+> per item; never batched.
+
+Why: the items already carry discrete, consultant-authored options, and
+this is the consultant↔client boundary where ambiguity is most expensive
+and the client can't ask for real-time clarification.
+
+**Before/after — triage-audit fallback verdict:**
+
+> Before: a prose prompt listing "Fix / Defer / Reject / Question" and
+> asking the user to type one.
+> After: AskUserQuestion — `header: "Verdict"`, four options, one per
+> finding, `multiSelect: false`.
+
+Why: four discrete mutually-exclusive verdicts that branch behavior —
+this scores well on all five §2 criteria.
+
+**EXCLUDED — orient registry-orphan prompt** (do NOT convert):
+
+> "Your old project 'deal-v1' seems to have been deleted — want me to
+> remove it from the registry?"
+
+This looks like a Remove/Keep choice but is an **obvious-default
+confirm**: the path no longer exists, so removal is plainly expected and
+"keep" is the rare exception. A structured two-option menu over-formalizes
+a routine yes/no. Leave it prose. This is the boundary that stops
+AskUserQuestion from being applied to every binary question in the
+codebase.