mindforge-cc 8.1.0 → 8.2.0

package/.mindforge/mirrors/mirror-sre-776a1cf9/.mindforge/dashboard/dashboard-spec.md

@@ -0,0 +1,96 @@
+# MindForge v2 — Dashboard Specification
+
+## Overview
+
+The MindForge dashboard is a real-time web UI that reflects the live state of
+the MindForge agent and all project artifacts. It serves as the team's window
+into what the agent is doing — designed for standup visibility, not agent control
+(though it does support approval actions for Tier 2/3 governance).
+
+## Architecture
+
+```
+Browser clients
+     ↑ SSE (push)     ↑ REST (pull on load)
+     │                │
+  bin/dashboard/server.js  (Express.js, localhost:7339)
+     │                │
+  sse-bridge.js       api-router.js
+     │ (tails files)  │ (reads files)
+     │                │
+  AUDIT.jsonl         HANDOFF.json
+  auto-state.json     session-quality.jsonl
+  APPROVAL-*.json     token-usage.jsonl
+  HANDOFF.json        knowledge-base.jsonl
+  TEAM-STATE.jsonl    .planning/phases/
+```
+
+## Port and binding
+
+- **Port:** 7339 (Dashboard = 7337+2, after SSE at 7337 and Browser Daemon at 7338)
+- **Binding:** 127.0.0.1 ONLY — never 0.0.0.0 (ADR-017 policy)
+- **Protocol:** HTTP/1.1 with SSE for live events
+- **Process lifecycle:**
+  - Started by: `/mindforge:dashboard` command or `bin/dashboard/server.js`
+  - Stopped by: `CTRL+C`, `/mindforge:dashboard --stop`, or SIGTERM
+  - Auto-stop: when MindForge session ends (watches for HANDOFF.json inactivity)
+
+## Dashboard pages (5 tabs)
+
+### Page 1 — Live Activity (default view)
+Shows real-time execution state:
+- Project name and current phase description
+- Auto mode status indicator (RUNNING/PAUSED/ESCALATED/IDLE)
+- Wave progress bar (current wave / total waves)
+- Current task name and elapsed time
+- Live AUDIT event feed (last 50 events, newest at top)
+- Steering input box (sends to steering queue if auto mode active)
+
+### Page 2 — Quality Metrics
+Charts powered by session-quality.jsonl and token-usage.jsonl:
+- Session quality score trend (last 20 sessions, sparkline)
+- Verify pass rate over time (last 20 sessions)
+- Security findings by severity (bar chart: CRITICAL/HIGH/MEDIUM/LOW)
+- Token cost per session trend
+- Node repair frequency (auto mode health signal)
+
+### Page 3 — Pending Approvals
+Governance queue visible to the whole team:
+- Shows all APPROVAL-*.json files with status: pending
+- For each: tier, phase/plan, change description, time since requested, expiry
+- [Approve] and [Reject] buttons that call POST /api/approve/:id
+- Expired approvals shown separately with red indicator
+
+### Page 4 — Knowledge Graph
+Visual representation of the knowledge base:
+- Force-directed graph: nodes = knowledge entries, edges = ADR links
+- Color by type: blue=decision, green=preference, red=bug_pattern, yellow=domain
+- Node size = confidence × 30px radius
+- Click node → side panel with full content
+- Filter by type, tags, or confidence threshold
+
+### Page 5 — Team Activity
+Multi-developer visibility:
+- Active developers (git email → last AUDIT event timestamp)
+- What each developer is working on (last task from AUDIT.jsonl)
+- File conflict detection (two developers recently touching the same file)
+- Session history (list of sessions, quality scores, costs)
+
+## Security model
+
+1. Localhost-only binding (127.0.0.1) — consistent with all MindForge servers
+2. No authentication — local dev tool, not exposed to network
+3. CORS policy: only allow requests from localhost
+4. Approval actions (POST /api/approve/:id) require the approval file to exist
+   in `.planning/approvals/` — cannot fabricate approvals from browser
+5. Steering (POST /api/steer) only works when auto-state.json shows `status: running`
+6. All file reads are restricted to `.planning/` and `.mindforge/` directories —
+   no arbitrary filesystem access from the API
+
+## SCREENSHARE MODE (recommended team use)
+The dashboard is designed to be screenshared during standups:
+- Product managers see live progress without CLI access
+- Designers see when their UI implementation tasks are running
+- Stakeholders see real estimates of completion time
+- On-call engineers see security findings as they're detected
+Never expose the dashboard URL externally — it contains project details.

package/.mindforge/mirrors/mirror-sre-776a1cf9/.mindforge/distribution/marketplace.md

@@ -0,0 +1,53 @@
+# MindForge v2 — Community Skills Marketplace
+
+## Purpose
+The MindForge Marketplace is a distribution network for reusable AI skills.
+It leverages the `mindforge-skill-` npm package prefix for discovery.
+
+## Naming conventions
+Skills published to the marketplace MUST follow this naming convention:
+`mindforge-skill-[technology-or-pattern]`
+
+Example:
+- `mindforge-skill-prisma-schema`
+- `mindforge-skill-zod-api-contracts`
+- `mindforge-skill-stripe-webhooks`
+
+## Marketplace categories
+Skills are grouped into these canonical categories:
+1. **Engines & Runtimes** (Node.js, Python, Go, Rust)
+2. **Databases & ORMs** (Prisma, Drizzle, Kysely, Sequelize)
+3. **API & Integration** (Stripe, Twilio, OpenAI, Anthropic)
+4. **UI & Frontend** (React, Next.js, Tailwind, Radix)
+5. **Patterns & Security** (Auth, RBAC, Validation, Error Handling)
+
+## Quality requirements
+To be listed in the marketplace, a skill MUST:
+- Achieve a quality score of ≥ 80/100
+- Pass all level 1 + level 2 validation checks
+- Include at least 5 complete, working code examples
+- Be free of any placeholder text
+- Be licensed under MIT or Apache-2.0
+
+## Publishing process
+1. Run `/mindforge:learn` to generate/update the skill.
+2. Achieve score ≥ 80 using `skill-scorer.js`.
+3. Fill in the optional `author`, `license`, and `category` fields in frontmatter.
+4. Run `/mindforge:marketplace publish [skill-name]`.
+   - This prepares the `package.json`.
+   - Runs final verification.
+   - Prompts for `npm publish`.
+
+## Interaction interface
+```
+/mindforge:marketplace search [query]       # Search the marketplace
+/mindforge:marketplace featured             # Show featured skills
+/mindforge:marketplace trending             # Show trending skills
+/mindforge:marketplace info [name]           # Show skill details and quality score
+/mindforge:marketplace install [name]        # Install a community skill
+/mindforge:marketplace publish [name]        # Publish your skill
+```
+
+## Marketplace Registry
+By default, the marketplace uses the global npm registry with the `mindforge-skill-` prefix.
+Private registries can be configured via `MARKETPLACE_REGISTRY` in MINDFORGE.md.

package/.mindforge/mirrors/mirror-sre-776a1cf9/.mindforge/distribution/registry-client.md

@@ -0,0 +1,166 @@
+# MindForge Skills Registry — Client Protocol
+
+## Purpose
+Define how MindForge discovers, downloads, validates, and installs skills
+from the public or private npm-based registry.
+
+## Installation flow
+
+### Step 1 — Resolve package name
+```bash
+# From skill name to package name:
+SKILL_NAME="security-owasp"
+PACKAGE_NAME="mindforge-skill-${SKILL_NAME}"
+
+# Or if user provides full package name:
+PACKAGE_NAME="mindforge-skill-security-owasp"
+```
+
+### Step 2 — Check if already installed
+```bash
+# Check local MANIFEST.md
+grep "| ${SKILL_NAME} |" .mindforge/org/skills/MANIFEST.md && echo "Already installed"
+
+# Check if SKILL.md exists
+[ -f ".mindforge/skills/${SKILL_NAME}/SKILL.md" ] && echo "Skill file exists"
+```
+
+### Step 3 — Secure temp directory creation
+```bash
+# Create temp directory with user-only permissions (prevents TOCTOU attacks)
+TEMP_DIR=$(mktemp -d)
+chmod 700 "${TEMP_DIR}"
+
+# All subsequent operations in this directory are protected
+npm pack "${PACKAGE_NAME}@latest" --pack-destination "${TEMP_DIR}" --quiet
+
+# Verify the tarball was downloaded (not empty, not corrupted)
+TARBALL=$(ls "${TEMP_DIR}"/*.tgz 2>/dev/null | head -1)
+if [ -z "${TARBALL}" ]; then
+  rm -rf "${TEMP_DIR}"
+  echo "Error: Failed to download ${PACKAGE_NAME} — no tarball produced"
+  exit 1
+fi
+
+# Verify tarball size is reasonable (not 0 bytes, not suspiciously large)
+TARBALL_SIZE=$(wc -c < "${TARBALL}")
+if [ "${TARBALL_SIZE}" -lt 100 ]; then
+  rm -rf "${TEMP_DIR}"
+  echo "Error: Downloaded tarball is suspiciously small (${TARBALL_SIZE} bytes)"
+  exit 1
+fi
+
+tar -xzf "${TARBALL}" --strip-components=1 -C "${TEMP_DIR}"
+```
+
+### Step 4 — Validate the downloaded skill
+Run the full skill validator (see `skill-validator.md`) against the downloaded SKILL.md.
+If validation fails: abort installation. Never install a skill that fails validation.
+
+For public registry installs: run Level 3 validation as well. Warn on failures but do not
+block install. For private registry installs: Level 2 is sufficient.
+
+### Step 4.5 — Dependency audit (optional but recommended)
+If the skill package includes scripts with dependencies, run an audit:
+```bash
+if [ -f "${TEMP_DIR}/package.json" ]; then
+  npm audit --prefix "${TEMP_DIR}" --audit-level=high || {
+    echo "Warning: HIGH/CRITICAL vulnerabilities detected in skill dependencies"
+    SKILL_DEPENDENCY_VULN=true
+  }
+fi
+```
+If vulnerabilities were found, warn but allow install. Record in AUDIT:
+`"skill_dependency_vulnerability": true`.
+
+### Step 5 — Injection guard check
+Run the injection guard from Day 3 (`loader.md`) against the skill content.
+If injection patterns detected: abort, write AUDIT entry, alert user.
+
+### Step 6 — Install to correct tier location
+```bash
+# Determine target tier from user input or package.json tier-recommendation
+TIER="${USER_SPECIFIED_TIER:-2}"
+
+if [ "${TIER}" = "1" ]; then
+  TARGET_DIR=".mindforge/skills/${SKILL_NAME}"
+elif [ "${TIER}" = "2" ]; then
+  TARGET_DIR=".mindforge/org/skills/${SKILL_NAME}"
+else
+  TARGET_DIR=".mindforge/project-skills/${SKILL_NAME}"
+fi
+
+mkdir -p "${TARGET_DIR}"
+cp "${TEMP_DIR}/SKILL.md" "${TARGET_DIR}/SKILL.md"
+[ -d "${TEMP_DIR}/examples" ] && cp -r "${TEMP_DIR}/examples" "${TARGET_DIR}/"
+[ -d "${TEMP_DIR}/scripts" ]  && cp -r "${TEMP_DIR}/scripts"  "${TARGET_DIR}/"
+```
+
+### Step 7 — Register in MANIFEST.md
+```bash
+# Add entry to the correct tier section of MANIFEST.md
+SKILL_VERSION=$(node -e "console.log(require('${TEMP_DIR}/package.json').version)")
+
+# Insert into MANIFEST.md under the appropriate tier section
+# Format: | name | version | stable | min-mf-version | path |
+```
+
+### Step 8 — Clean up and report
+```bash
+rm -rf "${TEMP_DIR}"
+```
+
+Report to user:
+```
+✅ Skill installed: ${SKILL_NAME} v${SKILL_VERSION} (Tier ${TIER})
+   Triggers: [list from SKILL.md frontmatter]
+   Path: ${TARGET_DIR}/SKILL.md
+
+Run /mindforge:skills validate to confirm installation.
+```
+
+### Step 9 — Write AUDIT entry
+```json
+{
+  "event": "skill_installed",
+  "skill_name": "security-owasp",
+  "skill_version": "1.2.0",
+  "package_name": "mindforge-skill-security-owasp",
+  "tier": 2,
+  "source": "npm-registry | private-registry",
+  "validation_passed": true,
+  "skill_dependency_vulnerability": false
+}
+```
+
+## Update protocol
+
+### Check for updates
+```bash
+# Compare installed version against registry latest
+INSTALLED=$(grep "| ${SKILL_NAME} |" MANIFEST.md | awk -F'|' '{print $3}' | tr -d ' ')
+LATEST=$(npm info "${PACKAGE_NAME}" version --prefer-offline 2>/dev/null)
+
+if [ "${INSTALLED}" != "${LATEST}" ]; then
+  echo "Update available: ${SKILL_NAME} v${INSTALLED} → v${LATEST}"
+fi
+```
+
+### Update a skill
+```bash
+# Run install flow for latest version
+# If MAJOR version bump: show breaking changes, require confirmation
+# If MINOR/PATCH: update silently
+```
+
+## Uninstall protocol
+```bash
+# Remove skill files
+rm -rf "${TARGET_DIR}"
+
+# Remove from MANIFEST.md
+sed -i "/| ${SKILL_NAME} |/d" .mindforge/org/skills/MANIFEST.md
+
+# Write AUDIT entry
+# Commit: "chore(skills): uninstall ${SKILL_NAME}"
+```

package/.mindforge/mirrors/mirror-sre-776a1cf9/.mindforge/distribution/registry-schema.md

@@ -0,0 +1,96 @@
+# MindForge Skills Registry — Schema & Protocol
+
+## Registry concept
+The public MindForge Skills Registry is an npm-based distribution system.
+Skills are published as npm packages with the `mindforge-skill-` prefix.
+The registry leverages the existing npm ecosystem for versioning, discovery,
+and distribution.
+
+## Package naming convention
+```
+mindforge-skill-[category]-[name]
+```
+
+Examples:
+- `mindforge-skill-security-owasp`       — OWASP security review skill
+- `mindforge-skill-db-postgres-patterns` — PostgreSQL-specific patterns
+- `mindforge-skill-frontend-react-a11y`  — React accessibility patterns
+- `mindforge-skill-testing-playwright`   — Playwright E2E testing patterns
+- `mindforge-skill-api-graphql`          — GraphQL API design patterns
+
+## Package structure
+
+```
+mindforge-skill-[category]-[name]/
+├── SKILL.md              ← The skill file (required)
+├── package.json          ← npm metadata
+├── README.md             ← Human documentation
+├── CHANGELOG.md          ← Version history
+├── examples/             ← Optional usage examples
+│   └── example-task.md
+├── scripts/              ← Optional helper scripts
+│   └── helper.sh
+└── tests/
+    └── skill.test.js     ← Skill validation tests
+```
+
+## `package.json` for a skill package
+
+```json
+{
+  "name": "mindforge-skill-security-owasp",
+  "version": "1.2.0",
+  "description": "OWASP Top 10 security review skill for MindForge",
+  "keywords": [
+    "mindforge",
+    "mindforge-skill",
+    "security",
+    "owasp",
+    "agentic-framework"
+  ],
+  "mindforge": {
+    "type": "skill",
+    "skill-name": "security-owasp",
+    "category": "security",
+    "min-mindforge-version": "0.5.0",
+    "triggers": ["OWASP", "security review", "injection", "auth", "XSS"],
+    "tier-recommendation": 1
+  },
+  "files": ["SKILL.md", "README.md", "examples/", "scripts/"],
+  "license": "MIT",
+  "homepage": "https://mindforge.dev/skills/security-owasp",
+  "repository": { "type": "git", "url": "https://github.com/mindforge-dev/skill-security-owasp" }
+}
+```
+
+## Registry discovery
+
+The MindForge registry is the standard npm registry with keyword filtering:
+```bash
+# Search for skills
+npm search mindforge-skill [query]
+
+# Example searches:
+npm search mindforge-skill security    # Find security skills
+npm search mindforge-skill react       # Find React-specific skills
+npm search mindforge-skill testing     # Find testing skills
+```
+
+## Registry quality standards
+
+A skill package published to the MindForge registry must pass:
+1. Schema validation: `npx mindforge-cc validate-skill ./SKILL.md`
+2. Required metadata: package.json `mindforge` field fully populated
+3. No malicious content: npm security audit passes
+4. Version policy: follows semver with documented breaking changes
+5. License: MIT, Apache-2.0, or BSD (GPL derivatives not accepted)
+
+## Local registry (private skills)
+
+Organisations with private skills can use:
+- Private npm registry (Verdaccio, Artifactory, GitHub Packages)
+- Configure in `.mindforge/org/integrations/INTEGRATIONS-CONFIG.md`:
+  ```
+  MINDFORGE_SKILL_REGISTRY=https://npm.your-org.internal/
+  ```
+- Skills from private registry install with the same `npx mindforge-skills install` command

package/.mindforge/mirrors/mirror-sre-776a1cf9/.mindforge/distribution/skill-publisher.md

@@ -0,0 +1,44 @@
+# MindForge Skills Registry — Skill Publisher
+
+## Purpose
+Define the publish workflow for MindForge skills to npm (public or private).
+Used by `/mindforge:publish-skill`.
+
+## Publish workflow
+
+1. Validate SKILL.md (Levels 1, 2, and 3).
+2. Confirm `package.json` includes required `mindforge` metadata.
+3. Verify `CHANGELOG.md` has an entry for the current version.
+4. Check if version already exists on the registry.
+5. Preview files with `npm pack --dry-run`.
+6. Confirm with the user.
+7. Publish.
+8. Verify publish succeeded.
+9. Write AUDIT entry.
+
+## Commands
+
+```bash
+# Level 1 + 2 + 3 validation
+npx mindforge-cc validate-skill ./SKILL.md --quality
+
+# Version check
+npm info ${PACKAGE_NAME}@${VERSION}
+
+# Dry-run preview
+npm pack --dry-run
+
+# Publish
+npm publish --access public
+```
+
+## Audit entry
+
+```json
+{
+  "event": "skill_published",
+  "package": "mindforge-skill-security-owasp",
+  "version": "1.2.0",
+  "registry": "https://registry.npmjs.org/"
+}
+```

package/.mindforge/mirrors/mirror-sre-776a1cf9/.mindforge/distribution/skill-validator.md

@@ -0,0 +1,74 @@
+# MindForge Skills Registry — Skill Validator
+
+## Purpose
+Validate a SKILL.md file before installation or publication.
+Run as part of both `install-skill` and `publish-skill` commands.
+
+## Validation levels
+
+### Level 1 — Schema validation (always runs)
+```bash
+npx mindforge-cc validate-skill ./SKILL.md
+```
+
+Checks:
+- [ ] File starts with `---` (YAML frontmatter delimiter)
+- [ ] Frontmatter closes with `---`
+- [ ] `name:` field present and matches kebab-case pattern `[a-z][a-z0-9-]+`
+- [ ] `version:` field present and valid semver `\d+\.\d+\.\d+`
+- [ ] `status:` is one of: `stable`, `beta`, `alpha`, `deprecated`
+- [ ] `triggers:` field present and has >= 5 keywords
+- [ ] No trigger keyword is fewer than 3 characters (too generic)
+- [ ] `min_mindforge_version:` present and valid semver
+
+### Level 2 — Content validation (runs after schema passes)
+- [ ] File size between 1KB and 200KB (not too small, not too large)
+- [ ] Contains `## Mandatory actions` or `## When this skill is active` section
+- [ ] Contains at least one checklist item (`- [ ]`) for self-verification
+- [ ] Does not contain any injection patterns (from `loader.md` guard)
+- [ ] Code examples have language specifiers in code fences (not bare ```)
+- [ ] No placeholder text: `[placeholder]`, `[your-name]`, `TODO`, `FIXME`, `[fill this in]`
+
+### Level 3 — Quality validation (required for publish, recommended for public install)
+- [ ] At least 3 code examples
+- [ ] CHANGELOG in frontmatter has at least current version entry
+- [ ] `breaking_changes:` field present (even if empty list)
+- [ ] Examples directory has at least one example file
+- [ ] README.md exists in the package
+
+**Install rule:**
+- Public registry installs: run Level 3 and warn on failures (do not block)
+- Private registry installs: Level 2 is sufficient
+
+## Validator output
+
+```
+MindForge Skill Validator — SKILL.md
+──────────────────────────────────────────────────────────────
+
+Schema validation:
+  ✅ Frontmatter valid
+  ✅ name: security-owasp (valid)
+  ✅ version: 1.2.0 (valid semver)
+  ✅ status: stable
+  ✅ triggers: 31 keywords (min: 5)
+  ✅ min_mindforge_version: 0.5.0
+
+Content validation:
+  ✅ File size: 8.4KB (1KB-200KB range)
+  ✅ Mandatory actions section present
+  ✅ Self-check checklist present (7 items)
+  ✅ No injection patterns detected
+  ✅ Code examples have language specifiers
+  ✅ No placeholder text found
+
+Quality validation:
+  ✅ 5 code examples found
+  ✅ CHANGELOG has version 1.2.0 entry
+  ✅ Breaking changes documented
+  ⚠️  Examples directory has 1 file (recommend: 3+)
+
+──────────────────────────────────────────────────────────────
+Result: VALID with 1 warning
+Ready for: installation ✅ | publication ✅ (warning noted)
+```

package/.mindforge/mirrors/mirror-sre-776a1cf9/.mindforge/engine/ads-protocol.md

@@ -0,0 +1,54 @@
+# MindForge Engine — Adversarial Decision Synthesis (ADS) Protocol
+
+## Purpose
+Evolve the standard single-agent planning model into a high-fidelity Red-Team/Blue-Team architectural synthesis. This protocol ensures all major decisions are stress-tested for maintainability, security, and scalability before execution begins.
+
+## Core Roles
+
+### 1. The Architect (Blue Team — Performance & Complexity)
+- **Persona**: `mindforge-architect` or `mf-planner`
+- **Objective**: Propose the most technically superior, performant, and feature-complete solution.
+- **Bias**: "We should build for scale and future-proof the system."
+
+### 2. The Auditor (Red Team — Simplicity & Maintainability)
+- **Persona**: `mindforge-qa-engineer` or `mindforge-security-reviewer`
+- **Objective**: Find logic gaps, security flaws, and architectural "over-engineering".
+- **Bias**: "Do we really need this complexity? How will this break tomorrow?"
+
+### 3. The Synthesizer (Gold Team — Decision Merge)
+- **Persona**: `mindforge-decision-architect`
+- **Objective**: Mediate the debate, score proposals using `SOUL.md` metrics, and merge into a final `PLAN.md`.
+- **Bias**: "Objective leverage. Minimal risk. Maximum impact."
+
+## Synthesis Loop — Execution Order
+
+### Step 1: Blue Proposal (Propose)
+The **Architect** generates a detailed implementation plan (`PLAN-[P]-BLUE.md`).
+- Focus on: Data flow, performance, and API design.
+
+### Step 2: Red Critique (Challenge)
+The **Auditor** reviews the Blue plan and generates a critique (`PLAN-[P]-RED-CRITIQUE.md`).
+- **Pressure Rule**: Red *must* identify at least 3 potential failure modes or "Complexity Traps."
+- Red proposes a "Simpler Alternative" if the Blue plan is deemed over-engineered.
+
+### Step 3: Gold Verdict (Synthesize)
+The **Synthesizer** ingest both plans and the critique. 
+1. Calculates the **SOUL_SCORE** for each approach:
+   `Score = (Impact × Leverage × Reversibility) / (Effort × Risk × Cost)`
+2. Generates the final `PLAN.md` by adopting the best parts of both.
+3. Produces a `DECISION_ADS.md` (ADR) justifying the synthesis.
+
+## Synthesis Tossing (Iterative Loop)
+If the **SOUL_SCORE** difference between approaches is < 0.2, the Synthesizer can trigger one round of "Tossing":
+- Both teams are given the other's feedback and asked to refine their proposal.
+- Total iterations capped at 2 to avoid scope-paralysis.
+
+## Output Structure
+The final result must always move to the standard `.planning/` directory:
+- `.planning/PLAN.md` (Validated & Hardened)
+- `.planning/decisions/ADS-[UUID].md` (The Proof of Synthesis)
+
+## Trigger Conditions
+- Any phase marked "Architectural" in `ROADMAP.md`
+- Manual trigger via `/mindforge:plan-phase --ads`
+- When a `security-reviewer` flags a high-risk change