thevoidforge 21.0.11 → 21.0.12

package/dist/.claude/commands/ux.md

@@ -0,0 +1,118 @@
+# /ux — Galadriel's UX/UI Pass
+
+**AGENT DEPLOYMENT IS MANDATORY.** Step 2 specifies parallel agent launches via the Agent tool. You MUST launch Elrond, Arwen, Samwise, and Celeborn as separate sub-processes. Do NOT shortcut to inline analysis. (Field report #68)
+
+## Context Setup
+1. Read `/logs/build-state.md` — understand current project state
+2. Read `/docs/methods/PRODUCT_DESIGN_FRONTEND.md`
+3. Read `/docs/LESSONS.md` — check for UX-relevant lessons (a11y gaps, component gotchas, CSS issues). Flag matches during review.
+
+## Step 0 — Orient
+Detect: framework, styling system, component library, routing, state management.
+Document in phase log: "How to run", key routes, where components/styles/copy live.
+
+## Step 1 — Product Surface Map
+List every screen/route, primary user journeys, key shared components, and the state taxonomy (loading/empty/error/success/partial/unauthorized). Write to phase log.
+
+## Step 1.75 — Éowyn's Enchantment Review
+Before the auditors begin, Éowyn dreams. Read the PRD's brand personality section. Walk through each primary flow and ask:
+- Where could this surprise and delight?
+- Where does functionality need warmth?
+- Do transitions breathe or just appear? (200ms ease-out minimum for panels, modals, state changes)
+- Do empty states invite or repel? (illustrations, warm copy, calls to action)
+- Does loading feel like anticipation or waiting? (progressive reveals, warm shimmers)
+- Do micro-moments celebrate? (toast personality, pin bounces, checkmark draws)
+- Is there a consistent motion language? (same duration/easing vocabulary throughout)
+- Does the first 5 seconds feel like the brand?
+- Could each opportunity be implemented in ~5 lines? (magic must be lightweight)
+
+Log enchantment opportunities to phase log with effort estimates. These are **nice-to-have** — never block ship. But the best ones get implemented in Step 6.
+
+See `PRODUCT_DESIGN_FRONTEND.md` Step 1.75 for full Éowyn protocol.
+
+## Step 2 — Parallel Analysis
+Use the Agent tool to run these simultaneously — all are read-only analysis:
+- **Agent 1 (Elrond — UX):** Review information architecture, navigation, task flows, friction points. Can users find things? Are flows intuitive?
+- **Agent 2 (Arwen — Visual):** Review spacing, typography, color usage, button hierarchy, visual consistency. Does it look intentional?
+- **Agent 3 (Samwise — A11y):** Check keyboard navigation, focus management, ARIA labels, color contrast, reduced motion. Test with keyboard-only navigation.
+- **Agent 4 (Celeborn — Design System):** Are spacing tokens consistent? Typography scale followed? Colors from the palette? Component naming conventions respected? Catches systemic inconsistencies (e.g., `gap-4` vs `gap-[18px]` for the same spacing).
+
+**Aragorn** orchestrates when multiple findings conflict — prioritizes which matter most for users.
+
+Synthesize findings from all agents.
+
+## Step 3 — Sequential Reviews
+These require interactive testing:
+
+**Bilbo (Copy):** Review all microcopy — labels, buttons, error messages, empty states, confirmations, destructive action warnings. Does the product speak clearly and consistently?
+
+**Pippin (Edge Cases):** Does the unexpected — resizes to 320px, pastes emoji in search, clicks back mid-flow, opens the same page in two tabs, toggles between light/dark mid-animation.
+
+**Frodo (Hardest Flow):** If the project has one flow that is both the most critical AND the most complex, Frodo gets dedicated attention on that single flow. Conditional — skip if no single flow dominates.
+
+**Legolas (Code):** Review component architecture — semantic HTML, CSS organization, state management patterns. Reference `/docs/patterns/component.tsx`.
+
+**Gimli (Performance):** Check loading states, skeleton screens, layout shift, optimistic UI, mobile responsiveness, touch targets (min 44px).
+
+**Radagast (Edge Cases + Error States):** Test forms with empty/huge/unicode inputs, broken states, dangerous actions without confirmation, validation gaps.
+
+**ERROR STATE TESTING (mandatory):** For every form/action in the UI:
+- Submit with intentionally invalid data (duplicate name, wrong format, missing required field)
+- Verify the error message is SPECIFIC and ACTIONABLE — never generic ("something went wrong", "failed to save")
+- Verify the form state after error allows retry without losing user input
+- If the feature involves a resource that can conflict (duplicate slug, duplicate email, taken domain), test the conflict case explicitly
+- For every API error the backend can return, verify the UI displays it meaningfully
+
+## Step 4 — Issue Tracker
+Log all findings to `/logs/phase-10-ux-audit.md`:
+
+| ID | Title | Severity | Confidence | Category | Location | Current | Expected | Fix | Status |
+|----|-------|----------|------------|----------|----------|---------|----------|-----|--------|
+
+Categories: UX, Visual, A11y, Copy, Performance, Edge Case
+
+**Confidence scoring is mandatory.** Every finding includes a confidence score (0-100). If confidence is below 60, escalate to a second agent from a different universe (e.g., if Samwise found it, escalate to Padmé or Nightwing) to verify before including. If the second agent disagrees, drop the finding. High-confidence findings (90+) skip re-verification in Step 7.5.
+
+## Step 5 — Enhancement Specs (before coding)
+For each fix: problem statement, proposed solution, acceptance criteria, a11y requirements (Samwise signs off), copy (Bilbo signs off). **Faramir** checks whether polish effort targets the right screens — high-traffic core flows, not low-traffic edge pages.
+
+## Step 6 — Implement (small batches — **Boromir** guards against hubris)
+One batch = one flow or component cluster (max ~200 lines changed). **Boromir** checks: is the polish overengineered? Too many animations? Does complexity hurt performance? **Glorfindel** handles the hardest rendering (canvas, WebGL, SVG — conditional, only if the project has visual complexity). After each batch:
+1. Re-run the app
+2. Re-walk the affected flow
+3. Test keyboard navigation
+4. Update issue tracker status
+5. Run `npm test` to catch regressions
+
+## Step 7 — Harden Design System (**Haldir** guards boundaries)
+Arwen leads. **Haldir** checks transitions between pages, states, and components — loading→success, error→retry, navigate→return. Are they smooth or jarring? Audit shared components (buttons, inputs, cards, modals, toasts) for:
+- Consistent variants (primary, secondary, danger, ghost)
+- Responsive behavior
+- Keyboard focus styles
+- Proper ARIA attributes
+
+## Step 7.5 — Pass 2: Re-Verify Fixes
+After all fixes are applied, run a verification pass:
+- **Samwise** re-audits accessibility on all modified components — verify a11y fixes didn't break other a11y properties
+- **Radagast** re-checks edge cases on fixed flows — verify fixes hold under adversarial input
+- **Merry** pair-verifies Pippin's edge case resolutions — one found it, the other confirms the fix
+
+If Pass 2 finds new issues, fix and re-verify until Samwise, Radagast, and Merry sign off.
+
+## Step 8 — Regression Checklist
+Add UX-specific items to the regression checklist in `/docs/qa-prompt.md`:
+
+| # | Flow | A11y Check | Responsive Check | Status |
+|---|------|-----------|-----------------|--------|
+
+## Step 9 — Deliverables
+1. UX_UI_AUDIT.md — all findings
+2. Updated regression checklist in qa-prompt.md
+3. Code fixes
+4. "Next improvements" backlog in phase log
+
+## Handoffs
+- Backend issues → Stark, log to `/logs/handoffs.md`
+- Security issues → Kenobi, log to `/logs/handoffs.md`
+- Architecture issues → Picard, log to `/logs/handoffs.md`
+- Non-UI bugs → Batman, log to `/logs/handoffs.md`

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

@@ -0,0 +1,189 @@
+# /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 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,108 @@
+# /void — Bombadil's Forge Sync
+
+## Context Setup
+1. Read `/docs/methods/FORGE_KEEPER.md`
+2. Read `VERSION.md` (~30 lines — current version + history)
+
+## 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/*`
+   - `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:
+
+**Transport A (npm — v21.0+):** If `npx voidforge` is available:
+1. Run `npx voidforge update` — uses the methodology diff/apply system
+2. This handles version comparison, diffing, and applying automatically
+3. If no changes → "The forge burns bright! You're on the latest." → Stop
+4. If changes applied → skip to Step 4 (npm transport handles Steps 2-3)
+
+**Transport B (git — legacy):** If `npx voidforge` is not installed:
+1. Run `git remote -v` — look for a remote pointing to `tmcleod3/voidforge`
+2. If no VoidForge remote exists → add: `git remote add voidforge https://github.com/tmcleod3/voidforge.git`
+3. Run `git fetch <remote> main` — get the latest main branch
+4. Read remote VERSION.md: `git show <remote>/main:VERSION.md`
+5. Compare versions numerically (parse major.minor.patch as integers, not strings)
+   - If current version matches or is ahead → "The forge burns bright!" → 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` 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 (`/security`)
+- 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