create-claude-cabinet 0.14.2 → 0.15.0

package/lib/cli.js

@@ -252,6 +252,9 @@ function generateSkillIndex(projectDir) {
       type: isCabinet ? 'cabinet' : 'workflow',
     };
 
+    // Argument hint (for skill index consumers)
+    if (fm['argument-hint']) entry.argumentHint = fm['argument-hint'];
+
     // Invocability flags
     if (fm['disable-model-invocation'] === 'true') entry.manual = true;
     if (fm['user-invocable'] === 'false') entry.userInvocable = false;
@@ -353,7 +356,7 @@ const MODULES = {
     mandatory: false,
     default: true,
     lean: true,
-    templates: ['hooks/git-guardrails.sh', 'hooks/cc-upstream-guard.sh', 'hooks/skill-telemetry.sh', 'hooks/skill-tool-telemetry.sh', 'scripts/cc-drift-check.cjs'],
+    templates: ['hooks/git-guardrails.sh', 'hooks/cc-upstream-guard.sh', 'hooks/skill-telemetry.sh', 'hooks/skill-tool-telemetry.sh', 'hooks/compaction-save.md', 'hooks/compaction-recover.sh', 'scripts/cc-drift-check.cjs'],
   },
   'work-tracking': {
     name: 'Work Tracking (pib-db or markdown)',
@@ -361,7 +364,7 @@ const MODULES = {
     mandatory: false,
     default: true,
     lean: false,
-    templates: ['scripts/pib-db.mjs', 'scripts/pib-db-schema.sql', 'scripts/work-tracker-server.mjs', 'scripts/work-tracker-ui.html', 'skills/work-tracker'],
+    templates: ['scripts/pib-db.mjs', 'scripts/pib-db-lib.mjs', 'scripts/pib-db-mcp-server.mjs', 'scripts/pib-db-schema.sql', 'scripts/work-tracker-server.mjs', 'scripts/work-tracker-ui.html', 'skills/work-tracker'],
     needsDb: true,
   },
   'planning': {
@@ -391,7 +394,8 @@ const MODULES = {
       'cabinet', 'briefing',
       'skills/cabinet-accessibility', 'skills/cabinet-anti-confirmation',
       'skills/cabinet-architecture', 'skills/cabinet-boundary-man',
-      'skills/cabinet-cc-health', 'skills/cabinet-data-integrity',
+      'skills/cabinet-anthropic-insider', 'skills/cabinet-cc-health',
+      'skills/cabinet-data-integrity',
       'skills/cabinet-debugger', 'skills/cabinet-historian',
       'skills/cabinet-organized-mind', 'skills/cabinet-process-therapist',
       'skills/cabinet-qa', 'skills/cabinet-record-keeper',
@@ -891,6 +895,27 @@ async function run() {
     console.log(`  ⚙️  Merged hooks into ${path.relative(projectDir, settingsPath)}`);
   }
 
+  // --- Merge pib-db MCP server into .mcp.json ---
+  if (selectedModules.includes('work-tracking') && !flags.dryRun) {
+    try {
+      const mcpTemplatePath = path.join(templateRoot, 'mcp', 'pib-db.json');
+      if (fs.existsSync(mcpTemplatePath)) {
+        const mcpConfig = JSON.parse(fs.readFileSync(mcpTemplatePath, 'utf8'));
+        const mcpJsonPath = path.join(projectDir, '.mcp.json');
+        let existing = {};
+        if (fs.existsSync(mcpJsonPath)) {
+          existing = JSON.parse(fs.readFileSync(mcpJsonPath, 'utf8'));
+        }
+        if (!existing.mcpServers) existing.mcpServers = {};
+        Object.assign(existing.mcpServers, mcpConfig.mcpServers);
+        fs.writeFileSync(mcpJsonPath, JSON.stringify(existing, null, 2) + '\n');
+        console.log(`  🔌 Merged pib-db MCP server into .mcp.json`);
+      }
+    } catch (err) {
+      console.log(`  ⚠ MCP config merge failed: ${err.message}`);
+    }
+  }
+
   // --- Set up database ---
   if (includeDb && selectedModules.includes('work-tracking') && !flags.dryRun) {
     try {

package/lib/settings-merge.js

@@ -15,6 +15,19 @@ const MEMORY_HOOKS = {
   ],
 };
 
+// Prompt text for the PreCompact hook. Source of truth: templates/hooks/compaction-save.md
+const COMPACTION_SAVE_PROMPT = `Before compaction destroys your current context, you MUST save state so the next session can recover.
+
+REQUIRED — Always write .claude/compaction-state.md with these sections:
+- Current Task: what you were actively working on (file paths, function names, exact step)
+- Decisions Made: key decisions with reasoning
+- Next Steps: ordered list, most urgent first
+- References: files, URLs, error messages needed by next context
+
+CONDITIONAL — If mid-workflow with intermediate results, ALSO write .claude/<workflow-name>-partial.md (e.g. .claude/audit-partial.md for a mid-audit). Include completed items, partial results, progress tracking.
+
+Keep total output under 200 lines. Use concrete details, not vague summaries. Write the files now.`;
+
 const DEFAULT_HOOKS = {
   PreToolUse: [
     {
@@ -58,6 +71,27 @@ const DEFAULT_HOOKS = {
       ],
     },
   ],
+  PreCompact: [
+    {
+      hooks: [
+        {
+          type: 'prompt',
+          prompt: COMPACTION_SAVE_PROMPT,
+        },
+      ],
+    },
+  ],
+  SessionStart: [
+    {
+      matcher: 'compact',
+      hooks: [
+        {
+          type: 'command',
+          command: '.claude/hooks/compaction-recover.sh',
+        },
+      ],
+    },
+  ],
 };
 
 /**
@@ -112,14 +146,15 @@ function mergeSettings(projectDir, { includeDb = true, includeMemory = false } =
     if (!settings.hooks[event]) {
       settings.hooks[event] = newHooks;
     } else {
-      // Add hooks that don't already exist (check by command path)
+      // Add hooks that don't already exist (check by command path or prompt text)
       for (const newHook of newHooks) {
-        const existingCommands = settings.hooks[event].flatMap(h =>
-          h.hooks.map(hh => hh.command)
+        const hookKey = h => h.command || h.prompt || '';
+        const existingKeys = settings.hooks[event].flatMap(h =>
+          h.hooks.map(hh => hookKey(hh))
         );
-        const newCommands = newHook.hooks.map(h => h.command);
-        const alreadyExists = newCommands.every(cmd =>
-          existingCommands.includes(cmd)
+        const newKeys = newHook.hooks.map(h => hookKey(h));
+        const alreadyExists = newKeys.every(k =>
+          existingKeys.includes(k)
         );
         if (!alreadyExists) {
           settings.hooks[event].push(newHook);

package/package.json

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

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

@@ -0,0 +1,56 @@
+# pib-db Access Protocol
+
+How to interact with the process infrastructure database (pib-db).
+
+## Preference Order
+
+1. **MCP tools (preferred):** If `pib_*` MCP tools are available (check
+   by attempting to use them), use them directly. They return structured
+   JSON — no parsing needed.
+
+2. **CLI fallback:** If MCP tools are not available, use the CLI:
+   ```bash
+   node scripts/pib-db.mjs <command> [args]
+   ```
+
+Skills should reference this document instead of embedding their own
+fallback logic. The access method is determined once at the start of the
+skill execution:
+
+```
+Check: are pib_* MCP tools available?
+  YES → use pib_list_projects, pib_create_action, etc.
+  NO  → use node scripts/pib-db.mjs list-projects, etc.
+```
+
+## Available Operations
+
+| MCP Tool               | CLI Equivalent                          | Description                    |
+| ---------------------- | --------------------------------------- | ------------------------------ |
+| pib_create_project     | create-project "name" --area X          | Create a project               |
+| pib_list_projects      | list-projects                           | List active projects           |
+| pib_create_action      | create-action "text" --notes X          | Create an action (work item)   |
+| pib_list_actions       | list-actions [--status X]               | List actions                   |
+| pib_update_action      | update-action fid --status X            | Update action fields           |
+| pib_complete_action    | complete-action fid                     | Mark action done               |
+| 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           |
+| pib_query              | query "SQL"                             | Run arbitrary SQL              |
+
+## Surface Area Validation
+
+`pib_create_action` (and the CLI `create-action`) require that notes
+contain a `## Surface Area` section with at least one `- files:` or
+`- dirs:` line. This ensures every action clearly defines what it
+touches.
+
+Example notes format:
+```
+Implement the new feature.
+
+## Surface Area
+- files: src/components/Widget.js
+- files: src/utils/helpers.js
+- dirs: tests/components/
+```

package/templates/hooks/compaction-recover.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+# Compaction Recovery — SessionStart command hook (compact matcher)
+#
+# Reads compaction state files written by the PreCompact prompt hook
+# and outputs them to stdout for injection as additionalContext.
+#
+# Files checked:
+#   .claude/compaction-state.md  — always (main state)
+#   .claude/*-partial.md         — any workflow partial state files
+
+PROJECT_DIR="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+STATE_FILE="$PROJECT_DIR/.claude/compaction-state.md"
+
+# Collect all partial state files
+PARTIAL_FILES=()
+for f in "$PROJECT_DIR"/.claude/*-partial.md; do
+  [ -f "$f" ] && PARTIAL_FILES+=("$f")
+done
+
+# If no state files exist, output fallback message
+if [ ! -f "$STATE_FILE" ] && [ ${#PARTIAL_FILES[@]} -eq 0 ]; then
+  echo "No compaction state found. This session started fresh (no prior compaction state to recover)."
+  exit 0
+fi
+
+echo "=== COMPACTION RECOVERY ==="
+echo ""
+echo "State was saved before compaction. Use this to resume where you left off."
+echo ""
+
+# Output main state file
+if [ -f "$STATE_FILE" ]; then
+  echo "--- compaction-state.md ---"
+  cat "$STATE_FILE"
+  echo ""
+fi
+
+# Output any partial state files
+for f in "${PARTIAL_FILES[@]}"; do
+  BASENAME=$(basename "$f")
+  echo "--- $BASENAME ---"
+  cat "$f"
+  echo ""
+done
+
+echo "=== END COMPACTION RECOVERY ==="

package/templates/hooks/compaction-save.md

@@ -0,0 +1,46 @@
+# Compaction State Save — PreCompact Prompt Hook
+
+Before compaction destroys your current context, you MUST save state so the
+next session can recover. This is not optional — compaction erases everything
+you're holding in working memory.
+
+## Required: Always write .claude/compaction-state.md
+
+Write this file with these structured sections:
+
+```
+# Compaction State
+
+## Current Task
+What you were actively working on. Be specific — include file paths, function
+names, the exact step you were on.
+
+## Decisions Made
+Key decisions from this session that a fresh context needs to know.
+Include the reasoning, not just the conclusion.
+
+## Next Steps
+What should happen immediately after recovery. Ordered list, most urgent first.
+
+## References
+Files, URLs, error messages, or other artifacts that the next context will need.
+```
+
+## Conditional: Write workflow-specific partial state
+
+If you are in the middle of a multi-step workflow with intermediate results,
+ALSO write a partial state file to `.claude/<workflow-name>-partial.md`.
+
+Use the workflow you're currently executing as the filename. Examples:
+- Mid-audit with findings collected so far → `.claude/audit-partial.md`
+- Mid-migration with some files moved → `.claude/migration-partial.md`
+- Mid-refactor tracking what's done → `.claude/refactor-partial.md`
+
+Include whatever intermediate work products would be lost to compaction:
+completed items, partial results, progress tracking, error logs.
+
+## Constraints
+
+- Keep total output under 200 lines across all files written.
+- Use concrete details (file paths, line numbers, variable names), not vague summaries.
+- Write the files using the Edit/Write tools — do not just describe what you would write.

package/templates/mcp/pib-db.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "pib-db": {
+      "command": "node",
+      "args": ["scripts/pib-db-mcp-server.mjs"],
+      "env": {
+        "PIB_DB_PATH": "./pib.db"
+      }
+    }
+  }
+}

package/templates/scripts/pib-db-lib.mjs

@@ -0,0 +1,281 @@
+// Process-in-a-Box shared library
+//
+// All database operations as importable functions.
+// Both the CLI (pib-db.mjs) and MCP server (pib-db-mcp-server.mjs)
+// import from here. Schema changes update one place.
+//
+// Every function takes (db, params) and returns a result object.
+// None of them do console.log — callers decide how to present output.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function generateFid(prefix) {
+  return `${prefix}:${randomUUID().replace(/-/g, '').slice(0, 8)}`;
+}
+
+function today() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+// ---------------------------------------------------------------------------
+// Init — create tables from schema
+// ---------------------------------------------------------------------------
+export function init(db, { schemaPath }) {
+  const schema = readFileSync(schemaPath, 'utf-8');
+  db.exec(schema);
+
+  // Migrate existing DBs — add columns that may not exist yet
+  const migrations = [
+    { table: 'actions', column: 'status', sql: "ALTER TABLE actions ADD COLUMN status TEXT NOT NULL DEFAULT 'open' CHECK(status IN ('open','in-progress','blocked','deferred','done'))" },
+    { table: 'actions', column: 'tags', sql: "ALTER TABLE actions ADD COLUMN tags TEXT NOT NULL DEFAULT ''" },
+  ];
+  for (const m of migrations) {
+    const cols = db.prepare(`PRAGMA table_info(${m.table})`).all();
+    if (!cols.some(c => c.name === m.column)) {
+      try { db.exec(m.sql); } catch { /* column may already exist */ }
+    }
+  }
+
+  return { message: `Database initialized` };
+}
+
+// ---------------------------------------------------------------------------
+// Query — run arbitrary SQL
+// ---------------------------------------------------------------------------
+export function query(db, { sql }) {
+  if (sql.trim().toUpperCase().startsWith('SELECT')) {
+    const rows = db.prepare(sql).all();
+    return { rows };
+  } else {
+    db.exec(sql);
+    return { message: 'Done.' };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Actions
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate that notes contain a ## Surface Area section with at least one
+ * - files: or - dirs: line. Returns null if valid, or an error object if not.
+ */
+function validateSurfaceArea(notes) {
+  if (!notes) {
+    return {
+      error: 'missing_surface_area',
+      message: 'Action notes must contain a ## Surface Area section.',
+      suggestedFormat: [
+        '## Surface Area',
+        '- files: path/to/file.js',
+        '- files: path/to/other.js',
+        '- dirs: src/components/',
+      ].join('\n'),
+    };
+  }
+
+  const hasSection = /^## Surface Area/m.test(notes);
+  if (!hasSection) {
+    return {
+      error: 'missing_surface_area',
+      message: 'Action notes must contain a ## Surface Area section.',
+      suggestedFormat: [
+        '## Surface Area',
+        '- files: path/to/file.js',
+        '- files: path/to/other.js',
+        '- dirs: src/components/',
+      ].join('\n'),
+    };
+  }
+
+  // Extract everything after ## Surface Area until the next ## or end
+  const sectionMatch = notes.match(/^## Surface Area\s*\n([\s\S]*?)(?=\n## |\n*$)/m);
+  const sectionBody = sectionMatch ? sectionMatch[1] : '';
+  const hasEntry = /^- (?:files|dirs):/m.test(sectionBody);
+  if (!hasEntry) {
+    return {
+      error: 'empty_surface_area',
+      message: '## Surface Area section must contain at least one "- files:" or "- dirs:" line.',
+      suggestedFormat: [
+        '## Surface Area',
+        '- files: path/to/file.js',
+        '- dirs: src/components/',
+      ].join('\n'),
+    };
+  }
+
+  return null; // valid
+}
+
+export function createAction(db, { text, area, projectFid, due, notes }) {
+  const validationError = validateSurfaceArea(notes);
+  if (validationError) {
+    return { error: validationError };
+  }
+
+  const fid = generateFid('act');
+  db.prepare(`
+    INSERT INTO actions (fid, text, area, project_fid, due, notes, created)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+  `).run(fid, text, area || null, projectFid || null, due || null, notes || '', today());
+  return { fid, text, message: `Created action ${fid}: ${text}` };
+}
+
+export function listActions(db, { status, project } = {}) {
+  const conditions = ['a.deleted_at IS NULL'];
+  const params = [];
+
+  if (status) {
+    conditions.push('a.status = ?');
+    params.push(status);
+  } else {
+    conditions.push('a.completed = 0');
+  }
+  if (project) {
+    conditions.push('a.project_fid = ?');
+    params.push(project);
+  }
+
+  const rows = db.prepare(`
+    SELECT a.fid, a.text, a.area, a.due, a.flagged, a.status, a.tags, p.name as project
+    FROM actions a
+    LEFT JOIN projects p ON a.project_fid = p.fid
+    WHERE ${conditions.join(' AND ')}
+    ORDER BY
+      CASE WHEN a.due IS NOT NULL AND a.due <= date('now') THEN 0 ELSE 1 END,
+      a.due,
+      a.flagged DESC,
+      a.created DESC
+  `).all(...params);
+  return { rows };
+}
+
+export function updateAction(db, { fid, status, text, tags, notes, due, flagged }) {
+  const sets = [];
+  const params = [];
+
+  if (status !== undefined) { sets.push('status = ?'); params.push(status); }
+  if (text !== undefined) { sets.push('text = ?'); params.push(text); }
+  if (tags !== undefined) { sets.push('tags = ?'); params.push(tags); }
+  if (notes !== undefined) { sets.push('notes = ?'); params.push(notes); }
+  if (due !== undefined) { sets.push('due = ?'); params.push(due); }
+  if (flagged !== undefined) { sets.push('flagged = ?'); params.push(flagged === 'true' || flagged === '1' || flagged === true ? 1 : 0); }
+
+  // If marking done, also set completed fields
+  if (status === 'done') {
+    sets.push('completed = 1', 'completed_at = ?');
+    params.push(new Date().toISOString());
+  }
+
+  if (sets.length === 0) {
+    return { error: { message: 'No fields to update. Use status, text, tags, notes, due, or flagged.' } };
+  }
+
+  params.push(fid);
+  db.prepare(`UPDATE actions SET ${sets.join(', ')} WHERE fid = ?`).run(...params);
+  return { fid, message: `Updated ${fid}` };
+}
+
+export function completeAction(db, { fid }) {
+  db.prepare(`
+    UPDATE actions SET completed = 1, completed_at = ?, status = 'done' WHERE fid = ?
+  `).run(new Date().toISOString(), fid);
+  return { fid, message: `Completed ${fid}` };
+}
+
+// ---------------------------------------------------------------------------
+// Projects
+// ---------------------------------------------------------------------------
+export function createProject(db, { name, area, notes, due }) {
+  const fid = generateFid('prj');
+  db.prepare(`
+    INSERT INTO projects (fid, name, area, notes, due, created)
+    VALUES (?, ?, ?, ?, ?, ?)
+  `).run(fid, name, area || null, notes || '', due || null, today());
+  return { fid, name, message: `Created project ${fid}: ${name}` };
+}
+
+export function listProjects(db) {
+  const rows = db.prepare(`
+    SELECT p.fid, p.name, p.area, p.status, p.due,
+      (SELECT COUNT(*) FROM actions a WHERE a.project_fid = p.fid AND a.completed = 0 AND a.deleted_at IS NULL) as open_actions
+    FROM projects p
+    WHERE p.status = 'active' AND p.deleted_at IS NULL
+    ORDER BY p.created DESC
+  `).all();
+  return { rows };
+}
+
+// ---------------------------------------------------------------------------
+// Audit — ingest findings from a run directory
+// ---------------------------------------------------------------------------
+export function ingestFindings(db, { runDir }) {
+  const summaryPath = join(runDir, 'run-summary.json');
+  if (!existsSync(summaryPath)) {
+    return { error: { message: `No run-summary.json found in ${runDir}` } };
+  }
+  const data = JSON.parse(readFileSync(summaryPath, 'utf-8'));
+  const runId = data.meta?.runId || `run-${Date.now()}`;
+  const timestamp = data.meta?.timestamp || new Date().toISOString();
+  const dateStr = timestamp.slice(0, 10);
+
+  db.prepare(`
+    INSERT OR REPLACE INTO audit_runs (id, date, timestamp, trigger, finding_count)
+    VALUES (?, ?, ?, ?, ?)
+  `).run(runId, dateStr, timestamp, data.meta?.trigger || 'manual', data.findings?.length || 0);
+
+  const insert = db.prepare(`
+    INSERT OR REPLACE INTO audit_findings
+      (id, run_id, cabinet_member, severity, title, description, assumption,
+       evidence, question, file, line, suggested_fix, auto_fixable, type)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+
+  let count = 0;
+  for (const f of (data.findings || [])) {
+    insert.run(
+      f.id, runId, f['cabinet-member'], f.severity, f.title,
+      f.description || null, f.assumption || null, f.evidence || null,
+      f.question || null, f.file || null, f.line || null,
+      f.suggestedFix || null, f.autoFixable ? 1 : 0, f.type || 'finding'
+    );
+    count++;
+  }
+  return { count, runId, message: `Ingested ${count} findings from ${runDir} (run: ${runId})` };
+}
+
+// ---------------------------------------------------------------------------
+// Triage
+// ---------------------------------------------------------------------------
+export function triage(db, { findingId, status, notes }) {
+  db.prepare(`
+    UPDATE audit_findings
+    SET triage_status = ?, triage_notes = ?, triaged_at = ?
+    WHERE id = ?
+  `).run(status, notes || null, new Date().toISOString(), findingId);
+  return { findingId, status, message: `Triaged ${findingId} → ${status}` };
+}
+
+export function triageHistory(db) {
+  const rejected = db.prepare(`
+    SELECT id, cabinet_member, title FROM audit_findings
+    WHERE triage_status = 'rejected'
+  `).all();
+
+  const deferred = db.prepare(`
+    SELECT id, cabinet_member, title FROM audit_findings
+    WHERE triage_status = 'deferred'
+  `).all();
+
+  return {
+    rejectedIds: rejected.map(r => r.id),
+    rejectedFingerprints: rejected.map(r => ({ 'cabinet-member': r.cabinet_member, title: r.title })),
+    deferredIds: deferred.map(r => r.id),
+    deferredFingerprints: deferred.map(r => ({ 'cabinet-member': r.cabinet_member, title: r.title })),
+  };
+}