mindforge-cc 2.0.0 → 2.1.1

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

@@ -1,157 +1,37 @@
-# MindForge — Review Command
-# Usage: /mindforge:review [path|phase N|--staged|--last-commit]
-# Performs a comprehensive code review using code-quality and security skills.
-
-## Review targets
-- `/mindforge:review` (no args) → review all uncommitted changes (`git diff`)
-- `/mindforge:review --staged` → review staged changes (`git diff --cached`)
-- `/mindforge:review --last-commit` → review the last commit (`git diff HEAD~1`)
-- `/mindforge:review phase [N]` → review all commits in phase N
-- `/mindforge:review [file-path]` → review a specific file
-- `/mindforge:review [dir-path]` → review all files in a directory
-
-## Step 1 — Establish review scope
-
-Based on the target argument, build the file list to review:
-```bash
-# Uncommitted changes
-git diff --name-only
-
-# Staged changes
-git diff --cached --name-only
-
-# Last commit
-git diff HEAD~1 --name-only
-
-# Phase N (all commits between phase start and phase end tags)
-git log --oneline --name-only [phase-start-sha]..[phase-end-sha]
-```
-
-Display the file list to the user before reviewing:
-"Reviewing [N] files: [list]"
-
-## Step 2 — Load review personas and skills
-
-Activate TWO personas simultaneously for a comprehensive review:
-
-**Primary:** `code-quality.md` — structural quality, conventions, complexity
-**Secondary:** `security-reviewer.md` — security issues, data exposure, auth
-
-Load these skills:
-- `code-quality/SKILL.md` — always
-- `security-review/SKILL.md` — always
-- Contextual skills based on file types detected in the diff:
-  - `.ts`/`.tsx` → also load `api-design/SKILL.md` (if routes present)
-  - Database migration files → also load `database-patterns/SKILL.md`
-  - UI component files → also load `accessibility/SKILL.md`
-
-## Step 3 — Review each file
-
-For each file in the review scope:
-
-**Read the full file content** (not just the diff — context matters).
-**Read the diff for this file** to understand what changed.
-
-Apply ALL of the following checks:
-
-### Code quality checks
-- [ ] Functions within length limits (CONVENTIONS.md standard)
-- [ ] Cyclomatic complexity ≤ 10 (count if/else/switch/catch/ternary branches)
-- [ ] No magic numbers (named constants used instead)
-- [ ] No commented-out code
-- [ ] No `TODO` or `FIXME` left uncommitted
-- [ ] Error handling is explicit (no empty catch blocks)
-- [ ] Naming is precise and unambiguous (no `data`, `info`, `temp`)
-- [ ] Every exported function has a JSDoc/docstring
-- [ ] DRY: no logic duplicated 3+ times
-- [ ] No dead code (imports/variables defined but never used)
-
-### Convention checks (from CONVENTIONS.md)
-- [ ] File naming follows convention
-- [ ] Import order follows the defined order
-- [ ] All forbidden patterns are absent
-- [ ] Architecture boundaries respected (services don't import routes, etc.)
-
-### Security checks (from security-review SKILL)
-- [ ] No hardcoded credentials or secrets
-- [ ] User input validated at boundaries
-- [ ] SQL queries parameterised
-- [ ] Sensitive data not in logs or error messages
-- [ ] New dependencies CVE-scanned
-
-### Type safety (TypeScript projects)
-- [ ] No `any` types without justification comment
-- [ ] No `as unknown as X` casting without justification
-- [ ] All function parameters typed (no implicit any)
-- [ ] Return types explicitly declared on public functions
-
-## Step 4 — Write the review report
-
-Create `.planning/phases/[current-phase]/CODE-REVIEW-[timestamp].md`
-or `.planning/quick/review-[timestamp].md` for ad-hoc reviews:
-
-```markdown
-# Code Review Report
-**Date:** [ISO-8601]
-**Reviewer:** MindForge (code-quality + security-reviewer)
-**Scope:** [what was reviewed]
-**Files reviewed:** [N]
-
-## Summary
-[2-3 sentences: overall quality, major themes, recommendation]
-
-## Findings
-
-### 🔴 Blocking (must fix before merge)
-| # | File | Line | Issue | Recommendation |
-|---|---|---|---|---|
-| 1 | src/auth/login.ts | 47 | Parameterised query not used | Use `db.query('SELECT * FROM users WHERE id = $1', [id])` |
-
-### 🟠 Major (should fix in this PR)
-| # | File | Line | Issue | Recommendation |
-|---|---|---|---|---|
-| 1 | src/api/users.ts | 23 | Function is 67 lines (limit: 40) | Extract `validateUserInput` to separate function |
-
-### 🟡 Minor (fix in follow-up)
-| # | File | Line | Issue | Recommendation |
-|---|---|---|---|---|
-| 1 | src/models/order.ts | 8 | Missing JSDoc on exported function | Add `@param`, `@returns`, `@throws` |
-
-### 💡 Suggestions (optional improvements)
-| # | File | Line | Suggestion |
-|---|---|---|---|
-| 1 | src/services/email.ts | 15 | Consider memoising the template compilation |
-
-## Metrics
-- Files reviewed: [N]
-- Lines reviewed: [N]  
-- Blocking findings: [N]
-- Major findings: [N]
-- Minor findings: [N]
-- Suggestions: [N]
-
-## Verdict
-✅ APPROVED — No blocking or major findings
-⚠️  APPROVED WITH CONDITIONS — Fix [N] major findings
-❌ CHANGES REQUIRED — [N] blocking findings must be fixed
-```
-
-## Step 5 — Write AUDIT entry
-
-```json
-{
-  "event": "code_review_completed",
-  "scope": "[what was reviewed]",
-  "files_reviewed": [N],
-  "blocking_findings": [N],
-  "major_findings": [N],
-  "verdict": "approved | changes_required",
-  "report_path": ".planning/.../CODE-REVIEW-[timestamp].md"
-}
-```
-
-## Step 6 — Report to user
-
-Display a summary of findings.
-If blocking findings exist: do not allow merge.
-Tell the user: "Fix the [N] blocking issues, then run /mindforge:review again to re-check."
+---
+name: mindforge:review
+description: Perform a comprehensive code quality and security review
+argument-hint: [path|phase N|--staged|--last-commit]
+allowed-tools:
+  - run_command
+  - view_file
+  - write_to_file
+  - list_dir
+---
+
+<objective>
+Conduct a deep code review of a specified target (files, directories, phases, or git SHAs), focusing on structural quality, security vulnerabilities, and adherence to project conventions.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/review.md
+</execution_context>
+
+<context>
+Target: Staged changes, last commit, specific phase, or path.
+Personas: code-quality.md, security-reviewer.md
+Skills: code-quality, security-review, accessibility (for UI), api-design (for routes), database-patterns (for migrations).
+</context>
+
+<process>
+1. **Establish Scope**: Use `git diff` or `git log` to determine the list of files needing review.
+2. **Initialize Personas**: Load the appropriate reviewer personas and skills based on file types.
+3. **Audit Implementation**: For each file, read full content and check:
+    - Code quality (complexity, naming, error handling).
+    - Conventions (from CONVENTIONS.md).
+    - Security (secrets, validation, injection).
+    - Type safety (TS specifics).
+4. **Generate Report**: Write `CODE-REVIEW-[timestamp].md` with categorized findings (Blocking, Major, Minor, Suggestion) and an overall verdict.
+5. **Update State**: Log `code_review_completed` in `AUDIT.jsonl`.
+6. **Report**: Summarize findings to the user and block merge if "Blocking" issues exist.
+</process>

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

@@ -1,233 +1,34 @@
-# 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 2 — Build scan scope
-
-```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.
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
+---
+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
+---
+
+<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>

package/.claude/commands/mindforge/session-report.md

@@ -0,0 +1,39 @@
+---
+name: mindforge:session-report
+description: Generate a post-session summary document capturing work performed and resource usage
+argument-hint: none
+allowed-tools:
+  - run_command
+  - view_file
+  - write_to_file
+  - list_dir
+---
+
+<objective>
+Generate a comprehensive summary of an active coding session, providing a clear trail of work for stakeholders and a diagnostic record of resource usage (tokens, time, etc.).
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/session-report.md
+</execution_context>
+
+<context>
+Storage: .planning/reports/
+Data sources: Git logs, terminal history, `STATE.md`, and session memory.
+</context>
+
+<process>
+1. **Gather Data**:
+    - Get recent git commits and diff summaries.
+    - Read the current `STATE.md` for phase/plan status updates.
+    - Extract key decisions or findings from the session.
+2. **Profile Resources**:
+    - Estimate token usage if possible.
+    - Calculate session duration.
+3. **Draft Report**: Create `SESSION_REPORT_[timestamp].md` containing:
+    - Summary of Work Performed
+    - Outcomes achieved (Plans "completed")
+    - Key Decisions
+    - Resource Usage Profile
+4. **Confirm**: Notify the user and provide a link to the report.
+</process>

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

@@ -1,100 +1,34 @@
-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 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] 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.
+---
+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
+---
+
+<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>