@dv.nghiem/flowdeck 0.3.9 → 0.4.0

package/docs/configuration.md

@@ -1,325 +0,0 @@
-# Configuration
-
-FlowDeck has two levels of configuration: the global OpenCode config (`opencode.json`) and the per-project config (`.planning/config.json`). This document covers both, plus environment variables and the plugin tools that FlowDeck exposes to every OpenCode session.
-
----
-
-## opencode.json
-
-OpenCode reads `~/.config/opencode/opencode.json` at startup. FlowDeck requires one entry in the `plugin` array and supports optional entries in `instructions` to load rule files.
-
-### Minimal configuration
-
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": ["@dv.nghiem/flowdeck"]
-}
-```
-
-The `plugin` entry is written automatically by the FlowDeck installer. If it is missing, agents, skills, and commands will not load.
-
-### Full configuration with rules
-
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": ["@dv.nghiem/flowdeck"],
-  "instructions": [
-    ".planning/PROJECT.md",
-    "flowdeck-rules/common/coding-style.md",
-    "flowdeck-rules/typescript/patterns.md"
-  ]
-}
-```
-
-Files listed under `instructions` are injected into every agent's context at session start. Use this to load project context and language-specific coding standards automatically.
-
----
-
-## Using Language Rules
-
-FlowDeck installs rule files under the npm package cache path:
-
-```
-~/.cache/opencode/packages/@dv.nghiem/flowdeck@latest/rules/
-```
-
-To activate rules, reference them by their path in the `instructions` array. Examples for each supported language:
-
-**TypeScript**
-```json
-"instructions": [
-  "flowdeck-rules/common/coding-style.md",
-  "flowdeck-rules/common/security.md",
-  "flowdeck-rules/common/testing.md",
-  "flowdeck-rules/typescript/patterns.md"
-]
-```
-
-**Python**
-```json
-"instructions": [
-  "flowdeck-rules/common/coding-style.md",
-  "flowdeck-rules/common/testing.md",
-  "flowdeck-rules/python/patterns.md"
-]
-```
-
-**Go**
-```json
-"instructions": [
-  "flowdeck-rules/common/coding-style.md",
-  "flowdeck-rules/common/git-workflow.md",
-  "flowdeck-rules/golang/patterns.md"
-]
-```
-
-**Java**
-```json
-"instructions": [
-  "flowdeck-rules/common/coding-style.md",
-  "flowdeck-rules/common/security.md",
-  "flowdeck-rules/java/patterns.md"
-]
-```
-
-**Rust**
-```json
-"instructions": [
-  "flowdeck-rules/common/coding-style.md",
-  "flowdeck-rules/rust/patterns.md"
-]
-```
-
-**Common rules (all projects)**
-
-| File | Purpose |
-|------|---------|
-| `flowdeck-rules/common/coding-style.md` | Formatting, naming conventions, comment standards |
-| `flowdeck-rules/common/testing.md` | Test structure, coverage targets, assertion patterns |
-| `flowdeck-rules/common/security.md` | Input validation, secrets handling, OWASP reminders |
-| `flowdeck-rules/common/git-workflow.md` | Branching strategy, commit message format, PR workflow |
-| `flowdeck-rules/common/agent-orchestration.md` | How agents hand off context and coordinate work |
-
----
-
-## Project Config (.planning/config.json)
-
-Each FlowDeck project stores its settings in `.planning/config.json`. This file is created by `/fd-new-project` and updated by `/fd-settings`.
-
-### Full schema
-
-```json
-{
-  "project_name": "MyApp",
-  "workspace_mode": "single",
-  "active_phase": 1,
-  "plan_confirmed": false,
-  "enforce_guardrails": true,
-  "sub_repos": [
-    {
-      "name": "user-service",
-      "path": "../user-service",
-      "role": "upstream-api",
-      "tech_stack": "node+typescript",
-      "owner_team": "platform"
-    }
-  ]
-}
-```
-
-### Field reference
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `project_name` | string | Human-readable name shown in `/fd-dashboard` and state files |
-| `workspace_mode` | `"single"` \| `"multi"` | `"single"` for one repo; `"multi"` enables the multi-repo coordinator |
-| `active_phase` | integer | The current phase number. `@orchestrator` reads this to determine which plan to execute |
-| `plan_confirmed` | boolean | Set to `true` when you type `CONFIRMED` after `/fd-plan`. Guards against unreviewed execution |
-| `enforce_guardrails` | boolean | When `true`, the `@plan-checker` must approve a plan before `@orchestrator` runs it |
-| `sub_repos` | array | List of additional repositories involved in this project (multi-repo mode only) |
-| `sub_repos[].name` | string | Short identifier used in cross-repo task delegation |
-| `sub_repos[].path` | string | Relative or absolute path to the repository on disk |
-| `sub_repos[].role` | string | Describes the relationship: `"upstream-api"`, `"downstream-consumer"`, `"shared-lib"`, etc. |
-| `sub_repos[].tech_stack` | string | Primary language and framework, used by `@multi-repo-coordinator` for context |
-| `sub_repos[].owner_team` | string | Informational — used in planning notes and review assignments |
-
----
-
-## flowdeck.json (Agent and Governance Config)
-
-The `flowdeck.json` file controls two things: per-agent model overrides and the governance layer. **No model is hardcoded** — if an agent is not listed, it uses whatever model is currently selected in OpenCode.
-
-### Locations
-
-| Scope | Path |
-|-------|------|
-| Global | `~/.config/opencode/flowdeck.json` |
-| Project | `<project>/.opencode/flowdeck.json` |
-
-Project config takes precedence over global config.
-
-### Full schema
-
-```json
-{
-  "agents": {
-    "<agent-name>": {
-      "model": "<provider>/<model-id>"
-    }
-  },
-  "designFirst": {
-    "enabled": true,
-    "enforcement": "strict",
-    "requireApprovalBeforeImplementation": true,
-    "modelOverrides": {
-      "design": "anthropic/claude-sonnet-4"
-    },
-    "defaultSkillsByTaskType": {
-      "landing-page": ["landing-page-design", "wireframe-planning", "design-system-definition", "frontend-handoff"]
-    }
-  },
-  "governance": {
-    "validator": {
-      "mode": "advisory"
-    },
-    "delegationBudget": {
-      "maxToolCalls": 200,
-      "maxDelegatedAgents": 30,
-      "maxRetries": 10,
-      "maxDepth": 8,
-      "maxSameStepRetries": 3
-    },
-    "deadlockDetection": {
-      "enabled": true,
-      "bounceThreshold": 3,
-      "stageStallMinutes": 30,
-      "autoStop": false
-    },
-    "scorecard": {
-      "enabled": true
-    }
-  }
-}
-```
-
-### Agent model overrides
-
-All agents default to the model currently selected in OpenCode. Only list agents you want to override:
-
-```json
-{
-  "agents": {
-    "planner":      { "model": "anthropic/claude-opus-4" },
-    "orchestrator": { "model": "anthropic/claude-sonnet-4" },
-    "tester":       { "model": "openai/gpt-4o-mini" },
-    "reviewer":     { "model": "google/gemini-2.5-flash" }
-  }
-}
-```
-
-Model strings must use the format `provider/model-id`. Common examples:
-
-| Provider | Example model string |
-|----------|---------------------|
-| Anthropic | `anthropic/claude-opus-4`, `anthropic/claude-sonnet-4`, `anthropic/claude-haiku-4` |
-| OpenAI | `openai/gpt-4o`, `openai/gpt-4o-mini` |
-| Google | `google/gemini-2.5-flash`, `google/gemini-2.5-pro` |
-| GitHub Copilot | `github-copilot/sonnet-4.6` |
-| Minimax | `minimax/minimax-m2.7-highspeed` |
-
-Agents with no entry in `agents` inherit the session model selected in OpenCode's model picker.
-
-### Governance config
-
-| Field | Default | Description |
-|-------|---------|-------------|
-| `governance.validator.mode` | `"advisory"` | `"off"` — disabled; `"advisory"` — warn but never block; `"strict"` — block on contract violations |
-| `governance.delegationBudget.maxToolCalls` | `200` | Total tool calls allowed per workflow run before escalation |
-| `governance.delegationBudget.maxDelegatedAgents` | `30` | Maximum number of sub-agent delegations per run |
-| `governance.delegationBudget.maxRetries` | `10` | Total retries allowed across all steps |
-| `governance.delegationBudget.maxDepth` | `8` | Maximum delegation nesting depth |
-| `governance.delegationBudget.maxSameStepRetries` | `3` | Retries allowed on a single failing step before escalation |
-| `governance.deadlockDetection.enabled` | `true` | Enable deadlock and loop detection |
-| `governance.deadlockDetection.bounceThreshold` | `3` | Agent-pair invocations before bounce is flagged |
-| `governance.deadlockDetection.stageStallMinutes` | `30` | Minutes without stage progress before stall is flagged |
-| `governance.deadlockDetection.autoStop` | `false` | Stop automatically on detection; `false` emits warning only |
-| `governance.scorecard.enabled` | `true` | Generate a quality scorecard after every run |
-
-### Design-first defaults
-
-- `designFirst.enabled`: defaults to `true`
-- `designFirst.enforcement`: defaults to `strict` (`advisory` supported)
-- `designFirst.requireApprovalBeforeImplementation`: defaults to `true`
-- UI-heavy tasks are blocked from implementation until design handoff is approved, unless explicit override is recorded.
-
----
-
-## Settings Command
-
-To view or modify project configuration interactively, run inside an OpenCode session:
-
-```
-/fd-settings
-```
-
-`/fd-settings` displays the current values from `.planning/config.json`, lists active model assignments for each agent, and presents options to:
-
-- Switch `workspace_mode` between `single` and `multi`
-- Change the `active_phase`
-- Toggle `enforce_guardrails`
-- Register or remove sub-repos
-- Run `/fd-doctor` to verify environment health
-
-Changes are written back to `.planning/config.json` immediately.
-
----
-
-## Built-in MCP Servers
-
-FlowDeck automatically registers three free, read-only remote Model Context Protocol (MCP) servers to give your agents extended capabilities:
-
-| MCP | Endpoint | Purpose |
-|---|---|---|
-| **Context7** | `mcp.context7.com/mcp` | Fast library and API documentation lookup |
-| **Exa Websearch** | `mcp.exa.ai/mcp` | General web search capabilities |
-| **Grep.app** | `mcp.grep.app` | Global code search across open-source repositories |
-
-These are enabled by default. If you have API keys (e.g., `CONTEXT7_API_KEY`, `EXA_API_KEY`), FlowDeck will automatically inject them. To disable any of these, use the `FLOWDECK_DISABLE_MCP` environment variable (e.g., `FLOWDECK_DISABLE_MCP=context7,websearch`).
-
----
-
-## Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `OPENCODE_CONFIG_DIR` | `~/.config/opencode` | Override the directory where FlowDeck looks for agents, skills, and commands |
-| `XDG_CONFIG_HOME` | `~/.config` | Standard XDG base directory; used to resolve `OPENCODE_CONFIG_DIR` when not explicitly set |
-| `FLOWDECK_CONTEXT_LIMIT` | `200000` | Token limit used by the Context Window Monitor to warn when context usage exceeds 70% |
-| `FLOWDECK_DISABLE_MCP` | (empty) | Comma-separated list of remote MCPs to disable. Valid options: `context7`, `websearch`, `grep_app` |
-| `FLOWDECK_ORCHESTRATOR_GUARD` | `off` | Enable the orchestrator guard hook. When `on`, the orchestrator session cannot use write/bash tools directly and must delegate all implementation work. |
-| `FLOWDECK_PATCH_TRUST_HIGH_RISK_ENABLED` | `off` | Enable blocking of high-risk AI-generated edits (score < 40). When `true` or `1`, the patch trust hook blocks edits flagged as high-risk. When `false`, `0`, or unset (default), high-risk edits are allowed without blocking. |
-| `FLOWDECK_GUARD_RAILS_ENABLED` | `off` | Enable the guard rails hook. When `on`, write/edit tools are warned/blocked based on plan confirmation state, .codebase/ existence, and execution mode. |
-| `FLOWDECK_TOOL_GUARD_ENABLED` | `off` | Enable the tool guard hook. When `on`, blocks dangerous bash commands (rm -rf), access to secret files (.env, .pem, .key), writes to node_modules, arch-constraint violations, and premature phase writes. |
-| `FLOWDECK_APPROVAL_HOOK_ENABLED` | `off` | Enable the approval hook. When `on`, blocks write/edit on sensitive files (auth/payment/secrets/infra) unless a recent approval exists. |
-| `TELEMETRY_ENABLED` | `false` | Enable telemetry events from hooks. When `true`, events are written to `.codebase/TELEMETRY.jsonl`. |
-
----
-
-## FlowDeck Plugin Tools
-
-When the `@dv.nghiem/flowdeck` plugin is loaded, six tools become available to every agent in your OpenCode session. You do not need to invoke these directly — they are used automatically by FlowDeck agents and workflows.
-
-| `planning-state` | Read and write `.planning/` state files (`STATE.md`, `PLAN.md`, `DISCUSS.md`, `config.json`). Used by every agent that needs project context. |
-| `codebase-state` | Read `.codebase/` documentation files generated by `@mapper`. Gives agents access to `STACK.md`, `ARCHITECTURE.md`, and `CONVENTIONS.md`. |
-| `workspace-state` | Read workspace and multi-repo metadata. Returns the current project config, sub-repo list, and active phase. |
-| `run-pipeline` | Execute a sequence of agent tasks in strict order, passing each step's output as input to the next. Used by `@orchestrator` for ordered workflows. |
-| `delegate` | Invoke a specific named agent with a given prompt and context. The core primitive used by orchestration agents to hand off work. |
-| `hash-edit` | Reliable file editing with content verification. Takes target content and its expected hash to prevent edits on stale versions. |
-| `council` | Ensemble-based reasoning. Runs 3 specialized agents in parallel and synthesizes their consensus for complex decisions. |
-| `context-generator` | Auto-generate/update hierarchical `AGENTS.md` and `CLAUDE.md` files throughout the project for better agent grounding. |
-
----
-
-← [Back to Index](index.md)

package/docs/design-first-workflow.md

@@ -1,94 +0,0 @@
-# Design-First Workflow
-
-FlowDeck enforces a design-first path for UI-heavy tasks by default.
-
-## Trigger Conditions
-
-Design-first is triggered when tasks mention user-facing work such as:
-- landing page
-- dashboard
-- admin panel
-- website redesign
-- onboarding UX
-- app screen/mobile UI
-
-Backend-only or infra-only tasks skip design-first.
-
-## Workflow
-
-```text
-task intake
-→ task classification
-→ design discovery
-→ UX structure
-→ wireframe/layout planning
-→ visual system definition
-→ design review/approval
-→ implementation handoff
-→ frontend implementation
-→ QA/review
-```
-
-## Commands
-
-- `/fd-design --mode=draft`: produce design artifact and handoff
-- `/fd-design --mode=review`: compare implementation to approved design artifact
-- `/fd-design --mode=system`: create/update token and component consistency guidance
-
-## Design Artifact Schema
-
-Each design run should persist:
-- `task_type`
-- `user_goals`
-- `target_audience`
-- `core_user_flows`
-- `page_map_or_screen_map`
-- `section_structure`
-- `layout_plan`
-- `component_list`
-- `state_list`
-- `responsive_behavior_notes`
-- `visual_direction`
-- `design_tokens_guidance`
-- `accessibility_notes`
-- `implementation_handoff_checklist`
-- `approval_status`
-
-## Example: Landing Page
-
-```yaml
-task_type: landing-page
-user_goals:
-  - understand value in <10 seconds
-  - complete signup CTA
-core_user_flows:
-  - hero -> social-proof -> pricing -> CTA
-layout_plan:
-  - hero_section: headline, subheadline, primary_cta, secondary_cta
-  - proof_section: logos, testimonials
-  - pricing_section: tier_cards, comparison_table
-state_list: [loading, empty, error, success]
-approval_status: approved
-```
-
-## Example: App Screen Redesign
-
-```yaml
-task_type: app-screen
-target_audience:
-  - returning mobile users
-core_user_flows:
-  - home -> quick-action -> detail -> completion
-section_structure:
-  - top_nav
-  - summary_cards
-  - task_list
-  - persistent_action_bar
-responsive_behavior_notes:
-  - compact_nav_on_small_screens
-  - collapse_secondary_panels_under_768
-design_tokens_guidance:
-  - spacing_scale: [4, 8, 12, 16, 24, 32]
-  - text_scale: [12, 14, 16, 20, 24]
-approval_status: approved
-```

package/docs/feature-integration-architecture.md

@@ -1,227 +0,0 @@
-# FlowDeck Integration Architecture
-
-Second-layer integration: trust, routing, observability, and repo-intelligence.
-
----
-
-## Overview
-
-This layer adds 8 capabilities behind the existing command architecture without expanding the top-level command surface:
-
-| Capability | Implementation | Data File |
-|---|---|---|
-| Patch Trust Engine | `src/hooks/patch-trust.ts` | `.codebase/DECISIONS.jsonl` |
-| Agent Performance Memory | `src/services/agent-performance.ts` | `.codebase/AGENT_PERF.json` |
-| Approval-Aware Execution | `src/services/approval-manager.ts` + `src/hooks/approval-hook.ts` | `.codebase/APPROVALS.json` |
-| Workflow Replay + Diff | `src/services/run-trace.ts` | `.codebase/RUNS.jsonl` |
-| Agent Performance Memory | `src/services/agent-performance.ts` | `.codebase/AGENT_PERF.json` |
-| Structured Telemetry | `src/services/telemetry.ts` + `src/hooks/telemetry-hook.ts` | `.codebase/TELEMETRY.jsonl` |
-| Dashboard Integration | `src/dashboard/` | reads all `.codebase/` files |
-| Failure-to-Rule Learning | `src/services/policy-compiler.ts` (`learnFromFailure`) | `.codebase/POLICIES.json` |
-
----
-
-## Services Layer (`src/services/`)
-
-### telemetry.ts
-Appends structured `TelemetryEvent` records to `.codebase/TELEMETRY.jsonl`.
-
-```typescript
-appendEvent(dir, { session_id, run_id, event, command, tool, model, duration_ms, status, risk_score })
-readEvents(dir, limit)
-getCommandSummary(dir)
-getRunEvents(dir, run_id)
-getRecentToolFailures(dir)
-```
-
-Event types: `command.start`, `command.end`, `tool.call`, `tool.complete`, `agent.dispatch`, `approval.request`, `approval.resolve`, `run.complete`, `run.fail`, `policy.violation`, `patch.scored`
-
-### run-trace.ts
-Records command execution runs with files touched, risk scores, and outcomes.
-
-```typescript
-startTrace(dir, command, args, session_id) → RunTrace
-endTrace(dir, run_id, status, outcome?, error?)
-touchFile(dir, run_id, filePath)
-setRiskScore(dir, run_id, score)
-getTrace(dir, run_id)
-listTraces(dir, limit)
-diffTraces(dir, run_id_a, run_id_b) → RunDiff
-```
-
-### approval-manager.ts
-Manages approval state for high-risk operations.
-
-```typescript
-requestApproval(dir, run_id, trigger, reason, options) → ApprovalRequest
-resolveApproval(dir, approval_id, "approved" | "rejected")
-checkApproval(dir, file_path, command) → ApprovalRequest | null
-getPendingApprovals(dir)
-isApprovalRequired(filePath, riskScore) → boolean
-isSensitivePath(filePath) → boolean
-```
-
-**Approval TTL:** 30 minutes. Sensitive path patterns: auth, payment, secrets, migrations, infra, production config.
-
-### agent-performance.ts
-Tracks success rates, costs, and durations per agent+model+task combination.
-
-```typescript
-recordRun(dir, agent, model, task_type, success, duration_ms, cost?)
-getStats(dir, filter?) → AgentPerfEntry[]
-getBestAgentForTask(dir, task_type) → AgentRecommendation | null
-getAgentLeaderboard(dir) → AgentRecommendation[]
-```
-
-Requires ≥ 3 runs per combination before making routing recommendations. Model is tracked from the actual call — no hardcoded model list.
-
----
-
-## Hooks Layer (`src/hooks/`)
-
-### Hook execution order (tool.execute.before)
-1. `telemetryHook` — record tool invocation
-2. `approvalHook` — block writes on sensitive files without approval
-3. `guardRailsHook` — enforce execution mode (auto/guarded/review-only)
-4. `toolGuardHook` — enforce architectural constraints
-5. `patchTrustHook` — score patch risk
-6. `decisionTraceHook` — record edit rationale
-
-### approval-hook.ts
-Intercepts write/edit tool calls on sensitive file paths. Throws with `APPROVAL_REQUIRED:` prefix to block. Emits `approval.request` telemetry event.
-
-Monitored tools: `write_file`, `edit_file`, `create_file`, `apply_patch`, `str_replace_editor`, `write`
-
-### telemetry-hook.ts
-Emits `tool.call` events for all tool invocations. Lightweight — never blocks.
-
----
-
-## Command Integration
-
-### /fd-new-feature
-- Calls `startTrace()` on entry → `run_id` included in config
-- Emits `command.start` telemetry event with risk score and phase
-
-### /fd-fix-bug
-- Calls `startTrace()` on entry → `run_id` included in config
-- Emits `command.start` telemetry with prior failure count in metadata
-
-### /fd-analyze-change
-- Consumes all impact services (impact radar, blast radius, volatility, regression)
-- Returns structured output with risk summary for dashboard
-
-### /fd-dashboard
-- Reads `DashboardData` including: `telemetrySummary`, `recentRuns`, `pendingApprovals`, `agentPerf`, `toolFailureCount`
-- Displays operational control plane sections alongside phase progress
-
-### /fd-guarded-edit
-- Run approval gate before risky operations
-- Uses `isApprovalRequired()` + `requestApproval()` pattern
-
----
-
-## Dashboard Sections
-
-The dashboard at `http://localhost:<port>` now includes:
-
-1. **Milestone Progress** — phase timeline (existing)
-2. **Blockers** — from STATE.md (existing)
-3. **⚠ Pending Approvals** — approval requests waiting on user
-4. **Recent Runs** — last 10 command runs with status, risk, files touched
-5. **Command Telemetry** — aggregate stats per command (total runs, success rate, avg duration)
-6. **Agent Performance** — success rate per agent/model/task combination
-
----
-
-## Data Schema
-
-### TELEMETRY.jsonl (append-only)
-```json
-{"id":"uuid","ts":"ISO","session_id":"s","run_id":"r","event":"command.end","command":"fd-fix-bug","status":"ok","duration_ms":1200,"risk_score":72}
-```
-
-### RUNS.jsonl (append-only, rewritten on end/update)
-```json
-{"run_id":"uuid","session_id":"s","command":"fd-new-feature","args":{},"started_at":"ISO","ended_at":"ISO","status":"complete","files_touched":["src/auth.ts"],"event_ids":[],"risk_score":65,"outcome":"Feature merged"}
-```
-
-### APPROVALS.json
-```json
-{"requests":[{"id":"uuid","run_id":"r","session_id":"s","requested_at":"ISO","status":"pending","trigger":"sensitive_file","reason":"Auth change","risk_score":25,"file_path":"src/auth.ts"}]}
-```
-
-### AGENT_PERF.json
-```json
-{"entries":[{"agent":"backend-coder","model":"<user-configured>","task_type":"implementation","runs":12,"successes":11,"failures":1,"total_duration_ms":60000,"total_cost":0.48,"last_run":"ISO","last_status":"success"}],"updated_at":"ISO"}
-```
-
----
-
-## Config Additions
-
-No new required config. Optional per-repo overrides:
-
-- `.codebase/POLICIES.json` — runtime policy rules (existing, enhanced)
-- `.codebase/CONSTRAINTS.md` — architectural constraints (existing)
-
----
-
-## Agents
-
-Three new specialist agents available for programmatic invocation:
-
-| Agent | File | Purpose |
-|---|---|---|
-| `replay-analyst` | `agents/replay-analyst.md` | Diff run traces, surface regressions |
-| `eval-reviewer` | `agents/eval-reviewer.md` | Evaluate agent/model routing quality |
-| `cost-optimizer` | `agents/cost-optimizer.md` | Recommend cheaper routing with no quality loss |
-
----
-
-## Policy Compiler Service (`src/services/policy-compiler.ts`)
-
-Compiles active policies from `POLICIES.json` into runtime evaluators.
-
-```typescript
-evaluatePolicies(dir, ctx) → PolicyViolation[]
-learnFromFailure(failure_type, affected_paths, root_cause?) → ProposedPolicy | null
-formatViolations(violations) → string
-```
-
-**PolicyContext fields:** `command`, `file_path`, `change_description`, `tool`, `risk_score`
-
-**Severity derivation:** Rules containing "require approval", "never", "must not" → `block`; otherwise → `warn`
-
-**Pattern learning:** Proposes policies for recognized failure types (`auth_bypass`, `payment_failure`, `migration_failure`, `infra_change`, `secrets_exposure`). Returns `null` for unrecognized patterns.
-
----
-
-## `/fd-approve` Command (`src/commands/governance/approve.ts`)
-
-Governance command for managing approval gates raised by the approval hook.
-
-```
-/fd-approve                           # list all pending approvals
-/fd-approve --id <uuid>               # approve → operation may proceed
-/fd-approve --id <uuid> --reject      # reject → operation stays blocked
-/fd-approve --recent                  # last 10 resolved approvals
-/fd-approve --json                    # machine-readable output
-```
-
-Resolving an approval emits an `approval.resolve` telemetry event and records the decision in `APPROVALS.json`.
-
----
-
-## Migration Notes
-
-All existing commands continue to work unchanged. New capabilities are additive:
-
-- `fd-new-feature` — now uses model router instead of hardcoded models; emits telemetry
-- `fd-fix-bug` — emits run trace on entry, evaluates policies, proposes new policies from failures
-- `fd-verify` — shows policy violations in output table
-- Dashboard — new operational sections appear only when data exists (no empty-state noise)
-- Approval hook — only triggers for write operations on sensitive file patterns; safe paths are unaffected
-- Telemetry — append-only, never read during hook execution, cannot slow down tool calls
-
-First-run behavior: all new `.codebase/` data files are created on first use. No migration needed.