feat: V3 MCP-native goal-driven adaptive engine (v0.2.1)

Complete V3 architecture implementation:
- New flowctl-mcp crate: rmcp 0.1.5 MCP server with 16 tool handlers (stdio transport)
- Domain types: Goal (PlanningMode × SuccessModel orthogonal), Node, PlanVersion, Attempt, Escalation
- Storage: 5 goal-scoped stores (GoalStore, PlanStore, AttemptStore, KnowledgeStore, EventStore)
- Engine: GoalEngine (assess_goal mode selection), Planner (RiskProfile), Scheduler (DAG), EscalationEngine (3-level)
- Knowledge: Learner (record/inject/compound/refresh) with word-overlap scoring + confidence weighting
- Quality: PolicyEngine with MCP + Hook adapters for physical enforcement
- Provider: ProviderRegistry with ReviewProvider/PlanningProvider traits + NoneProvider
- CLI: serve, goal, plan-v3, node, knowledge, policy, session, migrate commands
- MCP tools wired: lock→json_store, guard→subprocess, codebase_assess→CodeGraph+NgramIndex
- node.finish records Attempt+Event, releases locks, auto-records learning
- ADR-011, v3-hooks.json (2 hooks), 3 entry skills, project-context.md updated

469 tests passing. Design doc: docs/v3-final-architecture.md

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: z23cc

.flow-config/project-context.md

@@ -0,0 +1,52 @@
+# Project Context
+
+> Shared technical standards for all agents. Auto-loaded by workers during re-anchoring.
+> Focus on what's **unobvious** — things agents can't infer from code alone.
+
+## Technology Stack
+- Language: Rust (edition 2024, MSRV 1.85)
+- Runtime: tokio (async, flowctl-mcp crate ONLY)
+- MCP SDK: rmcp 0.16 (official Rust MCP SDK)
+- DAG: petgraph 0.7
+- Search: NgramIndex (bincode), nucleo-matcher (fuzzy)
+- Storage: JSON/JSONL files in .flow/ (zero external deps, no SQLite)
+- Testing: cargo test + trycmd snapshots
+- Linting: cargo clippy (unsafe_code = forbid)
+
+## Guard Commands
+```yaml
+test: "cd flowctl && cargo test --all"
+lint: "cd flowctl && cargo clippy --all -- -D warnings"
+typecheck: "cd flowctl && cargo build --all"
+format_check: ""
+```
+
+## Critical Implementation Rules
+- CI: GitHub Actions
+- Async boundary: tokio + rmcp are allowed ONLY in `flowctl-mcp` crate. `flowctl-core` MUST remain fully synchronous. MCP crate calls core via `spawn_blocking`.
+- Storage: all state is JSON/JSONL files in `.flow/`. No SQLite, no external database.
+- Architecture: V3 MCP-native goal-driven engine (see docs/v3-final-architecture.md)
+- Pipeline freeze: `pipeline.rs` and `pipeline_phase.rs` are FROZEN — bug fixes only, no new features
+
+## File Conventions
+<!-- Maps domains to file patterns for auto domain assignment -->
+```yaml
+frontend: []
+backend: ["flowctl/crates/"]
+testing: ["scripts/"]
+docs: []
+```
+
+## Architecture Decisions
+- ADR-011: flowctl is MCP-native runtime (see docs/decisions/ADR-011-v3-mcp-native.md)
+- Goal-driven, not pipeline-driven: PlanningMode (Direct/Graph) × SuccessModel (Criteria/Numeric/Mixed)
+- 3-crate workspace: flowctl-core (sync domain+storage+engine), flowctl-mcp (async MCP server), flowctl-cli (thin CLI)
+- PolicyEngine with 2 adapters (MCP internal + PreToolUse hook) for physical enforcement
+- ProviderRegistry with trait abstractions for review/planning backends
+
+## Non-Goals
+- Do not add SQLite or any external database dependency
+- Do not add async/tokio to flowctl-core (only flowctl-mcp)
+- Do not break existing flowctl CLI commands (provide compat shim)
+- Do not modify pipeline.rs or pipeline_phase.rs (FROZEN — bug fixes only)
+- Do not hardcode RP or Codex logic into core engine (use ProviderRegistry traits)

.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "forge_extension": {
+      "url": "http://localhost:13819/mcp"
+    },
+    "flowctl": {
+      "command": "bin/flowctl",
+      "args": ["serve"]
+    }
+  }
+}

bin/flowctl

@@ -0,0 +1,33 @@
+# ADR-011: V3 MCP-Native Goal-Driven Architecture
+
+**Status**: Accepted
+**Date**: 2026-04-11
+**Deciders**: z23cc
+**Supersedes**: V1 pipeline state machine
+
+## Context
+
+flowctl has grown to 90+ CLI commands, 52 skills, 24 agents, and 8 hook points. Control logic is scattered across multiple protocol layers. The 6-phase linear pipeline forces all tasks through the same steps regardless of complexity.
+
+## Decision
+
+Transform flowctl from a CLI-only pipeline tool into an MCP-native goal-driven adaptive engine:
+
+1. **MCP Server**: `flowctl serve` starts an rmcp-based MCP server (stdio transport) exposing 16 structured tools
+2. **Goal Model**: Replace Epic + 6-phase pipeline with Goal + orthogonal PlanningMode (Direct/Graph) × SuccessModel (Criteria/Numeric/Mixed)
+3. **Async Boundary**: tokio + rmcp are confined to `flowctl-mcp` crate. `flowctl-core` remains fully synchronous
+4. **3-Crate Architecture**: flowctl-core (domain+storage+engine), flowctl-mcp (MCP server), flowctl-cli (thin CLI facade)
+5. **Pipeline Freeze**: `pipeline.rs` and `pipeline_phase.rs` receive bug fixes only, no new features
+
+## Consequences
+
+- flowctl binary grows to include MCP server capability
+- First introduction of async runtime (tokio) — strictly confined to flowctl-mcp
+- Existing CLI commands preserved via compat shim layer
+- Old .flow/ data migrated via `flowctl migrate v3`, originals archived to `.flow/.archive/v1/`
+
+## Alternatives Considered
+
+- **Incremental evolution**: Continue adding to pipeline model. Rejected: complexity ceiling already reached.
+- **V3 Draft (merged ExecutionMode)**: Single enum mixing planning and success. Rejected: leads to condition sprawl.
+- **5-crate split**: Premature for ~27K LOC codebase. Defer until core exceeds 20K LOC.