create-claude-cabinet 0.24.0 → 0.25.1

package/README.md

@@ -5,7 +5,7 @@ gives Claude a memory, 31 domain experts, a planning process, and the
 habit of starting sessions informed and ending them properly.
 
 Built by a guy who'd rather talk to Claude than write code. Most of it
-was built by Claude. I just complained until it worked.
+was built by Claude. I just complained until it (mostly) worked.
 
 ## The Idea
 
@@ -63,8 +63,8 @@ automatically.
 
 - **`/orient`** — open every session with this. Claude reads project
   state, checks health, surfaces what needs attention, and briefs you
-  so you never start blind. Think of it as the morning briefing before
-  the cabinet gets to work.
+  so you never start blind. Think of it as the briefing before the
+  cabinet gets to work.
 - **`/debrief`** — close every session with this. Claude marks work
   done, records lessons, updates state, and prepares the briefing for
   next time. Without debrief, the next orient starts with stale
@@ -134,7 +134,7 @@ hooks — things that keep going wrong become things that can't go wrong.
 
 ## Your Workflow
 
-The day-to-day rhythm:
+The rhythm of each session:
 
 1. **Start a session** → `/orient` (get briefed)
 2. **Do your work** → talk to Claude, use `/plan` for anything non-trivial
@@ -227,7 +227,7 @@ other.
 ## Philosophy
 
 This started as the process layer of [Flow](https://github.com/orenmagid/flow),
-a cognitive workspace built on Claude Code over months of daily use. The
+a cognitive workspace built on Claude Code over months of intensive use. The
 patterns that emerged — the session loop, cabinet-style audits, feedback
 enforcement — turned out to be transferable to any project.
 

package/lib/cli.js

@@ -8,6 +8,7 @@ const { mergeSettings } = require('./settings-merge');
 const { create: createMetadata, read: readMetadata } = require('./metadata');
 const { setupDb } = require('./db-setup');
 const { setupOmega } = require('./omega-setup');
+const { setupVerifyRuntime } = require('./verify-setup');
 const { reset } = require('./reset');
 
 const VERSION = require('../package.json').version;
@@ -451,6 +452,20 @@ const MODULES = {
     needsOmega: true,
     templates: ['skills/memory', 'scripts/cabinet-memory-adapter.py', 'scripts/migrate-memory-to-omega.py', 'rules/memory-capture.md', 'hooks/omega-memory-guard.sh'],
   },
+  'verify': {
+    name: 'Verification Harness (Cucumber + Playwright)',
+    description: 'Walkthrough verification with human-in-the-loop verdict pauses. Replaces flat AC lists with re-runnable user-journey scenarios. Includes /verify skeleton skill + cabinet-verify npm runtime + opt-in integration phases for /plan, /execute, /debrief.',
+    mandatory: false,
+    default: false,
+    lean: false,
+    templates: [
+      'skills/verify',
+      'skills/plan/phases/verify-plan.md',
+      'skills/execute/phases/verify-emit.md',
+      'skills/debrief/phases/verify-coverage.md',
+    ],
+    postInstall: 'verify-setup',
+  },
 };
 
 /** Recursively collect all relative file paths under a directory. */
@@ -504,7 +519,8 @@ function parseArgs(argv) {
     targetDir: '.',
   };
 
-  for (const arg of args) {
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
     if (arg === '--yes' || arg === '-y') flags.yes = true;
     else if (arg === '--lean') flags.lean = true;
     else if (arg === '--no-db') flags.noDb = true;
@@ -512,6 +528,9 @@ function parseArgs(argv) {
     else if (arg === '--help' || arg === '-h') flags.help = true;
     else if (arg === '--reset') flags.reset = true;
     else if (arg === '--force') flags.force = true;
+    else if (arg === '--modules' && i + 1 < args.length) {
+      flags.modules = args[++i].split(',').map(s => s.trim()).filter(Boolean);
+    }
     else if (!arg.startsWith('-')) flags.targetDir = arg;
   }
 
@@ -526,6 +545,8 @@ function printHelp() {
     --yes, -y     Accept all defaults, no prompts
     --lean        Install core modules only (no work-tracking, compliance, validate)
     --no-db       Skip work tracking database setup
+    --modules <keys>  Comma-separated module keys to install (e.g., 'verify,memory').
+                  Mandatory modules are always included.
     --dry-run     Show what would be copied without writing
     --reset       Remove Claude Cabinet files (uses manifest for safety)
     --force       With --reset: remove even customized files
@@ -665,7 +686,45 @@ async function run() {
   let skippedModules = {};
   let includeDb = !flags.noDb;
 
-  if (flags.lean) {
+  if (flags.modules) {
+    // Explicit module selection via --modules <key1,key2,...>. Mandatory
+    // modules are always included regardless of the flag value, so the
+    // installer always has session-loop etc. available.
+    //
+    // On an upgrade (existing .ccrc.json present), --modules is treated
+    // ADDITIVELY: the requested keys are merged with whatever the
+    // existing installation already had enabled. Otherwise an `--modules
+    // verify` invocation on a project with 9 enabled modules would
+    // silently deregister 8 of them. Replacing the existing set on
+    // upgrade is almost never what the operator wants. (Fresh installs
+    // unchanged — there's no prior set to merge with.)
+    const mandatoryKeys = Object.entries(MODULES)
+      .filter(([, mod]) => mod.mandatory)
+      .map(([key]) => key);
+    const requested = flags.modules.filter(k => MODULES[k]);
+    const unknown = flags.modules.filter(k => !MODULES[k]);
+    if (unknown.length > 0) {
+      console.log(`  ⚠ Unknown modules ignored: ${unknown.join(', ')}`);
+      console.log(`    Known modules: ${Object.keys(MODULES).join(', ')}`);
+    }
+    let existingEnabled = [];
+    if (dirState === 'existing-install') {
+      const existing = readMetadata(projectDir);
+      existingEnabled = Object.entries(existing.modules || {})
+        .filter(([k, enabled]) => enabled && MODULES[k])
+        .map(([k]) => k);
+      if (existingEnabled.length > 0) {
+        console.log(`  Existing modules carried forward: ${existingEnabled.join(', ')}`);
+      }
+    }
+    selectedModules = [...new Set([...mandatoryKeys, ...existingEnabled, ...requested])];
+    const skippedKeys = Object.keys(MODULES).filter(k => !selectedModules.includes(k));
+    for (const k of skippedKeys) {
+      skippedModules[k] = `Skipped by --modules flag`;
+    }
+    if (!selectedModules.includes('work-tracking')) includeDb = false;
+    console.log(`  Installing modules: ${selectedModules.join(', ')}\n`);
+  } else if (flags.lean) {
     selectedModules = Object.entries(MODULES)
       .filter(([, mod]) => mod.mandatory || mod.lean)
       .map(([key]) => key);
@@ -955,6 +1014,26 @@ async function run() {
     }
   }
 
+  // --- Run module postInstall hooks ---
+  // Modules with a `postInstall` field dispatch to a matching setup
+  // function after templates are copied. Currently only 'verify-setup'
+  // (the cabinet-verify tarball builder) is wired.
+  for (const moduleKey of selectedModules) {
+    const mod = MODULES[moduleKey];
+    if (!mod.postInstall) continue;
+    if (mod.postInstall === 'verify-setup') {
+      try {
+        console.log('');
+        const verifyResult = setupVerifyRuntime({ dryRun: !!flags.dryRun });
+        for (const r of verifyResult.results || []) console.log(`  📋 ${r}`);
+      } catch (err) {
+        console.log(`  ⚠ cabinet-verify runtime setup failed: ${err.message}`);
+        console.log('    /verify install.sh will fail until the runtime is installed.');
+        console.log('    Re-run the installer to retry.');
+      }
+    }
+  }
+
   // --- Manifest key migration (act:d1f16bee) ---
   // When CC renames directories (e.g., perspectives/ → cabinet-*/), old manifest
   // keys no longer match new template paths. Migrate keys BEFORE cleanup so the

package/lib/verify-setup.js

@@ -0,0 +1,140 @@
+/**
+ * verify-setup.js — install the cabinet-verify runtime tarball at
+ * ~/.claude-cabinet/verify/<version>/dist/.
+ *
+ * Mirrors the omega-setup.js pattern: dispatched from cli.js's install
+ * pipeline when the `verify` module is selected. Idempotent: skips if
+ * the matching-version tarball is already present.
+ *
+ * See templates/verify-runtime/CONVENTIONS.md §Install Dir and
+ * §Tarball Install Pattern for the frozen contract this implements.
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const CC_HOME = path.join(os.homedir(), '.claude-cabinet');
+const VERIFY_BASE = path.join(CC_HOME, 'verify');
+
+/**
+ * Set up the cabinet-verify runtime.
+ *
+ * Steps:
+ * 1. Read the version from templates/verify-runtime/package.json
+ * 2. Compute installDir = ~/.claude-cabinet/verify/<version>/dist/
+ * 3. If a tarball already exists at that path with the same version,
+ *    log "already installed" and skip
+ * 4. Otherwise: mkdir -p installDir; npm pack inside templates/verify-runtime/;
+ *    move the .tgz to installDir
+ * 5. Write ~/.claude-cabinet/verify/current/VERSION (single-line pointer
+ *    used by /verify install.sh per CONVENTIONS.md Version Resolution)
+ *
+ * @param {Object} opts
+ * @param {boolean} [opts.dryRun] — print planned actions, don't execute
+ * @param {string} [opts.runtimeSourceDir] — override the templates/verify-runtime/
+ *   location. Defaults to <repo>/templates/verify-runtime/ resolved from __dirname.
+ * @returns {Object} { installPath, version, status: 'installed'|'skipped'|'dry-run' }
+ */
+function setupVerifyRuntime(opts = {}) {
+  const dryRun = !!opts.dryRun;
+  const runtimeSourceDir =
+    opts.runtimeSourceDir || path.resolve(__dirname, '..', 'templates', 'verify-runtime');
+
+  // 1. Read version
+  const packageJsonPath = path.join(runtimeSourceDir, 'package.json');
+  if (!fs.existsSync(packageJsonPath)) {
+    throw new Error(
+      `verify-setup: ${packageJsonPath} not found. Cannot resolve cabinet-verify version.`,
+    );
+  }
+  const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+  const version = pkg.version;
+  if (typeof version !== 'string' || version.length === 0) {
+    throw new Error(`verify-setup: ${packageJsonPath} has no version field`);
+  }
+
+  // 2. Compute installDir
+  const installDir = path.join(VERIFY_BASE, version, 'dist');
+  const tarballName = `cabinet-verify-${version}.tgz`;
+  const tarballPath = path.join(installDir, tarballName);
+  const versionPointer = path.join(VERIFY_BASE, 'current', 'VERSION');
+
+  const results = [];
+
+  if (dryRun) {
+    results.push(`Would install cabinet-verify@${version}`);
+    results.push(`  source:  ${runtimeSourceDir}`);
+    results.push(`  target:  ${tarballPath}`);
+    results.push(`  pointer: ${versionPointer}`);
+    return { installPath: installDir, version, status: 'dry-run', results };
+  }
+
+  // 3. Idempotency check. Existence alone is not enough — an earlier
+  // stub-touch (e.g., a test fixture) can leave a 0-byte file at the
+  // tarball path. npm install on the consumer side then fails with
+  // ENODATA / TAR_BAD_ARCHIVE. Validate the file has non-trivial size
+  // before treating it as installed.
+  if (fs.existsSync(tarballPath) && fs.statSync(tarballPath).size > 1024) {
+    results.push(`cabinet-verify@${version} already installed (${tarballPath})`);
+    // Even on skip, ensure the VERSION pointer is up-to-date so a later
+    // version downgrade doesn't leave a stale pointer behind.
+    writeVersionPointer(versionPointer, version);
+    results.push(`Updated VERSION pointer: ${versionPointer}`);
+    return { installPath: installDir, version, status: 'skipped', results };
+  }
+
+  // Remove a 0-byte stub before re-packing so the move below doesn't
+  // hit a "file exists" surprise.
+  if (fs.existsSync(tarballPath)) {
+    fs.unlinkSync(tarballPath);
+  }
+
+  // 4. mkdir + npm pack + move
+  fs.mkdirSync(installDir, { recursive: true });
+  // Run npm pack in the runtime source dir. --pack-destination writes
+  // the tarball directly to installDir without an intermediate cwd move.
+  const packStdout = execSync(`npm pack --silent --pack-destination "${installDir}"`, {
+    cwd: runtimeSourceDir,
+    encoding: 'utf8',
+  }).trim();
+
+  // npm pack prints the tarball filename to stdout on the last non-empty line.
+  // Normalise to the expected name so consuming projects can rely on the
+  // CONVENTIONS.md-documented path.
+  const lastLine = packStdout.split('\n').filter(Boolean).pop() || '';
+  const producedName = path.basename(lastLine);
+  if (producedName && producedName !== tarballName) {
+    // npm pack may produce a name like 'cabinet-verify-0.1.0.tgz' that already
+    // matches; if it doesn't (e.g., npm prefixes with @scope/), rename to match.
+    const producedPath = path.join(installDir, producedName);
+    if (fs.existsSync(producedPath)) {
+      fs.renameSync(producedPath, tarballPath);
+    }
+  }
+
+  if (!fs.existsSync(tarballPath)) {
+    throw new Error(
+      `verify-setup: npm pack completed but ${tarballPath} not found. ` +
+        `stdout was: ${packStdout.slice(0, 500)}`,
+    );
+  }
+
+  results.push(`Installed cabinet-verify@${version} to ${tarballPath}`);
+
+  // 5. Write VERSION pointer
+  writeVersionPointer(versionPointer, version);
+  results.push(`Wrote VERSION pointer: ${versionPointer}`);
+
+  return { installPath: installDir, version, status: 'installed', results };
+}
+
+function writeVersionPointer(pointerPath, version) {
+  fs.mkdirSync(path.dirname(pointerPath), { recursive: true });
+  // No trailing newline — CONVENTIONS.md frozen contract requires the
+  // file to equal the version string exactly under `cat`.
+  fs.writeFileSync(pointerPath, version, 'utf8');
+}
+
+module.exports = { setupVerifyRuntime };

package/package.json

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

package/templates/skills/debrief/phases/verify-coverage.md

@@ -0,0 +1,101 @@
+# /debrief integration with cabinet-verify — verify-coverage phase
+
+**Contract: v0.x soft — may change before v1.0.** This phase enables
+the `/verify` integration with `/debrief`. It is a customization phase
+(opt-in), copied into your project only when the `verify` module is
+selected during `npx create-claude-cabinet`.
+
+## What this phase does
+
+At session close, scan the acts shipped during the session window.
+For each act that touched UI code, check whether a feature-file edit
+landed in the same git commit window. If not, warn — drift risk:
+the product changed but the scenarios didn't.
+
+This is the safety net for the `/plan` + `/execute` integration. The
+upstream phases TRY to keep features in sync during the session;
+this phase catches the cases where they failed or weren't invoked.
+
+## No-op guard
+
+The phase should exit silently if the project has no `e2e/features/`
+directory.
+
+```bash
+test -d e2e/features
+```
+
+Without the runtime installed, there's nothing to be out of sync with.
+
+## When this phase runs
+
+Position: during `/debrief`'s inventory phase, after acts have been
+enumerated, before the briefing is presented to the user. The warning
+appears in the **Attention Items** section of the debrief output.
+
+## Detection algorithm
+
+1. **Establish the session window.** The session-start git sha is
+   captured at orient (or, lacking that, the most recent commit
+   before the first session action). HEAD is the end of the window.
+2. **List feature-file edits in the window.**
+   ```bash
+   git diff --name-only <session-start-sha>..HEAD | grep '\.feature$'
+   ```
+3. **List shipped acts.** Query pib-db for actions completed during
+   the session:
+   ```bash
+   node scripts/pib-db.mjs query "SELECT fid, text, notes FROM actions WHERE completed = 1 AND completed_at >= '<session-start-iso>'"
+   ```
+4. **For each shipped act, decide whether it was UI-touching.** Look
+   at the act's notes' Surface Area section. If the surface includes
+   any of:
+   - `webapp/frontend/`, `app/`, `pages/`, `components/`
+   - paths matching project-specific UI conventions (read
+     `phases/ui-paths.md` if defined; otherwise use the default
+     heuristic above)
+
+   then it's UI-touching.
+5. **For each UI-touching act, check if any feature file in the
+   diff overlaps with the act's surface area or description.** If
+   not, the act is "uncovered."
+
+## Warning format
+
+For each uncovered UI act, emit one Attention Items entry:
+
+> **Act <fid> shipped without a feature-file update — drift risk.**
+> The act touched [paths] but no `.feature` file changed in the same
+> session window. Consider:
+>   - `/verify update <fid>` to propose the matching scenario edits
+>   - Or accept the drift if the change isn't user-visible enough to
+>     warrant a scenario update.
+
+Advisory only — debrief still completes. The user decides whether to
+run `/verify update` immediately or defer.
+
+## Tuning to reduce false positives
+
+The default heuristic over-warns. Two common refinements:
+
+1. **Path filter.** Project-specific UI paths in `phases/ui-paths.md`
+   (if defined) override the default heuristic. For example, a project
+   where `app/` is the framework's app dir (server-side rendering)
+   but `webapp/frontend/` is the SPA might only count the latter.
+2. **Per-act opt-out.** An act can declare in its notes that it's a
+   "no-feature-edit-needed" act:
+   ```
+   ## Verify Coverage
+   Skip: this change is internal — no UI behavior changed.
+   ```
+   The phase reads this and skips the act.
+
+## What this phase does NOT do
+
+- It does not file an action for the uncovered act. The user runs
+  `/verify update` (or chooses to ignore) at their discretion.
+- It does not block debrief. Even with 10 uncovered acts, debrief
+  completes — the warnings just accumulate in the Attention Items
+  section.
+- It does not run the verification suite (`npm run verify`). That's
+  the user's call after they decide whether to update scenarios.

package/templates/skills/execute/phases/verify-emit.md

@@ -0,0 +1,104 @@
+# /execute integration with cabinet-verify — verify-emit phase
+
+**Contract: v0.x soft — may change before v1.0.** This phase enables
+the `/verify` integration with `/execute`. It is a customization phase
+(opt-in), copied into your project only when the `verify` module is
+selected during `npx create-claude-cabinet`.
+
+## What this phase does
+
+When `/execute` runs a plan that contains a `## Verify Plan` section,
+this phase writes the proposed feature-file edits alongside the
+code change in the same execution pass. The goal: feature files
+stay in sync with the product because the edit lands in the same
+commit as the code that motivated it.
+
+## No-op guards
+
+This phase will exit silently in two cases — checked in order:
+
+1. **The loaded plan has no `## Verify Plan` section.** Most plans
+   (backend-only, refactors, deploy configs) won't have one. No warning,
+   no log line.
+2. **The project has no `e2e/features/` directory.** Same as the
+   `/plan` integration phase — without the runtime installed, there
+   are no feature files to edit. Skip entirely.
+
+Detection:
+
+```bash
+test -d e2e/features
+```
+
+Both guards must pass before this phase emits any output or writes
+any files.
+
+## When this phase runs
+
+Position: after the file-group implementation loop, before the
+pre-commit cabinet sweep. The order matters — feature-file edits
+should be in the working tree when cabinet members review the full
+diff, so a security or QA cabinet member sees that the scenarios were
+updated alongside the code.
+
+## How to read the Verify Plan section
+
+Parse the plan notes for `## Verify Plan`. Each entry under the
+heading begins with `- features/<file>.feature:` followed by a verb
+phrase. Verbs the parser recognizes:
+
+- `ADD step after <anchor>` — insert a new step at a specific position
+- `MODIFY step <checkId>` — change an existing step's text
+- `NEW scenario` — create a whole new `.feature` file
+- `REMOVE step <checkId>` — delete a step
+- `(deferred) <anything>` — record but don't write
+
+For each non-deferred entry:
+
+1. Resolve the target file. If it's `NEW scenario`, the file is the
+   one named in the entry (must not exist yet).
+2. Apply the edit. For ADD/MODIFY/REMOVE, parse the surrounding step
+   structure to find the right insertion point. For NEW, write the
+   file using the skeleton from `templates/skills/verify/phases/scenario-template.md`.
+3. Verify the result by re-reading the file. The pathHash of any
+   modified step changes — that's expected (per CONVENTIONS.md the
+   cache will invalidate downstream verdicts).
+
+## AC enforcement
+
+Each Verify Plan entry maps to an implicit acceptance criterion:
+"the feature-file edit was written." If `/execute` finishes its
+implementation loop but a Verify Plan edit didn't land, mark that
+AC unmet in the verification breadcrumb.
+
+The code change itself can still ship — Verify Plan failures are
+acceptance failures, not blockers — but the user sees the unmet AC
+when they review the breadcrumb. The `/debrief` integration's
+`verify-coverage` phase catches this even if the user misses it.
+
+## Failure handling
+
+If a feature-file edit can't be applied (e.g., the anchor step
+described in `ADD step after <anchor>` doesn't exist in the file):
+
+1. Print a warning naming the file, the edit, and the reason
+2. Mark the corresponding AC unmet in the breadcrumb's `deviations`
+   array
+3. Continue with the next entry — don't fail the whole execute pass
+
+The user resolves these in a follow-up `/verify update <fid>` invocation
+after the code change lands.
+
+## NEW scenario handling
+
+When the entry is `NEW scenario`, the feature file must not exist
+yet. If it does, escalate:
+
+> Verify Plan proposes a NEW scenario at features/13-first-time-user.feature
+> but that file already exists. Did you mean ADD step or MODIFY?
+> Skipping this entry — fix the plan and re-run.
+
+NEW scenarios use the scaffolding shape from `phases/scenario-template.md`
+of `/verify`. Pull the template content and substitute the scenario
+name, persona tag, cost tag, and a starter journey from the entry's
+prose.

package/templates/skills/plan/phases/verify-plan.md

@@ -0,0 +1,97 @@
+# /plan integration with cabinet-verify — verify-plan phase
+
+**Contract: v0.x soft — may change before v1.0.** This phase enables
+the `/verify` integration with `/plan`. It is a customization phase
+(opt-in), copied into your project only when the `verify` module is
+selected during `npx create-claude-cabinet`.
+
+## What this phase does
+
+When `/plan` produces a plan involving UI changes, emit a
+`## Verify Plan` section that lists feature-file paths plus proposed
+edits. `/execute` reads this section and writes the feature-file
+edits alongside the code change, so scenarios stay in sync with the
+product.
+
+## No-op guard
+
+Before doing anything, this phase checks for `e2e/features/` in the
+project root. **If the directory is absent, exit silently** — the
+project hasn't installed the `/verify` runtime, and emitting a
+Verify Plan section against scenarios that don't exist would be
+noise.
+
+Detection:
+
+```bash
+test -d e2e/features
+```
+
+If the test fails, skip this phase entirely. No warning, no log line.
+The user installs `/verify` when they're ready; until then, `/plan`
+behaves as if this phase isn't here.
+
+## When to emit a Verify Plan section
+
+Emit the section when the plan's surface area touches UI code. The
+specific signals depend on project conventions; common patterns:
+
+- Modified file path matches `webapp/frontend/src/`, `app/`, `pages/`,
+  or `components/`
+- Plan description mentions a route, a page, a modal, a UI flow
+- Plan changes user-visible behavior (vs. internal refactor, schema
+  migration, deploy config)
+
+If unsure, ask the user during plan drafting: "Does this plan need a
+Verify Plan section? (y/n)". Don't auto-emit on every plan — that
+generates noise for backend-only changes.
+
+## Section format
+
+The `## Verify Plan` section sits alongside the existing
+`## Acceptance Criteria` and `## Surface Area` sections. It lists
+feature-file paths plus proposed edits:
+
+```markdown
+## Verify Plan
+
+- features/01-desktop-rewrite.feature: ADD step after the existing
+  "settings-bar-appears" check — verify the model picker is absent
+  (1.10b model-picker-absent).
+- features/03-multi-tab.feature: MODIFY the "active-run-banner-text"
+  step to assert the new banner copy after Phase B.
+- features/13-first-time-user.feature: NEW scenario — invite roundtrip
+  + empty states for a freshly-signed-up user.
+```
+
+Edit verbs:
+- **ADD step after `<anchor>`** — a new step inserted at a specific
+  position
+- **MODIFY step `<checkId>`** — change an existing step's assertion
+- **NEW scenario** — a whole new `.feature` file
+- **REMOVE step `<checkId>`** — for deprecations
+
+Each entry begins with `- features/<file>.feature:` so the line is
+machine-parseable for `/execute`'s `verify-emit` phase.
+
+## Integration with acceptance criteria
+
+The Verify Plan section is **treated like an AC**: if `/execute`
+fails to write the feature-file edit, the corresponding AC is marked
+unmet. This is enforced by the `verify-emit` phase in `/execute`.
+
+You may explicitly tag a Verify Plan entry as deferred:
+
+```markdown
+- features/05-framework-smoke.feature: (deferred) ADD step for the
+  new framework migration banner — requires the migration to land
+  in webapp first.
+```
+
+Deferred entries are recorded but don't block execution.
+
+## When the plan has no UI surface
+
+Backend-only plans, schema migrations, and infrastructure changes
+don't need a Verify Plan section. Emitting one for them generates
+noise during `/execute`. Use judgment — when in doubt, ask the user.