mindforge-cc 6.2.0-alpha → 6.2.0

package/.claude/commands/mindforge/security-scan.md

@@ -1,34 +1,242 @@
 ---
-name: mindforge:security-scan
-description: Perform a standalone security scan for OWASP Top 10 vulnerabilities and leaked secrets
-argument-hint: [path] [--deep] [--deps] [--secrets]
-allowed-tools:
-  - run_command
-  - view_file
-  - write_to_file
-  - list_dir
+description: - Default: OWASP Top 10 review on the changed files or specified path
 ---
 
-<objective>
-Execute a rigorous security audit of the codebase, scanning for OWASP vulnerabilities, hardcoded secrets, and vulnerable dependencies to ensure production readiness and compliance.
-</objective>
-
-<execution_context>
-.claude/commands/mindforge/security-scan.md
-</execution_context>
-
-<context>
-Mode: Runs entirely under the `security-reviewer.md` persona.
-Flags: --deep (all files), --deps (CVE scan), --secrets (fast secret detection).
-Output: .planning/SECURITY-SCAN-[timestamp].md
-</context>
-
-<process>
-1. **Build Scope**: Determine target files using `git diff` or `find` based on flags.
-2. **Top 10 Scan**: Audit for Access Control, Crypto failures, Injection, Insecure Design, etc.
-3. **Secret Detection**: Run pattern-based grep for high-confidence strings (API keys, connection strings, private keys). Redact values in output.
-4. **Dependency Audit**: If `--deps` is set, run `npm audit` or `pip-audit` and parse JSON for HIGH/CRITICAL CVEs.
-5. **Generate Report**: Write `SECURITY-SCAN-[timestamp].md` with categorized findings and a final verdict (CLEAN/ISSUES).
-6. **Alert**: If CRITICAL findings exist, block merging and display a prominent warning.
-7. **Audit**: Log `security_scan_completed` event.
-</process>
+# MindForge — Security Scan Command
+# Usage: /mindforge:security-scan [path] [--deep] [--deps] [--secrets]
+# Standalone security scan. Can be run independently of the phase lifecycle.
+
+## Scan modes
+- Default: OWASP Top 10 review on the changed files or specified path
+- `--deep`: Extended scan including all files, not just changed
+- `--deps`: Dependency audit (CVE scan of package.json / requirements.txt)
+- `--secrets`: Secret detection scan only (fast, suitable for pre-commit hook)
+- Flags composable: `--deps --secrets` runs both dependency audit and secret detection
+
+## Step 1 — Activate Security Reviewer persona
+
+Load `security-reviewer.md` persona immediately and completely.
+This command runs entirely in security mode. Do not switch personas.
+
+## Step 1.5 — Sovereign Integrity Check (v6.2.0-alpha)
+
+Before scanning user code, verify the integrity of the MindForge Sovereign Engine:
+1.  **Quantum Signature Verification**: Run `node bin/governance/quantum-crypto.js --verify .mindforge/engine/`.
+2.  **Policy Integrity**: Ensure `bin/governance/policy-engine.js` has not been tampered with (check for illegal bypass additions).
+3.  **Result**: If integrity check fails, mark the entire scan as **FAILED (CRITICAL)** and alert the user of a potential framework compromise.
+
+```bash
+# Default: staged + unstaged changes
+git diff HEAD --name-only
+
+# With path argument
+find [path] -name "*.ts" -o -name "*.js" -o -name "*.py"
+
+# --deep: all source files
+find src/ -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" \)
+```
+
+## Step 3 — OWASP Top 10 scan (always runs unless --secrets only)
+
+For each file in scope, check all 10 OWASP categories:
+
+### A01 — Broken Access Control
+- Scan for: missing auth middleware, direct object references, path traversal
+- Patterns to flag:
+  ```
+  req.params.userId         # Direct user ID from request — verify ownership check
+  fs.readFile(userInput)    # Path traversal risk
+  WHERE id = ${id}          # Direct injection without parameterisation
+  ```
+
+### A02 — Cryptographic Failures
+- Scan for: weak algorithms, insecure transport, unencrypted sensitive data
+- Patterns to flag:
+  ```
+  md5(, sha1(, sha256(password  # Weak password hashing
+  http://   # Non-HTTPS URLs in API calls
+  Math.random()  # Cryptographically insecure random
+  ```
+
+### A03 — Injection
+- Scan for: SQL, NoSQL, OS, LDAP injection
+- Patterns to flag:
+  ```
+  `SELECT * FROM users WHERE email = '${  # SQL injection
+  exec(, execSync(, child_process         # OS command injection
+  eval(userInput                          # Code injection
+  ```
+
+### A04 — Insecure Design
+- Scan for: missing rate limiting, no input validation, trust boundary issues
+- Patterns to flag: endpoints without validation middleware, no rate limit decorators
+
+### A05 — Security Misconfiguration
+- Scan for: debug mode in production, default credentials, verbose errors
+- Patterns to flag:
+  ```
+  console.error(err)        # Exposes stack traces to clients
+  NODE_ENV !== 'production' # Debug code paths
+  ALLOW_ALL, *, cors({origin: '*'})  # Overly permissive CORS
+  ```
+
+### A06 — Vulnerable Components
+- Run: `npm audit --audit-level=moderate` or `pip-audit`
+- Flag any HIGH or CRITICAL CVEs
+
+### A07 — Authentication Failures
+- Scan for: missing password complexity, no brute force protection, weak sessions
+- Patterns to flag:
+  ```
+  bcrypt.hashSync(pass, 1)  # Cost factor too low
+  jwt.verify(token, '', {   # Empty secret
+  session.destroy(          # Verify redirect after destroy
+  ```
+
+### A08 — Software and Data Integrity Failures
+- Check: no package-lock.json means no integrity guarantee
+- Check: any `curl | sh` or `wget | bash` patterns
+
+### A09 — Security Logging Failures
+- Scan for: no logging on auth failures, admin actions not logged, PII in logs
+- Patterns to flag:
+  ```
+  user.email in any log statement
+  password in any log statement
+  catch(e) {}  # Silent failure = no security log
+  ```
+
+### A10 — SSRF
+- Scan for: server-side requests to user-controlled URLs
+- Patterns to flag:
+  ```
+  fetch(req., axios.get(req., axios.post(req., http.get(req.,
+  req.body.url, req.params.url, req.query.url, req.headers
+  ```
+
+## Step 4 — Secret detection (--secrets or always as part of default scan)
+
+Pattern-based scan across all files in scope:
+
+```bash
+# High confidence patterns (always flag as CRITICAL)
+grep -rn -E "(sk-[a-zA-Z0-9]{20,}|AKIA[A-Z0-9]{16}|ghp_[a-zA-Z0-9]{36})" .
+
+# Credential assignment patterns (flag as HIGH)
+grep -rn -E "(password|passwd|secret|api_key|apikey|access_token)\s*=\s*['\"][^'\"]{8,}" .
+
+# Azure connection strings
+grep -rn -E "DefaultEndpointsProtocol=https;AccountName=" .
+
+# GCP service account keys
+grep -rn -E "\"type\"\\s*:\\s*\"service_account\"" .
+
+# PEM/Certificate content
+grep -rn "-----BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY-----" .
+
+# Database URLs with credentials
+grep -rn -E "postgres://[^:]+:[^@]+@|mysql://[^:]+:[^@]+@" .
+```
+
+Report each finding with:
+- File and line number
+- The matched pattern (redact the actual secret value: show first 4 chars + ***)
+- Severity: CRITICAL if a real credential pattern, HIGH if credential-shaped pattern
+Redaction applies to both console output and the report file.
+
+## Step 5 — Dependency audit (--deps flag)
+
+```bash
+# Node.js projects
+npm audit --json 2>/dev/null | node -e "
+  const data = JSON.parse(require('fs').readFileSync('/dev/stdin', 'utf8'));
+  const vulns = data.vulnerabilities || {};
+  Object.entries(vulns).forEach(([name, v]) => {
+    if (['high','critical'].includes(v.severity)) {
+      console.log(v.severity.toUpperCase() + ': ' + name + ' — ' + v.via[0]?.title);
+    }
+  });
+"
+
+# Python projects
+pip-audit --format json 2>/dev/null
+```
+
+## Step 6 — Write security scan report
+
+`.planning/SECURITY-SCAN-[timestamp].md`:
+
+```markdown
+# Security Scan Report
+**Date:** [ISO-8601]
+**Scope:** [what was scanned]
+**Scanner:** MindForge Security Reviewer
+
+## Executive Summary
+[1-2 sentences: overall security posture, number of findings by severity]
+
+## Critical Findings (fix immediately — block all merges)
+[OWASP category] | [File:Line] | [Description] | [Remediation]
+
+## High Findings (fix before next release)
+...
+
+## Medium Findings (fix in next sprint)
+...
+
+## Low Findings (backlog)
+...
+
+## Dependency Audit
+| Package | Version | Severity | CVE | Fixed in |
+|---|---|---|---|---|
+
+## Secret Detection
+| File | Pattern | Severity | Action |
+|---|---|---|---|
+
+## Verdict
+✅ CLEAN — No critical or high findings
+⚠️  ISSUES — [N] critical, [N] high findings require attention
+```
+
+## Important: scan report visibility
+
+Security scan reports are written to `.planning/SECURITY-SCAN-[timestamp].md`.
+
+**Private repository:** Keep reports committed — they are valuable for audit
+history and team security review.
+
+**Public repository:** Add `.planning/SECURITY-SCAN-*.md` to `.gitignore`
+to avoid exposing vulnerability information to potential attackers.
+
+MindForge does not make this decision for you — configure `.gitignore`
+based on your repository's visibility.
+
+## Step 7 — Write AUDIT entry
+
+```json
+{
+  "event": "security_scan_completed",
+  "scope": "[path or 'staged changes']",
+  "flags": ["--deps", "--secrets"],
+  "critical_findings": [N],
+  "high_findings": [N],
+  "secrets_detected": [N],
+  "vulnerable_deps": [N],
+  "report_path": ".planning/SECURITY-SCAN-[timestamp].md"
+}
+```
+
+## Automatic blocking behaviour
+If CRITICAL findings are detected: print a prominent warning:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🔴 CRITICAL SECURITY FINDINGS DETECTED
+
+  [N] critical issues must be fixed before any code is merged.
+  See: .planning/SECURITY-SCAN-[timestamp].md
+
+  Do NOT commit or deploy until these are resolved.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```

package/.claude/commands/mindforge/ship.md

@@ -1,34 +1,111 @@
 ---
-name: mindforge:ship
-description: Create a release PR for a verified phase
-argument-hint: [N]
-allowed-tools:
-  - run_command
-  - list_dir
-  - view_file
-  - write_to_file
+description: Create a release PR for a verified phase. Usage: /mindforge:ship [N]
 ---
 
-<objective>
-Coordinate the final transition of a phase from "Verified" to "Released" by generating changelogs, running final quality gates, and prepping the pull request for merge.
-</objective>
-
-<execution_context>
-.claude/commands/mindforge/ship.md
-</execution_context>
-
-<context>
-Prerequisite: `UAT.md` must be marked as "All passed ✅".
-Gates: Type checking, linting, full test suite, security audit.
-Format: Follows "Keep a Changelog" and structured PR templates.
-</context>
-
-<process>
-1. **Pre-check**: Abort if the phase N has not completed UAT or has blocking findings.
-2. **Changelog Generation**: Sync SUMMARY files and REQUIREMENTS.md into a new `CHANGELOG.md` entry.
-3. **Execution Oversight**: Run final gates (tsc, eslint, npm test, npm audit) and report results.
-4. **Draft PR**: Generate a comprehensive PR description including delivered requirements and testing stats.
-5. **Commit & Tag**: Commit the changelog changes and push the branch.
-6. **State Transition**: Mark Phase [N] as shipped in `STATE.md` and increment the next target phase in `HANDOFF.json`.
-7. **Audit**: Log `phase_shipped` with delivered requirement IDs.
-</process>
+Create a release PR for a verified phase. Usage: /mindforge:ship [N]
+
+## Pre-check
+Read UAT.md for phase N. If status is not "All passed ✅": stop.
+Tell the user: "Phase [N] has not been fully verified. Run /mindforge:verify-phase [N] first."
+
+## Step 1 — Generate changelog entry
+Read all SUMMARY files for phase N.
+Read REQUIREMENTS.md for phase N items.
+Generate a CHANGELOG.md entry following Keep a Changelog format:
+
+```markdown
+## [Unreleased] — Phase [N]: [Phase description]
+
+### Added
+- [New feature from this phase]
+
+### Changed
+- [Changed behaviour]
+
+### Fixed
+- [Bug fixes]
+
+### Security
+- [Security improvements]
+```
+
+Prepend this to CHANGELOG.md.
+
+## Step 2 — Run final quality gates
+Run all of the following and report results:
+```bash
+# Type checking
+npx tsc --noEmit
+
+# Linting
+npx eslint . --ext .ts,.tsx --max-warnings 0
+
+# Tests
+npm test
+
+# Security scan (if npm project)
+npm audit --audit-level=high
+```
+
+If any gate fails: stop. Report the failures. Do not proceed to PR creation.
+
+## Step 2.1 — Final Intelligence Audit
+1. Read `AGENTS_LEARNING.md` for this project.
+2. Verify if any new architectural patterns, anti-patterns, or mistakes from this phase were recorded.
+3. If not: Run `/mindforge:record-learning` now to capture them before shipping.
+4. Commit `AGENTS_LEARNING.md` if updated.
+
+## Step 3 — Create PR description
+Generate a complete PR description:
+
+```markdown
+## MindForge Phase [N] — [Phase description]
+
+### Summary
+[2-3 sentences describing what this phase delivered]
+
+### Changes
+[Bullet list of major changes from SUMMARY files]
+
+### Requirements delivered
+| FR ID | Description                  | Verified |
+|-------|------------------------------|----------|
+| FR-01 | ...                          | ✅       |
+
+### Testing
+- Unit tests: [pass/fail + coverage %]
+- Integration tests: [pass/fail]
+- UAT: Completed and signed off (see UAT.md)
+
+### Security
+- [ ] Security review completed (see SECURITY-REVIEW-N.md)
+- [ ] No hardcoded secrets in diff
+- [ ] All dependencies scanned for CVEs
+
+### Checklist
+- [x] CHANGELOG.md updated
+- [x] AGENTS_LEARNING.md updated with phase-specific insights
+- [x] All tests pass
+- [x] No linter errors
+- [x] UAT signed off
+- [ ] Reviewed by: [assign]
+```
+
+## Step 4 — Commit and tag
+```bash
+git add CHANGELOG.md
+git commit -m "docs(changelog): add Phase [N] release notes"
+git push origin feat/mindforge-core-scaffold
+```
+
+Tell the user the PR description and instruct them to open the PR manually
+(or provide the `gh pr create` command if GitHub CLI is available).
+
+Tell the user:
+"✅ Phase [N] ready to ship.
+ PR description generated above.
+ Open your PR, assign reviewers, and merge when approved."
+
+## Step 5 — Update state
+Update STATE.md to mark Phase [N] as shipped.
+Update HANDOFF.json with next phase number.

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

@@ -1,36 +1,145 @@
 ---
-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
+description: /mindforge:skills list
 ---
 
-<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>
+# 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)