@dv.nghiem/flowdeck 0.2.4 → 0.3.0

package/docs/command-migration.md

@@ -1,175 +0,0 @@
-# Command Architecture & Migration Guide
-
-FlowDeck v2 consolidates seven individual analysis commands into four umbrella commands, reducing the top-level command surface while keeping all capabilities. The 15 workflow commands remain as separate top-level slash commands.
-
----
-
-## Command Map
-
-### Workflow commands (unchanged — 15 total)
-
-These remain as separate top-level commands:
-
-| Command | Purpose |
-|---------|---------|
-| `/fd-new-project` | Bootstrap a new project |
-| `/fd-map-codebase` | Analyse and index the codebase |
-| `/fd-settings` | Configure FlowDeck settings |
-| `/fd-discuss` | Pre-planning discussion with impact radar |
-| `/fd-plan` | Generate a phase plan |
-| `/fd-roadmap` | View / update project roadmap |
-| `/fd-dashboard` | Visual progress dashboard |
-| `/fd-ask` | Smart agent dispatch |
-| `/fd-new-feature` | Implement a new feature |
-| `/fd-fix-bug` | Fix a bug with failure replay |
-| `/fd-review-code` | Code review with impact radar |
-| `/fd-write-docs` | Generate documentation |
-| `/fd-deploy-check` | Pre-deploy safety check |
-| `/fd-progress` | View project progress |
-| `/fd-checkpoint` | Save a session checkpoint |
-| `/fd-resume` | Resume from checkpoint |
-| `/fd-multi-repo` | Multi-repo management |
-
-### Analysis commands — old → new mapping
-
-| Old command | New umbrella command | Flag |
-|-------------|---------------------|------|
-| `/fd-impact-radar` | `/fd-analyze-change` | `--impact` |
-| `/fd-blast-radius` | `/fd-analyze-change` | `--blast-radius` |
-| `/fd-regression-predict` | `/fd-analyze-change` | `--regression` |
-| `/fd-test-gap` | `/fd-analyze-change` | `--test-gap` |
-| `/fd-volatility-map` | `/fd-analyze-change` | `--volatility` |
-| `/fd-review-route` | `/fd-analyze-change` | `--review-route` |
-| `/fd-translate-intent` | `/fd-translate-intent` | *(enhanced, kept as-is)* |
-| *(new)* | `/fd-guarded-edit` | — |
-| *(new)* | `/fd-evaluate-risk` | — |
-
-### New umbrella commands (4 total)
-
-| Command | Replaces / Adds |
-|---------|----------------|
-| `/fd-analyze-change` | Combines 6 analysis commands; `--all` runs all modules |
-| `/fd-guarded-edit` | New — edit gate decision (auto/confirm/review/block) |
-| `/fd-evaluate-risk` | New — standalone risk + regression assessment |
-| `/fd-translate-intent` | Enhanced — adds `assumptions`, `recommended_option`, `clarifying_questions` |
-
----
-
-## Architecture
-
-### Command layer
-
-Commands are thin entry points that dispatch to agent pipelines or shared utilities. No analysis logic lives inside command files.
-
-```
-User runs: /fd-analyze-change --change "..." --impact --regression
-     ↓
-analyzeChangeCommand.execute()
-     ↓
-  reads: VOLATILITY.json, FAILURES.json, MEMORY.json via shared libs
-  calls: runImpactRadar(), scorePatch()
-     ↓
-  returns: unified config object with agent pipeline + aggregated data
-```
-
-### Agent layer
-
-Agents are modular and reusable across commands:
-
-| Agent | Used by |
-|-------|---------|
-| `architect` | `/fd-analyze-change`, `/fd-translate-intent`, `/fd-plan` |
-| `researcher` | `/fd-analyze-change`, `/fd-evaluate-risk`, `/fd-discuss` |
-| `tester` | `/fd-analyze-change` |
-| `reviewer` | `/fd-analyze-change`, `/fd-evaluate-risk`, `/fd-review-code` |
-| `security-auditor` | `/fd-evaluate-risk` (high/critical risk), `/fd-review-code` |
-| `risk-analyst` | `/fd-evaluate-risk`, `/fd-guarded-edit` |
-| `policy-enforcer` | `/fd-guarded-edit` |
-
-### Plugin hooks
-
-Hooks intercept tool execution and enforce safety policies at the infrastructure layer:
-
-| Hook | Function |
-|------|---------|
-| `tool.execute.before` | `toolGuardHook` — blocks dangerous read/write/bash/edit |
-| `tool.execute.before` | `guardRailsHook` — enforces execution mode (auto/guarded/review-only) |
-| `tool.execute.before` | `patchTrustHook` — scores writes/edits; blocks high-risk without approval |
-| `tool.execute.before` | `decisionTraceHook` — records every edit to DECISIONS.jsonl |
-| `session.started` | `sessionStartHook` — announces FlowDeck, loads context |
-| `command.execute.before` | Command routing — dispatches slash commands |
-
-### Shared libraries
-
-Reusable utilities consumed by multiple commands:
-
-| Module | Exports |
-|--------|---------|
-| `src/lib/impact-radar.ts` | `runImpactRadar()`, `impactRadarSummaryLines()`, `lookupPriorFailures()` |
-| `src/hooks/patch-trust.ts` | `scorePatch()` |
-| `src/hooks/guard-rails.ts` | `resolveExecutionMode()` |
-| `src/hooks/tool-guard.ts` | `checkArchConstraint()`, `isBlocked()` |
-| `src/tools/planning-state-lib.ts` | `statePath()`, `codebaseDir()`, `readPlanningState()`, `timestamp()` |
-
-### Data files (`.codebase/`)
-
-| File | Purpose |
-|------|---------|
-| `MEMORY.json` | Architecture graph — modules, ownership, types |
-| `FAILURES.json` | Failure history — root causes, tags, recurrence counts |
-| `DECISIONS.jsonl` | Append-only edit audit log |
-| `VOLATILITY.json` | Churn metrics — stability ratings per path |
-| `POLICIES.json` | Self-healing policy rules |
-| `CONSTRAINTS.md` | Forbidden paths and architectural boundaries |
-| `ARCHITECTURE.md` | High-level architecture notes (written by `/fd-map-codebase`) |
-| `STACK.md` | Technology stack reference |
-
----
-
-## Migration Plan
-
-### For existing users
-
-**All old commands still work.** No action required. Old commands were not removed.
-
-**When to migrate:**
-
-| If you used to run | Now prefer |
-|-------------------|-----------|
-| `/fd-impact-radar --change "..."` | `/fd-analyze-change --change "..." --impact` |
-| Multiple analysis commands in sequence | `/fd-analyze-change --change "..." --all` |
-| Manual pre-edit risk assessment | `/fd-evaluate-risk --change "..." --file "..."` |
-| Manually deciding whether to apply a change | `/fd-guarded-edit --file "..." --change "..."` |
-| `/fd-translate-intent --intent "..."` | Same — now returns `assumptions` and `recommended_option` |
-
-### Quick start for new workflows
-
-**Before any significant edit:**
-```bash
-# 1. Translate vague intent to concrete options
-/fd-translate-intent --intent "make checkout faster"
-
-# 2. Full pre-change analysis
-/fd-analyze-change --change "add Redis cache for checkout queries"
-
-# 3. Gate decision for the specific file
-/fd-guarded-edit --file "src/checkout/query.ts" --change "add Redis cache layer"
-```
-
-**In CI/CD pipelines:**
-```bash
-# Risk gate — fail if approval required
-/fd-evaluate-risk --change "<PR description>" --json | jq '.approval_needed'
-
-# Edit gate — fail if block decision
-/fd-guarded-edit --file "<changed file>" --json | jq '.decision == "block"'
-```
-
----
-
-## Backward compatibility notes
-
-- All 7 original intelligence commands (`/fd-impact-radar`, `/fd-blast-radius`, `/fd-regression-predict`, `/fd-test-gap`, `/fd-volatility-map`, `/fd-review-route`, `/fd-translate-intent`) remain registered and functional.
-- Their implementations were not modified (except `/fd-translate-intent` which gained `assumptions`, `recommended_option`, and `clarifying_questions` in its output spec).
-- The new umbrella commands are registered alongside the old ones — no commands were removed.
-- Existing scripts, keybindings, or workflows that call the old commands will continue to work without changes.

package/docs/commands/fd-analyze-change.md

@@ -1,107 +0,0 @@
-# /fd-analyze-change
-
-**Umbrella analysis command** — runs up to 6 analysis modules in a single pass and produces a consolidated pre-change risk report.
-
-Replaces individual calls to `/fd-impact-radar`, `/fd-blast-radius`, `/fd-regression-predict`, `/fd-test-gap`, `/fd-volatility-map`, and `/fd-review-route`.
-
----
-
-## Usage
-
-```
-/fd-analyze-change --change "<what's changing>" [flags]
-```
-
-## Arguments
-
-| Flag | Type | Default | Description |
-|------|------|---------|-------------|
-| `--change` | string | — | Description of the proposed change |
-| `--scope` | string | `"all"` | Module or file path scope |
-| `--files` | string | — | Comma-separated file paths |
-| `--depth` | number | `2` | Blast radius traversal depth |
-| `--impact` | boolean | false | Run impact radar module |
-| `--blast-radius` | boolean | false | Run blast radius module |
-| `--regression` | boolean | false | Run regression prediction module |
-| `--test-gap` | boolean | false | Run test gap detection module |
-| `--volatility` | boolean | false | Run volatility map module |
-| `--review-route` | boolean | false | Run reviewer routing module |
-| `--all` | boolean | false | Force all modules (default when no module flags given) |
-| `--json` | boolean | false | Return raw JSON instead of table |
-
-**Default behaviour:** If no module flags are specified, all 6 modules run automatically.
-
----
-
-## Output
-
-```
-════════════════════════════════════════════════════════════════
-fd-analyze-change
-────────────────────────────────────────────────────────────────
-  Change:   update JWT token expiry
-  Scope:    all
-  Modules:  impact-radar, blast-radius, regression-predict, test-gap, volatility-map, review-route
-────────────────────────────────────────────────────────────────
-  ⚠ Affected zones:   src/auth/, src/session/, src/middleware/
-  ⚠ Known failures:   F-023, F-031
-  ≈ Regression cats:  auth, performance, async-flow...
-  ✗ Test gap types:   5 gap patterns checked
-  → Route to:          security, backend
-────────────────────────────────────────────────────────────────
-  ⚠ HIGH RISK: 3 volatile zone(s), 2 known failure(s), 1 fragile pattern(s)
-════════════════════════════════════════════════════════════════
-```
-
-### Top-level fields returned
-
-| Field | Description |
-|-------|-------------|
-| `modules_run` | Which analysis modules were executed |
-| `affected_zones` | Volatile/critical file paths matching the change |
-| `recommended_reviewers` | Reviewer types suggested (security, backend, infra, etc.) |
-| `risk_summary` | Human-readable risk advisory |
-| `risk_score` | Numeric score 0–100 (higher = lower risk) |
-| `config` | Full agent pipeline config dispatched to agents |
-
----
-
-## Examples
-
-```bash
-# Full analysis before editing auth middleware
-/fd-analyze-change --change "replace JWT with session tokens" --files "src/auth/token.ts"
-
-# Impact + regression only (partial analysis)
-/fd-analyze-change --change "refactor database connection pool" --impact --regression
-
-# JSON output for scripting
-/fd-analyze-change --change "update payment webhook handler" --json
-
-# Deep blast radius (3 levels)
-/fd-analyze-change --change "extract user service" --blast-radius --depth 3
-```
-
----
-
-## Old commands (still supported)
-
-These individual commands remain available and still work. Use `/fd-analyze-change` for combined analysis:
-
-| Old command | Equivalent flag |
-|-------------|----------------|
-| `/fd-impact-radar` | `--impact` |
-| `/fd-blast-radius` | `--blast-radius` |
-| `/fd-regression-predict` | `--regression` |
-| `/fd-test-gap` | `--test-gap` |
-| `/fd-volatility-map` | `--volatility` |
-| `/fd-review-route` | `--review-route` |
-
----
-
-## Agents dispatched
-
-- `researcher` — traces dependency graph from changed paths
-- `architect` — maps blast radius to configured depth, flags integration points
-- `tester` — estimates coverage gaps per regression category and test gap types
-- `reviewer` — ranks gaps by risk and confirms routing

package/docs/commands/fd-dashboard.md

@@ -1,11 +0,0 @@
----
-description: Open project dashboard — displays phase progress, milestones, and blockers
----
-Run the FlowDeck dashboard to view project progress.
-
-## What Next?
-
-1. **Start feature work** → `/fd-new-feature [description]`
-2. **Fix a bug** → `/fd-fix-bug [issue]`
-3. **View roadmap** → `/fd-roadmap`
-4. **Check progress** → `/fd-progress`

package/docs/commands/fd-evaluate-risk.md

@@ -1,134 +0,0 @@
-# /fd-evaluate-risk
-
-**Standalone risk assessment command** — estimates change risk, confidence, likely regression categories, and whether human approval is needed before proceeding.
-
-Works with a change description alone (keyword-based) or with a specific file path (trust score + keyword combined).
-
----
-
-## Usage
-
-```
-/fd-evaluate-risk --change "<description>" [--file "<path>"] [flags]
-```
-
-## Arguments
-
-| Flag | Type | Default | Description |
-|------|------|---------|-------------|
-| `--change` | string | — | Plain-language description of the proposed change |
-| `--file` | string | — | Specific file being changed (enables patch trust scoring) |
-| `--volatility` | boolean | true | Include volatile zone count in analysis |
-| `--json` | boolean | false | Return raw JSON instead of table |
-
-At least one of `--change` or `--file` is required.
-
----
-
-## Risk levels
-
-| Level | Score | Meaning |
-|-------|-------|---------|
-| `low` | 80–100 | Safe to proceed without approval |
-| `medium` | 50–79 | Proceed with care; review recommended |
-| `high` | 25–49 | Approval required; consider safer alternative |
-| `critical` | 0–24 | Approval required; safer alternative strongly recommended |
-
-**Approval is required when:** `risk_score < 60` OR `≥3 regression categories predicted`.
-
----
-
-## Output
-
-```
-════════════════════════════════════════════════════════════
-fd-evaluate-risk
-────────────────────────────────────────────────────────────
-  Change:      replace JWT with session tokens
-  File:        src/auth/token.ts
-────────────────────────────────────────────────────────────
-  ⚠ Risk level:  HIGH (score: 38/100)
-  Confidence:  72/100 (codebase context coverage)
-  Approval:    REQUIRED
-  Regressions: auth, security, async-flow
-  Hot zones:   src/auth/
-  Signals:     volatile path, auth keyword
-────────────────────────────────────────────────────────────
-  Safer alt:   Consider a feature-flag rollout before swapping auth tokens
-────────────────────────────────────────────────────────────
-  researcher → map to affected paths
-  reviewer   → validate risk + regressions
-  security   → targeted review of high-risk areas
-════════════════════════════════════════════════════════════
-```
-
-### Fields returned
-
-| Field | Description |
-|-------|-------------|
-| `risk_score` | 0–100 (higher = less risky) |
-| `risk_level` | low / medium / high / critical |
-| `confidence` | 0–100 (how much codebase context data exists) |
-| `approval_needed` | boolean — whether human approval is required |
-| `likely_regressions` | predicted regression categories from change keywords |
-| `volatile_zones` | count of volatile/critical zones in the repo |
-| `volatile_matches` | paths that match the change description |
-| `safer_alternative` | suggested safer approach if risk is high/critical |
-| `trust_signals` | risk signals from the patch trust scorer |
-
----
-
-## Regression categories detected
-
-| Category | Triggered by keywords |
-|----------|----------------------|
-| performance | slow, latency, cache, query, index, bulk, batch, load |
-| auth | auth, token, session, jwt, oauth, permission, rbac, login |
-| schema | schema, migration, column, table, foreign key, constraint |
-| ui-state | state, redux, context, store, hook, render, component |
-| async-flow | async, await, promise, callback, event, queue, worker |
-| api-contract | api, endpoint, route, request, response, payload, version |
-| data-integrity | transaction, rollback, constraint, unique, required, nullable |
-| security | secret, password, encrypt, decrypt, hash, sanitize |
-| config | env, config, setting, flag, feature flag, toggle |
-| i18n | locale, translation, i18n, format, timezone, language |
-
----
-
-## Confidence score
-
-Confidence reflects how much codebase context data the system has:
-
-| Data source | Points |
-|-------------|--------|
-| `.codebase/ARCHITECTURE.md` exists | +20 |
-| `.codebase/STACK.md` exists | +10 |
-| `.codebase/MEMORY.json` node count | up to +25 |
-| `.codebase/VOLATILITY.json` entries | up to +15 |
-| `.codebase/FAILURES.json` entries | up to +10 |
-| Base | +20 |
-
-Run `/fd-map-codebase` and let FlowDeck index the repo to increase confidence.
-
----
-
-## Examples
-
-```bash
-# Keyword-based risk estimate
-/fd-evaluate-risk --change "refactor JWT auth to use session tokens"
-
-# File + change (enables patch trust scoring)
-/fd-evaluate-risk --change "update stripe webhook" --file "src/payment/webhook.ts"
-
-# JSON output for CI decision gates
-/fd-evaluate-risk --change "drop users table column" --json
-```
-
----
-
-## Agents dispatched
-
-- `researcher` — maps change description to affected modules and paths
-- `reviewer` — validates risk level and regression predictions
-- `security-auditor` — targeted review (only when risk is high or critical)

package/docs/commands/fd-guarded-edit.md

@@ -1,105 +0,0 @@
-# /fd-guarded-edit
-
-**Edit gate command** — evaluates a proposed file change before it is applied and returns a binding gate decision.
-
-Combines: patch trust scoring, architectural constraint checking, policy enforcement, volatility analysis, and failure history into a single pass/block decision.
-
----
-
-## Usage
-
-```
-/fd-guarded-edit --file "<path>" --change "<description>" [flags]
-```
-
-## Arguments
-
-| Flag | Type | Default | Description |
-|------|------|---------|-------------|
-| `--file` | string | — | File path being changed |
-| `--change` | string | — | Plain-language description of the change |
-| `--dry-run` | boolean | false | Evaluate without recording or side effects |
-| `--json` | boolean | false | Return raw JSON instead of table |
-
-At least one of `--file` or `--change` is required.
-
----
-
-## Gate decisions
-
-| Decision | Meaning |
-|----------|---------|
-| `auto-approve` | Apply — no action needed (trust ≥70, no violations, stable file) |
-| `require-confirmation` | Review the diff carefully, then confirm (volatile file, guarded mode, or prior failures) |
-| `require-review` | Route to human reviewer — do not auto-apply (trust <40 or policy violation) |
-| `block` | Do NOT apply — arch constraint violation or critical policy breach |
-
-### Decision priority (highest first)
-
-1. Arch constraint violated → **block**
-2. Policy violation + trust < 30 → **block**
-3. `review-only` execution mode → **require-review**
-4. Trust < 40 OR any policy violation → **require-review**
-5. `guarded` execution mode OR volatile file OR prior failures → **require-confirmation**
-6. All else → **auto-approve**
-
----
-
-## Output
-
-```
-════════════════════════════════════════════════════════════
-fd-guarded-edit
-────────────────────────────────────────────────────────────
-  File:   src/auth/token.ts
-  Change: replace jwt secret rotation logic
-────────────────────────────────────────────────────────────
-  ⚑ Decision:    REQUIRE-REVIEW
-  Reason:       High risk: trust score 32/100, 0 policy violation(s)
-  Risk score:   32/100 (high-risk)
-  Exec mode:    guarded
-  Prior fails:  F-023, F-031
-────────────────────────────────────────────────────────────
-  → Route to human reviewer before applying — do not auto-apply
-════════════════════════════════════════════════════════════
-```
-
-### Fields returned
-
-| Field | Description |
-|-------|-------------|
-| `decision` | Gate decision string |
-| `reason` | Explanation for the decision |
-| `risk_score` | Patch trust score 0–100 |
-| `execution_mode` | Current repo execution mode (auto/guarded/review-only) |
-| `policy_violations` | Policy rule strings that were triggered |
-| `volatile_files` | Files that matched volatile/critical zones |
-| `prior_failures` | Failure IDs for prior failures on this path |
-| `arch_constraint` | Whether an architectural constraint was violated |
-| `recommended_action` | Plain-language next step |
-
----
-
-## Examples
-
-```bash
-# Check before editing auth token logic
-/fd-guarded-edit --file "src/auth/token.ts" --change "replace secret rotation"
-
-# Dry run (evaluate without recording)
-/fd-guarded-edit --file "src/payment/webhook.ts" --change "update stripe handler" --dry-run
-
-# JSON for CI/CD pipeline integration
-/fd-guarded-edit --file "src/core/engine.ts" --change "patch core engine" --json
-```
-
----
-
-## Data sources read
-
-- `.codebase/POLICIES.json` — active policy rules
-- `.codebase/VOLATILITY.json` — volatile/critical paths
-- `.codebase/FAILURES.json` — unresolved prior failures per path
-- `.codebase/CONSTRAINTS.md` — forbidden path patterns
-- `.planning/config.json` — execution mode setting
-- Patch trust scorer — keyword + volatility scoring

package/docs/commands/fd-progress.md

@@ -1,11 +0,0 @@
----
-description: Display current STATE.md, active PLAN.md, and recent results
----
-Run the FlowDeck progress command to see current project state.
-
-## What Next?
-
-1. **Continue feature work** → `/fd-new-feature [description]`
-2. **Fix a bug** → `/fd-fix-bug [issue]`
-3. **View dashboard** → `/fd-dashboard`
-4. **Check roadmap** → `/fd-roadmap`

package/docs/commands/fd-review-code.md

@@ -1,29 +0,0 @@
----
-description: Parallel code review — reviewer + researcher + tester — aggregates into critical/major/minor report
-argument-hint: "[scope: file, directory, or 'staged']"
----
-
-Run a comprehensive parallel code review.
-
-**What this does:**
-1. Determines scope: staged changes, a file/directory, or the whole PR
-2. Runs `@reviewer` (security, quality, logic), `@researcher` (API correctness), and `@tester` (test coverage) in parallel
-3. Aggregates findings into a single report ranked: CRITICAL → HIGH → MEDIUM → LOW
-4. Proposes fixes for every CRITICAL and HIGH finding
-5. Skips stylistic preferences — only real bugs and security issues
-
-**Output format:**
-```
-## Code Review Report
-### CRITICAL [n]
-- [finding]: [file:line] — [fix]
-### HIGH [n]
-...
-```
-
-## What Next?
-
-1. **Fix critical issues found** → `/fd-fix-bug [issue description]`
-2. **Deploy check** → `/fd-deploy-check`
-3. **Update documentation** → `/fd-write-docs`
-4. **Check project progress** → `/fd-progress`

package/docs/commands/fd-roadmap.md

@@ -1,10 +0,0 @@
----
-description: View or update the project roadmap — shows phase statuses and milestones
----
-Run the FlowDeck roadmap workflow to view or update project phases and milestones.
-
-## What Next?
-
-1. **Start next phase** → `/fd-new-feature [description]`
-2. **View progress** → `/fd-progress`
-3. **Check dashboard** → `/fd-dashboard`

package/docs/commands/fd-settings.md

@@ -1,10 +0,0 @@
----
-description: View or update FlowDeck settings — model assignments, guard enforcement, workspace mode
----
-Run the FlowDeck settings command to view or modify configuration.
-
-## What Next?
-
-1. **View dashboard** → `/fd-dashboard`
-2. **Check progress** → `/fd-progress`
-3. **Start working** → `/fd-new-feature [description]`