voidforge-build 23.9.1

package/dist/.claude/commands/vault.md

@@ -0,0 +1,198 @@
+# /vault — Seldon's Time Vault
+
+> *"I am Hari Seldon. The time I have is short, so I will not waste yours. What I have to say is important."*
+
+Distill session intelligence into a portable, actionable briefing. The Time Vault preserves expensive analysis so the next session starts informed, not ignorant.
+
+Read `/docs/methods/TIME_VAULT.md` for operating rules.
+
+## Arguments
+
+Parse the user's input for flags:
+
+| Flag | Behavior |
+|------|----------|
+| (none) | Generate vault briefing + pickup prompt, then confirm |
+| `--seal` | Auto-confirm, write without review |
+| `--open` | Read and display the most recent vault file |
+| `--list` | List all vault files with dates and summaries |
+| `--for <target>` | Tailor the briefing for a specific audience: `campaign` (next campaign session), `colleague` (human handoff), `trigger` (Thumper/cron pickup) |
+
+---
+
+## Step 0 — Gather Persisted State (Gaal Dornick)
+
+Gaal Dornick is the recorder. She gathers every source of persisted state before Seldon synthesizes.
+
+**Read these files (skip any that don't exist):**
+
+1. `/logs/build-state.md` — current build phase and progress
+2. `/logs/campaign-state.md` — campaign prophecy board, mission status
+3. `/docs/ROADMAP.md` — planned work, deferred items
+4. `/docs/PRD.md` — frontmatter only (project identity, stack, deploy target)
+
+**Run these commands:**
+
+5. `git log --oneline -20` — recent commit history
+6. `git diff --stat` — uncommitted changes
+7. `git stash list` — stashed work
+
+**Scan for session artifacts:**
+
+8. Check `/logs/` for any phase logs modified today
+9. Check `/logs/deep-current/` for situation model (if exists)
+10. Check `/logs/deploy-state.md` for deploy status (if exists)
+
+Log what was found and what was missing. Missing files are not errors — they indicate project maturity stage.
+
+---
+
+## Step 1 — Extract Session Intelligence (Seldon)
+
+Seldon synthesizes. He includes what is **expensive to re-derive** and excludes what is **cheap to re-read**.
+
+### Include (psychohistorical compression):
+
+**Muster Findings** — Consolidated findings from any review agents that ran this session. Not the full finding tables — the actionable summary: what was found, what was fixed, what remains open.
+
+**Decisions Made** — Architecture decisions, tradeoff resolutions, and "we chose X over Y because Z" moments. These are the most expensive items to re-derive because they require the full context that led to the decision.
+
+**Failed Approaches** — What was tried and didn't work, with the specific reason it failed. Prevents the next session from re-attempting dead ends. Format: "Tried [approach]. Failed because [specific reason]. Instead, [what worked or what to try next]."
+
+**Architecture Context** — Schema state, key relationships between modules, integration points, and any non-obvious wiring that a fresh session would need to trace through code to understand. Per-task file lists: which files were created/modified for each unit of work.
+
+**Execution Plan** — What to do next. Ordered list of remaining work with dependencies noted. If a campaign is active, include the current mission status and what the next mission should be.
+
+**Blocking Items** — Anything that prevents progress: missing credentials, unanswered PRD questions, external dependencies, known bugs without fixes.
+
+**Test State** — Suite status (passing/failing), coverage gaps identified, any tests that were written but are currently skipped or failing.
+
+### Exclude (cheap to re-read):
+
+- Full file contents (the code is in git)
+- Complete PRD text (it's in `/docs/PRD.md`)
+- Method doc contents (they're in `/docs/methods/`)
+- Pattern references (they're in `/docs/patterns/`)
+- Agent rosters (they're in `/docs/NAMING_REGISTRY.md`)
+
+---
+
+## Step 1.5 — Operational Learnings Sync
+
+Before sealing the vault, check for operational learnings from this session:
+
+1. If `/debrief` ran and produced approved learnings → they're already in `docs/LEARNINGS.md`. Skip extraction. Note count in the vault's Open Items.
+2. If no debrief ran, check the session for operational discoveries (API quirks, decision rationale, root causes that took multiple attempts). Flag candidates using the extraction criteria from FIELD_MEDIC.md Step 2.5.
+3. Before writing, count `###` headings in `docs/LEARNINGS.md` (excluding `## Archived`). If >= 50, ask user to archive or promote before adding.
+4. Before appending, grep the file for each candidate's title/description. Skip duplicates.
+5. Present candidates to user for approval. Append approved entries to `docs/LEARNINGS.md` (created on first use).
+6. Do NOT duplicate learnings content in the vault narrative — the vault references the file, not the entries.
+
+See ADR-035 and `/docs/methods/TIME_VAULT.md` Section 7 for full protocol.
+
+## Step 1.6 — Agent Definition Recommendations (ADR-045)
+
+If the session produced findings that suggest agent behavioral changes:
+
+1. Check if any session discovery maps to a specific agent (e.g., "Kenobi should check for X" → `kenobi-security.md`)
+2. For each match, check if the agent's `## Operational Learnings` section already covers it
+3. If not covered, add to the vault's **Open Items** as: "Agent update: `{agent-id}.md` — add `{learning}` to Operational Learnings"
+4. These recommendations carry forward to the next session's /debrief or manual update
+
+## Step 2 — Seal the Vault (Jake Sisko)
+
+Jake Sisko writes the record. He produces two artifacts:
+
+### Artifact 1: Vault File
+
+Write to `/logs/vault-YYYY-MM-DD.md` (use today's date). If a vault file for today already exists, append a counter: `vault-YYYY-MM-DD-2.md`.
+
+**Format:**
+
+```markdown
+---
+sealed: YYYY-MM-DDTHH:MM:SSZ
+project: [from PRD frontmatter or CLAUDE.md]
+branch: [current git branch]
+commit: [HEAD short hash]
+session_focus: [1-line summary of what this session accomplished]
+---
+
+# Time Vault — [Date]
+
+## Session Summary
+[2-3 sentences: what was accomplished, what changed, what's next]
+
+## Decisions
+- [Decision]: [Rationale]
+
+## Failed Approaches
+- Tried [X]: [Why it failed]
+
+## Architecture Context
+[Key relationships, schema state, non-obvious wiring]
+
+### Files Modified
+[Per-task file lists]
+
+## Open Items
+- [ ] [Blocking item or remaining work]
+
+## Test State
+[Suite status, coverage notes]
+
+## Next Session Plan
+1. [First priority]
+2. [Second priority]
+3. [Third priority]
+```
+
+### Artifact 2: Pickup Prompt
+
+Generate a pickup prompt that the next session can paste verbatim to recover context:
+
+```
+Read /logs/vault-YYYY-MM-DD.md for session context.
+Then read /logs/build-state.md and /logs/campaign-state.md for operational state.
+Resume from: [specific next action]
+```
+
+Print the pickup prompt to the console so the user can copy it.
+
+---
+
+## Step 3 — Confirm
+
+If `--seal` was NOT passed:
+
+1. Display the vault file contents
+2. Display the pickup prompt
+3. Ask: "Seal this vault? [Y/n]"
+4. On confirm: write the file, print the pickup prompt one final time
+5. On reject: ask what to change, revise, re-confirm
+
+If `--seal` WAS passed:
+
+1. Write the file immediately
+2. Print the pickup prompt
+3. Print: "Vault sealed. The Seldon Plan continues."
+
+---
+
+## `--open` Behavior
+
+1. Find the most recent file matching `/logs/vault-*.md`
+2. Read and display its full contents
+3. Print the pickup prompt from that vault's metadata
+
+## `--list` Behavior
+
+1. List all `/logs/vault-*.md` files
+2. For each: date, session_focus from frontmatter, commit hash
+3. Print as a table
+
+## `--for <target>` Tailoring
+
+- **campaign**: Emphasize mission status, next objectives, PRD progress. Pickup prompt includes `/campaign --resume`.
+- **colleague**: Write for a human reader. Include project context that an AI session wouldn't need. Expand abbreviations. Add a "Project Background" section.
+- **trigger**: Minimal format optimized for automated pickup. No prose — structured data only. Pickup prompt is a single executable line.

package/dist/.claude/commands/void.md

@@ -0,0 +1,148 @@
+# /void — Bombadil's Forge Sync
+
+> **Note:** This branch is a tombstone redirect. Running `/void` here upgrades your methodology to the latest from `main`. For the best experience, install the VoidForge CLI: `npm install -g voidforge-build`
+
+## Context Setup
+1. Read `/docs/methods/FORGE_KEEPER.md`
+2. Read `VERSION.md` (~30 lines — current version + history)
+
+## CRITICAL: Write Target Safety
+
+**NEVER write methodology files to `~/.claude/`.** All files MUST go to the PROJECT root (where `.voidforge` marker or `.git` exists). Writing to `~/.claude/commands/` or `~/.claude/agents/` creates user-level duplicates that appear alongside project-level commands in every project — Claude Code shows both "(user)" and "(project)" copies.
+
+**Detect and fix duplicates (auto-cleanup):** Before any sync, check if `~/.claude/commands/` or `~/.claude/agents/` contain VoidForge methodology files. If they do:
+1. Run `ls ~/.claude/commands/ 2>/dev/null | head -3` and `ls ~/.claude/agents/ 2>/dev/null | head -3`
+2. If VoidForge commands exist there (assess.md, build.md, qa.md, etc.), warn: "Found VoidForge commands in ~/.claude/ (user-level). These cause duplicate commands in Claude Code. Removing..."
+3. Run `rm -rf ~/.claude/commands/ ~/.claude/agents/` to clean them
+4. Confirm: "User-level duplicates removed. Project-level commands will be used."
+
+## Step 0 — Tune the Forge (Bombadil)
+Orient to the current state:
+1. Read `VERSION.md` — identify the current VoidForge version
+2. Run `git status` — note any uncommitted changes (warn if shared files are dirty)
+3. Check which shared files exist locally:
+   - `CLAUDE.md` (check both root and `.claude/CLAUDE.md` — if `.claude/CLAUDE.md` exists and root does not, use that path. If both exist, warn and don't create a duplicate.)
+   - `HOLOCRON.md`
+   - `.claude/commands/*`
+   - `.claude/agents/*`
+   - `docs/methods/*`, `docs/patterns/*`, `docs/NAMING_REGISTRY.md`
+   - `scripts/thumper/*`
+   - `VERSION.md` (conditional — only sync the "Current:" line, preserve project-specific version history rows)
+   - `CHANGELOG.md`
+4. Announce the current version and that you're checking for updates
+
+## Step 1 — Listen to the River (Goldberry)
+Fetch the latest from upstream. Two transports supported:
+
+### Migrating from `thevoidforge` or `@voidforge/cli` (v23.9.1+ rename)
+
+Per ADR-061, the npm package was renamed to `voidforge-build` in v23.9.1. If the user's global install is on `thevoidforge`, `@voidforge/cli`, or unscoped `voidforge` (the squatted name), they need a ONE-TIME manual migration:
+
+```bash
+# Check current state
+voidforge --version  # prints a migration banner if on legacy name
+
+# Migrate
+npm uninstall -g thevoidforge @voidforge/cli voidforge 2>/dev/null
+npm install -g voidforge-build@latest
+
+# Verify
+voidforge --version  # banner should be gone; version >= 23.9.1
+```
+
+Bin name `voidforge` is preserved — post-install UX is identical. After migration, normal `/void` flow continues via Transport A below. Do NOT edit a project's `package.json` to switch dependency names — projects consume methodology via `npx`, not direct deps.
+
+**Transport A (npm — v21.0+):** If `npx voidforge-build` is available:
+1. Check: run `npx voidforge-build --version` to get the installed CLI version
+2. **CLI freshness check (MANDATORY):** Run `npm view voidforge-build version` to get the latest npm version. Compare the two:
+   - If the CLI version is BEHIND npm latest → run `npm install -g voidforge-build@latest` FIRST. This is critical: old CLIs (pre-v23.1.1) compare against their own bundled methodology and will falsely report "up to date." The upgrade must happen BEFORE `npx voidforge-build update`.
+   - If the install fails (permissions) → try `sudo npm install -g voidforge-build@latest` or suggest the user run it manually
+   - After upgrading, verify with `npx voidforge-build --version` that the new version is active
+3. Run `npx voidforge-build update` — now using the latest CLI, which has the full methodology including `.claude/agents/`
+4. If no changes → "The forge burns bright! You're on the latest." → Stop
+5. If changes applied → skip to Step 4 (npm transport handles Steps 2-3)
+
+**Transport B (git — legacy):** If `npx voidforge-build` is NOT available:
+1. Offer to install: "Install VoidForge CLI for one-pass updates: `npm install -g voidforge-build`. Or continue with git transport (may require two passes for new file categories)."
+2. If user declines or npm unavailable, proceed with git:
+3. Run `git remote -v` — look for a remote pointing to `tmcleod3/voidforge`
+4. If no VoidForge remote exists:
+   - Run `git remote add voidforge https://github.com/tmcleod3/voidforge.git`
+   - Use `voidforge` as the remote name
+5. If a matching remote exists, use that name (could be `origin` or `voidforge`)
+6. Run `git fetch <remote> main` — get the latest main branch
+7. Read remote VERSION.md: `git show <remote>/main:VERSION.md`
+8. Compare versions numerically (parse major.minor.patch as integers, not strings — "3.10.0" is newer than "3.9.0"):
+   - If current version matches or is ahead → announce "The forge burns bright! You're on the latest." → Stop
+   - If behind → continue to Step 2
+
+## Step 1.5 — Spring Cleaning (Treebeard)
+Check the **Migration Registry** in `/docs/methods/FORGE_KEEPER.md` for one-time cleanup actions:
+1. Determine which migrations apply based on local version → upstream version range
+2. For each applicable migration, scan for the listed files
+3. **Fingerprint ambiguous files** before marking for removal — files like `docs/ARCHITECTURE.md` could be the user's own. Only remove if they contain VoidForge markers (e.g., "Version: 15.2.1", references to `wizard/`, "VoidForge" in header)
+4. **Always-remove files** (PRD-VOIDFORGE.md, PROPHECY.md, WORKSHOP.md, etc.) don't need fingerprinting — they're unambiguously VoidForge artifacts
+5. **wizard/ is NOT auto-removed.** Scaffold/core users may have pulled it via Full-tier commands (/cultivation, /dangerroom, /grow, /treasury, /portfolio, /current). Check: if package.json has dependencies or .voidforge/ exists on disk → user is running Full-tier, keep wizard/. If minimal package.json and no runtime data → ask the user whether to keep or remove
+6. Present the cleanup plan alongside the update plan in Step 2
+7. Apply cleanup in Step 3 alongside updates — same confirmation prompt ("all / selective / skip")
+8. For tracked `logs/*` files, use `git rm --cached` (untrack but keep on disk)
+9. If `package.json` has `dependencies`/`devDependencies` on scaffold/core AND wizard/ is being kept → leave package.json alone. Only strip to minimal if wizard/ is being removed
+
+## Step 2 — Walk the Forest (Treebeard)
+Compare every shared methodology file:
+1. For each shared file, compare local vs upstream using `git diff HEAD <remote>/main -- <path>`
+2. Also check for new files on upstream that don't exist locally: `git diff --name-status HEAD <remote>/main -- <shared paths>`
+3. Categorize each file:
+   - **New** — exists upstream, not locally
+   - **Updated** — content differs between local and upstream
+   - **Unchanged** — identical
+   - **Locally modified** — check with `git diff HEAD -- <path>` to see if user has uncommitted local changes to a file that upstream also changed
+4. For each changed file, summarize the changes in plain language (read the diff, describe what's new/different)
+5. Present the full update plan to the user:
+   - List new files with descriptions
+   - List updated files with change summaries
+   - Flag locally modified files with conflict warnings
+   - Count unchanged files (don't list them)
+6. Ask the user: "Shall old Tom sing these changes into being? (all / selective / skip)"
+
+## Step 3 — Carry the Message (Radagast)
+Apply updates based on user's choice:
+1. For **"all"** — update every file in the manifest
+2. For **"selective"** — walk through each file, ask yes/no
+3. For **"skip"** — stop gracefully
+
+For each file being updated:
+- **New files:** `git show <remote>/main:<path>` and write to local path
+- **Updated files (no local mods):** Replace with upstream version via `git show <remote>/main:<path>`
+- **Updated files (with local mods):**
+  - For `CLAUDE.md`: Preserve the `## Project` section (name, one-liner, domain, repo) and any user-added `## Coding Standards` entries. Update all methodology sections (Slash Commands, Team, Docs Reference, Release Tiers, etc.)
+  - For other files: Show both versions, let user choose, or attempt to merge non-overlapping changes
+- **Never touch:** `docs/PRD.md`, `docs/LESSONS.md`, `logs/*`, `wizard/*`, `scripts/* (except scripts/thumper/)`, `.env`, `.claude/settings.json`, `package.json`, application code
+
+## Step 4 — The Song Continues (Bombadil)
+Verify and celebrate:
+1. Confirm all updated files were written correctly (spot-check a couple)
+2. Update local `VERSION.md` current version to match upstream if it wasn't already in the shared file set
+3. Log the sync — append to `/logs/forge-sync.md`:
+   ```
+   ## Forge Sync — [DATE]
+   - Updated from v[OLD] to v[NEW]
+   - Files synced: [count]
+   - New: [list or "none"]
+   - Updated: [list]
+   - Conflicts: [list or "none"]
+   ```
+4. Note any handoffs:
+   - New slash commands added → mention what they do
+   - New method docs → mention what agent/domain they cover
+   - New patterns → mention what they demonstrate
+   - Changes to build protocol → recommend reviewing before next `/build`
+5. **Content impact check:** If NAMING_REGISTRY.md or CLAUDE.md was updated, diff the agent/command lists against the previous version. If new agents or commands were added, explicitly announce them: "New in this update: [Agent Name] ([role]). New commands: [/command]." Then warn: **"If your project displays agent counts, command lists, references the team roster, or assigns agents to protocol phases (e.g., marketing sites, docs pages, about pages, protocol timelines), update those data sources to match. New agents may need to be added to protocol phase assignments — check which phases they should participate in."** This is a handoff, not an auto-fix — `/void` doesn't know your project's data model.
+   - If `VERSION.md` was updated, check if the project has any pages displaying version/release history. Flag versions in VERSION.md not reflected in site content.
+6. Announce completion with flair
+
+## Handoffs
+- If build protocol phases changed → recommend **Picard** review (`/architect`)
+- If security method updated → recommend **Kenobi** review (`/sentinel`)
+- If new patterns added → note for **Stark** and **Galadriel** to review
+- If the update is a MAJOR version → strongly recommend reading the CHANGELOG before continuing work