create-claude-cabinet 0.29.14 → 0.31.0

package/lib/cli.js

@@ -485,7 +485,7 @@ const MODULES = {
     mandatory: false,
     default: true,
     lean: true,
-    templates: ['skills/plan', 'skills/execute', 'skills/execute-plans', 'skills/investigate'],
+    templates: ['skills/plan', 'skills/execute', 'skills/generate-plan-groups', 'skills/execute-group', 'workflows/execute-group.js', 'skills/investigate', 'cabinet/checkpoint-protocol.md'],
   },
   'compliance': {
     name: 'Compliance Stack (rules + enforcement)',
@@ -592,6 +592,22 @@ 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.',
+    mandatory: false,
+    default: false,
+    lean: false,
+    templates: [
+      'skills/handoff',
+      'skills/handoff-progress',
+      'skills/handoff-ask',
+      'skills/handoff-create',
+      'skills/handoff-add',
+      'skills/handoff-status',
+      'handoff',
+    ],
+  },
 };
 
 /** Recursively collect all relative file paths under a directory. */
@@ -1263,6 +1279,23 @@ async function run() {
         }
       }
     }
+    // execute-plans/ → generate-plan-groups/ (the plan→parallel split).
+    // Key-matched, not version-gated: if the old key is present it needs
+    // migrating; if it isn't, this no-ops. Idempotent on re-run.
+    for (const key of Object.keys(existingManifest)) {
+      const match = key.match(/\.claude\/skills\/execute-plans\//);
+      if (match) {
+        const newKey = key.replace('skills/execute-plans/', 'skills/generate-plan-groups/');
+        // Partial-state guard: if the project already tracks the new key
+        // (a prior partial migration), keep its hash — don't clobber it with
+        // the stale execute-plans hash, which would force a needless re-copy.
+        if (!existingManifest[newKey]) {
+          existingManifest[newKey] = existingManifest[key];
+        }
+        delete existingManifest[key];
+        migrationCount++;
+      }
+    }
     // Future manifest key migrations go here
     if (migrationCount > 0) {
       console.log(`  🔄 Migrated ${migrationCount} manifest key${migrationCount === 1 ? '' : 's'} for directory rename`);

package/package.json

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

package/templates/README.md

@@ -27,7 +27,7 @@ templates, see [EXTENSIONS.md](EXTENSIONS.md).
 | `rules/enforcement-pipeline.md` | Generic enforcement pipeline: capture, classify, promote, encode, monitor. Describes the compliance stack and promotion criteria. |
 | `rules/memory-capture.md` | When and how to capture memories via /cc-remember to the per-file curated layout at ~/.claude/projects/<slug>/memory/. What to capture, what not to, cadence guidance. |
 
-### Skills (22 workflow + 31 cabinet members)
+### Skills (24 workflow + 31 cabinet members)
 
 **Workflow Skills:**
 
@@ -39,7 +39,8 @@ templates, see [EXTENSIONS.md](EXTENSIONS.md).
 | `skills/debrief/` | Session close. Inventory work, close items, run cabinet consultations, update state, persist, record lessons. 9 phase files. |
 | `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/execute-plans/` | Batch execution of multiple plans with conflict detection. |
+| `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/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. |
@@ -103,6 +104,7 @@ mandates and scoped directives.
 | `cabinet/eval-protocol.md` | Structured assessment framework for evaluating skill/cabinet member effectiveness. |
 | `cabinet/lifecycle.md` | When to adopt, retire, and assess cabinet members. |
 | `cabinet/output-contract.md` | How cabinet members produce structured findings for the audit system. |
+| `cabinet/checkpoint-protocol.md` | The cabinet checkpoint mechanism (member selection, verdict schema, escalation) shared by /execute and /execute-group — read, not copied, so both stay in sync. |
 | `cabinet/prompt-guide.md` | Craft knowledge for writing cabinet member prompts. 17 principles. |
 
 ### Scripts (12)

package/templates/cabinet/checkpoint-protocol.md

@@ -0,0 +1,113 @@
+# Cabinet Checkpoint Protocol
+
+The single source of truth for how cabinet members review work in
+progress. `/execute` and `/execute-group` both **read this file and
+follow it** rather than copying the mechanism — so a change here flows to
+every checkpoint, everywhere, with no copy-drift.
+
+A checkpoint is a chance to stop before the cost of fixing goes up. The
+mechanism is the same at every scale; only the **scope** of what's
+reviewed changes.
+
+## When you are told to "follow the checkpoint protocol scoped to X"
+
+The caller names a scope. The scope determines what each spawned agent
+reviews — everything else (how to spawn, what to collect, how to
+escalate) is identical.
+
+| Scope | Reviews | Runs |
+|-------|---------|------|
+| `pre-impl` | The plan text + the list of files it will change | Before any code is written |
+| `this file group` | The git diff for one logical group of changed files | After each file group is implemented |
+| `pre-commit` | The full git diff of all changes | After implementation, before commit |
+| `this group's aggregate` *(group runs only)* | The combined diff of all plans in a parallel group | After a parallel group merges |
+
+A *parallel group* (the last row) is `/execute-group`'s unit of work: a
+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.
+
+## Step 1 — Select which members to spawn
+
+Spawn one Agent per cabinet member that matches **either**:
+
+- **Standing mandate** — `standingMandate` includes the current verb
+  (`execute`). Read `.claude/skills/_index.json` to find them. These run
+  at every checkpoint regardless of surface area.
+- **Surface area** — a file in the reviewed scope matches the member's
+  file patterns, or a keyword in the plan description matches the
+  member's topic keywords.
+
+Fall back to reading `cabinet-*/SKILL.md` frontmatter if the index is
+missing.
+
+**Err toward inclusion.** A member that activates unnecessarily costs a
+few seconds; one that stays silent when it was needed costs rework. For
+`this file group` scope, narrow to members matching *that group's* files
+— a member reviewing 3 changed files gives sharper feedback than one
+reviewing 30.
+
+If the project has no cabinet members, skip the checkpoint and proceed —
+checkpoints add depth, not structure.
+
+## Step 2 — Spawn the agents (concurrently)
+
+Spawn the selected members concurrently — they don't depend on each
+other. **How** you spawn depends on the caller:
+
+- From `/execute` (main session): issue all Agent-tool calls in a single
+  message so they run in parallel.
+- From `/execute-group` (workflow script): issue the spawns as `agent()`
+  calls inside a `parallel()` block. Worktree agents cannot spawn
+  reviewers themselves — the workflow orchestrator does it.
+
+Either way, each spawned agent receives:
+
+- The cabinet member's full `SKILL.md` content
+- Essential project briefing from `.claude/cabinet/_briefing.md` (read it
+  once, reuse for every agent)
+- The member's `directives.execute`, if present — paste it in to sharpen
+  the member's focus
+- **The scoped material:** plan text + file list (`pre-impl`), or the
+  relevant git diff (`this file group`, `pre-commit`, aggregate)
+- An instruction to return the verdict object below
+
+## Step 3 — Collect verdicts
+
+Each agent returns exactly this shape:
+
+```json
+{
+  "cabinet_member": "name",
+  "verdict": "continue" | "pause" | "stop",
+  "concerns": [
+    { "description": "...", "evidence": "...", "severity": "blocking" | "advisory" }
+  ]
+}
+```
+
+## Step 4 — Apply escalation
+
+Collect every verdict, then:
+
+- **Any `stop`** → halt. Show the concern. Require an explicit override
+  from the user before proceeding.
+- **Any `pause`** → show the concern with options: proceed / address /
+  abort.
+- **3+ `pause`** → escalate to stop-equivalent (halt, require override).
+- **All `continue`** → proceed with a brief one-line summary.
+
+At `pre-commit` and aggregate scopes, re-check earlier `continue`
+concerns: a concern that was minor in one file group can become
+significant once all changes are viewed together.
+
+## Principles
+
+- **Cabinet members are guardrails, not gates.** The user always has the
+  final say. A `stop` requires explicit override — it is not an automatic
+  rejection.
+- **Scope tightly.** The narrower the diff a member reviews, the better
+  the feedback.
+- **The pre-commit sweep catches emergent issues.** File groups that look
+  fine alone create problems in combination — type mismatches across
+  boundaries, security gaps from API + frontend changes landing together.

package/templates/handoff/capture-and-encrypt.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+//
+// Single-subprocess credential capture + encryption.
+// Plaintext never exits this process, never enters Claude's context or Anthropic's API.
+// stdout: serialized encrypted envelope (base64) only.
+//
+import { readFile } from 'node:fs/promises';
+import { captureSecureInput, detectPlatform, DialogCancelledError, DialogUnavailableError } from './secure-input.mjs';
+import { encryptCredential, serializeEnvelope } from './handoff-crypto.mjs';
+
+const args = process.argv.slice(2);
+
+function getArg(name) {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : null;
+}
+
+const prompt = getArg('--prompt');
+const publicKeyPath = getArg('--public-key');
+const testMode = args.includes('--test');
+
+if (!testMode && (!prompt || !publicKeyPath)) {
+  console.error('Usage: node capture-and-encrypt.mjs --prompt <text> --public-key <path>');
+  console.error('       node capture-and-encrypt.mjs --test');
+  process.exit(1);
+}
+
+try {
+  if (testMode) {
+    const { generateKeypair, decryptCredential, deserializeEnvelope } = await import('./handoff-crypto.mjs');
+    const plaintext = 'test-credential-value';
+    const { publicKey, privateKey } = await generateKeypair();
+    const envelope = await encryptCredential(plaintext, publicKey);
+    const serialized = serializeEnvelope(envelope);
+    const recovered = deserializeEnvelope(serialized);
+    const decrypted = await decryptCredential(recovered, privateKey);
+
+    if (decrypted !== plaintext) {
+      console.error(JSON.stringify({ error: 'test_failed', detail: 'Roundtrip mismatch' }));
+      process.exit(4);
+    }
+    console.log(JSON.stringify({
+      ok: true,
+      platform: detectPlatform(),
+      envelope_id: envelope.envelope_id,
+    }));
+    process.exit(0);
+  }
+
+  const publicKeyJWK = JSON.parse(await readFile(publicKeyPath, 'utf-8'));
+  const plaintext = await captureSecureInput(prompt);
+  const envelope = await encryptCredential(plaintext, publicKeyJWK);
+  // Plaintext is now only in local `plaintext` var — GC will collect it.
+  // Only the encrypted envelope reaches stdout.
+  process.stdout.write(serializeEnvelope(envelope));
+} catch (err) {
+  if (err instanceof DialogCancelledError) {
+    console.error(JSON.stringify({ error: 'cancelled' }));
+    process.exit(2);
+  }
+  if (err instanceof DialogUnavailableError) {
+    console.error(JSON.stringify({ error: 'no_dialog', platform: err.platform }));
+    process.exit(3);
+  }
+  console.error(JSON.stringify({ error: 'encrypt_failed', detail: err.message }));
+  process.exit(4);
+}

package/templates/handoff/decrypt-credential.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+//
+// Decrypt a credential envelope using the consultant's passphrase-protected private key.
+// Passphrase captured via secure OS dialog — never enters Claude's context.
+// stdout: decrypted plaintext (displayed once by the skill, not stored).
+//
+import { readFile } from 'node:fs/promises';
+import { captureSecureInput, DialogCancelledError, DialogUnavailableError } from './secure-input.mjs';
+import { decryptCredential, decryptPrivateKey, deserializeEnvelope } from './handoff-crypto.mjs';
+
+const args = process.argv.slice(2);
+
+function getArg(name) {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : null;
+}
+
+const envelopeInput = getArg('--envelope');
+const privateKeyPath = getArg('--private-key') || './keys/consultant.priv.jwk.enc';
+const testMode = args.includes('--test');
+
+if (!testMode && !envelopeInput) {
+  console.error('Usage: node decrypt-credential.mjs --envelope <base64> [--private-key <path>]');
+  console.error('       node decrypt-credential.mjs --test');
+  process.exit(1);
+}
+
+try {
+  if (testMode) {
+    const { generateKeypair, encryptCredential, encryptPrivateKey, serializeEnvelope } = await import('./handoff-crypto.mjs');
+    const testPassphrase = 'test-pass-123';
+    const testPlaintext = 'test-secret-value';
+
+    const { publicKey, privateKey } = await generateKeypair();
+    const encrypted = await encryptPrivateKey(privateKey, testPassphrase);
+    const envelope = await encryptCredential(testPlaintext, publicKey);
+    const serialized = serializeEnvelope(envelope);
+
+    const recovered = decryptPrivateKey(encrypted, testPassphrase);
+    const decrypted = await decryptCredential(deserializeEnvelope(serialized), await recovered);
+
+    console.log(JSON.stringify({
+      ok: decrypted === testPlaintext,
+      detail: decrypted === testPlaintext ? 'Roundtrip passed' : 'Mismatch',
+    }));
+    process.exit(decrypted === testPlaintext ? 0 : 4);
+  }
+
+  const encryptedKey = JSON.parse(await readFile(privateKeyPath, 'utf-8'));
+  const envelope = deserializeEnvelope(envelopeInput);
+
+  const passphrase = await captureSecureInput('Enter your private key passphrase');
+  const privateKeyJWK = await decryptPrivateKey(encryptedKey, passphrase);
+  const plaintext = await decryptCredential(envelope, privateKeyJWK);
+
+  process.stdout.write(plaintext);
+} catch (err) {
+  if (err instanceof DialogCancelledError) {
+    console.error(JSON.stringify({ error: 'cancelled' }));
+    process.exit(2);
+  }
+  if (err instanceof DialogUnavailableError) {
+    console.error(JSON.stringify({ error: 'no_dialog', platform: err.platform }));
+    process.exit(3);
+  }
+  if (err.message?.includes('decrypt') || err.message?.includes('OperationError')) {
+    console.error(JSON.stringify({ error: 'wrong_passphrase' }));
+    process.exit(5);
+  }
+  console.error(JSON.stringify({ error: 'decrypt_failed', detail: err.message }));
+  process.exit(4);
+}

package/templates/handoff/example-checklist.yaml

@@ -0,0 +1,81 @@
+# Example handoff checklist — customize for your engagement.
+# See schema.md for the full format reference.
+
+meta:
+  title: "Project Go-Live Credentials"
+  consultant: "Your Name"
+  public_key: "./keys/consultant.pub.jwk"
+
+transport:
+  type: email
+  consultant: "consultant@example.com"
+  client: "client@example.com"
+
+sections:
+  - key: hosting
+    title: "Hosting Setup"
+    items:
+      - key: hosting_provider
+        prompt: "Which hosting provider are you using?"
+        kind: decide
+        options: [Railway, Vercel, Fly.io, Other]
+
+      - key: railway_token
+        prompt: "Your Railway API token"
+        kind: credential
+        help: "Find this at railway.app → Account Settings → Tokens"
+        visibility:
+          depends_on: hosting_provider
+          value_in: [Railway]
+
+      - key: vercel_token
+        prompt: "Your Vercel access token"
+        kind: credential
+        help: "Find this at vercel.com → Settings → Tokens"
+        visibility:
+          depends_on: hosting_provider
+          value_in: [Vercel]
+
+  - key: email_service
+    title: "Email Service"
+    items:
+      - key: email_provider
+        prompt: "Which email service are you using?"
+        kind: decide
+        options: [Postmark, SendGrid, Resend, None]
+
+      - key: postmark_token
+        prompt: "Your Postmark server API token"
+        kind: credential
+        help: "Find this in your Postmark server → API Tokens tab"
+        visibility:
+          depends_on: email_provider
+          value_in: [Postmark]
+
+      - key: sendgrid_key
+        prompt: "Your SendGrid API key"
+        kind: credential
+        visibility:
+          depends_on: email_provider
+          value_in: [SendGrid]
+
+      - key: resend_key
+        prompt: "Your Resend API key"
+        kind: credential
+        help: "Find this at resend.com → API Keys"
+        visibility:
+          depends_on: email_provider
+          value_in: [Resend]
+
+  - key: domain
+    title: "Domain & DNS"
+    items:
+      - key: domain_name
+        prompt: "What domain will this project use?"
+        kind: provide
+        help: "e.g., example.com or app.example.com"
+
+      - key: dns_access
+        prompt: "Do you have access to your domain's DNS settings?"
+        kind: confirm
+        help: "We'll need to add records for the hosting provider and email service."

package/templates/handoff/generate-keys.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { generateKeypair, encryptPrivateKey } from './handoff-crypto.mjs';
+import { captureSecureInput } from './secure-input.mjs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+const args = process.argv.slice(2);
+
+function getArg(name) {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : null;
+}
+
+const outdir = getArg('--outdir') || './keys';
+const testPassphrase = getArg('--test-passphrase');
+
+let passphrase;
+if (testPassphrase) {
+  passphrase = testPassphrase;
+} else {
+  console.error('A passphrase dialog will appear — enter a passphrase to protect your private key.');
+  console.error('You will need this passphrase to decrypt credentials via /handoff-status.');
+  passphrase = await captureSecureInput('Create a passphrase for your private key');
+}
+
+const { publicKey, privateKey } = await generateKeypair();
+const encrypted = await encryptPrivateKey(privateKey, passphrase);
+
+await mkdir(resolve(outdir), { recursive: true });
+await writeFile(resolve(outdir, 'consultant.pub.jwk'), JSON.stringify(publicKey, null, 2));
+await writeFile(resolve(outdir, 'consultant.priv.jwk.enc'), JSON.stringify(encrypted, null, 2));
+
+console.log(`Keys written to ${outdir}/`);
+console.log('  consultant.pub.jwk      — share with client (ships with plugin)');
+console.log('  consultant.priv.jwk.enc — keep private (encrypted with your passphrase)');

package/templates/handoff/handoff-checklist.mjs

@@ -0,0 +1,172 @@
+import { readFile, writeFile, rename } from 'node:fs/promises';
+
+const VALID_KINDS = ['decide', 'provide', 'confirm', 'credential'];
+const VALID_TRANSPORT_TYPES = ['email', 'mcp', 'file'];
+
+export function validateChecklist(checklist) {
+  const errors = [];
+
+  if (!checklist.meta) errors.push('Missing "meta" section');
+  else {
+    if (!checklist.meta.title) errors.push('meta.title is required');
+    if (!checklist.meta.public_key) errors.push('meta.public_key is required');
+  }
+
+  if (!checklist.transport) {
+    errors.push('Missing "transport" section');
+  } else if (!VALID_TRANSPORT_TYPES.includes(checklist.transport.type)) {
+    errors.push(`transport.type must be one of: ${VALID_TRANSPORT_TYPES.join(', ')}`);
+  }
+
+  if (!Array.isArray(checklist.sections)) {
+    errors.push('Missing or invalid "sections" array');
+    return { valid: false, errors };
+  }
+
+  // First pass: collect all keys for cross-section dependency validation
+  const allKeys = new Set();
+  for (const section of checklist.sections) {
+    for (const item of (section.items || [])) {
+      if (item.key) allKeys.add(item.key);
+    }
+  }
+
+  const seenKeys = new Set();
+  for (const section of checklist.sections) {
+    if (!section.key) errors.push('Section missing "key"');
+    if (!section.title) errors.push(`Section ${section.key || '?'} missing "title"`);
+    if (!Array.isArray(section.items)) {
+      errors.push(`Section ${section.key || '?'} missing "items" array`);
+      continue;
+    }
+    for (const item of section.items) {
+      if (!item.key) { errors.push('Item missing "key"'); continue; }
+      if (!item.prompt) errors.push(`Item ${item.key} missing "prompt"`);
+      if (!VALID_KINDS.includes(item.kind)) {
+        errors.push(`Item ${item.key}: kind must be one of: ${VALID_KINDS.join(', ')}`);
+      }
+      if (seenKeys.has(item.key)) errors.push(`Duplicate item key: ${item.key}`);
+      seenKeys.add(item.key);
+
+      if (item.visibility) {
+        if (!item.visibility.depends_on) errors.push(`Item ${item.key}: visibility.depends_on is required`);
+        if (!Array.isArray(item.visibility.value_in)) errors.push(`Item ${item.key}: visibility.value_in must be an array`);
+        if (item.visibility.depends_on && !allKeys.has(item.visibility.depends_on)) {
+          errors.push(`Item ${item.key}: depends_on "${item.visibility.depends_on}" references non-existent key`);
+        }
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+function getAllItems(checklist) {
+  return (checklist.sections || []).flatMap(s => s.items || []);
+}
+
+export function detectCycles(checklist) {
+  const items = getAllItems(checklist);
+  const keySet = new Set(items.map(i => i.key));
+  const graph = new Map();
+  const inDegree = new Map();
+
+  for (const item of items) {
+    graph.set(item.key, []);
+    inDegree.set(item.key, 0);
+  }
+
+  for (const item of items) {
+    const parent = item.visibility?.depends_on;
+    if (parent && keySet.has(parent)) {
+      graph.get(parent).push(item.key);
+      inDegree.set(item.key, inDegree.get(item.key) + 1);
+    }
+  }
+
+  const queue = [...inDegree.entries()].filter(([, d]) => d === 0).map(([k]) => k);
+  let processed = 0;
+
+  while (queue.length > 0) {
+    const key = queue.shift();
+    processed++;
+    for (const child of graph.get(key) || []) {
+      const nd = inDegree.get(child) - 1;
+      inDegree.set(child, nd);
+      if (nd === 0) queue.push(child);
+    }
+  }
+
+  const hasCycle = processed < items.length;
+  const cycleKeys = hasCycle
+    ? [...inDegree.entries()].filter(([, d]) => d > 0).map(([k]) => k)
+    : [];
+
+  return { hasCycle, cycleKeys };
+}
+
+export function computeVisibility(checklist, answers) {
+  const items = getAllItems(checklist);
+  const visible = new Set();
+
+  for (const item of items) {
+    if (!item.visibility) visible.add(item.key);
+  }
+
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const item of items) {
+      if (visible.has(item.key) || !item.visibility) continue;
+      const parentKey = item.visibility.depends_on;
+      if (!visible.has(parentKey)) continue;
+      const parentAnswer = answers[parentKey]?.value;
+      if (parentAnswer && item.visibility.value_in.includes(parentAnswer)) {
+        visible.add(item.key);
+        changed = true;
+      }
+    }
+  }
+
+  return visible;
+}
+
+export async function loadState(path) {
+  try {
+    return JSON.parse(await readFile(path, 'utf-8'));
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+export function createState(checklistPath) {
+  return {
+    checklist: checklistPath,
+    started_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+    answers: {},
+  };
+}
+
+export async function saveState(path, state) {
+  state.updated_at = new Date().toISOString();
+  const tmp = path + '.tmp';
+  await writeFile(tmp, JSON.stringify(state, null, 2));
+  await rename(tmp, path);
+}
+
+export function recordAnswer(state, key, value) {
+  state.answers[key] = { value, answered_at: new Date().toISOString() };
+}
+
+export function recordCredentialSent(state, key, envelopeId) {
+  state.answers[key] = { status: 'sent', envelope_id: envelopeId, sent_at: new Date().toISOString() };
+}
+
+export function getProgress(checklist, state) {
+  const answers = state?.answers || {};
+  const visible = computeVisibility(checklist, answers);
+  const completed = [...visible].filter(key => answers[key]).length;
+  return { total: visible.size, completed, remaining: visible.size - completed };
+}