mindforge-cc 8.2.0 → 9.0.0

package/.mindforge/mirrors/mirror-sre-776a1cf9/docs/References/git-integration.md

@@ -1,295 +0,0 @@
-<overview>
-Git integration for MindForge framework.
-</overview>
-
-<core_principle>
-
-**Commit outcomes, not process.**
-
-The git log should read like a changelog of what shipped, not a diary of planning activity.
-</core_principle>
-
-<commit_points>
-
-| Event                   | Commit? | Why                                              |
-| ----------------------- | ------- | ------------------------------------------------ |
-| BRIEF + ROADMAP created | YES     | Project initialization                           |
-| PLAN.md created         | NO      | Intermediate - commit with plan completion       |
-| RESEARCH.md created     | NO      | Intermediate                                     |
-| DISCOVERY.md created    | NO      | Intermediate                                     |
-| **Task completed**      | YES     | Atomic unit of work (1 commit per task)         |
-| **Plan completed**      | YES     | Metadata commit (SUMMARY + STATE + ROADMAP)     |
-| Handoff created         | YES     | WIP state preserved                              |
-
-</commit_points>
-
-<git_check>
-
-```bash
-[ -d .git ] && echo "GIT_EXISTS" || echo "NO_GIT"
-```
-
-If NO_GIT: Run `git init` silently. MindForge projects always get their own repo.
-</git_check>
-
-<commit_formats>
-
-<format name="initialization">
-## Project Initialization (brief + roadmap together)
-
-```
-docs: initialize [project-name] ([N] phases)
-
-[One-liner from PROJECT.md]
-
-Phases:
-1. [phase-name]: [goal]
-2. [phase-name]: [goal]
-3. [phase-name]: [goal]
-```
-
-What to commit:
-
-```bash
-node ".agent/mindforge/bin/mindforge-tools.cjs" commit "docs: initialize [project-name] ([N] phases)" --files .planning/
-```
-
-</format>
-
-<format name="task-completion">
-## Task Completion (During Plan Execution)
-
-Each task gets its own commit immediately after completion.
-
-> **Parallel agents:** When running as a parallel executor (spawned by execute-phase),
-> use `--no-verify` on all commits to avoid pre-commit hook lock contention.
-> The orchestrator validates hooks once after all agents complete.
-
-```
-{type}({phase}-{plan}): {task-name}
-
-- [Key change 1]
-- [Key change 2]
-- [Key change 3]
-```
-
-**Commit types:**
-- `feat` - New feature/functionality
-- `fix` - Bug fix
-- `test` - Test-only (TDD RED phase)
-- `refactor` - Code cleanup (TDD REFACTOR phase)
-- `perf` - Performance improvement
-- `chore` - Dependencies, config, tooling
-
-**Examples:**
-
-```bash
-# Standard task
-git add src/api/auth.ts src/types/user.ts
-git commit -m "feat(08-02): create user registration endpoint
-
-- POST /auth/register validates email and password
-- Checks for duplicate users
-- Returns JWT token on success
-"
-
-# TDD task - RED phase
-git add src/__tests__/jwt.test.ts
-git commit -m "test(07-02): add failing test for JWT generation
-
-- Tests token contains user ID claim
-- Tests token expires in 1 hour
-- Tests signature verification
-"
-
-# TDD task - GREEN phase
-git add src/utils/jwt.ts
-git commit -m "feat(07-02): implement JWT generation
-
-- Uses jose library for signing
-- Includes user ID and expiry claims
-- Signs with HS256 algorithm
-"
-```
-
-</format>
-
-<format name="plan-completion">
-## Plan Completion (After All Tasks Done)
-
-After all tasks committed, one final metadata commit captures plan completion.
-
-```
-docs({phase}-{plan}): complete [plan-name] plan
-
-Tasks completed: [N]/[N]
-- [Task 1 name]
-- [Task 2 name]
-- [Task 3 name]
-
-SUMMARY: .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md
-```
-
-What to commit:
-
-```bash
-node ".agent/mindforge/bin/mindforge-tools.cjs" commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md
-```
-
-**Note:** Code files NOT included - already committed per-task.
-
-</format>
-
-<format name="handoff">
-## Handoff (WIP)
-
-```
-wip: [phase-name] paused at task [X]/[Y]
-
-Current: [task name]
-[If blocked:] Blocked: [reason]
-```
-
-What to commit:
-
-```bash
-node ".agent/mindforge/bin/mindforge-tools.cjs" commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/
-```
-
-</format>
-</commit_formats>
-
-<example_log>
-
-**Old approach (per-plan commits):**
-```
-a7f2d1 feat(checkout): Stripe payments with webhook verification
-3e9c4b feat(products): catalog with search, filters, and pagination
-8a1b2c feat(auth): JWT with refresh rotation using jose
-5c3d7e feat(foundation): Next.js 15 + Prisma + Tailwind scaffold
-2f4a8d docs: initialize ecommerce-app (5 phases)
-```
-
-**New approach (per-task commits):**
-```
-# Phase 04 - Checkout
-1a2b3c docs(04-01): complete checkout flow plan
-4d5e6f feat(04-01): add webhook signature verification
-7g8h9i feat(04-01): implement payment session creation
-0j1k2l feat(04-01): create checkout page component
-
-# Phase 03 - Products
-3m4n5o docs(03-02): complete product listing plan
-6p7q8r feat(03-02): add pagination controls
-9s0t1u feat(03-02): implement search and filters
-2v3w4x feat(03-01): create product catalog schema
-
-# Phase 02 - Auth
-5y6z7a docs(02-02): complete token refresh plan
-8b9c0d feat(02-02): implement refresh token rotation
-1e2f3g test(02-02): add failing test for token refresh
-4h5i6j docs(02-01): complete JWT setup plan
-7k8l9m feat(02-01): add JWT generation and validation
-0n1o2p chore(02-01): install jose library
-
-# Phase 01 - Foundation
-3q4r5s docs(01-01): complete scaffold plan
-6t7u8v feat(01-01): configure Tailwind and globals
-9w0x1y feat(01-01): set up Prisma with database
-2z3a4b feat(01-01): create Next.js 15 project
-
-# Initialization
-5c6d7e docs: initialize ecommerce-app (5 phases)
-```
-
-Each plan produces 2-4 commits (tasks + metadata). Clear, granular, bisectable.
-
-</example_log>
-
-<anti_patterns>
-
-**Still don't commit (intermediate artifacts):**
-- PLAN.md creation (commit with plan completion)
-- RESEARCH.md (intermediate)
-- DISCOVERY.md (intermediate)
-- Minor planning tweaks
-- "Fixed typo in roadmap"
-
-**Do commit (outcomes):**
-- Each task completion (feat/fix/test/refactor)
-- Plan completion metadata (docs)
-- Project initialization (docs)
-
-**Key principle:** Commit working code and shipped outcomes, not planning process.
-
-</anti_patterns>
-
-<commit_strategy_rationale>
-
-## Why Per-Task Commits?
-
-**Context engineering for AI:**
-- Git history becomes primary context source for future MindForge sessions
-- `git log --grep="{phase}-{plan}"` shows all work for a plan
-- `git diff <hash>^..<hash>` shows exact changes per task
-- Less reliance on parsing SUMMARY.md = more context for actual work
-
-**Failure recovery:**
-- Task 1 committed ✅, Task 2 failed ❌
-- MindForge in next session: sees task 1 complete, can retry task 2
-- Can `git reset --hard` to last successful task
-
-**Debugging:**
-- `git bisect` finds exact failing task, not just failing plan
-- `git blame` traces line to specific task context
-- Each commit is independently revertable
-
-**Observability:**
-- Solo developer + MindForge workflow benefits from granular attribution
-- Atomic commits are git best practice
-- "Commit noise" irrelevant when consumer is MindForge, not humans
-
-</commit_strategy_rationale>
-
-<sub_repos_support>
-
-## Multi-Repo Workspace Support (sub_repos)
-
-For workspaces with separate git repos (e.g., `backend/`, `frontend/`, `shared/`), MindForge routes commits to each repo independently.
-
-### Configuration
-
-In `.planning/config.json`, list sub-repo directories under `planning.sub_repos`:
-
-```json
-{
-  "planning": {
-    "commit_docs": false,
-    "sub_repos": ["backend", "frontend", "shared"]
-  }
-}
-```
-
-Set `commit_docs: false` so planning docs stay local and are not committed to any sub-repo.
-
-### How It Works
-
-1. **Auto-detection:** During `/mindforge-new-project`, directories with their own `.git` folder are detected and offered for selection as sub-repos. On subsequent runs, `loadConfig` auto-syncs the `sub_repos` list with the filesystem — adding newly created repos and removing deleted ones. This means `config.json` may be rewritten automatically when repos change on disk.
-2. **File grouping:** Code files are grouped by their sub-repo prefix (e.g., `backend/src/api/users.ts` belongs to the `backend/` repo).
-3. **Independent commits:** Each sub-repo receives its own atomic commit via `mindforge-tools.cjs commit-to-subrepo`. File paths are made relative to the sub-repo root before staging.
-4. **Planning stays local:** The `.planning/` directory is not committed; it acts as cross-repo coordination.
-
-### Commit Routing
-
-Instead of the standard `commit` command, use `commit-to-subrepo` when `sub_repos` is configured:
-
-```bash
-node .agent/mindforge/bin/mindforge-tools.cjs commit-to-subrepo "feat(02-01): add user API" \
-  --files backend/src/api/users.ts backend/src/types/user.ts frontend/src/components/UserForm.tsx
-```
-
-This stages `src/api/users.ts` and `src/types/user.ts` in the `backend/` repo, and `src/components/UserForm.tsx` in the `frontend/` repo, then commits each independently with the same message.
-
-Files that don't match any configured sub-repo are reported as unmatched.
-
-</sub_repos_support>

package/.mindforge/mirrors/mirror-sre-776a1cf9/docs/References/git-planning-commit.md

@@ -1,38 +0,0 @@
-# Git Planning Commit
-
-Commit planning artifacts using MindForge-tools CLI, which automatically checks `commit_docs` config and gitignore status.
-
-## Commit via CLI
-
-Always use `mindforge-tools.cjs commit` for `.planning/` files — it handles `commit_docs` and gitignore checks automatically:
-
-```bash
-node ".agent/mindforge/bin/mindforge-tools.cjs" commit "docs({scope}): {description}" --files .planning/STATE.md .planning/ROADMAP.md
-```
-
-The CLI will return `skipped` (with reason) if `commit_docs` is `false` or `.planning/` is gitignored. No manual conditional checks needed.
-
-## Amend previous commit
-
-To fold `.planning/` file changes into the previous commit:
-
-```bash
-node ".agent/mindforge/bin/mindforge-tools.cjs" commit "" --files .planning/codebase/*.md --amend
-```
-
-## Commit Message Patterns
-
-| Command | Scope | Example |
-|---------|-------|---------|
-| plan-phase | phase | `docs(phase-03): create authentication plans` |
-| execute-phase | phase | `docs(phase-03): complete authentication phase` |
-| new-milestone | milestone | `docs: start milestone v1.1` |
-| remove-phase | chore | `chore: remove phase 17 (dashboard)` |
-| insert-phase | phase | `docs: insert phase 16.1 (critical fix)` |
-| add-phase | phase | `docs: add phase 07 (settings page)` |
-
-## When to Skip
-
-- `commit_docs: false` in config
-- `.planning/` is gitignored
-- No changes to commit (check with `git status --porcelain .planning/`)

package/.mindforge/mirrors/mirror-sre-776a1cf9/docs/References/model-profile-resolution.md

@@ -1,36 +0,0 @@
-# Model Profile Resolution
-
-Resolve model profile once at the start of orchestration, then use it for all Task spawns.
-
-## Resolution Pattern
-
-```bash
-MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
-```
-
-Default: `balanced` if not set or config missing.
-
-## Lookup Table
-
-@.agent/mindforge/references/model-profiles.md
-
-Look up MindForge in the table for the resolved profile. Pass the model parameter to Task calls:
-
-```
-Task(
-  prompt="...",
-  subagent_type="mindforge-planner",
-  model="{resolved_model}"  # "inherit", "sonnet", or "haiku"
-)
-```
-
-**Note:** Opus-tier agents resolve to `"inherit"` (not `"opus"`). This causes MindForge to use the parent session's model, avoiding conflicts with organization policies that may block specific opus versions.
-
-If `model_profile` is `"inherit"`, all agents resolve to `"inherit"` (useful for OpenCode `/model`).
-
-## Usage
-
-1. Resolve once at orchestration start
-2. Store the profile value
-3. Look up each agent's model from the table when spawning
-4. Pass model parameter to each Task call (values: `"inherit"`, `"sonnet"`, `"haiku"`)

package/.mindforge/mirrors/mirror-sre-776a1cf9/docs/References/model-profiles.md

@@ -1,139 +0,0 @@
-# Model Profiles
-
-Model profiles control which MindForge model each MindForge agent uses. This allows balancing quality vs token spend, or inheriting the currently selected session model.
-
-## Profile Definitions
-
-| Agent | `quality` | `balanced` | `budget` | `inherit` |
-|-------|-----------|------------|----------|-----------|
-| mindforge-planner | opus | opus | sonnet | inherit |
-| mindforge-roadmapper | opus | sonnet | sonnet | inherit |
-| mindforge-executor | opus | sonnet | sonnet | inherit |
-| mindforge-phase-researcher | opus | sonnet | haiku | inherit |
-| mindforge-project-researcher | opus | sonnet | haiku | inherit |
-| mindforge-research-synthesizer | sonnet | sonnet | haiku | inherit |
-| mindforge-debugger | opus | sonnet | sonnet | inherit |
-| mindforge-codebase-mapper | sonnet | haiku | haiku | inherit |
-| mindforge-verifier | sonnet | sonnet | haiku | inherit |
-| mindforge-plan-checker | sonnet | sonnet | haiku | inherit |
-| mindforge-integration-checker | sonnet | sonnet | haiku | inherit |
-| mindforge-nyquist-auditor | sonnet | sonnet | haiku | inherit |
-
-## Profile Philosophy
-
-**quality** - Maximum reasoning power
-- Opus for all decision-making agents
-- Sonnet for read-only verification
-- Use when: quota available, critical architecture work
-
-**balanced** (default) - Smart allocation
-- Opus only for planning (where architecture decisions happen)
-- Sonnet for execution and research (follows explicit instructions)
-- Sonnet for verification (needs reasoning, not just pattern matching)
-- Use when: normal development, good balance of quality and cost
-
-**budget** - Minimal Opus usage
-- Sonnet for anything that writes code
-- Haiku for research and verification
-- Use when: conserving quota, high-volume work, less critical phases
-
-**inherit** - Follow the current session model
-- All agents resolve to `inherit`
-- Best when you switch models interactively (for example OpenCode `/model`)
-- **Required when using non-Anthropic providers** (OpenRouter, local models, etc.) — otherwise MindForge may call Anthropic models directly, incurring unexpected costs
-- Use when: you want MindForge to follow your currently selected runtime model
-
-## Using Non-MindForge Runtimes (Codex, OpenCode, Gemini CLI)
-
-When installed for a non-MindForge runtime, MindForge installer sets `resolve_model_ids: "omit"` in `~/.mindforge/defaults.json`. This returns an empty model parameter for all agents, so each agent uses the runtime's default model. No manual setup is needed.
-
-To assign different models to different agents, add `model_overrides` with model IDs your runtime recognizes:
-
-```json
-{
-  "resolve_model_ids": "omit",
-  "model_overrides": {
-    "mindforge-planner": "o3",
-    "mindforge-executor": "o4-mini",
-    "mindforge-debugger": "o3",
-    "mindforge-codebase-mapper": "o4-mini"
-  }
-}
-```
-
-The same tiering logic applies: stronger models for planning and debugging, cheaper models for execution and mapping.
-
-## Using Claude Code with Non-Anthropic Providers (OpenRouter, Local)
-
-If you're using Claude Code with OpenRouter, a local model, or any non-Anthropic provider, set the `inherit` profile to prevent MindForge from calling Anthropic models for subagents:
-
-```bash
-# Via settings command
-/mindforge-settings
-# → Select "Inherit" for model profile
-
-# Or manually in .planning/config.json
-{
-  "model_profile": "inherit"
-}
-```
-
-Without `inherit`, MindForge's default `balanced` profile spawns specific Anthropic models (`opus`, `sonnet`, `haiku`) for each agent type, which can result in additional API costs through your non-Anthropic provider.
-
-## Resolution Logic
-
-Orchestrators resolve model before spawning:
-
-```
-1. Read .planning/config.json
-2. Check model_overrides for agent-specific override
-3. If no override, look up agent in profile table
-4. Pass model parameter to Task call
-```
-
-## Per-Agent Overrides
-
-Override specific agents without changing the entire profile:
-
-```json
-{
-  "model_profile": "balanced",
-  "model_overrides": {
-    "mindforge-executor": "opus",
-    "mindforge-planner": "haiku"
-  }
-}
-```
-
-Overrides take precedence over the profile. Valid values: `opus`, `sonnet`, `haiku`, `inherit`, or any fully-qualified model ID (e.g., `"o3"`, `"openai/o3"`, `"google/gemini-2.5-pro"`).
-
-## Switching Profiles
-
-Runtime: `/mindforge-set-profile <profile>`
-
-Per-project default: Set in `.planning/config.json`:
-```json
-{
-  "model_profile": "balanced"
-}
-```
-
-## Design Rationale
-
-**Why Opus for mindforge-planner?**
-Planning involves architecture decisions, goal decomposition, and task design. This is where model quality has the highest impact.
-
-**Why Sonnet for mindforge-executor?**
-Executors follow explicit PLAN.md instructions. The plan already contains the reasoning; execution is implementation.
-
-**Why Sonnet (not Haiku) for verifiers in balanced?**
-Verification requires goal-backward reasoning - checking if code *delivers* what the phase promised, not just pattern matching. Sonnet handles this well; Haiku may miss subtle gaps.
-
-**Why Haiku for mindforge-codebase-mapper?**
-Read-only exploration and pattern extraction. No reasoning required, just structured output from file contents.
-
-**Why `inherit` instead of passing `opus` directly?**
-Claude Code's `"opus"` alias maps to a specific model version. Organizations may block older opus versions while allowing newer ones. MindForge returns `"inherit"` for opus-tier agents, causing them to use whatever opus version the user has configured in their session. This avoids version conflicts and silent fallbacks to Sonnet.
-
-**Why `inherit` profile?**
-Some runtimes (including OpenCode) let users switch models at runtime (`/model`). The `inherit` profile keeps all MindForge subagents aligned to that live selection.

package/.mindforge/mirrors/mirror-sre-776a1cf9/docs/References/phase-argument-parsing.md

@@ -1,61 +0,0 @@
-# Phase Argument Parsing
-
-Parse and normalize phase arguments for commands that operate on phases.
-
-## Extraction
-
-From `$ARGUMENTS`:
-- Extract phase number (first numeric argument)
-- Extract flags (prefixed with `--`)
-- Remaining text is description (for insert/add commands)
-
-## Using mindforge-tools
-
-The `find-phase` command handles normalization and validation in one step:
-
-```bash
-PHASE_INFO=$(node ".agent/mindforge/bin/mindforge-tools.cjs" find-phase "${PHASE}")
-```
-
-Returns JSON with:
-- `found`: true/false
-- `directory`: Full path to phase directory
-- `phase_number`: Normalized number (e.g., "06", "06.1")
-- `phase_name`: Name portion (e.g., "foundation")
-- `plans`: Array of PLAN.md files
-- `summaries`: Array of SUMMARY.md files
-
-## Manual Normalization (Legacy)
-
-Zero-pad integer phases to 2 digits. Preserve decimal suffixes.
-
-```bash
-# Normalize phase number
-if [[ "$PHASE" =~ ^[0-9]+$ ]]; then
-  # Integer: 8 → 08
-  PHASE=$(printf "%02d" "$PHASE")
-elif [[ "$PHASE" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
-  # Decimal: 2.1 → 02.1
-  PHASE=$(printf "%02d.%s" "${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}")
-fi
-```
-
-## Validation
-
-Use `roadmap get-phase` to validate phase exists:
-
-```bash
-PHASE_CHECK=$(node ".agent/mindforge/bin/mindforge-tools.cjs" roadmap get-phase "${PHASE}" --pick found)
-if [ "$PHASE_CHECK" = "false" ]; then
-  echo "ERROR: Phase ${PHASE} not found in roadmap"
-  exit 1
-fi
-```
-
-## Directory Lookup
-
-Use `find-phase` for directory lookup:
-
-```bash
-PHASE_DIR=$(node ".agent/mindforge/bin/mindforge-tools.cjs" find-phase "${PHASE}" --raw)
-```