create-claude-cabinet 0.46.0 → 0.48.0

package/templates/skills/debrief-classic/phases/upstream-feedback.md

@@ -0,0 +1,185 @@
+# Upstream Feedback — Surface CC Friction to the Source
+
+**Position:** Runs after record-lessons (step 9), before skill discovery
+(step 11). Lessons are fresh; friction is top of mind.
+
+**This is an instruction phase** — it tells Claude what to do, not a
+customization point for the project. It ships with CC and should not
+be deleted or replaced with `skip: true`.
+
+## What This Phase Does
+
+During debrief, Claude already has full session context: what was built,
+what went wrong, what was learned. This phase asks Claude to reflect on
+one narrow question: **was there friction with anything CC provided?**
+
+- A skill whose flow didn't match how the project actually works
+- A phase file whose default behavior was wrong or confusing
+- A convention that fought the project's grain
+- A missing capability that required a workaround
+- An unclear SKILL.md that led to wasted time
+
+This is NOT the same as `/cc-extract` (which looks for generalizable
+artifacts to upstream). This is field feedback — "this thing you shipped
+hurt when I used it."
+
+This phase also handles **pattern promotion** — surfacing project-level
+cabinet patterns that look universal enough to promote upstream.
+
+## Workflow
+
+### 1. Claude Reflects (silent)
+
+Review the session for CC-specific friction. Consider:
+
+- Did any CC skill need to be worked around or used in an unintended way?
+- Did a phase file's default behavior cause confusion or extra work?
+- Was a SKILL.md unclear, leading to misinterpretation?
+- Did the skeleton/phase separation feel wrong for something?
+- Was something missing that would have helped?
+- Did orient or debrief surface irrelevant information or miss something important?
+
+If nothing comes to mind — **stop here silently**. Most sessions have
+no CC friction. Do not prompt the user with "any CC feedback?" every
+time. The phase produces nothing and costs nothing unless there's
+something real.
+
+### 2. Draft Feedback (if friction found)
+
+For each friction point, draft a short feedback item:
+
+```
+## [Short title]
+
+**Skill/phase:** [which CC component]
+**Friction:** [what happened — 2-3 sentences max]
+**Suggestion:** [what might be better — optional, can be "not sure"]
+**Session context:** [one line about what the project was doing when this came up]
+```
+
+Keep it concrete. "The plan skill was confusing" is not useful.
+"The plan skill's critique phase activated 4 cabinet members when only 1
+was relevant, adding 3 minutes of noise to every plan" is useful.
+
+### 3. Surface for Confirmation
+
+Include the draft in the debrief report under a distinct heading:
+
+> **Upstream feedback for CC:**
+> I noticed friction with [component]. Here's what I'd send:
+> [draft]
+>
+> Send this upstream? (yes / edit / skip)
+
+The user confirms, edits, or dismisses. One quick decision per item.
+Do not ask open-ended questions. Do not batch — if there are multiple
+friction points (rare), present each separately.
+
+### 4. Deliver
+
+If the user confirms, deliver the feedback. Detection and delivery
+follow the same pattern as `/cc-extract`:
+
+**If this IS the CC source repo** (check: `node -e "const p = require('./package.json'); process.exit(p.name === 'create-claude-cabinet' ? 0 : 1)"` exits 0):
+
+- Write directly to the local `feedback/` directory (create if needed)
+- Filename: `[source-project]-[date]-[short-title].md`
+- This is the dogfood case — the project IS the upstream repo, so
+  feedback goes directly into the local `feedback/` directory.
+
+**If linked** (not the source repo, but CC package resolves to a local
+directory — check if
+`node -e "console.log(require.resolve('create-claude-cabinet'))"`
+points to a local path rather than a `node_modules` path):
+
+- Write the feedback as a markdown file in the CC repo's `feedback/`
+  directory (create it if needed)
+- Filename: `[source-project]-[date]-[short-title].md`
+  (e.g., `flow-2026-04-04-plan-critique-noise.md`)
+- Add frontmatter: `type: field-feedback`, `source: [project]`,
+  `date: [ISO date]`, `component: [skill/phase name]`
+
+**If not linked**, check whether `gh` is available and authenticated
+(`gh auth status` exits 0). Then present the user with their options:
+
+- **If `gh` works**, offer two choices:
+  > "I can send this as a GitHub issue so the developer sees it
+  > directly, or save it locally. Which do you prefer?"
+  >
+  > 1. Send as GitHub issue
+  > 2. Save locally (I'll send it later or pass it along myself)
+
+  If they choose GitHub:
+  - Open a GitHub issue on `orenmagid/claude-cabinet`
+  - Title: `Field feedback: [short title]`
+  - Label: `field-feedback` (create if needed)
+  - Body: the feedback markdown
+
+- **If `gh` is not available** (most common for non-developers):
+  > "I'll save this feedback locally for now. If you want, you can
+  > pass it along to the developer yourself, or set up a free GitHub
+  > account so future feedback goes directly to them. Here's a guide
+  > if you're interested:
+  > https://github.com/orenmagid/claude-cabinet/blob/main/GITHUB-SETUP.md
+  > — totally optional. Your feedback is saved either way."
+
+**For either local save path:**
+
+- Append the feedback to `~/.claude/cc-feedback-outbox.json` as a
+  JSON array entry with fields: `source` (project name), `date`,
+  `component`, `title`, `body`, `status: "pending"`
+- Create the file if it doesn't exist (initialize with `[]`)
+
+**Flushing the outbox:** If a user later sets up `gh` and asks to
+send saved feedback, read the outbox, post each `pending` entry as
+a GitHub issue, and update its status to `"sent"` with the issue URL.
+
+### 5. Check for Pattern Promotion Candidates
+
+After handling CC friction feedback, check for cabinet member patterns
+that should be promoted upstream.
+
+**Scan `patterns-project.md` files:**
+
+```bash
+# Find all project-level pattern files
+find .claude/skills/cabinet-*/patterns-project.md 2>/dev/null
+```
+
+For each file that exists, read it. For each pattern entry, evaluate:
+
+- **Is it universal?** Would this pattern apply to any project using
+  the same technology, or is it specific to this project's domain/codebase?
+- **Is it mature?** Has it been observed 3+ times, or is it still early?
+- **Is it already upstream?** Check the member's SKILL.md `## Historically
+  Problematic Patterns` section — if it's already there, skip it.
+
+**If a promotion candidate is found**, draft a feedback item:
+
+```markdown
+---
+type: pattern-promotion
+source: [project name]
+date: [ISO date]
+component: cabinet-[member-name]
+---
+
+## Pattern promotion: [pattern name]
+
+**Cabinet member:** cabinet-[member-name]
+**Pattern:** [description from patterns-project.md]
+**Occurrences:** [count] across [count] audits
+**Why it's universal:** [1 sentence — why this isn't project-specific]
+```
+
+Deliver via the same mechanism as friction feedback (step 4 above —
+linked → write to CC `feedback/`, not linked → GitHub issue or outbox).
+
+**Most sessions produce no promotion candidates.** Pattern promotion
+is rare — it requires both a mature project-level pattern AND evidence
+that the pattern is universal. Don't force it.
+
+### 6. Done
+
+Note in the debrief report what was sent and where. Move on to the
+next phase.

package/templates/skills/debrief-classic/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/SKILL.md

@@ -90,6 +90,25 @@ Each checkpoint is a chance to stop before the cost of fixing goes up.
 
 ## Workflow
 
+### 0. Worktree-Invocation Contract (core — runs before plan load)
+
+Running `/execute` from a mux/linked git worktree is the **normal case**,
+not an error. **Read `.claude/cabinet/worktree-invocation-contract.md` and
+follow it** — detect a linked worktree, sync main *into* it before reading
+plan/code state, and resolve every completion artifact to the MAIN checkout.
+Two points specific to `/execute`:
+
+- **`/execute` does NOT merge.** The worktree→main bridge is `/qa-handoff`:
+  Step 8's close-out files the handoff and the QA station merges + verifies.
+  Step 0 only syncs main *into* the worktree (so the staleness guard and the
+  checkpoints read current state); it never merges the worktree branch out.
+- **Sync conflict → HALT the whole skill** per the contract (don't
+  auto-resolve, don't implement on a half-synced tree); surface the
+  conflicted-worktree recovery and stop.
+
+On the main checkout the detection no-ops: artifacts resolve to cwd (which
+IS main) and no qa-handoff is filed — `/execute` behaves exactly as before.
+
 ### 1. Load the Plan
 
 Read `phases/load-plan.md` for where your project stores plans and how
@@ -117,8 +136,13 @@ After identifying the action to execute:
 3. Create the verification breadcrumb:
 
 ```bash
-mkdir -p .claude/verification
-cat > .claude/verification/<fid>.json << 'BREADCRUMB'
+# Resolve the MAIN checkout (worktree-invocation contract, Step 0): a
+# worktree's .claude/verification/ is gitignored and lost on cleanup, and the
+# completion-gate hook READS breadcrumbs from MAIN. On the main checkout $MAIN
+# is the cwd, so this line is correct in both places.
+MAIN="$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")"
+mkdir -p "$MAIN/.claude/verification"
+cat > "$MAIN/.claude/verification/<fid>.json" << 'BREADCRUMB'
 {
   "fid": "<fid>",
   "spec_read": true,
@@ -272,7 +296,9 @@ Do not mark the work item complete with failing AC.
 After verifying all ACs, update the breadcrumb:
 
 ```bash
-cat > .claude/verification/<fid>.json << 'BREADCRUMB'
+# Same MAIN checkout as Step 1 (worktree-invocation contract).
+MAIN="$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")"
+cat > "$MAIN/.claude/verification/<fid>.json" << 'BREADCRUMB'
 {
   "fid": "<fid>",
   "spec_read": true,
@@ -310,9 +336,48 @@ deployment strategy is project-specific.
 
 ### 8. Close the Loop
 
-Mark the work item as complete (if your project has a work tracker).
-Run debrief if this was a full session. At minimum, ensure the work
-is committed, validated, and verified before considering it done.
+Mark the work item as complete (if your project has a work tracker) —
+"done" = implemented + committed + breadcrumb-on-main, the same milestone
+`/execute-group` uses. **In a worktree, mark done at commit too** (not
+in-progress): the filed qa-handoff below carries the merge + QA debt, and
+a `qa_verdict` resolves that inbox item, never the work action — leaving
+the action open would orphan it forever. Run debrief if this was a full
+session. At minimum, ensure the work is committed, validated, and verified
+before considering it done.
+
+#### Worktree close-out: file the qa-handoff (worktree only)
+
+When Step 0 detected a linked worktree, `/execute` has committed to the
+worktree branch but has NOT merged — the worktree→main bridge is
+`/qa-handoff`. File the producer half of that handoff directly, so the
+merge + QA debt is surfaced and ageable instead of a pointer the operator
+must remember:
+
+1. Build the handoff payload per `/qa-handoff` Step 4 (what merged, what
+   the worktree could not runtime-verify, what hangs on the next step).
+2. **Classify `merge_state` by the same ancestry check `/qa-handoff`
+   uses:** `git merge-base --is-ancestor <branch> origin/<main>`. A
+   worktree close-out files BEFORE any merge, so the branch is not yet an
+   ancestor → `merge_state: "merge-pending"`, `merged_commit: null`,
+   `pending_branch_head: <branch tip>`; the pickup prompt says "merge then
+   QA." Dispatch is deferred (the QA station merges first).
+3. File it per `/qa-handoff` Step 5 (the `createItem` queue API), then
+   print the id: "Filed qa-handoff dec-XXXX — the QA station merges +
+   verifies."
+
+**If watchtower is not installed** (no `~/.claude-cabinet/watchtower/
+scripts/watchtower-queue.mjs` — `/execute` ships in the planning module;
+the inbox queue is the opt-in watchtower module), the queue does not
+exist. Do NOT fail the close-out and do NOT skip silently — surface a
+loud, plain-English note:
+
+> Worktree branch `<branch>` is committed and the action is marked done,
+> but watchtower isn't installed, so I couldn't file a tracked qa-handoff.
+> Merge it to main and QA manually (or install watchtower for the tracked
+> handoff). See `/qa-handoff`.
+
+On the **main checkout** this subsection is skipped — no worktree boundary
+means no handoff; do the merge/QA tail inline.
 
 #### Check downstream impact
 

package/templates/skills/execute/phases/commit-and-deploy.md

@@ -9,6 +9,14 @@ a clear message describing the implementation. Don't push or deploy —
 deployment strategy is project-specific. To explicitly skip commit
 (e.g., changes are committed manually), write only `skip: true`.
 
+**Worktree close-out is the skeleton's job, not this phase's.** When
+`/execute` runs from a linked worktree, its SKILL.md (Step 0 + Step 8, per
+`.claude/cabinet/worktree-invocation-contract.md`) already resolves
+completion artifacts to the MAIN checkout and files a `/qa-handoff` item
+for the post-merge merge + QA. This phase defines only *how to commit and
+deploy on main*; do NOT re-implement the worktree artifact-resolution or
+the handoff here — that would fork the single-sourced contract.
+
 ## What to Include
 
 - **Commit strategy** — message format, what to stage, branch conventions

package/templates/skills/execute-group/SKILL.md

@@ -92,32 +92,29 @@ first-class parallel participants.
 ### Step 0 — Environment precondition: the worktree-invocation contract
 
 Running this skill from a mux/linked git worktree is the **normal case**,
-not an error — do not refuse. Establish the environment facts first:
-
-1. **Detect where you are.**
-   `git rev-parse --path-format=absolute --git-common-dir` names the MAIN
-   checkout's `.git`; if its parent differs from
-   `git rev-parse --show-toplevel`, you are in a linked worktree.
-2. **If in a worktree, sync with main before anything else:** run
-   `git merge main --no-edit` if the branch is behind. Worktrees start
-   behind; the staleness guard (Step 1) and CP1 read plan and code state
-   that may have changed on main since the worktree was created.
-3. **The workflows ignore your cwd by design.** Stage 2's
-   `isolation: worktree` implementation agents branch from MAIN and merge
-   into MAIN regardless of the invoking checkout — the invoking worktree is
-   never the merge target and never receives the group's commits directly
-   (it picks them up on its next `git merge main`).
-4. **All completion artifacts land in the MAIN checkout.** Per-plan
-   breadcrumbs are persisted to `<main>/.claude/verification/` as each merge
-   lands (before any worktree cleanup), and the Completion Report is written
-   there before completion. Nothing verification-critical is written to the
-   invoking worktree — its `.claude/verification/` is gitignored and
-   disposable.
-5. **Escape hatch — inline build.** For a small, conflict-free group you may
-   skip the worktree machinery and implement the plans inline in the
-   invoking checkout, then merge once. Use it when worktree overhead exceeds
-   the parallelism gain; the staleness guard, CP1, and the completion-report
-   contract still apply.
+not an error — do not refuse. **Read
+`.claude/cabinet/worktree-invocation-contract.md` and follow it** — it
+establishes the universal facts: detect a linked worktree, sync main into
+it before any review or workflow, and resolve every completion artifact to
+the MAIN checkout. Per-plan breadcrumbs and the Completion Report land
+under `<main>/.claude/verification/` (each breadcrumb before any worktree
+cleanup, the report before completion); nothing verification-critical is
+written to the disposable worktree.
+
+Two facts are specific to `/execute-group` and stay inline here — they
+describe this skill's **merge model** and deliberately do NOT go in the
+shared contract (they would contradict `/execute`'s no-merge model):
+
+- **The workflows ignore your cwd by design.** Stage 2's
+  `isolation: worktree` implementation agents branch from MAIN and merge
+  into MAIN regardless of the invoking checkout — the invoking worktree is
+  never the merge target and never receives the group's commits directly
+  (it picks them up on its next `git merge main`).
+- **Escape hatch — inline build.** For a small, conflict-free group you may
+  skip the worktree machinery and implement the plans inline in the
+  invoking checkout, then merge once. Use it when worktree overhead exceeds
+  the parallelism gain; the staleness guard, CP1, and the completion-report
+  contract still apply.
 
 ### Step 1 — Staleness guard (BEFORE any review or workflow)
 

package/templates/skills/generate-plan-groups/SKILL.md

@@ -62,6 +62,26 @@ Phase files have three states:
 
 Read `phases/fetch-plans.md` for where plans come from.
 
+**Scoped invocation (operator-named subset) — prefer this when `$ARGUMENTS`
+is non-empty.** The default below grabs EVERY open action whose notes
+contain a `## Surface Area` block — often dozens of unrelated plans. When
+the operator names what to group, scope to exactly those instead:
+
+- `$ARGUMENTS` is a space-separated list of `act:` fids → group ONLY those
+  (`pib_query` with `WHERE a.fid IN (...)`).
+- `$ARGUMENTS` is `tag:<name>` → group only open actions carrying that tag.
+
+Then proceed to Phase 2 with just that subset. This is a first-class mode,
+not a deviation — `grp:2026-06-11-wt` had to be scoped by hand because it
+didn't exist (documented deviation, 2026-06-12).
+
+**Carrier-action convention (multi-action lanes).** When one plan absorbs
+others into a single lane, rename the absorbed actions' surface-area
+headers (e.g. `## Surface Area (absorbed into act:X)`) so the default
+fetch can't schedule them independently — only the carrier action keeps a
+live `## Surface Area`. (Used twice in `grp:2026-06-11-wt`: Plan A
+absorbed 2, Plan D absorbed 1.)
+
 **Default (absent/empty):** Query pib-db for open actions that have
 surface area declarations.