mindforge-cc 11.3.0 → 11.4.0

package/docs/References/commands.md

@@ -0,0 +1,107 @@
+# MindForge v2.0.0 — Complete Commands Reference
+
+## All 50+ commands
+
+### Lifecycle commands (core workflow)
+
+| Command | Usage | Description | Added |
+|---|---|---|---|
+| `/mindforge:init-project` | `init-project` | Guided project setup — creates all `.planning/` files | |
+| `/mindforge:discuss-phase` | `discuss-phase [N] [--batch|--auto]` | Pre-planning interview to capture implementation decisions | |
+| `/mindforge:ui-phase` | `ui-phase [N]` | Generate UI design contract (UI-SPEC.md) | v2.0.0 |
+| `/mindforge:plan-phase` | `plan-phase [N]` | Research, decompose, and create atomic task plans | |
+| `/mindforge:execute-phase` | `execute-phase [N]` | Wave-based parallel execution of all phase plans | Day 1+2 |
+| `/mindforge:ui-review` | `ui-review [N]` | Retroactive 6-pillar visual audit | v2.0.0 |
+| `/mindforge:verify-phase` | `verify-phase [N]` | Automated + human acceptance testing pipeline | |
+| `/mindforge:validate-phase` | `validate-phase [N]` | Requirement coverage and test gap audit | v2.0.0 |
+| `/mindforge:ship` | `ship [N]` | Create PR, write release notes, push to remote | |
+| `/mindforge:auto` | `auto [--phase N] [--milestone M]` | Walk-away autonomous execution with stuck detection | |
+| `/mindforge:steer` | `steer "instruction"` | Inject guidance into a running autonomous session | |
+| `/mindforge:next` | `next` | Auto-detect and execute the correct next workflow step | |
+| `/mindforge:cross-review` | `cross-review` | Adversarial multi-model code review and synthesis | |
+| `/mindforge:research` | `research "query"` | Deep research using Gemini 1.5 Pro 1M context | |
+| `/mindforge:remember` | `remember [--add X|--search Y|--promote ID|--stats]` | Persistent knowledge graph management | |
+| `/mindforge:workstreams` | `workstreams [list|create|switch|status|complete]` | Manage parallel feature tracks with isolated state | v2.0.0 |
+
+### Project setup & discovery
+
+| Command | Usage | Description | Added |
+|---|---|---|---|
+| `/mindforge:map-codebase` | `map-codebase` | Brownfield onboarding: infer stack and seed docs | |
+| `/mindforge:do` | `do <text>` | Smart dispatcher for natural language intent | v2.0.0 |
+| `/mindforge:note` | `note <text> [list|promote N]` | Zero-friction idea capture and todo promotion | v2.0.0 |
+| `/mindforge:quick` | `quick` | Run a small, single-task plan without a full phase | |
+| `/mindforge:status` | `status` | Show current phase, plan status, and next action | |
+| `/mindforge:health` | `health [--repair]` | Validate installation and repair drift | |
+| `/mindforge:review` | `review [N]` | Run a structured review pass for a phase | |
+| `/mindforge:debug` | `debug [plan-id]` | Debug a failed plan with root-cause workflow | |
+| `/mindforge:add-backlog` | `add-backlog <desc>` | Park ideas in 999.x "parking lot" | v2.0.0 |
+| `/mindforge:review-backlog` | `review-backlog` | Review and promote backlog items to active phases | v2.0.0 |
+| `/mindforge:plant-seed` | `plant-seed <idea>` | Capture speculative ideas with triggers | v2.0.0 |
+
+### Governance & compliance
+
+| Command | Usage | Description | Added |
+|---|---|---|---|
+| `/mindforge:approve` | `approve [--tier 2|3]` | Process approvals and emergency overrides | |
+| `/mindforge:audit` | `audit [--phase N] [--event X] [--since DATE]` | Query `AUDIT.jsonl` history | |
+| `/mindforge:security-scan` | `security-scan [--deep] [--secrets] [--deps]` | Security scan with OWASP classification | |
+| `/mindforge:milestone` | `milestone [name]` | Create or update milestone definitions | |
+| `/mindforge:complete-milestone` | `complete-milestone [name]` | Archive milestone and generate release report | |
+| `/mindforge:retrospective` | `retrospective [N]` | Phase retrospective and improvement actions | |
+
+### Skills & plugins
+
+| Command | Usage | Description | Added |
+|---|---|---|---|
+| `/mindforge:skills` | `skills [list|validate|refresh]` | Manage core/org/project skills | |
+| `/mindforge:install-skill` | `install-skill <name> [--version]` | Install skill from registry | |
+| `/mindforge:publish-skill` | `publish-skill <path>` | Publish a skill to the registry | |
+| `/mindforge:plugins` | `plugins [list|install|uninstall|validate]` | Manage plugin lifecycle | |
+
+### Intelligence & metrics
+
+| Command | Usage | Description | Added |
+|---|---|---|---|
+| `/mindforge:metrics` | `metrics [--phase N]` | Compute quality and throughput metrics | |
+| `/mindforge:profile-team` | `profile-team` | Generate team skill and ownership profile | |
+| `/mindforge:benchmark` | `benchmark [--skill X]` | Measure skill effectiveness | |
+| `/mindforge:tokens` | `tokens [--profile] [--summary]` | Token usage profiling and optimisation | |
+
+### Integrations & distribution
+
+| Command | Usage | Description | Added |
+|---|---|---|---|
+| `/mindforge:init-org` | `init-org` | Org-wide MindForge setup | |
+| `/mindforge:sync-jira` | `sync-jira [--project KEY]` | Sync phases and plans to Jira | |
+| `/mindforge:sync-confluence` | `sync-confluence [--page ...]` | Publish docs to Confluence | |
+| `/mindforge:pr-review` | `pr-review [--range A..B]` | AI PR review with context | |
+| `/mindforge:workspace` | `workspace [detect|plan|test]` | Monorepo workspace management | |
+| `/mindforge:browse` | `browse [--navigate URL] [--command]` | Control persistent browser daemon and sessions | |
+| `/mindforge:qa` | `qa [--diff] [--all]` | Run systematic visual QA and regression tests | |
+
+### Release & maintenance
+
+| Command | Usage | Description | Added |
+|---|---|---|---|
+| `/mindforge:update` | `update [--apply] [--force] [--check]` | Check for and apply framework updates | |
+| `/mindforge:migrate` | `migrate [--from vX] [--to vY] [--dry-run]` | Run schema migrations | |
+| `/mindforge:session-report` | `session-report` | Generate post-session summary and resource profiling | v2.0.0 |
+| `/mindforge:release` | `release [--tag vX]` | Framework release pipeline (core team) | |
+
+### Utility
+
+| Command | Usage | Description | Added |
+|---|---|---|---|
+| `/mindforge:help` | `help` | Show all available commands and current project status | |
+
+## Command interface contract (v1.0.0 stable)
+
+As of v1.0.0, the following are part of the stable interface:
+- All 36 command names (new commands require MINOR bump)
+- All flags documented here (new flags require MINOR, removed flags require MAJOR)
+- HANDOFF.json and AUDIT.jsonl schemas (additions: MINOR, removals: MAJOR)
+- All 10 core skill `name:` values and trigger lists
+- SDK exported types and functions
+
+See ADR-020 for the complete stability contract.

package/docs/References/config-reference.md

@@ -0,0 +1,122 @@
+# MINDFORGE.md Configuration Reference
+
+`MINDFORGE.md` acts as the project-level "constitution" for the MindForge framework. It allows teams to override default models, execution behaviors, and quality gates to fit specific project needs.
+
+---
+
+## 1. Model Configuration
+
+MindForge uses a tiered model routing system. You can specify exact models for different phases of the lifecycle.
+
+| Key | Description | Default |
+| :--- | :--- | :--- |
+| `PLANNER_MODEL` | Model used for task decomposition and planning. | `claude-sonnet-4-5` |
+| `EXECUTOR_MODEL` | Model used for code generation and implementation. | `claude-sonnet-4-5` |
+| `REVIEWER_MODEL` | Model used for code review and PR analysis. | `claude-opus-4-alpha` |
+| `VERIFIER_MODEL` | Model used for testing and UAT verification. | `claude-sonnet-4-5` |
+| `SECURITY_MODEL` | Model used for sensitive security scanning. | `claude-opus-4-alpha` |
+
+**Supported Values:**
+
+- `claude-opus-4-alpha` (High intelligence, slow, expensive)
+- `claude-sonnet-4-5` (Balanced, recommended)
+- `claude-haiku-4-5` (Fast, logical, best for trivial tasks)
+- `inherit` (Use the system-wide default)
+
+---
+
+## 2. Autonomous Execution Settings
+
+These settings control the `/mindforge:auto` engine's behavior and performance.
+
+| Key | Description | Default |
+| :--- | :--- | :--- |
+| `AUTONOMOUS_MODE_ENABLED` | Global toggle for autonomous task execution. | `true` |
+| `MAX_TASKS_PER_PHASE` | Limit on task expansion during planning. | `15` |
+| `STUCK_DETECTION_TIMEOUT_MS` | Time before an agent is considered "looping" or stuck. | `300000` |
+| `STEERING_CHECK_INTERVAL_MS` | How often the engine checks for user guidance. | `5000` |
+| `NODE_REPAIR_ENABLED` | If true, the engine attempts to self-heal on failures. | `true` |
+| `COMPACTION_THRESHOLD_PCT` | The context usage percentage at which to trigger compaction. | `70` |
+
+---
+
+## 3. Engineering Quality Gates
+
+Define the rules that code must follow to pass the `VERIFY` phase.
+
+| Key | Description | Default |
+| :--- | :--- | :--- |
+| `MIN_TEST_COVERAGE_PCT` | Required test coverage for any new module. | `80` |
+| `MAX_FUNCTION_LINES` | Maximum lines allowed for a single function. | `40` |
+| `MAX_CYCLOMATIC_COMPLEXITY` | Maximum complexity score (McCune) allowed. | `10` |
+| `BLOCK_ON_MEDIUM_SECURITY` | Fail the gate if any medium security findings exist. | `true` |
+| `ANTIPATTERN_SENSITIVITY` | Frequency at which suspicious patterns are flagged. | `0.7` |
+
+---
+
+## 4. Skills & Personalization
+
+Control how skills are discovered and injected.
+
+| Key | Description | Default |
+| :--- | :--- | :--- |
+| `ALWAYS_LOAD_SKILLS` | List of skill IDs to inject in every session. | `[]` |
+| `DISABLED_SKILLS` | List of skills to ignore even if triggers match. | `[]` |
+| `MAX_FULL_SKILL_INJECTIONS` | Max number of skills allowed to be fully injected. | `3` |
+| `AUTO_CAPTURE_SKILLS` | Automatically suggest new skills from session history. | `true` |
+
+---
+
+## 5. Temporal Configuration (v11.0.0+)
+
+Control reasoning snapshot retention for the Temporal Steering system.
+
+| Key | Description | Default |
+| :--- | :--- | :--- |
+| `temporal.max_snapshots` | Maximum number of reasoning snapshots retained per session. | `50` |
+| `temporal.max_age_days` | Snapshots older than this value (in days) are auto-pruned. | `30` |
+
+---
+
+## 6. Rate Limiting (v11.0.0+)
+
+Configure request rate limits for the dashboard and API endpoints.
+
+| Key | Description | Default |
+| :--- | :--- | :--- |
+| `rate_limiting.dashboard_rpm` | Maximum requests per minute to dashboard endpoints. | `120` |
+
+---
+
+## 7. Session Configuration (v11.0.0+)
+
+Control session token behaviour for dashboard authentication.
+
+| Key | Description | Default |
+| :--- | :--- | :--- |
+| `session.token_expiry_hours` | Hours before a dashboard bearer token expires. | `24` |
+
+---
+
+## 8. Wave Execution (v11.0.0+)
+
+Tune parallel wave execution behaviour.
+
+| Key | Description | Default |
+| :--- | :--- | :--- |
+| `wave_execution.max_concurrency` | Maximum number of tasks executed in parallel within a wave. | `6` |
+
+---
+
+## 9. Non-Overridable Governance
+
+To ensure enterprise safety, several rules **cannot** be disabled via `MINDFORGE.md`:
+
+1. **Security Auto-Trigger:** Any change touching PII/Auth/Payments *will* trigger a security review.
+2. **Plan-First Rule:** Every implementation task *must* have a signed-off plan.
+3. **Secret Detection:** Commits containing detected secrets will always be blocked.
+4. **Audit Writing:** All significant framework actions *will* be recorded to `.planning/AUDIT.jsonl`.
+5. **Critical Security Blocks:** High/Critical findings *will* block the `SHIP` command.
+
+> [!WARNING]
+> Attempting to disable these rules in your configuration will result in a silent enforcement of the defaults. See [ADR-013](../adr/ADR-013-immutable-governance.md) for architectural details.

package/docs/References/continuation-format.md

@@ -0,0 +1,249 @@
+# Continuation Format
+
+Standard format for presenting next steps after completing a command or workflow.
+
+## Core Structure
+
+```
+---
+
+## ▶ Next Up
+
+**{identifier}: {name}** — {one-line description}
+
+`{command to copy-paste}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `{alternative option 1}` — description
+- `{alternative option 2}` — description
+
+---
+```
+
+## Format Rules
+
+1. **Always show what it is** — name + description, never just a command path
+2. **Pull context from source** — ROADMAP.md for phases, PLAN.md `<objective>` for plans
+3. **Command in inline code** — backticks, easy to copy-paste, renders as clickable link
+4. **`/clear` explanation** — always include, keeps it concise but explains why
+5. **"Also available" not "Other options"** — sounds more app-like
+6. **Visual separators** — `---` above and below to make it stand out
+
+## Variants
+
+### Execute Next Plan
+
+```
+---
+
+## ▶ Next Up
+
+**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
+
+`/mindforge-execute-phase 2`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- Review plan before executing
+- `/mindforge-list-phase-assumptions 2` — check assumptions
+
+---
+```
+
+### Execute Final Plan in Phase
+
+Add note that this is the last plan and what comes after:
+
+```
+---
+
+## ▶ Next Up
+
+**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
+<sub>Final plan in Phase 2</sub>
+
+`/mindforge-execute-phase 2`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**After this completes:**
+- Phase 2 → Phase 3 transition
+- Next: **Phase 3: Core Features** — User dashboard and settings
+
+---
+```
+
+### Plan a Phase
+
+```
+---
+
+## ▶ Next Up
+
+**Phase 2: Authentication** — JWT login flow with refresh tokens
+
+`/mindforge-plan-phase 2`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/mindforge-discuss-phase 2` — gather context first
+- `/mindforge-research-phase 2` — investigate unknowns
+- Review roadmap
+
+---
+```
+
+### Phase Complete, Ready for Next
+
+Show completion status before next action:
+
+```
+---
+
+## ✓ Phase 2 Complete
+
+3/3 plans executed
+
+## ▶ Next Up
+
+**Phase 3: Core Features** — User dashboard, settings, and data export
+
+`/mindforge-plan-phase 3`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/mindforge-discuss-phase 3` — gather context first
+- `/mindforge-research-phase 3` — investigate unknowns
+- Review what Phase 2 built
+
+---
+```
+
+### Multiple Equal Options
+
+When there's no clear primary action:
+
+```
+---
+
+## ▶ Next Up
+
+**Phase 3: Core Features** — User dashboard, settings, and data export
+
+**To plan directly:** `/mindforge-plan-phase 3`
+
+**To discuss context first:** `/mindforge-discuss-phase 3`
+
+**To research unknowns:** `/mindforge-research-phase 3`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+```
+
+### Milestone Complete
+
+```
+---
+
+## 🎉 Milestone v1.0 Complete
+
+All 4 phases shipped
+
+## ▶ Next Up
+
+**Start v1.1** — questioning → research → requirements → roadmap
+
+`/mindforge-new-milestone`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+```
+
+## Pulling Context
+
+### For phases (from ROADMAP.md):
+
+```markdown
+### Phase 2: Authentication
+**Goal**: JWT login flow with refresh tokens
+```
+
+Extract: `**Phase 2: Authentication** — JWT login flow with refresh tokens`
+
+### For plans (from ROADMAP.md):
+
+```markdown
+Plans:
+- [ ] 02-03: Add refresh token rotation
+```
+
+Or from PLAN.md `<objective>`:
+
+```xml
+<objective>
+Add refresh token rotation with sliding expiry window.
+
+Purpose: Extend session lifetime without compromising security.
+</objective>
+```
+
+Extract: `**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry`
+
+## Anti-Patterns
+
+### Don't: Command-only (no context)
+
+```
+## To Continue
+
+Run `/clear`, then paste:
+/mindforge-execute-phase 2
+```
+
+User has no idea what 02-03 is about.
+
+### Don't: Missing /clear explanation
+
+```
+`/mindforge-plan-phase 3`
+
+Run /clear first.
+```
+
+Doesn't explain why. User might skip it.
+
+### Don't: "Other options" language
+
+```
+Other options:
+- Review roadmap
+```
+
+Sounds like an afterthought. Use "Also available:" instead.
+
+### Don't: Fenced code blocks for commands
+
+```
+```
+/mindforge-plan-phase 3
+```
+```
+
+Fenced blocks inside templates create nesting ambiguity. Use inline backticks instead.

package/docs/References/decimal-phase-calculation.md

@@ -0,0 +1,64 @@
+# Decimal Phase Calculation
+
+Calculate the next decimal phase number for urgent insertions.
+
+## Using mindforge-tools
+
+```bash
+# Get next decimal phase after phase 6
+node ".agent/mindforge/bin/mindforge-tools.cjs" phase next-decimal 6
+```
+
+Output:
+```json
+{
+  "found": true,
+  "base_phase": "06",
+  "next": "06.1",
+  "existing": []
+}
+```
+
+With existing decimals:
+```json
+{
+  "found": true,
+  "base_phase": "06",
+  "next": "06.3",
+  "existing": ["06.1", "06.2"]
+}
+```
+
+## Extract Values
+
+```bash
+DECIMAL_PHASE=$(node ".agent/mindforge/bin/mindforge-tools.cjs" phase next-decimal "${AFTER_PHASE}" --pick next)
+BASE_PHASE=$(node ".agent/mindforge/bin/mindforge-tools.cjs" phase next-decimal "${AFTER_PHASE}" --pick base_phase)
+```
+
+Or with --raw flag:
+```bash
+DECIMAL_PHASE=$(node ".agent/mindforge/bin/mindforge-tools.cjs" phase next-decimal "${AFTER_PHASE}" --raw)
+# Returns just: 06.1
+```
+
+## Examples
+
+| Existing Phases | Next Phase |
+|-----------------|------------|
+| 06 only | 06.1 |
+| 06, 06.1 | 06.2 |
+| 06, 06.1, 06.2 | 06.3 |
+| 06, 06.1, 06.3 (gap) | 06.4 |
+
+## Directory Naming
+
+Decimal phase directories use the full decimal number:
+
+```bash
+SLUG=$(node ".agent/mindforge/bin/mindforge-tools.cjs" generate-slug "$DESCRIPTION" --raw)
+PHASE_DIR=".planning/phases/${DECIMAL_PHASE}-${SLUG}"
+mkdir -p "$PHASE_DIR"
+```
+
+Example: `.planning/phases/06.1-fix-critical-auth-bug/`