create-claude-cabinet 0.25.3 → 0.26.0

package/README.md

@@ -131,6 +131,32 @@ hooks — things that keep going wrong become things that can't go wrong.
 - **`/cc-upgrade`** — when Claude Cabinet publishes updates, this skill
   runs the installer for the mechanical parts and walks you through
   what changed conversationally. Intelligence is the merge strategy.
+- **`/cc-feedback`** — file friction with CC itself mid-session
+  without waiting for debrief. When a skill, phase, or convention
+  causes pain, this captures the detail and queues it for upstream
+  delivery to the Claude Cabinet repo.
+
+### Verify (opt-in, off by default)
+
+Walkthrough verification harness — Cucumber `.feature` files describing
+user journeys, Playwright running them, and human-in-the-loop verdict
+pauses (Pass / Issue / Skip / Needs-info) at checks that need subjective
+judgment. Replaces flat AC checklists with re-runnable scenarios you can
+read months later.
+
+- **`/verify`** — run the suite
+- **`/verify learn`** — bootstrap from a cold start. Claude scans
+  routes, memory, git, and the live UI; proposes scenarios; calibrates
+  with you; then generates `.feature` files and step stubs
+- **`/verify update "I changed X"`** — keep scenarios in sync as the
+  product evolves
+- **`/verify backfill <fid>`** — attach a Verify Plan to a pending
+  action's notes
+
+Enable with `--modules verify` (existing installs merge, nothing else
+disturbed). Runtime lives at `~/.claude-cabinet/verify/<version>/` and
+ships an opinionated `cabinet-verify` npm package built from de[sic]ify's
+e2e harness.
 
 ## Your Workflow
 
@@ -158,14 +184,29 @@ that override default behavior for any skill. Write content in a phase
 file to customize it, write `skip: true` to disable it, or leave it
 absent to use the default. No config files, no YAML, no DSL.
 
+## Adding Modules to an Existing Install
+
+Some modules (like `verify` and `memory`) are opt-in. To add one
+without touching anything else in your install:
+
+```
+npx create-claude-cabinet --modules verify --yes
+```
+
+The `--modules` flag **merges** with your existing install — it adds
+the listed modules to what's already there, it doesn't replace your
+module set. Safe to run on a mature project without losing
+customization. You can pass multiple modules: `--modules verify,memory`.
+
 ## CLI Options
 
 ```
-npx create-claude-cabinet                 # Interactive walkthrough
-npx create-claude-cabinet my-project      # Install in ./my-project/
-npx create-claude-cabinet --yes           # Accept all defaults
-npx create-claude-cabinet --yes --no-db   # All defaults, skip database
-npx create-claude-cabinet --dry-run       # Preview without writing files
+npx create-claude-cabinet                         # Interactive walkthrough
+npx create-claude-cabinet my-project              # Install in ./my-project/
+npx create-claude-cabinet --yes                   # Accept all defaults
+npx create-claude-cabinet --yes --no-db           # All defaults, skip database
+npx create-claude-cabinet --dry-run               # Preview without writing files
+npx create-claude-cabinet --modules verify --yes  # Add an opt-in module (merges, doesn't replace)
 ```
 
 ## What Gets Installed

package/package.json

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

package/templates/hooks/action-completion-gate.sh

@@ -14,7 +14,6 @@ INPUT="$CLAUDE_TOOL_INPUT"
 FID=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('fid',''))" 2>/dev/null)
 
 if [ -z "$FID" ]; then
-  echo '{"decision":"allow"}'
   exit 0
 fi
 
@@ -43,4 +42,4 @@ if [ "$AC_VERIFIED" != "True" ]; then
   exit 0
 fi
 
-echo '{"decision":"allow"}'
+exit 0

package/templates/hooks/action-quality-gate.sh

@@ -47,4 +47,4 @@ if ! echo "$NOTES" | grep -qiE '(## Surface|files:|dirs:)'; then
   exit 0
 fi
 
-echo '{"decision":"allow"}'
+exit 0

package/templates/hooks/cc-upstream-guard.sh

@@ -14,13 +14,14 @@
 #
 # Hook contract:
 #   Input: $CLAUDE_TOOL_INPUT has the tool use JSON with "file_path" field
-#   Output: JSON on stdout with { "decision": "block"|"allow", "reason": "..." }
+#   Output: JSON on stdout with { "decision": "block", "reason": "..." }
+#           when blocking. Otherwise empty stdout + exit 0 (allow is the
+#           default; emitting "allow" violates the hook output schema).
 
 # Extract file_path from tool input
 FILE_PATH=$(echo "$CLAUDE_TOOL_INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('file_path',''))" 2>/dev/null)
 
 if [ -z "$FILE_PATH" ]; then
-  echo '{"decision":"allow"}'
   exit 0
 fi
 
@@ -42,7 +43,6 @@ PROJECT_ROOT=$(find_project_root)
 
 if [ -z "$PROJECT_ROOT" ]; then
   # No .ccrc.json found — not a CC project, allow everything
-  echo '{"decision":"allow"}'
   exit 0
 fi
 
@@ -53,7 +53,6 @@ if [[ "$FILE_PATH" = /* ]]; then
   REL_PATH="${FILE_PATH#$PROJECT_ROOT/}"
   # If the path didn't change, the file is outside the project
   if [ "$REL_PATH" = "$FILE_PATH" ]; then
-    echo '{"decision":"allow"}'
     exit 0
   fi
 else
@@ -74,6 +73,5 @@ except:
 
 if [ "$IN_MANIFEST" = "yes" ]; then
   echo "{\"decision\":\"block\",\"reason\":\"Blocked: $REL_PATH is managed by Claude Cabinet. CC-managed files are upstream-owned — edits come through /cc-upgrade, not direct modification. Put project-specific content in briefing files or phase files instead.\"}"
-else
-  echo '{"decision":"allow"}'
 fi
+exit 0

package/templates/hooks/git-guardrails.sh

@@ -9,13 +9,15 @@
 #
 # Hook contract:
 #   Input: $CLAUDE_TOOL_INPUT has the tool use JSON with "command" field
-#   Output: JSON on stdout with { "decision": "block"|"allow", "reason": "..." }
+#   Output: JSON on stdout with { "decision": "block", "reason": "..." }
+#           when blocking. Otherwise empty stdout + exit 0 (Claude Code
+#           treats no-output as allow; emitting "allow" violates the
+#           hook output schema).
 
 # Read the command from the tool input
 COMMAND=$(echo "$CLAUDE_TOOL_INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('command',''))" 2>/dev/null)
 
 if [ -z "$COMMAND" ]; then
-  echo '{"decision":"allow"}'
   exit 0
 fi
 
@@ -62,6 +64,5 @@ RESULT=$(check_command "$COMMAND")
 
 if [ -n "$RESULT" ]; then
   echo "$RESULT"
-else
-  echo '{"decision":"allow"}'
 fi
+exit 0

package/templates/hooks/omega-memory-guard.sh

@@ -16,13 +16,14 @@
 #
 # Hook contract:
 #   Input: $CLAUDE_TOOL_INPUT has the tool use JSON with "file_path" field
-#   Output: JSON on stdout with { "decision": "block"|"allow", "reason": "..." }
+#   Output: JSON on stdout with { "decision": "block", "reason": "..." }
+#           when blocking. Otherwise empty stdout + exit 0 (allow is the
+#           default; emitting "allow" violates the hook output schema).
 
 # Extract file_path from tool input
 FILE_PATH=$(echo "$CLAUDE_TOOL_INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('file_path',''))" 2>/dev/null)
 
 if [ -z "$FILE_PATH" ]; then
-  echo '{"decision":"allow"}'
   exit 0
 fi
 
@@ -30,21 +31,18 @@ fi
 # Note: case patterns with * don't cross / boundaries in some shells,
 # so we use [[ ]] substring matching for absolute path compatibility.
 if [[ "$FILE_PATH" != *"/.claude/memory/"* ]] && [[ "$FILE_PATH" != *"/.claude/projects/"*"/memory/"* ]]; then
-  echo '{"decision":"allow"}'
   exit 0
 fi
 
 # Allow MEMORY.md index files (structural, not memory content)
 BASENAME=$(basename "$FILE_PATH")
 if [ "$BASENAME" = "MEMORY.md" ]; then
-  echo '{"decision":"allow"}'
   exit 0
 fi
 
 # Allow pattern files (enforcement pipeline artifacts, not semantic memories)
 case "$FILE_PATH" in
   */memory/patterns/*)
-    echo '{"decision":"allow"}'
     exit 0
     ;;
 esac
@@ -53,7 +51,6 @@ esac
 OMEGA_PYTHON="$HOME/.claude-cabinet/omega-venv/bin/python3"
 if [ ! -x "$OMEGA_PYTHON" ]; then
   # Omega not available — flat markdown IS the correct fallback
-  echo '{"decision":"allow"}'
   exit 0
 fi
 
@@ -73,7 +70,6 @@ find_adapter() {
 ADAPTER=$(find_adapter)
 if [ -z "$ADAPTER" ]; then
   # No adapter found — flat markdown fallback is correct
-  echo '{"decision":"allow"}'
   exit 0
 fi
 

package/templates/hooks/work-tracker-guard.sh

@@ -10,7 +10,6 @@ INPUT="$CLAUDE_TOOL_INPUT"
 COMMAND=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('command',''))" 2>/dev/null)
 
 if [ -z "$COMMAND" ]; then
-  echo '{"decision":"allow"}'
   exit 0
 fi
 
@@ -19,20 +18,18 @@ PHASE_FILE=".claude/skills/hooks/phases/work-tracker-guard.md"
 if [ -f "$PHASE_FILE" ]; then
   FIRST_LINE=$(head -1 "$PHASE_FILE")
   if [ "$FIRST_LINE" = "skip: true" ]; then
-    echo '{"decision":"allow"}'
     exit 0
   fi
 fi
 
 # Check for SQL operations against actions table
 if echo "$COMMAND" | grep -qiE '(INSERT\s+INTO|UPDATE|DELETE\s+FROM)\s+actions'; then
-  # Override escape hatch
+  # Override escape hatch — allow is the default, just exit 0
   if echo "$COMMAND" | grep -q '\-\-force-raw-sql'; then
-    echo '{"decision":"allow","reason":"Raw SQL override acknowledged. Quality gates bypassed."}'
     exit 0
   fi
   echo '{"decision":"block","reason":"Raw SQL against actions table detected. Use MCP tools instead: pib_create_action, pib_update_action, pib_complete_action, pib_get_action. These enforce quality gates. To override (almost certainly wrong): add --force-raw-sql to your command."}'
   exit 0
 fi
 
-echo '{"decision":"allow"}'
+exit 0

package/templates/scripts/triage-server.mjs

@@ -1,21 +1,53 @@
 /**
- * Minimal triage server — serves the triage UI and holds findings/verdicts in memory.
+ * Minimal triage server — serves the triage UI and holds findings/verdicts.
  *
  * Claude POSTs findings, user triages in browser, Claude GETs verdicts.
+ * Each verdict is written through to disk as the user makes it, so page
+ * reloads or server restarts don't lose in-progress triage decisions.
  *
  * Usage: node triage-server.mjs [--port 3457]
  */
 
 import { createServer } from 'node:http';
-import { readFile } from 'node:fs/promises';
+import { readFile, writeFile, mkdir, unlink } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PORT = parseInt(process.argv.find((_, i, a) => a[i - 1] === '--port') || '3457');
+const DRAFT_PATH = join(process.cwd(), '.claude', 'triage-draft.json');
 
 let currentFindings = [];
 let currentVerdicts = null;
+let drafts = {}; // { findingId: { verdict, feedback } }
+
+async function loadDrafts() {
+  try {
+    drafts = JSON.parse(await readFile(DRAFT_PATH, 'utf-8'));
+  } catch {
+    drafts = {};
+  }
+}
+
+async function saveDrafts() {
+  await mkdir(dirname(DRAFT_PATH), { recursive: true });
+  await writeFile(DRAFT_PATH, JSON.stringify(drafts, null, 2));
+}
+
+function dedupById(items) {
+  const seen = new Set();
+  const out = [];
+  for (const f of items) {
+    if (!f || !f.id || seen.has(f.id)) continue;
+    seen.add(f.id);
+    out.push(f);
+  }
+  return out;
+}
+
+function withDrafts(findings) {
+  return findings.map((f) => ({ ...f, draft: drafts[f.id] || null }));
+}
 
 function json(res, data, status = 200) {
   res.writeHead(status, { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': '*' });
@@ -53,21 +85,47 @@ const server = createServer(async (req, res) => {
     for await (const chunk of req) body += chunk;
     try {
       const data = JSON.parse(body);
-      currentFindings = data.findings || data;
-      currentVerdicts = null; // Reset verdicts for new batch
-      console.log(`Loaded ${currentFindings.length} findings`);
+      const raw = data.findings || data;
+      currentFindings = dedupById(Array.isArray(raw) ? raw : []);
+      currentVerdicts = null;
+      // Trim drafts to the new finding id set so a fresh batch doesn't
+      // surface stale entries, but a re-POST of the same batch preserves
+      // in-progress work.
+      const idSet = new Set(currentFindings.map((f) => f.id));
+      drafts = Object.fromEntries(Object.entries(drafts).filter(([id]) => idSet.has(id)));
+      await saveDrafts();
+      console.log(`Loaded ${currentFindings.length} findings (${Object.keys(drafts).length} drafts retained)`);
       return json(res, { ok: true, count: currentFindings.length });
     } catch (err) {
       return json(res, { error: 'Invalid JSON' }, 400);
     }
   }
 
-  // GET /api/findings — UI fetches findings
+  // GET /api/findings — UI fetches findings (with any saved drafts attached)
   if (req.method === 'GET' && url.pathname === '/api/findings') {
-    return json(res, { findings: currentFindings });
+    return json(res, { findings: withDrafts(currentFindings) });
+  }
+
+  // POST /api/verdict — UI writes a single verdict as the user makes it
+  if (req.method === 'POST' && url.pathname === '/api/verdict') {
+    let body = '';
+    for await (const chunk of req) body += chunk;
+    try {
+      const { id, verdict, feedback } = JSON.parse(body);
+      if (!id) return json(res, { error: 'Missing id' }, 400);
+      const existing = drafts[id] || { verdict: '', feedback: '' };
+      drafts[id] = {
+        verdict: verdict !== undefined ? verdict : existing.verdict,
+        feedback: feedback !== undefined ? feedback : existing.feedback,
+      };
+      await saveDrafts();
+      return json(res, { ok: true });
+    } catch (err) {
+      return json(res, { error: 'Invalid JSON' }, 400);
+    }
   }
 
-  // POST /api/verdicts — UI submits verdicts
+  // POST /api/verdicts — UI submits final verdicts batch
   if (req.method === 'POST' && url.pathname === '/api/verdicts') {
     let body = '';
     for await (const chunk of req) body += chunk;
@@ -80,7 +138,7 @@ const server = createServer(async (req, res) => {
     }
   }
 
-  // GET /api/verdicts — Claude reads verdicts
+  // GET /api/verdicts — Claude reads submitted verdicts
   if (req.method === 'GET' && url.pathname === '/api/verdicts') {
     if (!currentVerdicts) {
       return json(res, { submitted: false, message: 'No verdicts submitted yet' });
@@ -88,11 +146,23 @@ const server = createServer(async (req, res) => {
     return json(res, currentVerdicts);
   }
 
+  // DELETE /api/draft — clear in-progress draft state
+  if (req.method === 'DELETE' && url.pathname === '/api/draft') {
+    drafts = {};
+    try {
+      await unlink(DRAFT_PATH);
+    } catch {}
+    return json(res, { ok: true });
+  }
+
   // 404
   res.writeHead(404);
   res.end('Not found');
 });
 
+await loadDrafts();
 server.listen(PORT, () => {
   console.log(`Triage server running at http://localhost:${PORT}`);
+  const draftCount = Object.keys(drafts).length;
+  if (draftCount) console.log(`Restored ${draftCount} in-progress draft verdict(s) from ${DRAFT_PATH}`);
 });

package/templates/scripts/triage-ui.html

@@ -285,13 +285,42 @@
     let findings = [];
     const verdicts = {};  // { findingId: { verdict, feedback } }
     const memberNotes = {};  // { member: { comment, question } }
+    const feedbackDebounce = {}; // { findingId: timeoutId }
+
+    function dedupById(items) {
+      const seen = new Set();
+      const out = [];
+      for (const f of items) {
+        if (!f || !f.id || seen.has(f.id)) continue;
+        seen.add(f.id);
+        out.push(f);
+      }
+      return out;
+    }
+
+    // POST a verdict write-through to the server (silent on failure
+    // — write-through is best-effort; submit remains the source of truth)
+    function persistVerdict(id) {
+      const v = verdicts[id] || { verdict: '', feedback: '' };
+      fetch('/api/verdict', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ id, verdict: v.verdict, feedback: v.feedback }),
+      }).catch(() => {});
+    }
 
     // ── Public API for Claude (javascript_tool) ──
     window.loadFindings = function(data) {
-      findings = Array.isArray(data) ? data : [];
-      // Pre-populate from recommendations
+      findings = dedupById(Array.isArray(data) ? data : []);
+      // Hydrate from server-persisted drafts first; recommendations only
+      // fill in when there's no prior draft.
       findings.forEach(f => {
-        if (f.recommendation && !verdicts[f.id]) {
+        if (f.draft && f.draft.verdict !== undefined) {
+          verdicts[f.id] = {
+            verdict: f.draft.verdict || '',
+            feedback: f.draft.feedback || '',
+          };
+        } else if (f.recommendation && !verdicts[f.id]) {
           verdicts[f.id] = { verdict: f.recommendation, feedback: '' };
         }
       });
@@ -476,6 +505,7 @@
         const v = e.target.dataset.v;
         if (!verdicts[id]) verdicts[id] = { verdict: '', feedback: '' };
         verdicts[id].verdict = v;
+        persistVerdict(id);
         render();
       }
       // Bulk buttons
@@ -485,6 +515,7 @@
         findings.filter(f => f['cabinet-member'] === member).forEach(f => {
           if (!verdicts[f.id]) verdicts[f.id] = { verdict: '', feedback: '' };
           verdicts[f.id].verdict = v;
+          persistVerdict(f.id);
         });
         render();
       }
@@ -504,6 +535,9 @@
         const id = e.target.dataset.id;
         if (!verdicts[id]) verdicts[id] = { verdict: '', feedback: '' };
         verdicts[id].feedback = e.target.value;
+        // Debounce write-through so we don't POST on every keystroke
+        clearTimeout(feedbackDebounce[id]);
+        feedbackDebounce[id] = setTimeout(() => persistVerdict(id), 400);
       }
       if (e.target.classList.contains('member-input')) {
         const p = e.target.dataset.member;

package/templates/skills/debrief/SKILL.md

@@ -493,7 +493,8 @@ Read `phases/report.md` for how to present the debrief summary.
 
 Phases are either **core** (maintain system state) or **presentation**
 (surface information for the user). For lightweight session closes,
-skip presentation phases. Core phases always run.
+skip presentation phases. **Core phases always run — Quick Mode is not
+a license to skip them.**
 
 - **Core phases** (always run): inventory, close-work,
   cabinet-consultations, audit-pattern-capture, auto-maintenance,
@@ -505,6 +506,26 @@ skip presentation phases. Core phases always run.
 A project that wants a quick debrief variant skips the report and
 outputs a minimal summary instead.
 
+### What Quick Mode does NOT skip
+
+**Cabinet-consultations (step 3) is core and MUST run — do NOT skip,
+do NOT paraphrase, do NOT defer.** This is where record-keeper (and
+any other debrief-mandated members) verifies documentation against
+reality. Skipping it is the single most common Quick Mode failure
+mode: the consultations *feel* like overhead because they spawn
+agents, but they are the only mechanism that catches doc drift,
+methodology gaps, and stale state. A debrief without
+cabinet-consultations leaves the next orient reading stale docs.
+
+**Audit-pattern-capture, methodology-capture, and upstream-feedback
+are instruction phases — they ship with CC and are always required**,
+in Quick Mode as much as in full debrief. Their per-session cost is
+near zero when nothing fires.
+
+If a session genuinely has no audit findings, no methodology work,
+and no CC friction, those phases self-skip in seconds. That is not
+the same as Claude choosing to skip them.
+
 ## Extending and Calibration
 
 See [calibration.md](calibration.md) for the phase-extension pattern

package/templates/skills/orient/phases/verify-backfill.md

@@ -83,8 +83,9 @@ alongside any items surfaced by deferred-check, health-checks, etc.
 
 ## What this phase does NOT do
 
-- It does not modify action notes. The operator runs `/plan <fid>`
-  to backfill, or chooses to accept the drift.
+- It does not modify action notes. The operator runs
+  `/verify backfill <fid>` to backfill, or chooses to accept the
+  drift.
 - It does not file new actions or projects.
 - It does not block orient. Even with 5 backfill candidates, orient
   completes; the Attention Items accumulate.

package/templates/skills/verify/SKILL.md

@@ -30,6 +30,9 @@ related:
   - type: file
     path: .claude/skills/verify/phases/backfill.md
     role: "How to draft a ## Verify Plan section for a pending action"
+  - type: file
+    path: .claude/skills/verify/phases/recipes.md
+    role: "Testability gotchas (dnd-kit drag, dynamic file inputs, hash routing) and their workarounds"
   - type: file
     path: cabinet/_briefing.md
     role: "Project identity and configuration"
@@ -125,8 +128,15 @@ scenario change.
 
 1. Check if `e2e/` exists in the project root. If not, recommend
    `/verify learn` and exit.
-2. Run `npm run verify` from the project's `e2e/` dir.
-3. Surface the output. If failures or I-verdicts landed, suggest
+2. **Test-isolation nudge.** If `e2e/` exists but `e2e/start-test-stack.sh`
+   does not — and the project's dev stack is suspected to write to a
+   real DB (signal: `package.json` references a single `data/`,
+   `db/`, or similar shared persistence path) — surface a one-line
+   note before running: *"No isolated test stack detected. Scenarios
+   will run against your dev stack. Run `/verify learn` to generate
+   an isolation scaffold if your dev DB matters."* Do not block.
+3. Run `npm run verify` from the project's `e2e/` dir.
+4. Surface the output. If failures or I-verdicts landed, suggest
    `npm run report:last` to triage.
 
 This mode is intentionally thin — the harness is the value, not
@@ -155,8 +165,12 @@ The "learn" flow runs four phases:
    question at a time. Examples: "I see admin routes but only one admin
    user — real persona or fold into main?", "Should the fresh-user
    flow be its own scenario or part of admin?", "What's the dev stack
-   URL for preflight?". Do NOT batch questions — one at a time per
-   project convention.
+   URL for preflight?". Calibrate also includes a **test-isolation
+   probe** — if the project's dev stack writes to a real DB, the
+   skill captures the DB path, dev-server proxy config, and test
+   stack ports so install.sh can emit an `e2e/start-test-stack.sh`
+   scaffold. Do NOT batch questions — one at a time per project
+   convention.
 
 4. **Generate** (read `phases/generate.md`): write the `.feature`
    files using the template in `phases/scenario-template.md` plus
@@ -221,14 +235,25 @@ once the action runs. Backfill only adds the planning artifact so
 | `update.md` | Default: action fid / diff / free-text dispatch | How change descriptions map to edits |
 | `scenario-template.md` | Default: Gherkin with cost+role tags, NN.NN checkIds | Project-specific scenario shape |
 | `backfill.md` | Default: interview-driven Verify Plan section drafting | Project-specific backfill questions |
+| `recipes.md` | Default: dnd-kit, dynamic file input, hash routing gotchas | Project-specific testability recipes |
 
 ## Principles
 
 - **One question at a time.** Calibrate phase NEVER batches questions
   (per CLAUDE.md global convention). Each answer shapes the next.
-- **≤5 scenarios on initial draft.** Force calibration before
-  expansion. Adding scenarios later is cheap; removing scenarios
-  the user didn't ask for is expensive (per process-therapist).
+- **≤5 scenarios on initial draft (cabinet-qa cap).** Force calibration
+  before expansion. Adding scenarios later is cheap; removing scenarios
+  the user did not ask for is expensive (per process-therapist). The
+  cap is load-bearing; do not loosen it without an audit-grade reason.
+- **Depth-first, not shallow-first.** A scenario that touches a
+  surface but verifies nothing is worse than no scenario at all —
+  it occupies a slot in the catalogue and creates a false sense of
+  coverage. The first lap through a scenario should produce real
+  assertions and human-verdict pauses for the parts that genuinely
+  need subjective judgment. If a step can not be exercised (a
+  testability gotcha — see `phases/recipes.md`), file a finding
+  against the consuming project and mark the step "skip until
+  testable" rather than emitting a no-op stub.
 - **cabinet-qa owns "what's worth a scenario".** /verify learn
   delegates that judgment via subagent; it doesn't re-derive it.
 - **The .feature file is the spec.** Anyone (user, future Claude,