mindforge-cc 1.0.0

package/.mindforge/intelligence/health-engine.md

@@ -0,0 +1,208 @@
+# MindForge Intelligence — Health Engine
+
+## Purpose
+Run a comprehensive health check across installation, context, skills, personas,
+state, integrations, and security. Detect drift and provide safe auto-repair.
+
+## Categories
+1. Installation integrity
+2. Context file health
+3. Skills registry health
+4. Persona system health
+5. State consistency
+6. Integration connectivity
+7. Security configuration
+
+## Category 1 — Installation integrity
+
+### Required files checklist
+```bash
+REQUIRED_FILES=(
+  ".claude/CLAUDE.md"
+  ".agent/CLAUDE.md"
+
+  ".claude/commands/mindforge/help.md"
+  ".claude/commands/mindforge/init-project.md"
+  ".claude/commands/mindforge/plan-phase.md"
+  ".claude/commands/mindforge/execute-phase.md"
+  ".claude/commands/mindforge/verify-phase.md"
+  ".claude/commands/mindforge/ship.md"
+  ".claude/commands/mindforge/next.md"
+  ".claude/commands/mindforge/quick.md"
+  ".claude/commands/mindforge/status.md"
+  ".claude/commands/mindforge/debug.md"
+  ".claude/commands/mindforge/skills.md"
+  ".claude/commands/mindforge/review.md"
+  ".claude/commands/mindforge/security-scan.md"
+  ".claude/commands/mindforge/map-codebase.md"
+  ".claude/commands/mindforge/discuss-phase.md"
+  ".claude/commands/mindforge/audit.md"
+  ".claude/commands/mindforge/milestone.md"
+  ".claude/commands/mindforge/complete-milestone.md"
+  ".claude/commands/mindforge/approve.md"
+  ".claude/commands/mindforge/sync-jira.md"
+  ".claude/commands/mindforge/sync-confluence.md"
+  ".claude/commands/mindforge/health.md"
+  ".claude/commands/mindforge/retrospective.md"
+  ".claude/commands/mindforge/profile-team.md"
+  ".claude/commands/mindforge/metrics.md"
+
+  ".mindforge/engine/wave-executor.md"
+  ".mindforge/engine/dependency-parser.md"
+  ".mindforge/engine/context-injector.md"
+  ".mindforge/engine/compaction-protocol.md"
+  ".mindforge/engine/verification-pipeline.md"
+  ".mindforge/engine/skills/registry.md"
+  ".mindforge/engine/skills/loader.md"
+  ".mindforge/engine/skills/versioning.md"
+  ".mindforge/engine/skills/conflict-resolver.md"
+
+  ".mindforge/skills/security-review/SKILL.md"
+  ".mindforge/skills/code-quality/SKILL.md"
+  ".mindforge/skills/api-design/SKILL.md"
+  ".mindforge/skills/testing-standards/SKILL.md"
+  ".mindforge/skills/documentation/SKILL.md"
+  ".mindforge/skills/performance/SKILL.md"
+  ".mindforge/skills/accessibility/SKILL.md"
+  ".mindforge/skills/data-privacy/SKILL.md"
+  ".mindforge/skills/incident-response/SKILL.md"
+  ".mindforge/skills/database-patterns/SKILL.md"
+
+  ".mindforge/personas/analyst.md"
+  ".mindforge/personas/architect.md"
+  ".mindforge/personas/developer.md"
+  ".mindforge/personas/qa-engineer.md"
+  ".mindforge/personas/security-reviewer.md"
+  ".mindforge/personas/tech-writer.md"
+  ".mindforge/personas/debug-specialist.md"
+  ".mindforge/personas/release-manager.md"
+
+  ".mindforge/intelligence/health-engine.md"
+  ".mindforge/intelligence/difficulty-scorer.md"
+  ".mindforge/intelligence/antipattern-detector.md"
+  ".mindforge/intelligence/skill-gap-analyser.md"
+  ".mindforge/intelligence/smart-compaction.md"
+
+  ".mindforge/governance/change-classifier.md"
+  ".mindforge/governance/approval-workflow.md"
+  ".mindforge/governance/compliance-gates.md"
+
+  ".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"
+
+  ".planning/HANDOFF.json"
+  ".planning/STATE.md"
+  ".planning/AUDIT.jsonl"
+)
+```
+
+`MINDFORGE.md` is optional and is not in required files.
+If `MINDFORGE.md` exists, validate:
+- no unknown skills (must exist in `.mindforge/org/skills/MANIFEST.md`)
+- no invalid model names (fallback to `inherit` + warning)
+- no attempted overrides of governance primitives
+
+### Version check
+- Validate `package.json` semver is `>= 0.5.0`.
+
+### CLAUDE parity
+- `.claude/CLAUDE.md` and `.agent/CLAUDE.md` must be identical.
+- All commands under `.claude/commands/mindforge/` must exist in `.agent/mindforge/`.
+
+## Category 2 — Context file health
+- `PROJECT.md` has tech stack, v1 scope, success criteria, and no placeholders.
+- `REQUIREMENTS.md` has FR entries with acceptance criteria and scope tags.
+- `STATE.md` has recent `Last updated` timestamp and coherent status.
+- `HANDOFF.json` is valid JSON with required fields and no secrets.
+- `ARCHITECTURE.md` exists with stack and decision references.
+
+## Category 3 — Skills registry health
+- `MANIFEST.md` exists; all 10 core skills listed with valid semver.
+- Every manifest skill path exists.
+- Every `SKILL.md` includes frontmatter: `name`, `version`, `status`, `triggers`.
+- Trigger conflict check runs and reports count.
+
+## Category 4 — Persona system health
+- Each persona has Identity, Pre-task checklist, Escalation, DoD.
+- Persona files are non-stub (>500 bytes).
+- Override files contain no prompt-injection markers.
+
+## Category 5 — State consistency
+- For every phase in ROADMAP: directory + required artifacts match phase status.
+- Explicit check: if `STATE.md` marks phase complete and summaries exist but `VERIFICATION.md` is missing, flag as error.
+- `AUDIT.jsonl` lines parse as JSONL and timestamps are chronological.
+- Commit hygiene:
+  - conventional commit format in recent history
+  - on `main`, only flag commits whose subject starts with `wip` (case-insensitive)
+
+## Category 6 — Integration connectivity
+For configured integrations, run lightweight auth checks and report:
+- `available`
+- `invalid_credentials`
+- `unreachable`
+- `unconfigured` (informational only)
+
+## Category 7 — Security configuration
+- `.gitignore` covers env files and keys.
+- Secret scan covers:
+  - `.planning/`
+  - `.mindforge/`
+  - root-level `MINDFORGE.md`, `.env.example`, `*.config.js`
+- `SECURITY.md` has no placeholders.
+- Governance approval files are not stale beyond SLA.
+
+## Auto-repair protocol
+
+### Auto-repairable
+- sync `.agent/CLAUDE.md` from `.claude/CLAUDE.md`
+- mirror missing command files from `.claude` to `.agent`
+- add missing `Last updated` in `STATE.md`
+- create `.planning/approvals/` if missing
+- mark expired approvals and audit them
+- trigger AUDIT archive protocol when threshold exceeded
+
+### AUDIT.jsonl corruption handling (updated)
+**Never delete lines from `AUDIT.jsonl`.**
+
+```bash
+python3 - <<'PY'
+import json
+from pathlib import Path
+
+audit = Path('.planning/AUDIT.jsonl')
+if not audit.exists():
+    raise SystemExit(0)
+
+invalid = []
+for i, raw in enumerate(audit.read_text().splitlines(), 1):
+    s = raw.strip()
+    if not s:
+        continue
+    try:
+        json.loads(s)
+    except Exception:
+        invalid.append({"line": i, "raw": s})
+
+if invalid:
+    qf = Path('.planning/AUDIT.jsonl.quarantine')
+    with qf.open('a', encoding='utf-8') as f:
+        for row in invalid:
+            f.write(json.dumps(row) + "\n")
+    print(f"Quarantined {len(invalid)} invalid lines to {qf}")
+PY
+
+echo "{\"event\":\"audit_quarantine\",\"quarantine_file\":\".planning/AUDIT.jsonl.quarantine\"}" >> .planning/AUDIT.jsonl
+```
+
+### Non-auto-repairable
+- missing core skill files
+- invalid credentials
+- secrets found in `HANDOFF.json`
+- prompt-injection patterns in persona overrides
+
+## Health report format
+Provide summary by category with errors, warnings, info, and exact next fixes.

package/.mindforge/intelligence/skill-gap-analyser.md

@@ -0,0 +1,40 @@
+# MindForge Intelligence — Skill Gap Analyser
+
+## Purpose
+Identify required/recommended skills for a phase, compare with installed
+skills, and report gaps before planning.
+
+## Run points
+1. `/mindforge:plan-phase` start
+2. `/mindforge:discuss-phase`
+3. `/mindforge:health`
+
+## Analysis flow
+1. Extract work signals from roadmap/context/requirements/architecture.
+2. Map work categories to required/recommended skills.
+3. Validate skills in manifest + filesystem + status.
+4. Report missing/deprecated required skills and mitigation options.
+
+## Category -> skill mapping
+- UI/UX -> accessibility (required), performance (recommended)
+- Database changes -> database-patterns (required), data-privacy (if PII)
+- API endpoints -> api-design (required), security-review (if auth)
+- Auth/payments/PII -> security-review (required), data-privacy (required for PII)
+- Performance work -> performance (required)
+- New feature -> testing-standards (required), documentation (recommended)
+
+## Gap definition
+A required skill is a gap if:
+- not present in MANIFEST
+- manifest path missing
+- marked deprecated with no replacement
+
+## Output
+Produce `Skill Gap Analysis` section with:
+- required skills table
+- recommended skills table
+- explicit gap count and options
+
+## Health mode
+In `/mindforge:health`, include org-level recommendation list using recent
+phase patterns and missing capability frequencies.

package/.mindforge/intelligence/smart-compaction.md

@@ -0,0 +1,71 @@
+# MindForge Intelligence — Smart Context Compaction
+
+## Purpose
+Replace truncation with structured extraction so future sessions preserve reasoning,
+constraints, and in-progress state.
+
+## Triggering and level selection
+Day 2 threshold (`70%`) remains valid and now invokes Day 5 Level 1.
+Level selection uses both context usage and session depth.
+
+- Light session (`<5` tasks): use Level 1 even when context is high.
+- Moderate session (`5-10` tasks): use Level 2 at `80%+`.
+- Deep session (`10+` tasks): use Level 2 at `75%+`.
+- Level 3 at `90%+` or urgent near-limit state.
+
+## Levels
+### Level 1 — Lightweight
+Quick checkpoint: update `STATE.md` and `HANDOFF.json` with next task.
+
+### Level 2 — Structured extraction
+Capture:
+- decisions made
+- discoveries
+- implicit knowledge
+- quality signals
+- precise in-progress state
+
+### Level 3 — Emergency extraction
+Capture minimum viable continuation context before hard limit.
+
+## Level 2 extraction protocol
+### Block A — Decisions made
+For each decision: what, why, alternatives ruled out, impact area, ADR need.
+
+### Block B — Discoveries
+For each finding: fact, location, significance, assumption impact.
+
+### Block C — Current task state
+Record plan id, completed steps, remaining steps, current file, and inconsistency state.
+
+### Block D — Implicit knowledge
+Capture quirks, environment facts, and workarounds.
+
+A knowledge item qualifies as a **quirk** if either:
+1. It contradicts documentation or expected tool behavior.
+2. A new agent reading only plans/personas would not infer it.
+
+### Block E — Quality signals
+Capture failed assumptions, friction patterns, quality gate root causes, and next-plan suggestions.
+
+## Level 2 HANDOFF schema additions
+- `decisions_made[]`
+- `discoveries[]`
+- `implicit_knowledge[]`
+- `quality_signals[]`
+- `in_progress.current_state`
+
+## Session restart protocol
+When loading Level 2 handoff:
+1. Print compact summary counts.
+2. Preload `implicit_knowledge` before plan execution.
+3. If `in_progress.current_state` is inconsistent, block execution and ask to resolve first.
+4. If user asks to inspect first, print first 50 lines of the inconsistent file inline.
+
+## Compaction quality metric
+Write one entry to `.mindforge/metrics/compaction-quality.jsonl`:
+- `decisions_captured`
+- `discoveries_captured`
+- `implicit_knowledge_items`
+- `quality_signals_captured`
+- `next_session_continuation_success` (auto-inferred from next session, nullable initially)

package/.mindforge/metrics/METRICS-SCHEMA.md

@@ -0,0 +1,42 @@
+# MindForge Metrics — Schema Reference
+
+## Files
+- `session-quality.jsonl`
+- `phase-metrics.jsonl`
+- `skill-usage.jsonl`
+- `compaction-quality.jsonl`
+
+All files are append-only JSONL.
+
+## session-quality.jsonl fields
+- session_id, date, phase, developer_id
+- tasks_attempted, tasks_completed, tasks_failed
+- verify_pass_rate, quality_gates_failed
+- security_findings, context_compactions
+- skills_loaded_count, antipatterns_detected
+- session_quality_score, session_quality_score_raw
+
+Score formula:
+- base 100
+- minus task/gate/security/antipattern penalties
+- bonus for zero gate failures and zero security findings
+- keep both raw and clamped (`0-100`) score for trend analysis
+
+## phase-metrics.jsonl fields
+- phase lifecycle and delivery coverage
+- difficulty score
+- security and UAT outcomes
+- phase_quality_score
+
+## skill-usage.jsonl fields
+- date, phase, plan
+- skill_name, skill_version
+- trigger_type (`text_match|file_path_match|file_name_match`)
+- trigger_keyword
+- task_outcome, verify_passed_first_try
+
+## compaction-quality.jsonl fields
+- date, compaction_level, context_pct_at_compaction
+- decisions_captured, discoveries_captured
+- implicit_knowledge_items, quality_signals_captured
+- next_session_continuation_success (auto-inferred where possible)

package/.mindforge/metrics/quality-tracker.md

@@ -0,0 +1,32 @@
+# MindForge Metrics — Quality Tracker
+
+## Trend windows
+- short: last 5 sessions
+- medium: last 20 sessions
+- long: all sessions
+
+## Key targets
+- Verify pass rate > 85% (warning < 75%)
+- Task failure rate < 10% (warning > 20%)
+- Compactions < 1 per 8 tasks (warning > 2 per session)
+
+## Early warnings
+- quality score drop >= 10 points over 3 sessions
+- any CRITICAL security finding after clean streak
+- compaction overhead > 2/session
+- stale skills not triggered in 10 sessions
+
+## Quality metrics -> agent behaviour adjustment
+Automatic adjustments at session start:
+
+- If verify pass rate < 75% over last 3 sessions:
+  tighten verify-step determinism checks before execution.
+- If last-session task failure rate > 20%:
+  halve estimated scope and suggest splitting.
+- If compaction frequency > 2/session:
+  proactively summarize every 4 tasks.
+- If security findings trend worsens over 3 phases:
+  force-load `security-review` for all tasks in current phase.
+
+Always report adjustment to user:
+`Quality signal detected: [signal]. Adjusting behaviour: [adjustment].`

package/.mindforge/monorepo/cross-package-planner.md

@@ -0,0 +1,114 @@
+# MindForge — Cross-Package Planner
+
+## Purpose
+When a phase spans multiple packages in a monorepo, coordinate execution
+so that shared dependencies are built and tested before packages that
+depend on them.
+
+## Execution order algorithm
+
+```
+Given: a set of packages involved in the current phase
+       and their inter-package dependencies
+
+Algorithm: topological sort of package dependency graph
+
+Input: WORKSPACE-MANIFEST.json dependency_order
+Output: ordered list of packages to process
+
+Example:
+  Phase touches: @myapp/api, @myapp/shared, @myapp/web
+  Dependencies: api→shared, web→shared, web→api
+  Topological order: shared → api → web
+  
+  Execution: 
+    Wave 1: process @myapp/shared (no dependencies on other changed packages)
+    Wave 2: process @myapp/api (depends on Wave 1: shared)
+    Wave 3: process @myapp/web (depends on Wave 2: api + Wave 1: shared)
+```
+
+## Per-package PLAN file routing
+
+When PLAN files are created for a monorepo phase, each plan specifies its target package:
+
+```xml
+<task type="auto">
+  <n>Add auth middleware to API</n>
+  <package>@myapp/api</package>
+  <working-dir>apps/api</working-dir>
+  <files>
+    apps/api/src/middleware/auth.ts
+    apps/api/src/middleware/auth.test.ts
+  </files>
+  <action>...</action>
+  <verify>cd apps/api && npm test -- --testPathPattern=auth.middleware</verify>
+  <done>Auth middleware tests passing in apps/api</done>
+</task>
+```
+
+## Cross-package test execution
+
+After all packages in the phase are processed:
+```bash
+# Run tests across all affected packages
+AFFECTED_PACKAGES=$(cat .planning/WORKSPACE-MANIFEST.json | \
+  node -e "const m=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')); \
+  console.log(m.packages.map(p=>p.path).join(' '))")
+
+for PKG_PATH in ${AFFECTED_PACKAGES}; do
+  echo "Testing ${PKG_PATH}..."
+  cd "${PKG_PATH}" && npm test && cd -
+done
+
+# Run integration tests from root (if configured)
+[ -f "package.json" ] && npm run test:integration 2>/dev/null || true
+```
+
+## Affected package detection (revised)
+
+```bash
+# CORRECTED: Match against declared package paths, not assume 2-level depth
+detect_affected_packages() {
+  local MANIFEST=".planning/WORKSPACE-MANIFEST.json"
+
+  if [ ! -f "${MANIFEST}" ]; then
+    echo "Run /mindforge:workspace detect first"
+    return 1
+  fi
+
+  # Get list of changed files
+  CHANGED_FILES=$(git diff --name-only HEAD~1 2>/dev/null || git diff --cached --name-only)
+
+  # For each package in manifest, check if any changed file is within that package
+  node -e "
+    const fs = require('fs');
+    const manifest = JSON.parse(fs.readFileSync('${MANIFEST}', 'utf8'));
+    const changedFiles = \`${CHANGED_FILES}\`.split('\n').filter(Boolean);
+
+    const affected = new Set();
+    manifest.packages.forEach(pkg => {
+      // Check if any changed file is within this package's path
+      const pkgPath = pkg.path.replace(/\/$/, ''); // remove trailing slash
+      changedFiles.forEach(file => {
+        if (file.startsWith(pkgPath + '/') || file === pkgPath) {
+          affected.add(pkg.name);
+        }
+      });
+    });
+
+    // Also add packages that depend on affected packages
+    manifest.packages.forEach(pkg => {
+      if (pkg.dependencies && pkg.dependencies.some(dep => affected.has(dep))) {
+        affected.add(pkg.name);
+      }
+    });
+
+    console.log([...affected].join('\n'));
+  "
+}
+```
+
+This correctly handles:
+- Packages at any nesting depth (`libs/shared/utils/` → 3 levels deep)
+- Packages whose path is a prefix of another (avoid false matches)
+- Transitive dependencies (packages that depend on changed packages)

package/.mindforge/monorepo/dependency-graph-builder.md

@@ -0,0 +1,32 @@
+# MindForge — Dependency Graph Builder
+
+## Purpose
+Build a dependency graph of packages in a monorepo to support topological
+ordering and affected package detection.
+
+## Input
+- `.planning/WORKSPACE-MANIFEST.json`
+- Each package's `package.json` dependencies
+
+## Output
+A directed graph where nodes are packages and edges represent internal
+package dependencies.
+
+Example:
+```
+@myapp/shared → @myapp/api
+@myapp/shared → @myapp/web
+@myapp/api    → @myapp/web
+```
+
+## Steps
+
+1. Load `WORKSPACE-MANIFEST.json`.
+2. For each package, read `dependencies` and `devDependencies`.
+3. Filter dependencies to only those that match workspace package names.
+4. Build adjacency list and compute topological order.
+5. Write to `.planning/WORKSPACE-MANIFEST.json` as `dependency_order`.
+
+## Failure modes
+- Cycles detected: stop, report cycle path, require manual resolution.
+- Missing package metadata: warn and skip.

package/.mindforge/monorepo/workspace-detector.md

@@ -0,0 +1,129 @@
+# MindForge — Monorepo Workspace Detector
+
+## Purpose
+Detect and understand monorepo structures (npm workspaces, pnpm workspaces,
+Nx, Turborepo, Lerna) so MindForge can plan and execute phases across
+multiple packages correctly.
+
+## Supported monorepo types
+
+| Type | Detection file | Package locations |
+|---|---|---|
+| npm workspaces | `package.json` with `"workspaces":` | Defined in workspaces array |
+| pnpm workspaces | `pnpm-workspace.yaml` | Defined in packages array |
+| Nx | `nx.json` | `apps/` and `libs/` |
+| Turborepo | `turbo.json` | `apps/` and `packages/` |
+| Lerna | `lerna.json` | Defined in packages array |
+| Yarn workspaces | `package.json` with `"workspaces":` | Same as npm |
+
+## Detection protocol
+
+```bash
+detect_workspace_type() {
+  local ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+
+  # Check in priority order
+  if [ -f "${ROOT}/nx.json" ]; then
+    echo "nx"
+  elif [ -f "${ROOT}/turbo.json" ]; then
+    echo "turborepo"
+  elif [ -f "${ROOT}/lerna.json" ]; then
+    echo "lerna"
+  elif [ -f "${ROOT}/pnpm-workspace.yaml" ]; then
+    echo "pnpm"
+  elif node -e "
+    const p = require('./package.json');
+    process.exit(p.workspaces ? 0 : 1)
+  " 2>/dev/null; then
+    echo "npm-workspaces"
+  else
+    echo "none"
+  fi
+}
+
+list_packages() {
+  local TYPE="$1"
+  case "${TYPE}" in
+    nx)
+      find apps/ libs/ -name "package.json" -not -path "*/node_modules/*" \
+        -exec dirname {} \; 2>/dev/null | sort
+      ;;
+    turborepo)
+      find apps/ packages/ -name "package.json" -not -path "*/node_modules/*" \
+        -exec dirname {} \; 2>/dev/null | sort
+      ;;
+    pnpm)
+      cat pnpm-workspace.yaml | grep "^  -" | sed "s/  - '//;s/'$//"
+      ;;
+    npm-workspaces|lerna)
+      node -e "
+        const p = require('./package.json');
+        const ws = p.workspaces || require('./lerna.json').packages || [];
+        ws.forEach(w => console.log(w.replace(/\/\*$/, '')));
+      " 2>/dev/null
+      ;;
+  esac
+}
+```
+
+## Package metadata extraction
+
+For each detected package, extract:
+```javascript
+{
+  "name": "package name from package.json",
+  "path": "relative path from monorepo root",
+  "type": "app | lib | shared | api | web | cli",
+  "dependencies": ["list of internal package dependencies"],
+  "scripts": {
+    "build": "build command",
+    "test": "test command",
+    "lint": "lint command"
+  },
+  "mindforge": {
+    "phase-scope": "global | package-specific",
+    "test-command": "override test command if needed",
+    "affected-by": ["list of packages that affect this one"]
+  }
+}
+```
+
+## Workspace manifest
+
+Write to `.planning/WORKSPACE-MANIFEST.json`:
+
+```json
+{
+  "schema_version": "1.0.0",
+  "workspace_type": "turborepo",
+  "root": "/path/to/project",
+  "packages": [
+    {
+      "name": "@myapp/api",
+      "path": "apps/api",
+      "type": "api",
+      "dependencies": ["@myapp/shared"],
+      "test_command": "npm test",
+      "build_command": "npm run build"
+    },
+    {
+      "name": "@myapp/web",
+      "path": "apps/web",
+      "type": "web",
+      "dependencies": ["@myapp/shared", "@myapp/ui"],
+      "test_command": "npm test",
+      "build_command": "npm run build"
+    },
+    {
+      "name": "@myapp/shared",
+      "path": "packages/shared",
+      "type": "lib",
+      "dependencies": [],
+      "test_command": "npm test",
+      "build_command": "npm run build"
+    }
+  ],
+  "dependency_order": ["@myapp/shared", "@myapp/api", "@myapp/web"],
+  "affected_packages": {}
+}
+```