mindforge-cc 10.0.2 → 10.7.0

package/.mindforge/config.json

@@ -1,11 +1,11 @@
 {
-  "version": "10.0.1",
+  "version": "10.7.0",
   "environment": "development",
   "governance": {
     "drift_threshold": 0.75,
     "critical_drift_threshold": 0.5,
     "res_threshold": 0.8,
-    "active_did": "did:mindforge:d623d3ee-0911-4098-b9c8-260ab5824ab5"
+    "active_did": "did:mindforge:5a537f83-69de-40ac-a613-e96d4a84a270"
   },
   "revops": {
     "market_registry": {
@@ -44,6 +44,12 @@
         "cost_output": 0.0004,
         "benchmark": 82,
         "provider": "Anthropic"
+      },
+      "claude-opus-4-7": {
+        "cost_input": 0.015,
+        "cost_output": 0.075,
+        "benchmark": 100,
+        "provider": "Anthropic"
       }
     },
     "default_baseline_model": "claude-sonnet-4-6",
@@ -62,5 +68,70 @@
     "min_success_count": 3,
     "max_drift_threshold": 0.1,
     "auto_verify": false
+  },
+  "instincts": {
+    "mode": "auto-capture",
+    "max_active_per_project": 100,
+    "promotion_confidence_threshold": 0.85,
+    "promotion_min_applications": 5,
+    "prune_below_confidence": 0.2,
+    "prune_after_days_inactive": 30,
+    "max_capture_per_session": 5,
+    "store_path": ".mindforge/engine/instincts/instinct-store.jsonl"
+  },
+  "council": {
+    "voices": [
+      "architect",
+      "skeptic",
+      "pragmatist",
+      "critic"
+    ],
+    "max_rounds": 2,
+    "consensus_threshold": 0.75,
+    "word_limit_per_voice": 200,
+    "output_path": ".planning/decisions/"
+  },
+  "cost_routing": {
+    "enabled": true,
+    "simple_threshold": 3,
+    "standard_threshold": 6,
+    "complex_threshold": 8,
+    "model_tiers": {
+      "simple": "claude-haiku-4-5",
+      "standard": "claude-sonnet-4-6",
+      "complex": "claude-opus-4-7",
+      "research": "gemini-2.5-pro",
+      "consult": "gpt-4o"
+    },
+    "budget": {
+      "session_warn_usd": 5,
+      "session_hard_limit_usd": 20,
+      "project_weekly_warn_usd": 50,
+      "project_weekly_hard_limit_usd": 200
+    },
+    "ledger_path": ".mindforge/metrics/token-ledger.jsonl"
+  },
+  "proactive_suggestions": {
+    "enabled": true,
+    "confidence_threshold": 0.7,
+    "cooldown_seconds": 300,
+    "debounce_seconds": 30,
+    "max_recent": 50,
+    "store_path": ".mindforge/engine/proactive/recent-suggestions.json"
+  },
+  "eval": {
+    "default_k": 5,
+    "evals_path": ".mindforge/evals/",
+    "default_grader": "code"
+  },
+  "quality_audit": {
+    "passing_threshold": 3,
+    "accuracy_blocking_gate": 3,
+    "weights": {
+      "clarity": 0.25,
+      "completeness": 0.25,
+      "accuracy": 0.3,
+      "usefulness": 0.2
+    }
   }
 }

package/.mindforge/engine/autonomous/cross-iteration-bridge.md

@@ -0,0 +1,96 @@
+# Autonomous Engine — Cross-Iteration Bridge
+
+## Purpose
+Provides semantic context bridging across autonomous mode iterations via
+a shared notes file. Complements the structural `HANDOFF.json` (which tracks
+task state) with reasoning context (WHY decisions were made).
+
+## The Problem
+In autonomous mode, each task gets a fresh context window. While HANDOFF.json
+preserves structural state (what tasks remain, what was completed), it loses:
+- Why a particular approach was chosen over alternatives
+- Observations that inform subsequent tasks
+- Warnings discovered during earlier tasks
+- Cross-task patterns that only emerge over multiple iterations
+
+## Solution: SHARED_TASK_NOTES.md
+
+### Location
+`.planning/SHARED_TASK_NOTES.md` — single file, managed by the autonomous engine.
+
+### Format
+```markdown
+# Shared Task Notes (Auto-Managed)
+<!-- Entries are append-only during autonomous execution. Pruned after phase completion. -->
+
+## [2026-05-25T10:30:00Z] Task: implement-auth-middleware
+**Observation:** The existing session store uses Redis, not in-memory. All new auth code must use the Redis client at `src/lib/redis.ts`.
+**Decision:** Chose JWT + Redis session store over pure stateless JWT because existing code already depends on session lookups.
+**Warning:** The Redis connection pool is limited to 10 — avoid opening new connections per request.
+
+## [2026-05-25T10:45:00Z] Task: add-rate-limiting  
+**Observation:** Rate limiting should use the same Redis instance (discovered in previous task).
+**Decision:** Implemented sliding window counter in Redis rather than in-memory Map.
+**Cross-ref:** Auth middleware (previous task) sets `req.userId` which rate limiter needs.
+```
+
+### Entry Schema
+Each entry contains:
+- **Timestamp** — When the note was written
+- **Task** — Which task produced this note
+- **Observation** — Facts discovered (not opinions)
+- **Decision** — Choices made and WHY (the reasoning)
+- **Warning** (optional) — Hazards for future tasks
+- **Cross-ref** (optional) — Dependencies on other tasks
+
+## Lifecycle Rules
+
+### Writing
+- Auto-executor appends an entry after EACH task completion
+- Only write if the task produced non-obvious insights
+- Keep entries under 100 words each (concise, not verbose)
+- Never write secrets, credentials, or full code blocks
+
+### Reading
+- Auto-executor reads SHARED_TASK_NOTES.md at the START of each new task
+- Only the last 20 entries are loaded (FIFO window)
+- Notes inform task execution but do NOT override task specifications
+
+### Pruning
+- After a phase completes: review all notes
+- Notes with lasting value → migrate to knowledge base (`.mindforge/memory/`)
+- Remaining notes → archive to `.planning/history/shared-notes-[phase]-[date].md`
+- Clear SHARED_TASK_NOTES.md for next phase
+
+### Size Limits
+- Maximum entries: 50
+- Maximum total size: 10K tokens
+- When limit is reached: evict oldest entries (FIFO)
+- Evicted entries are NOT archived (they served their purpose)
+
+## Integration with HANDOFF.json
+
+HANDOFF.json tracks WHAT (task state, completion, queue).
+SHARED_TASK_NOTES tracks WHY (reasoning, context, warnings).
+
+Both are read at task start:
+1. Read HANDOFF.json → know what to do next
+2. Read SHARED_TASK_NOTES.md → know what context to carry forward
+3. Execute task with both structural and semantic context
+4. Write HANDOFF.json → update task state
+5. Write SHARED_TASK_NOTES.md → preserve reasoning for next iteration
+
+## When NOT to Write Notes
+
+- Trivial tasks (single-line changes, formatting)
+- Tasks with no cross-task implications
+- Duplicate information already in HANDOFF.json
+- Information derivable from git history
+
+## Failure Recovery
+
+If SHARED_TASK_NOTES.md becomes corrupted or too large:
+1. Archive current file as-is
+2. Create fresh empty file
+3. Log incident in AUDIT
+4. Continue — notes are advisory, not required for execution

package/.mindforge/engine/cost-tracking/budget-enforcer.md

@@ -0,0 +1,68 @@
+# Cost Tracking — Budget Enforcer
+
+## Purpose
+Monitor and enforce token budgets across sessions, preventing runaway costs
+while maintaining quality standards.
+
+## Budget Hierarchy
+
+```
+Organization budget (monthly)
+  └── Project budget (weekly)
+       └── Session budget (per-session)
+            └── Task budget (per-task)
+```
+
+## Default Budgets (configurable in config.json)
+
+| Scope | Default | Hard Limit |
+|-------|---------|-----------|
+| Session | $5.00 | $20.00 |
+| Task | $1.00 | $5.00 |
+| Project (weekly) | $50.00 | $200.00 |
+
+## Enforcement Rules
+
+### Pre-Task Check
+Before each task starts:
+1. Estimate tokens required (based on task type + file count)
+2. Compare estimate against remaining budget at all levels
+3. If estimate > remaining at ANY level: warn user with breakdown
+4. If hard limit reached at ANY level: block execution, require override
+
+### During-Task Monitoring
+- Track actual tokens consumed per model call
+- Running total visible via `/mindforge:cost-report`
+- If task exceeds its estimate by 2x: pause and report
+
+### Post-Task Accounting
+After each task completes:
+1. Record actual tokens: input, output, cached, by model
+2. Update all budget levels (session, project)
+3. Compare actual vs estimated (for future estimation accuracy)
+
+## Token Counting
+
+For each model interaction, record:
+```json
+{
+  "timestamp": "ISO-8601",
+  "task_id": "task-uuid",
+  "model": "claude-sonnet-4-6",
+  "tokens_input": 12500,
+  "tokens_output": 3200,
+  "tokens_cached": 8000,
+  "estimated_cost_usd": 0.085,
+  "routing_tier": "standard",
+  "routing_reason": "difficulty_score_5"
+}
+```
+
+## Optimization Recommendations
+
+The enforcer generates recommendations when patterns indicate waste:
+- "Task X used opus but produced a simple edit → suggest standard tier"
+- "80% of tokens were re-sent context → suggest compaction"
+- "3 consecutive tasks hit the same files → suggest batching"
+
+These appear in `/mindforge:cost-report` output.

package/.mindforge/engine/cost-tracking/router.md

@@ -0,0 +1,58 @@
+# Cost Tracking — Model Router
+
+## Purpose
+Select the optimal model for each task based on complexity scoring, token budget,
+and cost-performance tradeoffs. Routes tasks to the cheapest model that can handle them.
+
+## Model Tiers
+
+| Tier | Model | Cost/1M tokens (est.) | Use When |
+|------|-------|----------------------|----------|
+| simple | claude-haiku-4-5 | $0.25/$1.25 | Single-file edits, formatting, simple lookups, file reads |
+| standard | claude-sonnet-4-6 | $3/$15 | Multi-file implementation, code review, 90% of daily tasks |
+| complex | claude-opus-4-7 | $15/$75 | Architecture decisions, security audits, debugging hard problems |
+| research | gemini-2.5-pro | ~$1.25/$10 | External research, web search synthesis, long-context analysis |
+| consult | gpt-4o | ~$2.50/$10 | Second opinions, alternative perspectives, validation |
+
+## Routing Decision Matrix
+
+The router uses the difficulty score from `.mindforge/intelligence/difficulty-scorer.md`:
+
+| Difficulty Score | Files Touched | Recommended Tier |
+|-----------------|---------------|-----------------|
+| 1-3 | 1 file | simple |
+| 3-6 | 1-3 files | standard |
+| 6-8 | 3-7 files | complex |
+| 8-10 | 7+ files OR architectural | complex |
+| Any (research needed) | N/A | research |
+
+## Override Rules
+
+These always override the matrix:
+- Security-sensitive tasks (auth/payment/PII): minimum **standard** tier
+- Architectural decisions (ADRs, new systems): minimum **complex** tier  
+- Simple file reads/exploration: always **simple** tier regardless of score
+- Multi-LLM consult requests: use **consult** + **research** tiers
+
+## Routing Protocol
+
+1. Receive task description and file list
+2. Run difficulty scorer → get score 1-10
+3. Map score to tier via decision matrix
+4. Apply override rules
+5. Check budget: if remaining budget < estimated cost, downgrade one tier with WARNING
+6. Log routing decision to token-ledger.jsonl
+7. Return selected model ID
+
+## Budget Guard
+
+If the session's cumulative cost exceeds thresholds from MINDFORGE.md:
+- `[COST_WARN_USD]` → Log warning, continue
+- `[COST_HARD_LIMIT_USD]` → HALT, require user confirmation to continue
+
+## Downgrade Protocol
+
+When budget is tight but task is critical:
+1. Attempt at lower tier first (standard instead of complex)
+2. If result quality is insufficient (verification fails): escalate to correct tier
+3. Log the escalation with reason in AUDIT

package/.mindforge/engine/cost-tracking/token-ledger.md

@@ -0,0 +1,77 @@
+# Cost Tracking — Token Ledger Specification
+
+## Purpose
+Append-only ledger recording all token usage for analytics, budgeting, and optimization.
+
+## Storage
+
+- Location: `.mindforge/metrics/token-ledger.jsonl`
+- Format: JSON Lines (one entry per model interaction)
+- Rotation: Archive entries older than 30 days to `.mindforge/metrics/archive/`
+- Retention: Archives kept for 90 days, then deleted
+
+## Entry Format
+
+Each line in the ledger is a complete JSON object:
+
+```json
+{
+  "id": "txn-[uuid]",
+  "timestamp": "2026-05-25T10:30:00Z",
+  "session_id": "session-abc123",
+  "task_id": "task-def456",
+  "phase": "execute",
+  "model": "claude-sonnet-4-6",
+  "tier": "standard",
+  "routing_reason": "difficulty_score_5_multi_file",
+  "tokens": {
+    "input": 12500,
+    "output": 3200,
+    "cached_input": 8000,
+    "total": 15700
+  },
+  "cost_usd": 0.085,
+  "budget_remaining": {
+    "session": 4.915,
+    "project_weekly": 49.915
+  },
+  "task_type": "implementation",
+  "files_touched": 3,
+  "skills_loaded": ["code-quality", "testing-standards"],
+  "outcome": "success"
+}
+```
+
+## Reporting Queries
+
+The `/mindforge:cost-report` command reads this ledger to produce:
+
+### By Model
+```
+Model           | Calls | Tokens    | Cost    | % of Total
+----------------|-------|-----------|---------|----------
+claude-sonnet   | 45    | 580,000   | $4.50   | 62%
+claude-opus     | 8     | 210,000   | $8.25   | 28%
+claude-haiku    | 120   | 350,000   | $0.75   | 10%
+```
+
+### By Task Type
+```
+Type            | Avg Cost | Avg Tokens | Count
+----------------|----------|------------|------
+implementation  | $0.42    | 18,500     | 23
+code-review     | $0.15    | 8,200      | 15
+debugging       | $0.85    | 32,000     | 8
+```
+
+### Efficiency Metrics
+- Cache hit rate: % of input tokens served from cache
+- Routing accuracy: % of tasks where tier matched actual complexity
+- Over-spend rate: % of tasks that exceeded their estimated budget
+
+## Integration
+
+- Written to by the budget-enforcer after every model interaction
+- Read by `/mindforge:cost-report` command
+- Summarized weekly into `.mindforge/metrics/weekly-cost-summary.json`
+- Referenced by AgRevOps dashboard for ROI tracking

package/.mindforge/engine/council/council-protocol.md

@@ -0,0 +1,96 @@
+# Council Framework — Decision Protocol
+
+## Purpose
+A structured multi-voice decision harness for resolving ambiguous architectural
+decisions. Four specialist voices debate from different perspectives, producing
+a verdict with confidence scoring and documented dissent.
+
+## When to Invoke Council
+
+Council is appropriate when:
+- Multiple valid approaches exist with non-obvious tradeoffs
+- The decision affects system architecture (new systems, breaking changes)
+- Team members (or prior sessions) have expressed conflicting preferences
+- The Adversarial Decision Loop (ADS) produces a split verdict
+- Tier 3 security escalations require multi-perspective review
+
+Council is NOT appropriate for:
+- Simple implementation choices with one obvious answer
+- Bug fixes with clear root causes
+- Tasks where the user has already made the decision
+
+## The Four Voices
+
+| Voice | Persona | Perspective | Bias (intentional) |
+|-------|---------|-------------|-------------------|
+| Architect | council-architect | System design, scalability, long-term | Favors elegant, extensible solutions |
+| Skeptic | council-skeptic | Adversarial, edge cases, failure modes | Favors caution, surfaces hidden risks |
+| Pragmatist | council-pragmatist | Delivery, time-to-value, incremental | Favors shipping, "good enough" |
+| Critic | council-critic | Quality, craftsmanship, standards | Favors excellence, refuses shortcuts |
+
+## Protocol Steps
+
+### Step 1 — Frame the Decision
+Present the decision to all four voices with:
+- Context: what prompted this decision
+- Options: the 2-4 approaches being considered
+- Constraints: deadlines, budget, team capacity, existing tech debt
+- Stakes: what happens if we get this wrong
+
+### Step 2 — Individual Positions (parallel)
+Each voice independently analyzes and states:
+- Their recommended option
+- Their top 3 reasons (from their perspective)
+- Their biggest concern with the other options
+- Confidence in their position (0.0-1.0)
+
+### Step 3 — Challenge Round
+Each voice responds to the strongest counterargument against their position:
+- Acknowledge valid concerns
+- Rebut where possible
+- Adjust confidence if swayed
+
+### Step 4 — Synthesis
+The synthesis engine (see `synthesis-engine.md`) produces:
+- Final verdict (the recommended option)
+- Consensus score (0.0-1.0)
+- Key factors that decided it
+- Documented dissent (any voice that disagrees with confidence > 0.6)
+- Risk register (concerns raised by Skeptic that remain unmitigated)
+
+### Step 5 — Output
+Write to `.planning/decisions/COUNCIL-[timestamp].md`:
+```markdown
+# Council Decision: [Title]
+Date: [timestamp]
+Consensus: [score]
+
+## Verdict
+[The recommended approach in 2-3 sentences]
+
+## Positions
+| Voice | Recommendation | Confidence | Aligned with Verdict? |
+...
+
+## Key Deciding Factors
+1. ...
+2. ...
+3. ...
+
+## Dissent
+[Any voice that disagreed, with their reasoning]
+
+## Risk Register
+[Unmitigated concerns from the Skeptic]
+
+## Action Items
+[Concrete next steps based on the verdict]
+```
+
+## Guardrails
+
+- Council is advisory — the user ALWAYS has final say (User Sovereignty principle)
+- If consensus < 0.5: report "No consensus reached" and present all positions equally
+- Council never auto-executes decisions; it only recommends
+- Maximum 2 rounds (initial + challenge); no infinite debates
+- Each voice is limited to 200 words per round

package/.mindforge/engine/council/council-templates.md

@@ -0,0 +1,85 @@
+# Council Framework — Reusable Templates
+
+## Purpose
+Pre-configured council invocations for common decision types. Each template
+adjusts the framing and weight of voices for the specific domain.
+
+## Template: Architecture Decision
+
+**Trigger:** New system design, major refactor, technology choice
+**Voice weights:** Architect (1.2x), Skeptic (1.0x), Pragmatist (0.9x), Critic (0.9x)
+
+**Framing prompt:**
+> We need to decide on [DECISION]. This affects the system's [scalability/maintainability/performance].
+> Current constraints: [CONSTRAINTS].
+> Options under consideration: [OPTIONS].
+> The decision is hard to reverse because: [IRREVERSIBILITY FACTORS].
+
+---
+
+## Template: Breaking Change
+
+**Trigger:** API change, schema migration, dependency upgrade
+**Voice weights:** Skeptic (1.3x), Pragmatist (1.1x), Architect (0.8x), Critic (0.8x)
+
+**Framing prompt:**
+> We're considering a breaking change: [CHANGE].
+> Affected consumers: [WHO].
+> Migration path: [HOW].
+> Timeline pressure: [WHEN].
+> What could go wrong and is it worth the risk?
+
+---
+
+## Template: Security Escalation
+
+**Trigger:** Tier 3 security finding, compliance concern
+**Voice weights:** Skeptic (1.4x), Critic (1.2x), Architect (0.8x), Pragmatist (0.6x)
+
+**Framing prompt:**
+> Security concern identified: [FINDING].
+> Severity: [LEVEL]. Exploitability: [EASE].
+> Current mitigation: [IF ANY].
+> Options: [FIX OPTIONS WITH EFFORT ESTIMATES].
+> User data at risk: [YES/NO + SCOPE].
+
+---
+
+## Template: Ship-or-Wait
+
+**Trigger:** Feature complete but uncertain quality, deadline pressure
+**Voice weights:** Pragmatist (1.3x), Critic (1.2x), Skeptic (1.0x), Architect (0.5x)
+
+**Framing prompt:**
+> Feature [NAME] is at [COMPLETION%]. Deadline is [DATE].
+> Known issues: [ISSUES].
+> Test coverage: [COVERAGE%].
+> User impact of delay: [IMPACT].
+> Should we ship now with known issues, or delay for quality?
+
+---
+
+## Template: Build-vs-Buy
+
+**Trigger:** Evaluating third-party dependencies, SaaS vs self-hosted
+**Voice weights:** Pragmatist (1.2x), Architect (1.1x), Skeptic (1.0x), Critic (0.7x)
+
+**Framing prompt:**
+> We need [CAPABILITY]. Options:
+> Build: [EFFORT ESTIMATE, MAINTENANCE COST]
+> Buy: [COST, VENDOR LOCK-IN RISK, FEATURE GAPS]
+> Current team capacity: [AVAILABLE BANDWIDTH]
+> Strategic importance of owning this: [LOW/MEDIUM/HIGH]
+
+---
+
+## Using Templates
+
+Templates are invoked by the `/mindforge:council` command:
+```
+/mindforge:council --template architecture "Should we use PostgreSQL or DynamoDB?"
+/mindforge:council --template breaking-change "Removing the v1 API"
+/mindforge:council --template security "SQL injection in user search"
+```
+
+If no template is specified, the command uses the generic protocol from `council-protocol.md`.

package/.mindforge/engine/council/synthesis-engine.md

@@ -0,0 +1,71 @@
+# Council Framework — Synthesis Engine
+
+## Purpose
+Merge four independent council voices into a single coherent verdict with
+confidence scoring, documented dissent, and actionable output.
+
+## Synthesis Algorithm
+
+### Input
+Four voice outputs, each containing:
+- recommended_option: string
+- reasons: string[3]
+- concerns_with_others: string[]
+- confidence: float (0.0-1.0)
+- post_challenge_confidence: float (after challenge round)
+
+### Step 1 — Vote Counting
+```
+For each option:
+  weighted_votes = sum(voice.confidence for voice if voice.recommended_option == option)
+  
+winner = option with highest weighted_votes
+```
+
+### Step 2 — Consensus Scoring
+```
+consensus = weighted_votes_for_winner / sum(all_confidences)
+
+Interpretation:
+  >= 0.85: Strong consensus (proceed with confidence)
+  0.65-0.84: Moderate consensus (proceed but monitor risks)
+  0.50-0.64: Weak consensus (consider user input)
+  < 0.50: No consensus (present all options, defer to user)
+```
+
+### Step 3 — Dissent Identification
+A voice is marked as dissenting if:
+- They did NOT vote for the winning option AND
+- Their post-challenge confidence remains > 0.6
+
+Dissenting voices have their full reasoning preserved in the output.
+
+### Step 4 — Risk Extraction
+From the Skeptic voice (regardless of their vote):
+- Extract all concerns rated "high" or "critical"
+- These become the Risk Register
+- Each risk must have a proposed mitigation or be flagged as unmitigated
+
+### Step 5 — Factor Identification
+Identify the top 3 deciding factors by:
+1. Finding reasons that appear in 2+ voices' reasoning
+2. Finding reasons from the winning voices with highest confidence
+3. Prioritizing reasons that address the Skeptic's concerns
+
+## Edge Cases
+
+### Tie (2v2 split)
+- If exactly 2 voices choose each option: report "Split verdict"
+- Present both options with their respective advocates
+- Recommend the option favored by Architect (as tiebreaker for technical decisions)
+- Flag for user decision
+
+### Single Dissenter with Very High Confidence
+- If one voice has confidence > 0.9 while disagreeing with the majority:
+- Include a "Strong Dissent Warning" in the output
+- The dissenter's concerns get elevated visibility
+
+### All Agree (4-0)
+- Consensus = 1.0
+- Still include the Skeptic's concerns (they may have low-confidence risks)
+- Fast-path: skip challenge round if all initial confidences > 0.8