mindforge-cc 9.0.0 → 10.0.0

package/docs/References/planning-config.md

@@ -1,202 +0,0 @@
-<planning_config>
-
-Configuration options for `.planning/` directory behavior.
-
-<config_schema>
-```json
-"planning": {
-  "commit_docs": true,
-  "search_gitignored": false
-},
-"git": {
-  "branching_strategy": "none",
-  "phase_branch_template": "mindforge/phase-{phase}-{slug}",
-  "milestone_branch_template": "mindforge/{milestone}-{slug}",
-  "quick_branch_template": null
-}
-```
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `commit_docs` | `true` | Whether to commit planning artifacts to git |
-| `search_gitignored` | `false` | Add `--no-ignore` to broad rg searches |
-| `git.branching_strategy` | `"none"` | Git branching approach: `"none"`, `"phase"`, or `"milestone"` |
-| `git.phase_branch_template` | `"mindforge/phase-{phase}-{slug}"` | Branch template for phase strategy |
-| `git.milestone_branch_template` | `"mindforge/{milestone}-{slug}"` | Branch template for milestone strategy |
-| `git.quick_branch_template` | `null` | Optional branch template for quick-task runs |
-</config_schema>
-
-<commit_docs_behavior>
-
-**When `commit_docs: true` (default):**
-- Planning files committed normally
-- SUMMARY.md, STATE.md, ROADMAP.md tracked in git
-- Full history of planning decisions preserved
-
-**When `commit_docs: false`:**
-- Skip all `git add`/`git commit` for `.planning/` files
-- User must add `.planning/` to `.gitignore`
-- Useful for: OSS contributions, client projects, keeping planning private
-
-**Using mindforge-tools.cjs (preferred):**
-
-```bash
-# Commit with automatic commit_docs + gitignore checks:
-node ".agent/mindforge/bin/mindforge-tools.cjs" commit "docs: update state" --files .planning/STATE.md
-
-# Load config via state load (returns JSON):
-INIT=$(node ".agent/mindforge/bin/mindforge-tools.cjs" state load)
-if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-# commit_docs is available in the JSON output
-
-# Or use init commands which include commit_docs:
-INIT=$(node ".agent/mindforge/bin/mindforge-tools.cjs" init execute-phase "1")
-if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-# commit_docs is included in all init command outputs
-```
-
-**Auto-detection:** If `.planning/` is gitignored, `commit_docs` is automatically `false` regardless of config.json. This prevents git errors when users have `.planning/` in `.gitignore`.
-
-**Commit via CLI (handles checks automatically):**
-
-```bash
-node ".agent/mindforge/bin/mindforge-tools.cjs" commit "docs: update state" --files .planning/STATE.md
-```
-
-The CLI checks `commit_docs` config and gitignore status internally — no manual conditionals needed.
-
-</commit_docs_behavior>
-
-<search_behavior>
-
-**When `search_gitignored: false` (default):**
-- Standard rg behavior (respects .gitignore)
-- Direct path searches work: `rg "pattern" .planning/` finds files
-- Broad searches skip gitignored: `rg "pattern"` skips `.planning/`
-
-**When `search_gitignored: true`:**
-- Add `--no-ignore` to broad rg searches that should include `.planning/`
-- Only needed when searching entire repo and expecting `.planning/` matches
-
-**Note:** Most MindForge operations use direct file reads or explicit paths, which work regardless of gitignore status.
-
-</search_behavior>
-
-<setup_uncommitted_mode>
-
-To use uncommitted mode:
-
-1. **Set config:**
-   ```json
-   "planning": {
-     "commit_docs": false,
-     "search_gitignored": true
-   }
-   ```
-
-2. **Add to .gitignore:**
-   ```
-   .planning/
-   ```
-
-3. **Existing tracked files:** If `.planning/` was previously tracked:
-   ```bash
-   git rm -r --cached .planning/
-   git commit -m "chore: stop tracking planning docs"
-   ```
-
-4. **Branch merges:** When using `branching_strategy: phase` or `milestone`, the `complete-milestone` workflow automatically strips `.planning/` files from staging before merge commits when `commit_docs: false`.
-
-</setup_uncommitted_mode>
-
-<branching_strategy_behavior>
-
-**Branching Strategies:**
-
-| Strategy | When branch created | Branch scope | Merge point |
-|----------|---------------------|--------------|-------------|
-| `none` | Never | N/A | N/A |
-| `phase` | At `execute-phase` start | Single phase | User merges after phase |
-| `milestone` | At first `execute-phase` of milestone | Entire milestone | At `complete-milestone` |
-
-**When `git.branching_strategy: "none"` (default):**
-- All work commits to current branch
-- Standard MindForge behavior
-
-**When `git.branching_strategy: "phase"`:**
-- `execute-phase` creates/switches to a branch before execution
-- Branch name from `phase_branch_template` (e.g., `mindforge/phase-03-authentication`)
-- All plan commits go to that branch
-- User merges branches manually after phase completion
-- `complete-milestone` offers to merge all phase branches
-
-**When `git.branching_strategy: "milestone"`:**
-- First `execute-phase` of milestone creates the milestone branch
-- Branch name from `milestone_branch_template` (e.g., `mindforge/v1.0-mvp`)
-- All phases in milestone commit to same branch
-- `complete-milestone` offers to merge milestone branch to main
-
-**Template variables:**
-
-| Variable | Available in | Description |
-|----------|--------------|-------------|
-| `{phase}` | phase_branch_template | Zero-padded phase number (e.g., "03") |
-| `{slug}` | Both | Lowercase, hyphenated name |
-| `{milestone}` | milestone_branch_template | Milestone version (e.g., "v1.0") |
-
-**Checking the config:**
-
-Use `init execute-phase` which returns all config as JSON:
-```bash
-INIT=$(node ".agent/mindforge/bin/mindforge-tools.cjs" init execute-phase "1")
-if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-# JSON output includes: branching_strategy, phase_branch_template, milestone_branch_template
-```
-
-Or use `state load` for the config values:
-```bash
-INIT=$(node ".agent/mindforge/bin/mindforge-tools.cjs" state load)
-if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-# Parse branching_strategy, phase_branch_template, milestone_branch_template from JSON
-```
-
-**Branch creation:**
-
-```bash
-# For phase strategy
-if [ "$BRANCHING_STRATEGY" = "phase" ]; then
-  PHASE_SLUG=$(echo "$PHASE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
-  BRANCH_NAME=$(echo "$PHASE_BRANCH_TEMPLATE" | sed "s/{phase}/$PADDED_PHASE/g" | sed "s/{slug}/$PHASE_SLUG/g")
-  git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
-fi
-
-# For milestone strategy
-if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
-  MILESTONE_SLUG=$(echo "$MILESTONE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
-  BRANCH_NAME=$(echo "$MILESTONE_BRANCH_TEMPLATE" | sed "s/{milestone}/$MILESTONE_VERSION/g" | sed "s/{slug}/$MILESTONE_SLUG/g")
-  git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
-fi
-```
-
-**Merge options at complete-milestone:**
-
-| Option | Git command | Result |
-|--------|-------------|--------|
-| Squash merge (recommended) | `git merge --squash` | Single clean commit per branch |
-| Merge with history | `git merge --no-ff` | Preserves all individual commits |
-| Delete without merging | `git branch -D` | Discard branch work |
-| Keep branches | (none) | Manual handling later |
-
-Squash merge is recommended — keeps main branch history clean while preserving the full development history in the branch (until deleted).
-
-**Use cases:**
-
-| Strategy | Best for |
-|----------|----------|
-| `none` | Solo development, simple projects |
-| `phase` | Code review per phase, granular rollback, team collaboration |
-| `milestone` | Release branches, staging environments, PR per version |
-
-</branching_strategy_behavior>
-
-</planning_config>

package/docs/References/questioning.md

@@ -1,162 +0,0 @@
-<questioning_guide>
-
-Project initialization is dream extraction, not requirements gathering. You're helping the user discover and articulate what they want to build. This isn't a contract negotiation — it's collaborative thinking.
-
-<philosophy>
-
-**You are a thinking partner, not an interviewer.**
-
-The user often has a fuzzy idea. Your job is to help them sharpen it. Ask questions that make them think "oh, I hadn't considered that" or "yes, that's exactly what I mean."
-
-Don't interrogate. Collaborate. Don't follow a script. Follow the thread.
-
-</philosophy>
-
-<the_goal>
-
-By the end of questioning, you need enough clarity to write a PROJECT.md that downstream phases can act on:
-
-- **Research** needs: what domain to research, what the user already knows, what unknowns exist
-- **Requirements** needs: clear enough vision to scope v1 features
-- **Roadmap** needs: clear enough vision to decompose into phases, what "done" looks like
-- **plan-phase** needs: specific requirements to break into tasks, context for implementation choices
-- **execute-phase** needs: success criteria to verify against, the "why" behind requirements
-
-A vague PROJECT.md forces every downstream phase to guess. The cost compounds.
-
-</the_goal>
-
-<how_to_question>
-
-**Start open.** Let them dump their mental model. Don't interrupt with structure.
-
-**Follow energy.** Whatever they emphasized, dig into that. What excited them? What problem sparked this?
-
-**Challenge vagueness.** Never accept fuzzy answers. "Good" means what? "Users" means who? "Simple" means how?
-
-**Make the abstract concrete.** "Walk me through using this." "What does that actually look like?"
-
-**Clarify ambiguity.** "When you say Z, do you mean A or B?" "You mentioned X — tell me more."
-
-**Know when to stop.** When you understand what they want, why they want it, who it's for, and what done looks like — offer to proceed.
-
-</how_to_question>
-
-<question_types>
-
-Use these as inspiration, not a checklist. Pick what's relevant to the thread.
-
-**Motivation — why this exists:**
-- "What prompted this?"
-- "What are you doing today that this replaces?"
-- "What would you do if this existed?"
-
-**Concreteness — what it actually is:**
-- "Walk me through using this"
-- "You said X — what does that actually look like?"
-- "Give me an example"
-
-**Clarification — what they mean:**
-- "When you say Z, do you mean A or B?"
-- "You mentioned X — tell me more about that"
-
-**Success — how you'll know it's working:**
-- "How will you know this is working?"
-- "What does done look like?"
-
-</question_types>
-
-<using_askuserquestion>
-
-Use AskUserQuestion to help users think by presenting concrete options to react to.
-
-**Good options:**
-- Interpretations of what they might mean
-- Specific examples to confirm or deny
-- Concrete choices that reveal priorities
-
-**Bad options:**
-- Generic categories ("Technical", "Business", "Other")
-- Leading options that presume an answer
-- Too many options (2-4 is ideal)
-- Headers longer than 12 characters (hard limit — validation will reject them)
-
-**Example — vague answer:**
-User says "it should be fast"
-
-- header: "Fast"
-- question: "Fast how?"
-- options: ["Sub-second response", "Handles large datasets", "Quick to build", "Let me explain"]
-
-**Example — following a thread:**
-User mentions "frustrated with current tools"
-
-- header: "Frustration"
-- question: "What specifically frustrates you?"
-- options: ["Too many clicks", "Missing features", "Unreliable", "Let me explain"]
-
-**Tip for users — modifying an option:**
-Users who want a slightly modified version of an option can select "Other" and reference the option by number: `#1 but for finger joints only` or `#2 with pagination disabled`. This avoids retyping the full option text.
-
-</using_askuserquestion>
-
-<freeform_rule>
-
-**When the user wants to explain freely, STOP using AskUserQuestion.**
-
-If a user selects "Other" and their response signals they want to describe something in their own words (e.g., "let me describe it", "I'll explain", "something else", or any open-ended reply that isn't choosing/modifying an existing option), you MUST:
-
-1. **Ask your follow-up as plain text** — NOT via AskUserQuestion
-2. **Wait for them to type at the normal prompt**
-3. **Resume AskUserQuestion** only after processing their freeform response
-
-The same applies if YOU include a freeform-indicating option (like "Let me explain" or "Describe in detail") and the user selects it.
-
-**Wrong:** User says "let me describe it" → AskUserQuestion("What feature?", ["Feature A", "Feature B", "Describe in detail"])
-**Right:** User says "let me describe it" → "Go ahead — what are you thinking?"
-
-</freeform_rule>
-
-<context_checklist>
-
-Use this as a **background checklist**, not a conversation structure. Check these mentally as you go. If gaps remain, weave questions naturally.
-
-- [ ] What they're building (concrete enough to explain to a stranger)
-- [ ] Why it needs to exist (the problem or desire driving it)
-- [ ] Who it's for (even if just themselves)
-- [ ] What "done" looks like (observable outcomes)
-
-Four things. If they volunteer more, capture it.
-
-</context_checklist>
-
-<decision_gate>
-
-When you could write a clear PROJECT.md, offer to proceed:
-
-- header: "Ready?"
-- question: "I think I understand what you're after. Ready to create PROJECT.md?"
-- options:
-  - "Create PROJECT.md" — Let's move forward
-  - "Keep exploring" — I want to share more / ask me more
-
-If "Keep exploring" — ask what they want to add or identify gaps and probe naturally.
-
-Loop until "Create PROJECT.md" selected.
-
-</decision_gate>
-
-<anti_patterns>
-
-- **Checklist walking** — Going through domains regardless of what they said
-- **Canned questions** — "What's your core value?" "What's out of scope?" regardless of context
-- **Corporate speak** — "What are your success criteria?" "Who are your stakeholders?"
-- **Interrogation** — Firing questions without building on answers
-- **Rushing** — Minimizing questions to get to "the work"
-- **Shallow acceptance** — Taking vague answers without probing
-- **Premature constraints** — Asking about tech stack before understanding the idea
-- **User skills** — NEVER ask about user's technical experience. MindForge builds.
-
-</anti_patterns>
-
-</questioning_guide>

package/docs/References/sdk-api.md

@@ -1,53 +0,0 @@
-# MindForge SDK API — Reference (v2.0.0-alpha.4)
-
-## Package
-
-`@mindforge/sdk`
-
-## Exports
-
-From `sdk/src/index.ts`:
-
-- `MindForgeClient`
-- `MindForgeEventStream`
-- `commands`
-- `MindForgeMemory`
-- Types: `MindForgeConfig`, `PhaseResult`, `TaskResult`, `SecurityFinding`,
-  `GateResult`, `HealthReport`, `HealthIssue`, `MindForgeEvent`, `CommandOptions`
-- `VERSION`
-
-## MindForgeClient
-
-High-level API for reading local project state.
-
-Methods:
-- `isInitialised(): boolean`
-- `readState(): object | null`
-- `readHandoff(): object | null`
-- `health(): Promise<HealthReport>`
-- `readAuditLog(filter?): unknown[]`
-- `readSessionMetrics(limit?): unknown[]`
-- `validateConfig(): { valid: boolean, errors: string[], warnings: string[] }`
-
-## MindForgeEventStream
-Localhost-only SSE server for streaming audit events.
-
-Methods:
-- `start(port = 7337)`
-- `watchAuditLog(projectRoot)`
-- `broadcast(eventType, data)`
-- `stop()`
-
-## Command builders
-`commands` provides helpers to build slash-command strings:
-- `health(opts)`
-- `planPhase(phase, opts)`
-- `executePhase(phase, opts)`
-- `securityScan(path?, opts)`
-- `audit(filter)`
-- `prReview(opts)`
-
-## Security notes
-- The SDK reads local files that may contain sensitive data.
-- Event stream binds to `127.0.0.1` only and rejects non-local connections.
-- Do not expose the SSE port on public interfaces.

package/docs/References/skills-api.md

@@ -1,57 +0,0 @@
-# MindForge Skills API — Reference (v1.0.0)
-
-## Overview
-Skills are domain knowledge packs loaded on demand. They are stored as
-`SKILL.md` files with frontmatter and optional assets.
-
-## File structure
-```
-.mindforge/skills/<skill-name>/
-  SKILL.md
-  assets/
-  references/
-```
-
-## SKILL.md schema (frontmatter)
-Required fields:
-- `name`: string (stable in 1.x.x)
-- `description`: string
-- `triggers`: array of keywords
-- `version`: semver string
-- `owner`: string (team or org)
-
-Optional fields:
-- `scope`: `core | org | project`
-- `severity`: `low | medium | high`
-- `links`: array of URLs
-
-Example:
-```yaml
----
-name: security-review
-version: 1.0.0
-description: Secure coding review checklist and threat modeling prompts
-triggers: ["auth", "payment", "pii", "encryption"]
-owner: mindforge-core
-scope: core
----
-```
-
-## Loading rules
-- Skills load only when trigger keywords match the task description
-- At most 3 skills are loaded at full size; others are summarized
-- Skills can be force-loaded via `ALWAYS_LOAD_SKILLS` in `MINDFORGE.md`
-
-## Validation
-`/mindforge:skills validate` enforces:
-- Valid frontmatter
-- No injection patterns in content
-- Required fields present
-
-## Publishing
-Skills can be published to the npm registry under `mindforge-skill-*`.
-See `docs/skills-publishing-guide.md` for full workflow.
-
-## Stability contract
-As of v1.0.0, the `name` values of the 10 core skills are stable. New optional
-fields may be added in minor versions; removals require a major version bump.