mindforge-cc 2.0.0 → 2.1.0

package/.claude/commands/mindforge/skills.md

@@ -1,141 +1,36 @@
-# MindForge — Skills Command
-# Usage: /mindforge:skills [subcommand] [args]
-# Subcommands: list | add | update | validate | info | search
-
-## Subcommand: list
-`/mindforge:skills list`
-
-Read MANIFEST.md. Display all registered skills in a formatted table
-(include path for each skill):
-
-```
-MindForge Skills Registry
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-  Tier 1 — Core Skills (10 installed)
-  ────────────────────────────────────────────────────────────
-  ✅  security-review     v1.0.0   stable   .mindforge/skills/security-review/SKILL.md
-  ✅  code-quality        v1.0.0   stable   .mindforge/skills/code-quality/SKILL.md
-  ✅  api-design          v1.0.0   stable   .mindforge/skills/api-design/SKILL.md
-  ✅  testing-standards   v1.0.0   stable   .mindforge/skills/testing-standards/SKILL.md
-  ✅  documentation       v1.0.0   stable   .mindforge/skills/documentation/SKILL.md
-  ✅  performance         v1.0.0   stable   .mindforge/skills/performance/SKILL.md
-  ✅  accessibility       v1.0.0   stable   .mindforge/skills/accessibility/SKILL.md
-  ✅  data-privacy        v1.0.0   stable   .mindforge/skills/data-privacy/SKILL.md
-  ✅  incident-response   v1.0.0   stable   .mindforge/skills/incident-response/SKILL.md
-  ✅  database-patterns   v1.0.0   stable   .mindforge/skills/database-patterns/SKILL.md
-
-  Tier 2 — Org Skills (0 installed)
-  ────────────────────────────────────────────────────────────
-  (none — run /mindforge:skills add to add org skills)
-
-  Tier 3 — Project Skills (0 installed)
-  ────────────────────────────────────────────────────────────
-  (none)
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Total: 10 skills   |   Run /mindforge:skills validate to check health
-```
-
-## Subcommand: info
-`/mindforge:skills info [skill-name]`
-
-Display detailed information about a specific skill:
-
-```
-Skill: security-review
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Version      : 1.0.0
-  Status       : stable
-  Tier         : 1 (Core)
-  Min MindForge: 0.1.0
-  Path         : .mindforge/skills/security-review/SKILL.md
-
-  Triggers (25):
-  auth, authentication, authorisation, authorization, login,
-  logout, password, token, JWT, session, cookie, OAuth,
-  payment, billing, stripe, PII, GDPR, personal data,
-  upload, file upload, credentials, API key, secret, env,
-  environment variable, encryption, hashing, bcrypt, argon2
-
-  Changelog:
-  1.0.0 — Initial stable release
-```
-
-## Subcommand: search
-`/mindforge:skills search [keyword]`
-
-Find which skills would activate for a given keyword:
-
-```
-/mindforge:skills search "database query"
-
-  Matching skills for "database query":
-  ────────────────────────────────────────────────────────────
-  database-patterns  v1.0.0  [tier 1]  trigger: "database", "query"
-  performance        v1.0.0  [tier 1]  trigger: "query time"
-
-  These 2 skills would be automatically loaded for a task
-  containing "database query" in its description.
-```
-
-## Subcommand: validate
-`/mindforge:skills validate`
-
-Run a health check on all installed skills:
-
-```
-Validating skills...
-
-  ✅  security-review     — frontmatter valid, file readable, triggers: 29
-  ✅  code-quality        — frontmatter valid, file readable, triggers: 14
-  ✅  performance         — frontmatter valid, file readable, triggers: 31
-  ⚠️  [org-skill-name]   — frontmatter valid but missing 'version' field
-  ❌  [missing-skill]    — listed in MANIFEST.md but file not found
-
-  Issues found: 2
-  Run /mindforge:skills add to fix missing skills.
-  Fix frontmatter issues manually in the SKILL.md file.
-```
-
-Validation checks:
-1. Every manifest entry has a corresponding SKILL.md file
-2. Every SKILL.md has: `name`, `version`, `status`, `triggers` in frontmatter
-3. Every SKILL.md has a self-check or checklist section
-4. All versions are valid semver strings
-5. No two skills at the same tier share the same trigger keyword (flag as ⚠️)
-6. Every skill file is readable (not empty, not corrupted)
-
-## Subcommand: add
-`/mindforge:skills add [path-to-skill-dir]`
-
-Register a new skill in the manifest:
-
-1. Read the SKILL.md in the provided path
-2. Validate the frontmatter (all required fields present)
-3. Check for trigger keyword conflicts with existing skills
-4. Ask the user: "Which tier should this skill be registered as? (2=Org / 3=Project)"
-5. Show the exact MANIFEST.md entry that will be written and ask for confirmation
-6. Add the entry to MANIFEST.md in the correct section
-7. Run `/mindforge:skills validate` to confirm registration is clean
-8. Commit: `feat(skills): register [skill-name] v[version] as tier [N] skill`
-
-## Subcommand: update
-`/mindforge:skills update [skill-name]`
-
-Update a skill to a newer version:
-
-1. Read current version from MANIFEST.md
-2. Check the skill's changelog in SKILL.md for available updates
-3. If MAJOR version change: show breaking changes, require confirmation
-4. If MINOR or PATCH: update automatically
-5. Update MANIFEST.md version entry
-6. Run `/mindforge:skills validate` after update
-7. Run `node tests/skills-platform.test.js` after update
-8. Commit: `chore(skills): update [name] v[old] → v[new]`
-
-## Error handling
-- If MANIFEST.md does not exist: offer to create it with current skills
-- If a skill name is not found: suggest similar names (fuzzy match)
-- If validation finds critical errors: block any phase execution until fixed
-  (A skills validation failure is a BLOCKING issue)
+---
+name: mindforge:skills
+description: Manage the MindForge skills registry and validation status
+argument-hint: [list|info|search|validate|add|update] [skill-name]
+allowed-tools:
+  - list_dir
+  - view_file
+  - write_to_file
+  - run_command
+---
+
+<objective>
+Provide a centralized interface for managing, searching, and validating the project's skill registry, ensuring all automated knowledge is current, conflict-free, and healthy.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/skills.md
+</execution_context>
+
+<context>
+Manifest: MANIFEST.md
+Structure: Organized by Tier 1 (Core), Tier 2 (Org), and Tier 3 (Project).
+Validation: Checks semver, required fields, trigger conflicts, and file accessibility.
+</context>
+
+<process>
+1. **Route Subcommand**:
+    - `list`: Render a formatted table of all registered skills and their active versions.
+    - `info`: Display detail for a specific skill (triggers, changelog, status).
+    - `search`: Show which skills would activate for a specific query.
+    - `validate`: Audit the full registry for broken paths, invalid frontmatter, or trigger overlaps.
+    - `add`: Register a new skill directory, prompting for tier and confirming the manifest entry.
+    - `update`: Handle version bumps, showing breaking changes for major updates.
+2. **Enforce Health**: If validation finds critical errors, block phase execution.
+3. **Commit**: Automatically commit manifest changes with structured messages.
+</process>

package/.claude/commands/mindforge/status.md

@@ -1,104 +1,30 @@
-# MindForge — Status Command
-# Usage: /mindforge:status
-
-Display a rich dashboard of the current project state.
-Pull data from STATE.md, AUDIT.jsonl, REQUIREMENTS.md, and the phases directory.
-
-## Dashboard sections
-
-### Section 1 — Project header
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-⚡ MindForge Status — [Project Name]
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Last updated : [STATE.md last updated timestamp]
-  Current phase: Phase [N] — [phase description]
-  Status       : [status from STATE.md]
-```
-
-### Section 2 — Phase progress
-```
-Phase Progress
-───────────────────────────────────────────────────────
-  Phase 1  [████████████████████] 100% — Complete ✅
-  Phase 2  [████████░░░░░░░░░░░░]  40% — In progress
-  Phase 3  [░░░░░░░░░░░░░░░░░░░░]   0% — Not started
-  Phase 4  [░░░░░░░░░░░░░░░░░░░░]   0% — Not started
-```
-Calculate percentage from: tasks with SUMMARY files / total tasks in phase.
-Count ONLY SUMMARY files that contain `Status: Completed ✅` (or `Status` + `Completed`).
-Do not count failed tasks as progress.
-If VERIFICATION.md is missing for a phase: label it "In progress" not "0% verified".
-
-### Section 3 — Requirements coverage
-Read REQUIREMENTS.md and count:
-- Total v1 requirements
-- Requirements with a passing test (from VERIFICATION.md files)
-- Requirements implemented but untested
-- Requirements not yet started
-
-```
-Requirements (v1)
-───────────────────────────────────────────────────────
-  Total        : [N]
-  ✅ Done + tested  : [N]
-  ⚠️  Done, no test : [N]
-  🔴 Not started   : [N]
-```
-
-### Section 4 — Recent activity (from AUDIT.jsonl)
-Read the last 10 entries from AUDIT.jsonl and display:
-```
-Recent Activity
-───────────────────────────────────────────────────────
-  [timestamp]  task_completed  Plan 03: User API endpoints ✅
-  [timestamp]  task_completed  Plan 02: Product model ✅
-  [timestamp]  task_started    Plan 03: User API endpoints
-  [timestamp]  task_completed  Plan 01: User model ✅
-  [timestamp]  context_compaction  Phase 2, Plan 03 (72% context)
-```
-If AUDIT.jsonl is empty or missing, display:
-```
-Recent Activity
-───────────────────────────────────────────────────────
-  No activity logged yet. Activity will appear here
-  after running /mindforge:execute-phase.
-```
-
-### Section 5 — Open issues
-Check for:
-- Any open SECURITY-REVIEW files with CRITICAL or HIGH findings
-- Any BUGS.md files with open issues
-- Any failed tasks in WAVE-REPORT files
-- Any blockers in STATE.md
-
-```
-Open Issues
-───────────────────────────────────────────────────────
-  🔴 CRITICAL: [if any — from SECURITY-REVIEW]
-  🟠 HIGH:     [if any]
-  ✅ No open issues
-```
-
-### Section 6 — Next action
-```
-Next Action
-───────────────────────────────────────────────────────
-  [What STATE.md says the next action is]
-  Run: /mindforge:next
-     to auto-execute the next step.
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-## Data sources (in priority order)
-1. STATE.md — authoritative for current status
-2. AUDIT.jsonl — authoritative for history
-3. REQUIREMENTS.md — authoritative for scope
-4. VERIFICATION.md files — authoritative for test coverage
-5. WAVE-REPORT files — authoritative for execution history
-6. HANDOFF.json — authoritative for session state
-
-## Performance notes
-- For recent activity, read only the last 500 bytes of AUDIT.jsonl:
-  `tail -c 500 .planning/AUDIT.jsonl | [parse last complete JSON objects]`
-- For requirement counts, count lines starting with `| FR-` instead of parsing the whole file.
+---
+name: mindforge:status
+description: Display a rich dashboard of the current project state
+argument-hint: none
+allowed-tools:
+  - list_dir
+  - view_file
+  - run_command
+---
+
+<objective>
+Provide a high-level visual summary of the project's health, progress, requirement coverage, and recent activity by synthesizing data from the `.planning/` directory.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/status.md
+</execution_context>
+
+<context>
+Sources: STATE.md, AUDIT.jsonl, REQUIREMENTS.md, and phase directories.
+Focus: Real-time visibility into phase completion and open issues.
+</context>
+
+<process>
+1. **Gather Phase Data**: Read `STATE.md` and calculate progress percentage for active/planned phases.
+2. **Audit Requirements**: Count total, completed (verified), implemented (untested), and pending requirements from `REQUIREMENTS.md`.
+3. **Extract Recent Activity**: Parse the last few entries of `AUDIT.jsonl` (using efficient tail read).
+4. **Monitor Issues**: Check for critical security findings, open bugs, or execution blockers.
+5. **Render Dashboard**: Display the multi-section summary including header, progress bars, requirement counts, and activity logs.
+</process>

package/.claude/commands/mindforge/steer.md

@@ -1,13 +1,28 @@
-# /mindforge:steer "[instruction]"
+---
+name: mindforge:steer
+description: Inject mid-execution guidance into the running autonomous engine
+argument-hint: "[instruction]"
+allowed-tools:
+  - write_to_file
+  - view_file
+---
 
-**Purpose**: Injects mid-execution guidance into the running autonomous engine.
-Steering guidance is applied at the next task boundary to course-correct the agent.
+<objective>
+Provide a mechanism for human course-correction during long-running autonomous waves, allowing the user to redirect the agent's focus or update constraints without stopping the process.
+</objective>
 
-## Usage
-- `/mindforge:steer "Use the new logger in all created files"`
-- `/mindforge:steer --task 3-05 "This plan is too broad, focus on login only"`
-- `/mindforge:steer --cancel` (Clears the steering queue)
+<execution_context>
+.claude/commands/mindforge/steer.md
+</execution_context>
 
-## Precedence
-- Steering instructions take precedence over the original `PLAN-N-MM.md` actions.
-- Steering cannot override core security constraints or governance gates.
+<context>
+Lifecycle: Applied at the next task boundary in `/mindforge:auto` mode.
+Priority: Steering takes precedence over the original `PLAN.md` instructions.
+</context>
+
+<process>
+1. **Queue Instruction**: Write the steering guidance to the active execution state.
+2. **Target (Optional)**: Explicitly target a future task ID for modification.
+3. **Validate**: Ensure steering does not violate core security or governance gates.
+4. **Cancel**: Clear the steering queue if instructions are no longer relevant.
+</process>

package/.claude/commands/mindforge/sync-confluence.md

@@ -1,11 +1,30 @@
-Publish approved planning artifacts to Confluence. Usage:
-`/mindforge:sync-confluence [--architecture] [--phase N] [--milestone name]`
+---
+name: mindforge:sync-confluence
+description: Publish approved planning artifacts to Confluence
+argument-hint: [--architecture] [--phase N] [--milestone name]
+allowed-tools:
+  - run_command
+  - view_file
+  - write_to_file
+---
 
-## Behaviour
-- verify Confluence availability through `connection-manager.md`
-- publish idempotently by existing page title or page ID
-- never publish secrets, raw approval notes, or raw audit logs
-- log success, skip, or failure to AUDIT
+<objective>
+Automate the publication of key project documentation and architectural decisions to Confluence, providing a durable and searchable record for the broader organization.
+</objective>
 
-Publishing failures are non-fatal and create a pending manual action in
- `STATE.md`.
+<execution_context>
+.claude/commands/mindforge/sync-confluence.md
+</execution_context>
+
+<context>
+Auth: Managed via `connection-manager.md`.
+Exclusion: Secrets, raw logs, and PII are strictly filtered before publication.
+</context>
+
+<process>
+1. **Assemble Content**: Gather target artifacts (ARCHITECTURE.md, Phase Plans, Milestone reports).
+2. **Filter & Sanitize**: Remove all sensitive data (passwords, tokens, raw audit trails).
+3. **Publish**: Update existing pages or create new ones in the specified Confluence space.
+4. **Indempotency**: Match pages by title or project-wide ID to avoid duplication.
+5. **Audit**: Log publication success or skipped files.
+</process>

package/.claude/commands/mindforge/sync-jira.md

@@ -1,12 +1,32 @@
-Synchronise MindForge phase and plan metadata to Jira. Usage:
-`/mindforge:sync-jira [--phase N] [--plan M]`
-
-## Behaviour
-- verify Jira availability through `connection-manager.md`
-- create or update Epic and Story mappings in `.planning/jira-sync.json`
-- use dynamic transition lookup, never hardcoded IDs
-- preserve manual Jira edits
-- log all actions to AUDIT
-
-Integration failures are non-fatal and should be written to `STATE.md` for
- manual retry.
+---
+name: mindforge:sync-jira
+description: Synchronize MindForge phase and plan metadata to Jira
+argument-hint: [--phase N] [--plan M]
+allowed-tools:
+  - run_command
+  - view_file
+  - write_to_file
+---
+
+<objective>
+Maintain parity between local MindForge planning state and the enterprise Jira issue tracker, ensuring stakeholders have visibility into phase progress and task status.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/sync-jira.md
+</execution_context>
+
+<context>
+Metadata: .planning/jira-sync.json
+Auth: Managed via `connection-manager.md`.
+Resilience: Failures are non-fatal; state is logged in `STATE.md` for retry.
+</context>
+
+<process>
+1. **Verify Connection**: Ensure Jira API availability and auth tokens are valid.
+2. **Resolve Mappings**: Map Phase and Plan IDs to Jira Epics and Stories.
+3. **Transition Issues**: Update Jira statuses based on verification results (e.g., Verified -> Done).
+4. **Sync Content**: Push plan descriptions and requirements to the relevant Jira tickets.
+5. **Preserve Manual Edits**: Avoid overwriting manual comments or fields in Jira.
+6. **Audit**: Log the sync event with counts of updated and created tickets.
+</process>

package/.claude/commands/mindforge/tokens.md

@@ -1,8 +1,27 @@
-# MindForge — Token Usage Command
-# Usage: /mindforge:tokens [--phase N] [--session ID] [--window short|medium|long] [--optimise]
+---
+name: mindforge:tokens
+description: Analyze token consumption profile and efficiency
+argument-hint: [--phase N] [--session ID] [--window short|medium|long] [--optimise]
+allowed-tools:
+  - view_file
+  - run_command
+---
 
-## Purpose
-Display token consumption profile and efficiency analysis.
-Helps identify where tokens are being spent and how to reduce waste.
+<objective>
+Deeply analyze how tokens are being consumed across the project to identify waste, improve prompt efficiency, and optimize context budgeting.
+</objective>
 
-## Default output (no flags — last 5 sessions)
+<execution_context>
+.claude/commands/mindforge/tokens.md
+</execution_context>
+
+<context>
+Analysis Focus: Input vs Output tokens, cache hits/misses, compaction efficiency.
+</context>
+
+<process>
+1. **Fetch Profiles**: Read token usage data for the specified scope.
+2. **Identify Waste**: Detect large, repetitive context injections or missed cache opportunities.
+3. **Optimization Advice**: If `--optimise` is set, provide specific recommendations (e.g., "Summarize ARCHITECTURE.md to save 2k tokens/session").
+4. **Report**: Display the token consumption profile and efficiency score.
+</process>

package/.claude/commands/mindforge/ui-phase.md

@@ -0,0 +1,34 @@
+---
+name: mindforge:ui-phase
+description: Generate a UI Design Contract (UI-SPEC.md) for the current phase
+argument-hint: [N]
+allowed-tools:
+  - view_file
+  - write_to_file
+  - list_dir
+---
+
+<objective>
+Generate a detailed UI design contract (UI-SPEC.md) for a frontend development phase to ensure consistent spacing, typography, color palettes, and accessibility standards before implementation.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/ui-phase.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (The phase number [N], optional)
+Configuration: MINDFORGE.md `UI_PHASE_ACCESSIBILITY_STANDARD`
+State: Resolves the phase from STATE.md if N is not provided.
+</context>
+
+<process>
+1. **Identify Phase**: Get the current or targeted phase number.
+2. **Read Inputs**: Read `REQUIREMENTS.md` and `DESIGN_SYSTEM.md`.
+3. **Generate UI-SPEC.md**:
+    - Define component-level spacing and layout for the phase.
+    - Specify required colors and typography from the design system.
+    - List accessibility requirements (WCAG level).
+4. **Finalize**: Write `UI-SPEC.md` to the phase's planning directory or the root `.planning/`.
+5. **Confirm**: Provide a link to the user for review.
+</process>

package/.claude/commands/mindforge/ui-review.md

@@ -0,0 +1,36 @@
+---
+name: mindforge:ui-review
+description: Perform a retroactive visual audit of implemented UI against the DESIGN_SYSTEM.md and UI-SPEC.md
+argument-hint: [N]
+allowed-tools:
+  - view_file
+  - write_to_file
+  - read_browser_page
+  - open_browser_url
+---
+
+<objective>
+Perform a retroactive, multi-pillar visual audit of implemented UI features against the defined Design System and UI-SPEC.md to ensure pixel-perfect fidelity and accessibility compliance.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/ui-review.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (The phase number [N], optional)
+Sources: `DESIGN_SYSTEM.md`, `UI-SPEC.md`, and the live application UI.
+</context>
+
+<process>
+1. **Identify Target**: Determine the phase to review.
+2. **Audit Application**:
+    - Use the browser tool to inspect the implemented features.
+    - Compare against the `UI-SPEC.md` for spacing, colors, and layout.
+    - Audit for accessibility (ARIA labels, contrast, keyboard navigation).
+3. **Generate UI-REVIEW.md**:
+    - Grade each pillar (Layout, Color, Typography, etc.).
+    - List specific "Needs Work" items.
+    - Provide "Approved" status if all criteria are met.
+4. **Finalize**: Notify the user of the audit results.
+</process>

package/.claude/commands/mindforge/update.md

@@ -1,42 +1,33 @@
-# MindForge — Update Command
-# Usage: /mindforge:update [--apply] [--force] [--check] [--skip-changelog]
-
-## Purpose
-Check for and apply MindForge framework updates in a safe, scope-preserving way.
-
-## Execution flow
-
-### 1. Version check
-Execute `bin/updater/self-update.js` `checkAndUpdate()`.
-Always show: current version, latest version, update type (major/minor/patch).
-
-### 2. Changelog display (unless --skip-changelog)
-Fetch and display the relevant CHANGELOG.md section.
-For major updates: prefix with ⚠️ BREAKING CHANGES notice.
-Limit display to 3,000 characters — link to full CHANGELOG for the rest.
-
-### 3. Confirmation gate (unless --apply)
-Without --apply: show update info, stop. Do not modify any files.
-Message: "To apply this update: /mindforge:update --apply"
-
-### 4. Apply (with --apply)
-a. Detect original install scope (local vs global, claude vs antigravity)
-b. Read schema_version from HANDOFF.json (captures current version BEFORE update)
-c. Run `npx mindforge-cc@[latest] --[runtime] --[scope]`
-d. Run migration: `node bin/migrations/migrate.js` with captured schema_version
-e. Run /mindforge:health to verify update succeeded
-
-### 5. Post-update health check
-If health errors: surface them immediately with specific fix instructions.
-Common post-update issue: CLAUDE.md and .agent/CLAUDE.md drifted → auto-repair.
-
-## Error scenarios and recovery
-
-| Error | Recovery |
-|---|---|
-| npm registry unreachable | Message: "Check internet. Manual: npm info mindforge-cc version" |
-| Update download fails | Retry once, then suggest manual: `npx mindforge-cc@latest` |
-| Migration fails | Restored from backup automatically. Run /mindforge:migrate manually. |
-| Install scope detection fails | Prompt user: "Is your install global or local?" |
-
-## AUDIT entry
+---
+name: mindforge:update
+description: Safely check for and apply MindForge framework updates
+argument-hint: [--apply] [--force] [--check] [--skip-changelog]
+allowed-tools:
+  - run_command
+  - view_file
+  - write_to_file
+---
+
+<objective>
+Keep the project's MindForge installation up to date with the latest features, bug fixes, and security patches while ensuring no data loss or architectural regression.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/update.md
+</execution_context>
+
+<context>
+Platform: bin/updater/self-update.js
+Scope: Local vs. Global detection.
+Security: Enforces schema migration during the update process.
+</context>
+
+<process>
+1. **Check**: Query the registry for the latest version and compare with the current installation.
+2. **Changelog**: Display relevant updates, highlighting **BREAKING CHANGES** for major versions.
+3. **Pre-update State**: Capture the `schema_version` from HANDOFF.json.
+4. **Apply**: If `--apply` is set, download and install the new version into the detected scope.
+5. **Migrate**: Run `/mindforge:migrate` to reconcile the project schema with the new framework version.
+6. **Verify**: Run `/mindforge:health` to confirm the update succeeded without introducing errors.
+7. **Audit**: Log `update_completed` with the jump range (X.Y.Z -> A.B.C).
+</process>

package/.claude/commands/mindforge/validate-phase.md

@@ -0,0 +1,31 @@
+---
+name: mindforge:validate-phase
+description: Audit the current phase for requirement coverage and test gaps
+argument-hint: [N]
+allowed-tools:
+  - view_file
+  - list_dir
+---
+
+<objective>
+Audit a completed project phase to ensure every requirement has been addressed and that corresponding automated tests have been implemented and are passing.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/validate-phase.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (The phase number [N], optional)
+Knowledge: `STATE.md`, `REQUIREMENTS.md`, and the codebase test suite.
+</context>
+
+<process>
+1. **Identify Phase**: Resolve the targeted phase.
+2. **Cross-reference**:
+    - List all requirements in `REQUIREMENTS.md` marked for this phase.
+    - Verify implementation of each requirement in the code.
+    - Check for the existence of passing tests for each requirement.
+3. **Analyze Gaps**: Identify any "orphaned" requirements or features missing tests.
+4. **Report Findings**: Summarize coverage and call out specific gaps to the user.
+</process>