create-claude-cabinet 0.23.0 → 0.24.0

package/lib/cli.js

@@ -348,7 +348,18 @@ const MODULES = {
     name: 'Session Loop (orient + debrief)',
     description: 'The briefing cycle. Claude starts each session informed, ends by preparing the next briefing.',
     mandatory: true,
-    templates: ['skills/orient', 'skills/orient-quick', 'skills/debrief', 'skills/debrief-quick', 'skills/debrief/phases/upstream-feedback.md', 'skills/menu'],
+    templates: [
+      'skills/orient',
+      'skills/orient-quick',
+      'skills/debrief',
+      'skills/debrief-quick',
+      // Instruction phases — always ship, overriding the default skip-phases rule in copy.js
+      'skills/debrief/phases/audit-pattern-capture.md',
+      'skills/debrief/phases/methodology-capture.md',
+      'skills/debrief/phases/record-lessons.md',
+      'skills/debrief/phases/upstream-feedback.md',
+      'skills/menu',
+    ],
   },
   'hooks': {
     name: 'Git Guardrails + Telemetry',

package/package.json

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

package/templates/skills/debrief/SKILL.md

@@ -306,27 +306,24 @@ Don't silently bundle unrelated changes.
 
 ### 9. Record Lessons (core)
 
-Read `phases/record-lessons.md` for how to capture what was learned.
-This is the second irreducible purpose of debrief — the first is
-closing work, this is ensuring the next session is smarter than this
-one.
-
-**Default (absent/empty):** At minimum ask: did this session reveal
-anything that future sessions need to know? A new pattern, a gotcha,
-a process gap, a user preference? Lessons are perishable — capture
-them now while context is fresh.
-
-**Omega-only:** If `~/.claude-cabinet/omega-venv/bin/python3` and
-`scripts/cabinet-memory-adapter.py` both exist, write lessons to omega
-— never to flat markdown. A guard hook enforces this. Use the adapter:
-
-```bash
-echo '{"text": "the lesson", "type": "lesson"}' | \
-  ~/.claude-cabinet/omega-venv/bin/python3 scripts/cabinet-memory-adapter.py store
-```
-
-Types: `decision`, `lesson`, `preference`, `constraint`, `pattern`.
-Flat markdown memory is the fallback only when omega is unavailable.
+Read `phases/record-lessons.md` for how to route session outputs to
+their real homes. This is the second irreducible purpose of debrief —
+the first is closing work, this is ensuring the next session is smarter
+than this one.
+
+**The phase file teaches a routing discipline:** every output has
+exactly one home with a forcing function — omega `decision`/`lesson`/
+`constraint`/`preference` memory, inline in CLAUDE.md or a briefing
+(for load-bearing project facts), a pib-db deferred action (for
+conditional revisits), or the upstream-feedback phase (for CC-applicable
+friction). Loose `.md` files written next to the code they describe
+are explicitly an **anti-pattern** — they rot silently when the code
+changes. Hybrid observations (part project, part CC) must be split.
+
+**Default (absent/empty):** Follow the routing tree in the phase file.
+Ask the user only when routing is genuinely ambiguous — not as a
+catch-all "what did we learn?" prompt, which tends to produce vague
+lessons that don't get recorded anywhere useful.
 
 **Omega broken:** If the memory module is installed (check `.ccrc.json`
 for `"memory": true`) but the venv or adapter is missing, surface this
@@ -485,7 +482,7 @@ Read `phases/report.md` for how to present the debrief summary.
 | `auto-maintenance.md` | Skip | Recurring session-end tasks |
 | `update-state.md` | Default: check system-status.md | What state files to update |
 | `health-checks.md` | Skip | Session-end health checks |
-| `record-lessons.md` | Default: ask what was learned | How to capture learnings |
+| `record-lessons.md` | Default: route outputs per the decision tree | How to route session outputs to omega / CLAUDE.md / pib-db triggers / upstream |
 | `audit-pattern-capture.md` | **Instruction: always runs** | Detect recurring audit findings, write to patterns-project.md |
 | `methodology-capture.md` | **Instruction: always runs** | Detect methodology-level work; capture reasoning chain + narrative to `.claude/methodology/` |
 | `upstream-feedback.md` | **Instruction: always runs** | Surface CC friction to source repo |

package/templates/skills/debrief/phases/record-lessons.md

@@ -1,94 +1,173 @@
-# Record Lessons — Capture What Was Learned
+# Record Lessons — Route Session Outputs to Their Real Homes
 
-Define how to capture lessons from the session so future sessions are
-smarter. This is the second irreducible purpose of debrief — without it,
-the system does work but doesn't learn from it.
+This is debrief's second irreducible purpose: make sure the next session
+is smarter than this one. Without it, the system does work but doesn't
+learn from it.
 
-When this file is absent or empty, the default behavior is: ask whether
-the session revealed anything future sessions need to know. To explicitly
-skip lesson recording, write only `skip: true`.
+Lessons are perishable. A lesson captured while context is fresh is
+worth ten captured from memory next week.
 
-Lessons are perishable. A lesson captured while context is fresh is worth
-ten captured from memory next week. This is why recording happens during
-debrief, not "sometime later."
+## The Routing Principle
 
-## Where to Record — Omega Primary
+Every session output has **exactly one primary home**. The home must
+have a forcing function — something that keeps the content accurate
+when the code it describes changes. Loose `.md` files next to code
+are the wrong home: they rot silently because nothing invalidates
+them when the system evolves.
 
-Check whether omega memory is available:
-- `~/.claude-cabinet/omega-venv/bin/python3` exists AND
-- `scripts/cabinet-memory-adapter.py` exists
+**Each output has one home. Don't double-store.** A decision stored
+in omega doesn't also need a `.md` file. A constraint documented in
+CLAUDE.md doesn't also need an omega entry "for backup." Duplication
+just creates two things to keep in sync.
 
-**When omega is available — use it. No exceptions.** Write lessons to
-omega via the adapter. Never write to flat markdown memory files when
-omega is available — a guard hook will block the attempt.
+## Routing Decision Tree
+
+For each thing you'd want future sessions to know, pick the single
+best home:
+
+### Decisions — "we chose X over Y because Z"
+
+Architectural choices, tradeoff resolutions, accepted gaps, rejected
+alternatives.
+
+**Primary home:** omega `decision` memory. Omega has contradiction
+detection — when a later decision supersedes this one, the old entry
+can be marked `status=superseded` instead of silently rotting.
 
 ```bash
-echo '{"text": "the lesson", "type": "lesson", "tags": ["tag1"]}' | \
+echo '{"text": "the decision + why", "type": "decision"}' | \
   ~/.claude-cabinet/omega-venv/bin/python3 scripts/cabinet-memory-adapter.py store
 ```
 
-Memory types to use:
-- `decision` — architectural choices, tradeoff resolutions
-- `lesson` — gotchas, discoveries, things that surprised
-- `preference` — user corrections, style choices, workflow preferences
-- `constraint` — limitations discovered, prerequisites found
-- `pattern` — conventions established, recurring solutions
-
-**When omega is NOT available:** Only then use flat markdown memory
-(auto-memory in `~/.claude/projects/` memory directory). Check omega
-availability first — don't assume it's unavailable without checking.
-
-## What to Look For
-
-Review the session and ask:
-- Did we learn something future sessions need to know?
-  - A new pattern established
-  - A gotcha discovered
-  - A process gap identified
-  - A user preference revealed
-- Is this the second or third time something came up? If the same kind
-  of problem keeps recurring, the lesson is "create a prevention mechanism"
-  not just "remember this."
-- Did the session's work contradict any existing recorded knowledge?
-  If so, update or remove the stale record (in omega: use `query` to
-  find it, then note the contradiction in the new memory).
-
-## What NOT to Record
-- Code patterns derivable by reading current files
-- Git history (use git log)
-- Debugging solutions (the fix is in the code)
-- Anything already in CLAUDE.md files
-- Ephemeral task details only relevant to this session
+**Also add to CLAUDE.md** only if the decision is load-bearing enough
+that *every* session needs to know it at startup (not just sessions
+that touch the relevant code). Examples: "auth is per-user via FastAPI
+Users (no shared passwords)" is load-bearing. "We rejected a specific
+library option after evaluation" is not — omega is enough.
 
-## After Storing — Link and Check
+### Project constraints / conventions / gotchas
 
-After storing each memory, omega auto-relates it to similar existing
-memories. Surface this to the user:
+Environmental quirks, dev-workflow requirements, "this project has a
+weird setup" facts.
 
-```bash
-~/.claude-cabinet/omega-venv/bin/python3 -c "
-from omega import find_similar_memories
-result = find_similar_memories('THE_NEW_MEMORY_ID')
-print(result)
-"
+**Primary home:** inline in `CLAUDE.md` or the project briefing. These
+files get edited when the code changes — the forcing function is that
+they're load-bearing for every session, so staleness surfaces fast.
+
+Use omega `constraint` type only for cross-project patterns (e.g.,
+"in any project with nested package.json..."). Project-specific
+constraints belong inline.
+
+### Conditional revisits — "do X later when Y happens"
+
+"If we ever get multiple concurrent users, add a token blocklist."
+"When curl becomes annoying, build a /settings UI."
+
+**Primary home:** pib-db deferred action with `trigger_condition`.
+
+```
+pib_create_action text="..." status="deferred" trigger_condition="..."
 ```
 
-If the new memory is similar to existing ones, mention it:
-"This connects to your earlier memory about [topic]."
+Orient's deferred-check phase re-evaluates these every session. If the
+condition has fired, the user gets asked; if it's obsolete, it gets
+marked so. No silent rot.
+
+### CC upstream friction embedded in a project observation
+
+Sometimes a project-scoped observation contains a CC-applicable piece:
+"in this project auth tests are hard, AND cabinet-qa should flag this
+pattern in any auth work." That's two things, not one.
+
+**Split it.** Route the project piece to its home (omega / CLAUDE.md /
+trigger). Route the CC piece to the upstream-feedback phase (step 11)
+where it will be drafted and delivered. Don't bury the upstream piece
+inside a project decision doc — it will never find its way home.
+
+### Lessons, gotchas, discoveries (not decisions, not constraints)
+
+"We learned that X behaves differently from docs." "This pattern
+works." "The CI was green but prod failed because…"
+
+**Primary home:** omega `lesson` memory. Same forcing function as
+decisions — superseded lessons can be marked and surfaced.
+
+### User preferences
+
+Style choices, workflow preferences, corrections the user made.
+
+**Primary home:** omega `preference` memory.
 
-Also check for contradictions — if the new memory conflicts with an
-existing one, ask the user which is correct:
+## The Anti-Pattern: Loose Project-Scoped .md Files
+
+**Do not write `feedback-project-*.md`, `decision-*.md`, or similar
+loose .md files as the primary record of a session output.** This
+pattern has been observed to rot — in one audited case, 4 of 5 such
+files went stale within 7 days because the underlying code changed
+and the files had no forcing function to catch it.
+
+If you are tempted to write a loose .md file:
+- Is it a decision? → omega `decision`
+- Is it a constraint everyone needs? → CLAUDE.md / briefing
+- Is it a conditional revisit? → pib-db deferred trigger
+- Is it CC upstream friction? → upstream-feedback phase
+- None of the above? → it probably doesn't need recording at all
+
+## Before Writing — Contradiction Check
+
+For each memory you're about to write, query omega for existing
+entries on the same topic:
+
+```bash
+~/.claude-cabinet/omega-venv/bin/omega query "topic keywords" --limit 5
+```
+
+If an existing entry contradicts or is superseded by the new one,
+mark the old one:
 
 ```bash
-~/.claude-cabinet/omega-venv/bin/python3 -c "
-from omega import SQLiteStore
-s = SQLiteStore()
-edges = s.get_edges_by_type('contradicts')
-for e in edges: print(f\"{e['source_id']} <-> {e['target_id']} ({e['weight']:.2f})\")
-"
+~/.claude-cabinet/omega-venv/bin/omega update <old-id> --status superseded
+```
+
+This is the forcing function that turns omega into a living record
+instead of another pile of rotting notes.
+
+## When Omega Is Not Available
+
+If `~/.claude-cabinet/omega-venv/bin/python3` is missing AND the
+memory module is not installed (check `.ccrc.json`), fall back to
+flat markdown memory in `~/.claude/projects/...`. But recognize
+this fallback has the same rot problem — prefer CLAUDE.md for
+anything load-bearing and pib-db triggers for anything conditional.
+
+If the memory module IS installed but omega is broken, surface this
+in the debrief report:
+
+> **⚠ Memory module is installed but omega is not working.**
+> Decisions/lessons from this session were saved to flat markdown
+> instead. Run `npx create-claude-cabinet` to rebuild the omega venv.
+
+## What NOT to Record — Anywhere
+
+- Code patterns derivable by reading current files
+- Git history (use `git log`)
+- Debugging solutions (the fix is already in the code; the commit
+  message has the context)
+- Anything already in CLAUDE.md files
+- Ephemeral task details only relevant to this session
+- "We made progress on X" session summaries — that's what git is for
+
+## Report What Was Routed
+
+Tell the user what went where so they can audit the routing:
+
+```
+Routed this session:
+- 1 decision → omega mem-xxxxx (JWT revocation tradeoff)
+- 1 constraint → article-rewriter/CLAUDE.md (tsc must run from frontend)
+- 1 deferred trigger → pib-db act:xxxxxxxx (add blocklist if multi-user)
+- 1 upstream piece → CC feedback outbox (cabinet-qa testability)
 ```
 
-## Report What Was Recorded
-Tell the user what memories were created or updated so they know what
-the system will remember next time. Include the count, types, and any
-new connections discovered in the knowledge graph.
+This is also how you catch routing errors: if everything ended up in
+omega, the routing discipline didn't actually run.

package/templates/skills/orient/SKILL.md

@@ -163,29 +163,37 @@ anything else.
 
 ### Feedback pipeline check
 
-1. **Flush outbox.** Read `~/.claude/cc-feedback-outbox.json`:
-   ```bash
-   cat ~/.claude/cc-feedback-outbox.json 2>/dev/null || echo '[]'
-   ```
-   If items exist with `"delivered": false`:
-   - If this is the CC source repo (check `package.json` name is
-     `create-claude-cabinet`): copy items to `feedback/` directory
-     as individual .md files, mark as delivered in the outbox.
-   - If this is a consuming project with `~/.claude/cc-registry.json`:
-     read the CC source path from registry and copy items to that
-     path's `feedback/` directory.
+1. **Flush outbox.** Read `~/.claude/cc-feedback-outbox.json`. Determine
+   destination: if this is the CC source repo (`package.json` name is
+   `create-claude-cabinet`), destination is `./feedback/`; otherwise
+   read CC source path from `~/.claude/cc-registry.json` and use its
+   `feedback/`. For each item with `"delivered": false`:
+
+   - **Compute destination filename** from `{date}-{slug(title)}-{seq}.md`.
+   - **Skip-if-exists check:** before writing, look for any file in the
+     destination `feedback/` OR `feedback/resolved/` whose name contains
+     the slugified title. If found, the item was already delivered (or
+     already resolved) by a prior session — do not rewrite. Mark the
+     item handled and move on.
+   - Otherwise write the item's `body` to the destination.
+   - After processing all items, atomically rewrite the outbox: write
+     `~/.claude/cc-feedback-outbox.json.tmp`, then rename. On a fully
+     successful pass, reset to `[]` — don't accumulate delivered
+     markers. If some items failed, keep only the failed ones.
    - Error handling: wrap JSON.parse in try/catch. If the outbox is
-     malformed, log warning and reset to `[]`. Write atomically: write
-     to `~/.claude/cc-feedback-outbox.json.tmp`, then rename over
-     the original. On successful flush, reset to `[]` — don't
-     accumulate delivered markers.
-
-2. **Scan wrong-write locations.** Check these paths for CC-scoped
-   feedback that got written to the wrong place:
-   - `.claude/memory/feedback/*.md`
-   - `.claude/feedback/*.md`
-   If found: "Found N feedback files in [path] that may be CC
-   upstream feedback written to the wrong location. Move to outbox?"
+     malformed, log warning and reset to `[]`.
+
+2. **Scan wrong-write locations.** Check `.claude/memory/feedback/*.md`
+   and `.claude/feedback/*.md` for files that may be CC upstream
+   feedback misfiled. **Exclude project-scoped files** — skip any file
+   whose name starts with `feedback-project-` or whose frontmatter
+   contains `scope: project-specific`. Those are intentionally
+   project-scoped decisions/constraints, not CC upstream feedback; they
+   belong in omega memory (decision/constraint types), CLAUDE.md, or a
+   pib-db deferred trigger — not in the outbox.
+   If remaining candidates found: "Found N feedback files in [path]
+   that may be CC upstream feedback written to the wrong location.
+   Move to outbox?"
 
 ### 2. Sync Data (core)