mindforge-cc 6.2.0-alpha → 6.2.0

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

@@ -1,37 +1,200 @@
 ---
-name: mindforge:execute-phase
-description: Execute the wave-based execution plan for a specific phase
-argument-hint: [N]
-allowed-tools:
-  - view_file
-  - write_to_file
-  - run_command
-  - list_dir
+description: 1. Read STATE.md — confirm phase [N] is in "planned" status.
 ---
 
-<objective>
-Coordinate the parallel execution of task plans for a phase using a wave-based approach, ensuring dependency integrity, automated verification, and audit logging.
-</objective>
-
-<execution_context>
-.claude/commands/mindforge/execute-phase.md
-</execution_context>
-
-<context>
-Arguments: $ARGUMENTS (Phase N)
-Sources: .planning/phases/[N]/PLAN-*.md, STATE.md, REQUIREMENTS.md
-Engine: wave-executor.md, dependency-parser.md, context-injector.md
-</context>
-
-<process>
-1. **Pre-checks**: Verify phase status, plan existence, and requirement content. Run dependency parser.
-2. **Display Wave Plan**: Present the wave-based execution graph and wait for user approval.
-3. **Audit Initiation**: Log `phase_execution_started` in `AUDIT.jsonl`.
-4. **Wave Execution**:
-    - For each wave: Execute tasks in parallel.
-    - For each task: Inject context, run implementation, run `<verify>`, and commit with SHA.
-    - If any task fails: Stop the wave and offer debugging.
-5. **Phase Verification**: Check requirement coverage in the implementation and write `VERIFICATION.md`.
-6. **Update State**: Update `STATE.md`, `HANDOFF.json`, and write `WAVE-REPORT-[N].md`.
-7. **Auto-capture**: If enabled, detect new patterns/skills from the implemented phase.
-</process>
+# MindForge — Execute Phase Command
+# Usage: /mindforge:execute-phase [N]
+
+## Pre-checks (all must pass before execution starts)
+
+1. Read STATE.md — confirm phase [N] is in "planned" status.
+   If STATE.md shows phase [N] as already "complete": ask user to confirm re-execution.
+
+2. Verify plan files exist:
+   ```
+   .planning/phases/[N]/PLAN-[N]-01.md   (minimum one plan required)
+   ```
+   If missing: stop. Tell user: "No plans found for Phase [N]. Run /mindforge:plan-phase [N] first."
+
+3. Verify REQUIREMENTS.md exists and has content.
+   If empty: warn user but allow continuation.
+
+4. Run the dependency parser (`.mindforge/engine/dependency-parser.md`).
+   If validation fails (circular deps, missing deps): stop and report. Do not execute.
+
+## Step 1 — Build and display the execution plan
+
+After dependency parsing succeeds, display the wave plan to the user:
+
+```
+Phase [N] Execution Plan
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Wave 1 (parallel)     Wave 2 (parallel)     Wave 3
+  ┌─────────────┐       ┌─────────────┐       ┌─────────────┐
+  │ Plan 01     │       │ Plan 03     │       │ Plan 05     │
+  │ User model  │──┐    │ User API    │──┐    │ Checkout UI │
+  └─────────────┘  │    └─────────────┘  │    └─────────────┘
+  ┌─────────────┐  │    ┌─────────────┐  │
+  │ Plan 02     │──┘    │ Plan 04     │──┘
+  │ Product     │       │ Product API │
+  └─────────────┘       └─────────────┘
+
+  Total tasks: 5    Waves: 3    Est. time: depends on model speed
+
+Proceed? (yes/no)
+```
+
+If the user says no: stop. Do not execute anything.
+
+## Step 2 — Write pre-execution audit entry
+
+Append to `.planning/AUDIT.jsonl`:
+```json
+{
+  "id": "[uuid-v4]",
+  "timestamp": "[ISO-8601]",
+  "event": "phase_execution_started",
+  "phase": [N],
+  "wave_count": [total waves],
+  "task_count": [total tasks],
+  "agent": "mindforge-orchestrator",
+  "session_id": "[session identifier]"
+}
+```
+
+## Step 3 — Execute waves using the wave executor
+
+Follow the complete protocol in `.mindforge/engine/wave-executor.md`.
+
+For each wave:
+
+### Wave start
+Write to console:
+```
+━━━ Wave [W] of [total] ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Starting [X] tasks in parallel...
+```
+
+### Per-task execution (inject context per `context-injector.md`)
+For each plan in the wave:
+1. Load context package (per `context-injector.md`)
+2. Execute the plan instructions
+   - Run `<verify>` — capture exact output
+   - If verify PASSES:
+     - Run `<verify-visual>` via `visual-verify-executor.js`
+     - If visual verify FAILS: stop and report (treat as verify failure)
+     - Write SUMMARY-[N]-[M].md
+   - Execute commit: `git add [files] && git commit -m "[type]([scope]): [task name]"`
+   - Capture git SHA
+   - Write AUDIT entry for task completion
+5. If verify FAILS:
+   - Write SUMMARY-[N]-[M].md with failure details
+   - Write AUDIT entry for task failure
+   - STOP this wave immediately
+   - Report: "Task [plan ID] failed: [verify output]. Stopping Phase [N]."
+   - Do not start next wave
+   - Ask user: "Spawn debug agent to diagnose? (yes/no)"
+
+### Wave completion (before starting next wave)
+After all tasks in wave complete:
+1. Run: `[project test command]`
+2. If tests fail:
+   - Identify failing tests
+   - Run `git log --oneline -[wave-task-count]` to see wave commits
+   - Report which commit likely introduced the failure
+   - Stop. Ask user how to proceed.
+3. If tests pass:
+   - Report: "Wave [W] complete. All [X] tasks passed. Tests passing. ✅"
+   - Run `/mindforge:record-learning` if any architectural "Aha!" moments or significant anti-patterns were discovered during this wave.
+   - Write WAVE-REPORT update
+
+## Step 4 — Phase-level verification
+
+After all waves complete, run the verification pipeline:
+
+1. Read every v1 requirement from REQUIREMENTS.md for this phase
+2. For each requirement, verify it is implemented:
+   - Search the codebase for the implementation
+   - Check if a test covers it
+   - Mark: ✅ implemented + tested | ⚠️ implemented, no test | ❌ not found
+3. Write `.planning/phases/[N]/VERIFICATION.md`
+4. Run the full test suite one final time
+5. If any requirement is ❌: create a fix plan and report to user
+
+## Step 5 — Update state and write wave report
+
+Write `.planning/phases/[N]/WAVE-REPORT-[N].md` (per template in wave-executor.md)
+
+Update STATE.md:
+```markdown
+## Current phase
+[N] — Execution complete ✅
+
+## Last completed task
+Phase [N]: All [X] tasks completed across [W] waves.
+
+## Next action
+Run /mindforge:verify-phase [N] for human acceptance testing.
+```
+
+Update HANDOFF.json with completed phase info.
+
+## Step 5.1 — Final Intelligence Sync
+1. Read `AGENTS_LEARNING.md` one last time.
+2. Run `/mindforge:record-learning` to capture the final phase-level learnings (Mistakes discovered during UAT, architectural refinements).
+3. Commit `AGENTS_LEARNING.md` if updated.
+
+Write final AUDIT entry:
+```json
+{
+  "id": "[uuid-v4]",
+  "timestamp": "[ISO-8601]",
+  "event": "phase_execution_completed",
+  "phase": [N],
+  "tasks_completed": [X],
+  "waves_executed": [W],
+  "commits": ["sha1", "sha2", "..."],
+  "test_result": "passing",
+  "agent": "mindforge-orchestrator"
+}
+```
+
+## Step 6 — Report to user
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ Phase [N] execution complete
+
+  Tasks completed : [X] / [X]
+  Waves executed  : [W]
+  Commits made    : [X]
+  Tests           : All passing
+  Requirements    : [X] / [X] implemented
+
+Next step: Run /mindforge:verify-phase [N] for UAT sign-off.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## Step 7 — Auto-capture check (when AUTO_CAPTURE_SKILLS=true)
+
+After all gates pass and the phase is verified:
+
+```bash
+# Check if auto-capture is enabled
+CAPTURE=$(grep -m1 "^AUTO_CAPTURE_SKILLS=" MINDFORGE.md 2>/dev/null | cut -d= -f2 | tr -d ' ')
+if [ "$CAPTURE" = "true" ]; then
+  node -e "
+    const { detectPatterns, formatForPresentation } = require('./bin/skills-builder/pattern-detector');
+    detectPatterns(${PHASE_NUM}).then(result => {
+      const display = formatForPresentation(result);
+      console.log(display);
+    }).catch(err => console.error('[auto-capture] Error:', err.message));
+  "
+fi
+```
+
+If patterns are found: display the prompt and await user input.
+If user selects yes: run `/mindforge:learn --session` targeting this phase's SUMMARY files.
+If user selects no: write AUDIT entry `auto_capture_skipped` and continue.
+If no patterns found: exit silently (no noise in the output).
+```

package/.claude/commands/mindforge/health.md

@@ -1,31 +1,31 @@
 ---
-name: mindforge:health
-description: Run the MindForge health engine to diagnose and repair issues
-argument-hint: [--repair] [--category C] [--verbose]
-allowed-tools:
-  - run_command
-  - list_dir
-  - view_file
+description: Run all seven health-engine categories from .mindforge/intelligence/health-engine.md.
 ---
 
-<objective>
-Ensure the MindForge environment and project state are valid, secure, and optimally configured by running a suite of diagnostic checks across multiple categories.
-</objective>
+# MindForge — Health Command
+# Usage: /mindforge:health [--repair] [--category C] [--verbose]
 
-<execution_context>
-.claude/commands/mindforge/health.md
-</execution_context>
+Run all seven health-engine categories from `.mindforge/intelligence/health-engine.md`.
 
-<context>
-Engine: .mindforge/intelligence/health-engine.md
-Categories: installation, context, skills, personas, state, integrations, security.
-Flags: --repair (auto-fix), --verbose (full details).
-</context>
+## Output
+- category status summary
+- errors (must fix)
+- warnings (should fix)
+- informational signals
 
-<process>
-1. **Initialize Diagnostics**: Load the health engine and target specifically requested categories (or all by default).
-2. **Execute Checks**: Scan for configuration errors, missing files, security misconfigurations, and state inconsistencies.
-3. **Repair (Optional)**: If `--repair` is set, apply safe automated fixes for detected issues.
-4. **Report Findings**: Categorize results into Errors (must fix), Warnings (should fix), and Info.
-5. **Audit**: Log `health_check_completed` with counts of errors, warnings, and repairs.
-</process>
+## Sovereign Intelligence Checks (v6.2.0-alpha)
+- **PQAS Verification**: Check `bin/governance/quantum-crypto.js` presence
+- **Homing Verification**: Check `bin/autonomous/intent-harvester.js` presence
+- **Self-Healer Verification**: Check `bin/autonomous/mesh-self-healer.js` presence
+- **Policy Check**: Verify `bin/governance/policy-engine.js` is Sovereign-configured
+
+## Flags
+- `--repair`: apply safe auto-repair only
+- `--category`: one of `installation|context|skills|personas|state|integrations|security`
+- `--verbose`: include passing checks and exact inspected values
+
+## AUDIT
+Append:
+```json
+{ "event": "health_check_completed", "errors": 0, "warnings": 0, "repaired": 0 }
+```

package/.claude/commands/mindforge/help.md

@@ -1,29 +1,33 @@
 ---
-name: mindforge:help
-description: Show all available MindForge commands and current project summary
-argument-hint: none
-allowed-tools:
-  - list_dir
-  - view_file
+description: Show all available MindForge commands.
 ---
 
-<objective>
-Provide a searchable, categorized directory of all accessible MindForge commands, along with a quick snapshot of the project's current state.
-</objective>
+Show all available MindForge commands.
 
-<execution_context>
-.claude/commands/mindforge/help.md
-</execution_context>
+## Pre-check
+If `.planning/STATE.md` exists, read it.
+If `.planning/PROJECT.md` is missing, treat the project as "Not initialised".
 
-<context>
-Discovery: Scans `.claude/commands/mindforge/*.md`
-State: PROJECT.md and STATE.md
-</context>
+1. Scan every .md file in `.claude/commands/mindforge/`
+2. For each file, extract the first non-empty line as the command description
+3. Display as a clean table:
 
-<process>
-1. **Command Scan**: List all markdown definitions in the command directory and extract their first-line descriptions or YAML metadata.
-2. **Read Project Info**: Summarize the current project name, active phase, and recommended next step.
-3. **Format Dashboard**: Render a clean table of commands and descriptions.
-4. **Verify Context**: If `CLAUDE.md` hasn't been read in the current session, remind the user to load it as the agent's context.
-5. **Display**: Present the help table and project summary.
-</process>
+| Command                      | Description                                  |
+|------------------------------|----------------------------------------------|
+| /mindforge:help              | Show all available commands                  |
+| /mindforge:init-project      | ...                                          |
+| ...                          | ...                                          |
+
+## Sovereign Intelligence (v6.2.0-alpha)
+MindForge now operates with **Sovereign Intelligence** enabled by default:
+- **PQAS**: Post-Quantum Agentic Security is active. High-risk operations require biometric/executive bypass.
+- **Proactive Homing**: The swarm now proactively harvests intent and self-heals reasoning drifts.
+- **Integrity**: Every `security-scan` now verifies framework signatures using lattice-based cryptography.
+
+4. After the table, print:
+   "Current project: [read PROJECT.md first line, or 'Not initialised']"
+   "Current phase:   [read STATE.md current phase, or 'None']"
+   "Next step:       [read STATE.md next action]"
+
+5. If CLAUDE.md has not been read this session, remind the user to ensure
+   it is loaded as MindForge's system context.

package/.claude/commands/mindforge/init-org.md

@@ -1,37 +1,135 @@
 ---
-name: mindforge:init-org
-description: Set up MindForge at the organization level with standardized context
-argument-hint: [--org-name "Name"] [--update]
-allowed-tools:
-  - run_command
-  - list_dir
-  - write_to_file
-  - view_file
+description: Set up MindForge at the organisation level — create standardised org-level
 ---
 
-<objective>
-Establish a consistent engineering culture and governance framework by generating organization-wide context files, security policies, and tech stack defaults for all projects.
-</objective>
-
-<execution_context>
-.claude/commands/mindforge/init-org.md
-</execution_context>
-
-<context>
-Scope: Organization-wide (Tier 1/2).
-Output: Shared `.mindforge/org/` repository or npm package.
-Governance: Defines Tier 2/3 approver lists and compliance burdens.
-</context>
-
-<process>
-1. **Interview**: Conduct a structured interview about org identity, tech stack, deployment defaults, and compliance (GDPR, HIPAA, etc.).
-2. **Generate Defaults**:
-    - `ORG.md`: Mission and global architecture defaults.
-    - `CONVENTIONS.md`: Tech-stack-specific coding standards.
-    - `SECURITY.md`: Compliance-mapped security policies.
-    - `TOOLS.md`: Approved library and dependency list.
-3. **Configuration**: Pre-populate `INTEGRATIONS-CONFIG.md` and `GOVERNANCE-CONFIG.md`.
-4. **Skill Recommendation**: Suggest core and compliance skills to install org-wide.
-5. **Distribution**: Offer to package the configuration into an npm package for project-wide inheritance.
-6. **Audit**: Log `org_initialised` with frameworks and recommended skills.
-</process>
+# MindForge — Init Org Command
+# Usage: /mindforge:init-org [--org-name "Name"] [--update]
+
+## Purpose
+Set up MindForge at the organisation level — create standardised org-level
+context files that are shared across ALL projects in the organisation.
+
+Intended to be run ONCE by a platform engineer or engineering lead.
+Output is committed to a shared `mindforge-org-config` repository
+and distributed to projects as a git submodule or npm package.
+
+## Step 1 — Gather org information
+
+Ask (one question at a time):
+1. "What is your organisation name?"
+2. "Describe what your organisation builds in 1-2 sentences."
+3. "What is your primary tech stack? (describe in plain English)"
+4. "What is your default deployment target? (AWS / GCP / Azure / self-hosted / hybrid)"
+5. "What regulatory frameworks apply to your organisation?"
+   Options: GDPR / HIPAA / SOC 2 / PCI-DSS / ISO 27001 / None / Multiple
+6. "What is your source control platform?" (GitHub / GitLab / Bitbucket / Azure DevOps)
+7. "What is your issue tracker?" (Jira / GitHub Issues / Linear / Azure DevOps / None)
+8. "Who are your Tier 3 compliance approvers? (email addresses, comma-separated)"
+
+## Step 2 — Generate org-level context files
+
+Create (or update with `--update`) these files:
+
+### `.mindforge/org/ORG.md`
+Populated from answers with:
+- Organisation identity and mission
+- Default tech stack with version recommendations
+- Architecture defaults
+- Team conventions
+- Compliance requirements
+
+### `.mindforge/org/CONVENTIONS.md`
+Generate sensible defaults based on the tech stack detected.
+For TypeScript/Node.js stacks: strict TypeScript, ESLint, Conventional Commits
+For Python stacks: ruff, mypy, black formatting
+For Go: standard Go toolchain conventions
+Mark each section clearly: [DEFAULT] or [CUSTOMISE THIS]
+
+### `.mindforge/org/SECURITY.md`
+Generate based on declared compliance frameworks:
+- GDPR → include GDPR-specific policies
+- HIPAA → include PHI handling requirements
+- PCI-DSS → include card data handling policies
+- SOC 2 → include access control requirements
+Mark critical sections: [REVIEW WITH SECURITY TEAM]
+
+### `.mindforge/org/TOOLS.md`
+Generate approved library list based on tech stack.
+Include common forbidden libraries (moment.js, request, etc.)
+Mark: [ADD YOUR APPROVED LIBRARIES]
+
+### `.mindforge/org/integrations/INTEGRATIONS-CONFIG.md`
+Pre-populate based on declared platforms:
+- GitHub → fill GitHub config section
+- Jira → fill Jira config section
+Mark credential fields clearly: [SET VIA ENVIRONMENT VARIABLE]
+
+### `.mindforge/governance/GOVERNANCE-CONFIG.md`
+Pre-populate based on declared approvers and compliance frameworks.
+Higher compliance burden → lower Tier 2/3 thresholds.
+Stricter approval SLAs for HIPAA/PCI-DSS organisations.
+
+## Step 3 — Generate skills recommendation
+
+Based on the tech stack and compliance requirements, recommend skills to install:
+
+```
+Recommended skills for your tech stack:
+
+Core skills (already included — v0.6.0):
+  ✅ security-review, code-quality, api-design, testing-standards, documentation,
+     performance, accessibility, data-privacy, incident-response, database-patterns
+
+Additional skills recommended for your stack:
+  [tech-stack-specific recommendations from registry]
+
+For your compliance requirements:
+  [compliance-specific skill recommendations]
+
+Install all recommendations?
+  yes → npx mindforge-skills install [list]
+  no  → I'll show you the install commands for each
+```
+
+## Step 4 — Create distribution package
+
+Offer to create an org-skills npm package for distributing org-level config:
+
+```
+Create `@your-org/mindforge-config` npm package?
+This package will distribute your org-level MindForge configuration
+to all projects in your organisation via: npx @your-org/mindforge-config
+
+Files included:
+  .mindforge/org/ORG.md
+  .mindforge/org/CONVENTIONS.md
+  .mindforge/org/SECURITY.md
+  .mindforge/org/TOOLS.md
+  .mindforge/org/skills/MANIFEST.md
+  .mindforge/org/integrations/INTEGRATIONS-CONFIG.md (without credentials)
+  .mindforge/governance/GOVERNANCE-CONFIG.md (without credentials)
+```
+
+## Step 5 — Write AUDIT entry and report
+
+```json
+{ "event": "org_initialised", "org_name": "[name]", "compliance_frameworks": [...], "skills_recommended": [...] }
+```
+
+Report:
+```
+✅ MindForge organisation configuration complete.
+
+Files created:
+  .mindforge/org/ORG.md
+  .mindforge/org/CONVENTIONS.md
+  .mindforge/org/SECURITY.md
+  .mindforge/org/TOOLS.md
+  .mindforge/governance/GOVERNANCE-CONFIG.md
+
+Next steps:
+  1. Review each file — look for [CUSTOMISE THIS] markers
+  2. Fill in SECURITY.md with your security team
+  3. Commit to your org's mindforge-config repository
+  4. Share with all projects: npx @your-org/mindforge-config (if you created the package)
+```