mindforge-cc 8.1.0 → 8.2.0

package/.mindforge/mirrors/mirror-sre-776a1cf9/.agent/workflows/mindforge:researcher.md

@@ -0,0 +1,18 @@
+---
+description: Invoke the Knowledge Detective persona (mf-researcher)
+---
+# 🔍 /mindforge:researcher
+
+## Objective
+Adopt the **Knowledge Detective** persona for grounded research and recursive browsing.
+
+---
+
+## Execution
+// turbo
+1. Execute the MindForge CLI to spawn the researcher essence:
+   ```bash
+   node bin/mindforge-cli.js spawn mf-researcher
+   ```
+
+2. The AI will adopt the **Deep Context Synthesis** pattern and await your research objective.

package/.mindforge/mirrors/mirror-sre-776a1cf9/.agent/workflows/mindforge:retrospective.md

@@ -0,0 +1,29 @@
+---
+description: Facilitate a structured retrospective with objective metrics + qualitative insights.
+---
+# MindForge — Retrospective Command
+# Usage: /mindforge:retrospective [phase N|milestone M] [--template agile|4ls|starfish]
+
+Facilitate a structured retrospective with objective metrics + qualitative insights.
+
+## Workflow
+1. Gather quantitative signals (tasks, verify pass rate, findings, UAT, approvals).
+2. Run structured discussion by template.
+3. Write retrospective artifact in `.planning/phases/...` or `.planning/milestones/...`.
+4. Create follow-up tasks/tickets for action items.
+5. Update metrics with retrospective-completed event.
+
+## Step 5 — Apply learnings to MINDFORGE.md
+Ask explicitly:
+`Based on this retrospective, should we update MINDFORGE.md to improve future phases?`
+
+If yes:
+- propose exact config changes
+- apply only after confirmation
+- commit with clear rationale
+
+Common mappings:
+- vague plans -> lower discuss threshold / enable auto-discuss
+- low verify pass rate -> lower max tasks per phase
+- rising security findings -> force-load `security-review,data-privacy`
+- frequent compaction pressure -> lower compaction threshold

package/.mindforge/mirrors/mirror-sre-776a1cf9/.agent/workflows/mindforge:review-backlog.md

@@ -0,0 +1,26 @@
+---
+description: Review and promote backlog items to the active phase sequence
+---
+<objective>
+Review items currently parked in the ROADMAP.md backlog and facilitate their promotion to the active development plan.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/review-backlog.md
+</execution_context>
+
+<context>
+Target File: ROADMAP.md, STATE.md
+State: Resolves the next available phase number from STATE.md for promotion.
+</context>
+
+<process>
+1. **Read ROADMAP.md**: Extract all items under the `## Backlog` section (999.x).
+2. **Present to User**: List the backlog items and ask which one(s) should be promoted.
+3. **Determine Promotion Slot**: Read STATE.md to find the next sequential phase number.
+4. **Promote Item**:
+    - Move the item from the backlog to the active milestone list.
+    - Renumber the item to the next available phase number.
+5. **Update STATE.md**: Add the new phase to STATE.md in `unplanned` or `planned` status as appropriate.
+6. **Confirm**: Summarize the promotion to the user.
+</process>

package/.mindforge/mirrors/mirror-sre-776a1cf9/.agent/workflows/mindforge:review.md

@@ -0,0 +1,160 @@
+---
+description: - /mindforge:review (no args) → review all uncommitted changes (git diff)
+---
+# 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."

package/.mindforge/mirrors/mirror-sre-776a1cf9/.agent/workflows/mindforge:reviewer.md

@@ -0,0 +1,18 @@
+---
+description: Invoke the Quality Auditor persona (mf-reviewer)
+---
+# 🛡️ /mindforge:reviewer
+
+## Objective
+Adopt the **Quality Auditor** persona for adversarial review and 6-pillar logic auditing.
+
+---
+
+## Execution
+// turbo
+1. Execute the MindForge CLI to spawn the reviewer essence:
+   ```bash
+   node bin/mindforge-cli.js spawn mf-reviewer
+   ```
+
+2. The AI will adopt the **Adversarial Logic Verification** pattern and await your review target.

package/.mindforge/mirrors/mirror-sre-776a1cf9/.agent/workflows/mindforge:security-scan.md

@@ -0,0 +1,236 @@
+---
+description: - Default: OWASP Top 10 review on the changed files or specified path
+---
+# 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.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```

package/.mindforge/mirrors/mirror-sre-776a1cf9/.agent/workflows/mindforge:session-report.md

@@ -0,0 +1,31 @@
+---
+description: Generate a post-session summary document capturing work performed and resource usage
+---
+<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/.mindforge/mirrors/mirror-sre-776a1cf9/.agent/workflows/mindforge:ship.md

@@ -0,0 +1,108 @@
+---
+description: Create a pull request from completed phase/milestone work, generate a rich PR body from planning artifacts, optionally run code review, and prepare for merge. Closes the plan → execute → verify → ship loop.
+---
+Create a release PR for a verified phase. Usage: /mindforge:ship [N]
+
+## Step 0 — Protocol Activation
+
+**MANDATORY**: Invoke the `mindforge-ship_extended` skill.
+This ensures the shipping process uses rigorous quality gates, branch sanitization, and automated PR body generation.
+
+## 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.