create-claude-cabinet 0.25.1 → 0.25.3

package/lib/cli.js

@@ -463,6 +463,7 @@ const MODULES = {
       'skills/plan/phases/verify-plan.md',
       'skills/execute/phases/verify-emit.md',
       'skills/debrief/phases/verify-coverage.md',
+      'skills/orient/phases/verify-backfill.md',
     ],
     postInstall: 'verify-setup',
   },
@@ -874,6 +875,7 @@ async function run() {
         const alwaysCopyPhases = [
           'skills/onboard', 'skills/seed',
           'skills/cc-upgrade', 'skills/cc-extract',
+          'skills/verify',
         ];
         const isSkill = tmpl.startsWith('skills/') && !alwaysCopyPhases.some(p => tmpl.startsWith(p));
         const results = await copyTemplates(srcPath, destPath, {
@@ -909,6 +911,19 @@ async function run() {
             continue;
           }
 
+          // Phase file customization guard — mirrors copy.js:48-59 for the
+          // single-file install path. If the destination path is a phase
+          // file and the on-disk content differs from upstream (operator
+          // edited it), preserve it. This keeps the documented "customize
+          // by editing the phase file" affordance intact across upgrades.
+          const isPhaseFile = tmpl.includes('/phases/') || tmpl.includes('\\phases\\');
+          if (isPhaseFile && existingContent.trim() !== '' && existingContent.trim() !== incoming.trim()) {
+            console.log(`  Preserved customized phase: ${tmpl}`);
+            totalSkipped++;
+            allManifest[mPath] = hashContent(existingContent);
+            continue;
+          }
+
           if (flags.yes || dirState === 'existing-install') {
             // If file is in the old manifest, it's upstream-managed — overwrite.
             // If not, it's project-created — skip.

package/package.json

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

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

@@ -0,0 +1,108 @@
+# Verify-Plan Backfill
+
+**Contract: v0.x soft — may change before v1.0.** This phase is part
+of the `/verify` integration with `/orient`. Customization phase
+(opt-in), copied into your project only when the `verify` module is
+selected during `npx create-claude-cabinet`.
+
+**Runs:** after work-scan, before briefing. Pairs with
+[verify-coverage on /debrief] — verify-coverage catches drift on
+acts that already shipped; this phase catches the same gap on the
+*front* end, at planning time, on acts still pending.
+
+## What this phase does
+
+Surfaces pending plans in pib-db whose surface area touches UI but
+whose notes lack a `## Verify Plan` section. Advisory only — never
+auto-modifies an action. The operator decides whether to re-plan the
+act (adding the section) or accept the drift.
+
+## No-op guards
+
+This phase exits silently in two cases — checked in order:
+
+1. **The project has no `e2e/features/` directory.** Without the
+   runtime installed, there are no feature files to be out of sync
+   with. Skip.
+2. **No pending actions match the UI heuristic.** No Attention Items
+   entry, no warning.
+
+Detection for guard 1:
+
+```bash
+test -d e2e/features
+```
+
+If either guard trips, skip the phase entirely. No briefing line.
+
+## Detection algorithm
+
+1. **Query pib-db for pending UI-touching actions without a Verify
+   Plan section.** The default heuristic matches the surface-area path
+   patterns used by `verify-coverage.md`:
+
+   ```sql
+   SELECT fid, text, notes FROM actions
+   WHERE completed = 0
+     AND deleted_at IS NULL
+     AND (
+       notes LIKE '%webapp/frontend/%'
+       OR notes LIKE '%components/%'
+       OR notes LIKE '%pages/%'
+       OR notes LIKE '%app/%'
+     )
+     AND notes NOT LIKE '%## Verify Plan%'
+   ORDER BY created ASC;
+   ```
+
+   Run via `node scripts/pib-db.mjs query "<sql>"` or, if the project
+   has a `phases/ui-paths.md` override, substitute those paths.
+
+2. **Per match, judge whether it really is UI-touching.** The path
+   heuristic over-matches (e.g., an action that merely mentions
+   `webapp/frontend/` in a passing comment). Read the action's
+   `## Surface Area` section if present and confirm the listed files
+   include a UI path. If not, drop the match silently.
+
+3. **Cap at 5 entries.** If more than 5 match, list the 5
+   oldest-created and append a "(+N more — run /pulse for full list)"
+   note. Don't dump 20 entries into the orient briefing.
+
+## Output
+
+For each remaining match, emit one Attention Items entry:
+
+> **`<fid>`** — `<action text>`
+>   Pending plan touches UI but lacks a `## Verify Plan` section.
+>   Suggest: `/verify backfill <fid>` to draft the section interactively,
+>   or accept drift — `/debrief` will flag this act on completion if
+>   it ships uncovered.
+
+The entries go in the briefing's **Attention Items** section,
+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 file new actions or projects.
+- It does not block orient. Even with 5 backfill candidates, orient
+  completes; the Attention Items accumulate.
+- It does not look at *completed* acts — that's verify-coverage's job
+  on `/debrief`.
+
+## Tuning to reduce false positives
+
+Two common refinements:
+
+1. **Path override.** A project's `phases/ui-paths.md` (if defined)
+   replaces the default path list. See `verify-coverage.md` for the
+   same pattern.
+2. **Per-act opt-out.** An action can declare in its notes that it's
+   intentionally backend-only:
+   ```
+   ## Verify Coverage
+   Skip: this change is internal — no UI behavior changed.
+   ```
+   This phase reads that line and skips the act, same as
+   verify-coverage does.

package/templates/skills/verify/SKILL.md

@@ -4,9 +4,10 @@ description: |
   Walkthrough verification harness. Cucumber + Playwright scenarios with
   human-in-the-loop verdict pauses (P/I/S/N) for subjective checks.
   Subcommands: bare (run the suite), 'learn' (bootstrap from cold start),
-  'update <change>' (sync feature files to a code change). Use when:
-  "verify", "/verify", "/verify learn", "/verify update", "run walkthrough",
-  "verify scenarios", after a multi-PR umbrella ships.
+  'update <change>' (sync feature files to a code change), 'backfill <fid>'
+  (add a Verify Plan section to a pending action's notes). Use when:
+  "verify", "/verify", "/verify learn", "/verify update", "/verify backfill",
+  "run walkthrough", "verify scenarios", after a multi-PR umbrella ships.
 related:
   - type: file
     path: .claude/skills/verify/phases/discover.md
@@ -26,10 +27,13 @@ related:
   - type: file
     path: .claude/skills/verify/phases/scenario-template.md
     role: "Gherkin scenario template (cost+role tags, NN.NN checkIds)"
+  - type: file
+    path: .claude/skills/verify/phases/backfill.md
+    role: "How to draft a ## Verify Plan section for a pending action"
   - type: file
     path: cabinet/_briefing.md
     role: "Project identity and configuration"
-argument-hint: "subcommand — 'learn', 'update <change>', or empty to run"
+argument-hint: "subcommand — 'learn', 'update <change>', 'backfill <fid>', or empty to run"
 user-invocable: true
 standing-mandate: []
 ---
@@ -47,6 +51,13 @@ If `$ARGUMENTS` is provided:
   extending an existing scenario set.
 - **'update <change-description>'**: Sync feature files to a code change.
   The change can be a pib-db action fid, a diff snippet, or free-text.
+- **'backfill <fid>'**: Add a `## Verify Plan` section to a pending action's
+  notes. For actions that were planned before the verify module existed,
+  or planned without Verify Plan questions surfaced. Reads the existing
+  notes, interviews the user one question at a time about UI surface and
+  feature-file edits, drafts the section, and appends via
+  `pib_update_action`. Does NOT modify feature files — that's `/execute`'s
+  job at action ship time.
 
 ## Purpose
 
@@ -175,6 +186,30 @@ may want a new scenario, not an edit to an existing one).
 The proposed edits are presented inline. User approves, the skill
 writes them.
 
+### Mode D: `/verify backfill <fid>` — add Verify Plan to pending action
+
+Read `phases/backfill.md` for the full flow. Brief overview:
+
+1. **Load the action.** Call `pib_get_action <fid>`. Read the
+   action's `text` and `notes` (especially the `## Surface Area`
+   section). Confirm the action is pending (`completed = 0`) — if
+   already shipped, redirect the user to `/verify update <fid>`.
+2. **Read existing feature files.** `ls e2e/features/*.feature` so
+   the interview can reference real scenarios and checkIds.
+3. **Interview, one question at a time.** Per CLAUDE.md global
+   convention. Walk the user through: which features need edits,
+   what verb (ADD/MODIFY/REMOVE/NEW), what anchor or scenario name.
+4. **Draft the section.** Format matches `verify-plan.md`'s output
+   spec (one `- features/<file>.feature:` line per entry).
+5. **Show the diff.** Display the action's current notes alongside
+   the proposed appended section.
+6. **Confirm + write.** On approval, call `pib_update_action` with
+   the augmented notes. Without approval, exit without changes.
+
+This mode does NOT modify feature files. That's `/execute`'s job
+once the action runs. Backfill only adds the planning artifact so
+`/execute`'s `verify-emit` phase has something to read.
+
 ## Phase Summary
 
 | Phase | Absent = | What it customizes |
@@ -185,6 +220,7 @@ writes them.
 | `generate.md` | Default: write .feature + step stubs from calibrated draft | Generation rules (collision handling, naming) |
 | `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 |
 
 ## Principles
 

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

@@ -0,0 +1,164 @@
+# Backfill — add a Verify Plan section to a pending action
+
+Default behavior for `/verify backfill <fid>`. The mode adds a
+`## Verify Plan` section to a pending pib-db action's notes so
+`/execute`'s `verify-emit` phase can read it later. Does NOT touch
+feature files — that's `/execute`'s job at action ship time.
+
+## Inputs
+
+- A pib-db action fid (`act:abc12345`). Passed as `$ARGUMENTS` to
+  `/verify backfill`. If missing or malformed, ask the user for
+  it; don't guess from context.
+
+## Preconditions
+
+1. The action exists. If `pib_get_action <fid>` returns nothing,
+   exit with "no action found for <fid>".
+2. The action is pending (`completed = 0`). If already shipped,
+   tell the user: "act:<fid> already shipped on <date>. To sync
+   feature files retroactively, use `/verify update <fid>` instead."
+3. The action's notes don't already have a `## Verify Plan` section.
+   If they do, ask: "act:<fid> already has a Verify Plan section.
+   Replace it or skip?"
+4. `e2e/features/` exists. If not, recommend `/verify learn` first.
+
+## Workflow
+
+### 1. Load and summarize
+
+Print:
+
+```
+Backfilling Verify Plan for act:abc12345 — <action text>
+
+Current Surface Area (from notes):
+  - files: webapp/frontend/src/components/Foo.tsx
+  - files: webapp/frontend/src/hooks/useFoo.ts
+```
+
+If no Surface Area section is found, say so and proceed to step 2 —
+the user may want to add one inline.
+
+### 2. Show available feature files
+
+```
+e2e/features/:
+  01-desktop-rewrite.feature      (@api-small, @as-user)
+  02-browse-history.feature       (@free, @as-user)
+  04-admin-spot-check.feature     (@free, @as-admin)
+  ...
+```
+
+Read the first two lines of each `.feature` file to surface its
+tags. Skip features tagged `@manual` from suggestions unless the
+action explicitly mentions iOS/mobile.
+
+### 3. Interview, one question at a time
+
+Per CLAUDE.md global convention — never batch. Each answer shapes
+the next question. Typical sequence:
+
+**Q1 — surface area mapping.**
+
+> "act:abc12345 touches webapp/frontend/src/components/Foo.tsx.
+> Which feature file(s) exercise that component or the route it
+> renders on?"
+
+Wait for answer. If unclear, propose candidates based on:
+- The action's notes mentioning a route (`/admin`, `/history`)
+- The scenario names in `e2e/features/`
+- Cabinet-qa subagent if multiple plausible matches
+
+**Q2 — edit verb.**
+
+For each chosen feature file, ask:
+
+> "For features/04-admin-spot-check.feature, what kind of edit?
+>   - ADD step after an existing anchor
+>   - MODIFY an existing step's assertion
+>   - NEW scenario in a new file
+>   - REMOVE a step (for deprecations)"
+
+Wait for answer.
+
+**Q3 — specifics.**
+
+Depending on the verb, follow up:
+- **ADD step after <anchor>**: "What's the anchor checkId, and what
+  should the new step assert?"
+- **MODIFY step <checkId>**: "Which step? What should the new
+  assertion text say?"
+- **NEW scenario**: "Scenario name? Tags (cost + role)? Brief
+  description of the journey?"
+- **REMOVE step <checkId>**: "Which checkId? Confirm — removed
+  steps invalidate prior verdicts."
+
+Wait for answer.
+
+**Repeat Q1–Q3** for each additional feature file the action
+touches. After the user signals "that's all," proceed.
+
+### 4. Draft the section
+
+Format matches `verify-plan.md`'s output spec exactly so
+`verify-emit` parses it identically to plan-time output:
+
+```markdown
+## Verify Plan
+
+- features/04-admin-spot-check.feature: ADD step after the existing
+  "admin-history-list-loads" check — verify the new "balance owed"
+  column renders for users with outstanding refunds (4.12b
+  admin-balance-owed-column).
+- features/14-downloaded-files.feature: (deferred) NEW scenario for
+  the bulk-download flow — requires Phase B framework migration to
+  ship first.
+```
+
+Edit verbs: `ADD step after <anchor>`, `MODIFY step <checkId>`,
+`NEW scenario`, `REMOVE step <checkId>`. Use `(deferred)` prefix
+for entries that depend on other work.
+
+### 5. Show the diff
+
+Display:
+
+```
+Existing notes:
+─────────────
+<truncated existing notes — last 20 lines>
+
+Proposed appended section:
+──────────────────────────
+## Verify Plan
+
+<the drafted section from step 4>
+```
+
+### 6. Confirm and write
+
+> "Append this Verify Plan section to act:abc12345's notes? (y/n)"
+
+If yes:
+- Call `pib_update_action <fid> --notes "<existing_notes>\n\n<new_section>"`
+- Confirm: "Updated act:abc12345 with Verify Plan (N entries)."
+
+If no:
+- Exit without changes.
+
+## Out of scope
+
+- Modifying feature files. That's `/execute`'s `verify-emit` phase
+  when the action runs.
+- Re-running the full /plan flow (acceptance criteria, surface area,
+  cabinet review). Backfill is narrow — Verify Plan section only.
+- Creating new actions. The action already exists by definition.
+
+## When to escalate to a full /plan
+
+If the interview reveals the action is mis-scoped — e.g., the user
+realizes the surface area listed in the notes is wrong — recommend
+re-planning the whole action via `/plan` instead. Backfill is only
+useful when the action's scope and surface area are correct and
+just the Verify Plan layer is missing.