@dv.nghiem/flowdeck 0.3.9 → 0.4.1

package/docs/concepts/intelligence.md

@@ -0,0 +1,145 @@
+# Intelligence
+
+FlowDeck's intelligence layer evaluates every change before it is applied. It scores edit safety, tracks file change history, reproduces prior failures, predicts regressions, and enforces workflow discipline through phase gating. All intelligence services run as hooks on every tool execution — no additional commands needed.
+
+---
+
+## Patch Trust Score
+
+Before any `edit` tool call is applied, the **patch trust scorer** evaluates the edit and assigns a trust score from 0.0 (dangerous) to 1.0 (safe).
+
+The score is computed from:
+
+| Factor | Weight | What it measures |
+|--------|--------|-----------------|
+| File volatility | 25% | Historical change frequency from `.codebase/VOLATILITY.json` |
+| Edit scope | 20% | Lines changed vs. file total — large rewrites score lower |
+| Context window pressure | 15% | Remaining context space — edits under pressure score lower |
+| Agent history | 20% | Historical failure rate of the calling agent on this file |
+| Rule compliance | 20% | Does the edit violate project rules from `.flowdeck/rules/` |
+
+**Threshold behavior:**
+
+- Score >= 0.8 — edit applied automatically
+- Score 0.5–0.8 — user notified; edit applied with confirmation prompt
+- Score < 0.5 — edit blocked; user must resolve concerns or override explicitly
+
+The `@policy-enforcer` agent is invoked automatically when the score is below threshold. The score is logged in the tool span metadata.
+
+---
+
+## Volatility Map
+
+The **volatility map** tracks change frequency per file over the session and across sessions. It is maintained by the `volatility-map` tool and stored in `.codebase/VOLATILITY.json`.
+
+```json
+{
+  "src/auth/login.ts": {
+    "changeCount": 7,
+    "lastChanged": "2026-05-26T09:30:00Z",
+    "avgRevisionsPerSession": 3.2,
+    "risk": "high"
+  },
+  "src/config/default.ts": {
+    "changeCount": 1,
+    "lastChanged": "2026-05-25T14:00:00Z",
+    "avgRevisionsPerSession": 0.4,
+    "risk": "low"
+  }
+}
+```
+
+Files with high volatility:
+
+- Receive lower Patch Trust Scores automatically
+- Trigger `@risk-analyst` review before large refactors
+- Are flagged in the Workflow Scorecard under `context_preserved` if they change frequently within a single session
+
+The volatility map is rebuilt on first session start and incrementally updated on each `edit` tool call.
+
+---
+
+## Failure Replay
+
+When a task fails (test failure, build error, runtime crash), the **failure replay** service can reproduce the failure in isolation to generate a clean diagnostic trace.
+
+Invoked by the `@debugger` agent via the `failure-replay` tool:
+
+1. The tool reads the original error context from the failed span in `AGENT_SPANS.jsonl`
+2. It re-runs the minimal subset of the task that caused the failure
+3. The trace is written to `.codebase/FAILURE_REPLAY.jsonl`:
+
+```json
+{
+  "replay_id": "fr-001",
+  "original_span": "s1a2b3c",
+  "task": "Run user authentication tests",
+  "reproduced": true,
+  "root_cause": "Missing mock for auth service in test environment",
+  "trace": [
+    "Step 1: npm test src/auth/login.test.ts",
+    "Error: Cannot read property 'validate' of undefined",
+    "Step 2: Mock auth service — result: test passes"
+  ],
+  "fix_suggestion": "Add mock for auth service in login.test.ts line 42"
+}
+```
+
+Replays are deterministic — the same failure will reproduce the same trace. This prevents "heisenbugs" that only appear in full runs.
+
+---
+
+## Regression Prediction
+
+Before a plan is executed, the **regression predictor** evaluates the planned changes against the volatility map and historical failure data to predict which tasks are likely to break tests.
+
+The predictor runs as a pre-execution check in `/fd-execute`:
+
+1. For each task in the plan, look up every file the task will modify in `VOLATILITY.json`
+2. Cross-reference with historical failure data in `SCORECARDS.jsonl` — if similar changes broke tests before, flag the task
+3. Assign a regression probability score (0.0–1.0) per task and per wave
+
+**Output appended to PLAN.md:**
+
+```markdown
+## Regression Predictions
+
+| Task | Files | Regression Probability | Flag |
+|------|-------|----------------------|------|
+| 1a: Write user model | src/models/user.ts | 0.15 | low |
+| 1b: Refactor auth service | src/auth/login.ts | 0.72 | high — historically fragile |
+| 2a: Integration tests | src/auth/*.test.ts | 0.31 | medium |
+```
+
+Tasks flagged `high` are presented to the user before `CONFIRM` in `/fd-plan`. The user may choose to skip, refactor, or add additional test coverage before proceeding.
+
+---
+
+## Phase Gating
+
+Phase gating enforces workflow discipline by blocking entry into a phase unless the prerequisites from the previous phase are satisfied.
+
+| Transition | Gate |
+|------------|------|
+| `/fd-new-feature` → `/fd-discuss` | `DISCUSS.md` must exist and have at least 3 Q&A entries |
+| `/fd-discuss` → `/fd-plan` | `DISCUSS.md` must have a risk summary section |
+| `/fd-plan` → `/fd-execute` | User must type `CONFIRM`; no blockers in regression predictions |
+| `/fd-execute` → `/fd-verify` | All plan tasks must be marked `done` or `skipped` |
+
+If a gate check fails, the command exits with a descriptive error listing the missing prerequisites. The user resolves them before retrying.
+
+Phase gating is implemented by the `guard-rails` hook running in `tool.execute.before` — it intercepts command invocations and validates prerequisites before the command logic runs.
+
+---
+
+## Intelligence Tool Summary
+
+| Tool / Hook | Service | Purpose |
+|-------------|---------|---------|
+| `patch-trust` hook | Patch Trust Score | Score edits before application |
+| `volatility-map` tool + hook | Volatility Map | Track per-file change frequency |
+| `failure-replay` tool | Failure Replay | Reproduce and trace prior failures |
+| Regression predictor (in `/fd-plan`) | Regression Prediction | Score planned changes for breakage risk |
+| `guard-rails` hook | Phase Gating | Enforce workflow discipline at phase boundaries |
+| `policy-engine` tool | Rule Compliance | Evaluate edits against project rules |
+| `hash-edit` tool | Edit Hashing | Content-address edits for deduplication |

package/docs/concepts/multi-repo.md

@@ -0,0 +1,227 @@
+# Multi-Repo
+
+FlowDeck can coordinate changes across multiple repositories in a single session. Each repository is registered with the session, assigned a role, and managed through the `/fd-multi-repo` command. Coordination state is persisted in `.planning/multi-repo/` so sessions can be resumed.
+
+---
+
+## /fd-multi-repo Command
+
+The `fd-multi-repo` command is the entry point for all multi-repo operations. It supports four subcommands:
+
+| Subcommand | Description |
+|------------|-------------|
+| `fd-multi-repo add <path> [role]` | Register a repository at `<path>` with an optional role |
+| `fd-multi-repo remove <path>` | Unregister a repository |
+| `fd-multi-repo list` | Print all registered repositories and their roles |
+| `fd-multi-repo status` | Show sync state, pending changes, and divergence status |
+
+**Roles** classify the repository's purpose in the session:
+
+| Role | Meaning |
+|------|---------|
+| `primary` | The main development repository (default for the first added) |
+| `library` | An internal library or shared module |
+| `service` | A microservice or backend API |
+| `frontend` | A frontend application |
+| `config` | A configuration or infrastructure repository |
+
+The role determines how FlowDeck routes planning and which agents are responsible for changes to that repo.
+
+### Adding a Repository
+
+```bash
+fd-multi-repo add /home/user/project-lib library
+```
+
+This:
+
+1. Verifies the path exists and is a git repository
+2. Reads the `flowdeck.json` config if present in that repo
+3. Records the repo in `.planning/multi-repo/REPOSITORIES.json`
+4. Runs `/fd-map-codebase` on the new repository to index it into `.codebase/<repo-name>/`
+
+### Removing a Repository
+
+```bash
+fd-multi-repo remove /home/user/project-lib
+```
+
+This removes the repository from `REPOSITORIES.json` and deletes its `.codebase/<repo-name>/` index. It does not delete any files.
+
+---
+
+## Coordination State
+
+All multi-repo state lives under `.planning/multi-repo/`:
+
+```
+.planning/multi-repo/
+  REPOSITORIES.json      — registered repos, roles, paths
+  CHANGES.json           — pending cross-repo changes
+  DEPENDENCIES.json      — dependency graph between repos
+  SYNC.json              — sync status and divergence flags
+```
+
+### REPOSITORIES.json
+
+```json
+{
+  "repositories": [
+    {
+      "name": "flowdeck",
+      "path": "/home/user/flowdeck",
+      "role": "primary",
+      "addedAt": "2026-05-26T08:00:00Z",
+      "lastSynced": "2026-05-26T10:00:00Z"
+    },
+    {
+      "name": "flowdeck-lib",
+      "path": "/home/user/flowdeck-lib",
+      "role": "library",
+      "addedAt": "2026-05-26T08:05:00Z",
+      "lastSynced": "2026-05-26T09:55:00Z"
+    }
+  ]
+}
+```
+
+### CHANGES.json
+
+Tracks planned or in-progress changes that span multiple repositories:
+
+```json
+{
+  "changes": [
+    {
+      "id": "ch-001",
+      "description": "Add telemetry API to flowdeck-lib",
+      "status": "planned",
+      "affectedRepos": ["flowdeck-lib", "flowdeck"],
+      "planRef": ".planning/PLAN.md#ch-001"
+    }
+  ]
+}
+```
+
+### DEPENDENCIES.json
+
+Records declared dependencies between repositories (e.g., `flowdeck` imports `flowdeck-lib`):
+
+```json
+{
+  "dependencies": [
+    {
+      "from": "flowdeck",
+      "to": "flowdeck-lib",
+      "type": "import",
+      "files": ["src/lib/telemetry.ts"]
+    }
+  ]
+}
+```
+
+Dependencies are inferred from import analysis during `/fd-map-codebase` but can be manually overridden in `flowdeck.json`.
+
+---
+
+## Cross-Repo Planning
+
+When `/fd-plan` runs in a multi-repo session:
+
+1. The `@planner` agent reads `DISCUSS.md` and `FEATURE.md` as usual
+2. For each planned task, it checks `DEPENDENCIES.json` to determine which repository the task belongs to
+3. Tasks are organized by repository, then by wave within each repository
+4. Tasks that span multiple repositories (e.g., adding an API to a library and updating callers in the primary) are marked as **cross-repo tasks** and placed in a shared wave
+
+**Cross-repo wave execution:**
+
+```
+Wave 1 (parallel across repos)
+  ├── [flowdeck-lib] Task 1a: Add telemetry API      → @coder (flowdeck-lib)
+  └── [flowdeck]     Task 1b: Update telemetry callers → @coder (flowdeck)
+
+Wave 2 (sequential, primary waits for library)
+  └── [flowdeck]     Task 2a: Run integration tests    → @tester
+```
+
+The orchestrator enforces that all tasks in Wave 1 complete before Wave 2 begins, even across repositories.
+
+---
+
+## Cross-Repo Execution
+
+During `/fd-execute`, the orchestrator:
+
+1. Iterates through waves
+2. For each wave, dispatches tasks to their target repositories in parallel
+3. Each agent operates in its assigned repository's working directory
+4. The `DEADLOCK_SIGNALS.jsonl` from each repository is aggregated into the primary repo's `.codebase/`
+5. If a task in one repository depends on output from another, the orchestrator waits for the source task to complete first
+
+### File Coordination
+
+When a change in one repository depends on a change in another:
+
+- The dependency is declared in `DEPENDENCIES.json`
+- The planner ensures the source task runs before the dependent task
+- If both repos are on the same filesystem, FlowDeck uses absolute paths
+- If repos are on different machines, FlowDeck uses git worktree references or suggests a shared git remote
+
+---
+
+## Multi-Repo State Sync
+
+Use `fd-multi-repo status` to see the current state:
+
+```
+fd-multi-repo status
+
+Repository: flowdeck (primary)
+  Path: /home/user/flowdeck
+  Role: primary
+  Last synced: 2026-05-26 10:00:00
+  Status: clean ✓
+
+Repository: flowdeck-lib (library)
+  Path: /home/user/flowdeck-lib
+  Role: library
+  Last synced: 2026-05-26 09:55:00
+  Status: 2 commits ahead of remote
+  Pending:
+    - ch-001: Add telemetry API
+
+Cross-repo changes:
+  ch-001: Add telemetry API to flowdeck-lib
+    Status: planned
+    Affects: flowdeck-lib, flowdeck
+    Blocker: none
+```
+
+---
+
+## Configuration
+
+Declare multi-repo dependencies explicitly in `flowdeck.json` to override inferred dependencies:
+
+```json
+{
+  "multiRepo": {
+    "repositories": [
+      {
+        "name": "flowdeck-lib",
+        "path": "/home/user/flowdeck-lib",
+        "role": "library"
+      }
+    ],
+    "dependencies": [
+      {
+        "from": "flowdeck",
+        "to": "flowdeck-lib",
+        "type": "import"
+      }
+    ]
+  }
+}
+```
+
+This is useful when FlowDeck cannot infer dependencies from imports (e.g., binary dependencies, API contracts, or generated files).

package/docs/concepts/workflows.md

@@ -0,0 +1,205 @@
+# Workflows
+
+FlowDeck structures every feature through a six-step command cycle. Each step has a clear purpose, produces specific artifacts, and transitions the project state forward.
+
+## The Six-Step Cycle
+
+```
+/fd-map-codebase
+      │
+      ▼
+/fd-new-feature ─────────────────────────────────────────┐
+      │                                                 │
+      ▼                                                 │
+/fd-discuss ─────────────────────────────────────────┐   │
+      │                                              │   │
+      ▼                                              │   │
+/fd-plan ─────────────────────────────────────────┐  │   │
+      │                                            │  │   │
+      ▼                                            │  │   │
+/fd-execute ──────────────────────────────────┐    │  │   │
+      │                                      │    │  │   │
+      ▼                                      │    │  │   │
+/fd-verify ───────────────────────────────────┘    │  │   │
+                                                   │  │   │
+               (loop back to /fd-new-feature) ◄───┘  └───┘
+```
+
+Each command reads the current `STATE.md` and writes updated state when it completes. Use `/fd-checkpoint` at any time to save a mid-session snapshot and `/fd-resume` to restore it in a new session.
+
+---
+
+## /fd-map-codebase
+
+**Purpose:** Analyse and index the codebase into structured `.codebase/` files — required before starting any feature.
+
+**Files created:**
+- `.codebase/CODEGRAPH.json`
+- `.codebase/CONVENTIONS.md`
+- `.codebase/CODEBASE_INDEX.md`
+
+**Step-by-step:**
+
+1. Scan the project files and detect languages, frameworks, and patterns.
+2. Build a structured dependency graph and write it to `.codebase/CODEGRAPH.json`.
+3. Extract conventions and write them to `.codebase/CONVENTIONS.md`.
+4. Write a high-level index to `.codebase/CODEBASE_INDEX.md`.
+
+---
+
+## /fd-new-feature
+
+**Purpose:** Define a new feature and initialize its context. Requires codebase mapping (`.codebase/`) to exist.
+
+**Files created/modified:**
+- `.planning/FEATURE.md` (created)
+- `.planning/STATE.md` (created if missing, phase updated)
+- `.planning/ROADMAP.md` (feature entry added)
+
+**Step-by-step:**
+
+1. Verify `.codebase/` exists — error if not (codebase mapping is required first).
+2. Initialize `.planning/` and `STATE.md` lazily if they do not exist.
+3. Parse the feature description from the command argument.
+4. Create `FEATURE.md` with: feature name, summary, acceptance criteria, estimated complexity, related files.
+5. Append the feature to `ROADMAP.md` with status `pending`.
+6. Update `STATE.md` — set `phase: define`, `feature: <name>`, `status: in_progress`.
+
+---
+
+## /fd-discuss
+
+**Purpose:** Pre-planning structured Q&A to capture design decisions before a plan is written.
+
+**Files created/modified:**
+- `.planning/DISCUSS.md` (created)
+- `.planning/STATE.md` (phase updated)
+
+**Step-by-step:**
+
+1. The `@discusser` agent asks a series of targeted questions covering: scope boundaries, edge cases, dependencies, non-functional requirements, and known risks.
+2. Each answer is recorded in `DISCUSS.md` under a corresponding heading.
+3. The `@risk-analyst` agent reviews the Q&A log and adds a risk summary section.
+4. `STATE.md` is updated — set `phase: discuss`, `status: ready_to_plan`.
+
+The output of `/fd-discuss` is a signed decision log that the planner treats as authoritative input.
+
+---
+
+## /fd-plan
+
+**Purpose:** Build a wave-structured execution plan from the discuss decisions.
+
+**Files created/modified:**
+- `.planning/PLAN.md` (created)
+- `.planning/STATE.md` (phase updated)
+
+**Step-by-step:**
+
+1. The `@planner` agent reads `DISCUSS.md`, `FEATURE.md`, and `PROJECT.md`.
+2. It breaks the feature into **waves** — groups of tasks that can run in parallel within a wave, with waves ordered sequentially.
+3. Each task records: description, responsible agent, files affected, rollback plan, and dependencies.
+4. The plan is written to `PLAN.md`.
+5. The user reviews the plan. Typing `CONFIRM` (case-insensitive) proceeds to execution; anything else aborts.
+6. `STATE.md` is updated — set `phase: plan_confirmed`, `status: ready_to_execute`.
+
+Wave-structured planning prevents agents from blocking on tasks that could run in parallel. Wave 1 tasks that are independent run simultaneously. Wave 2 does not start until all Wave 1 tasks are complete.
+
+---
+
+## /fd-execute
+
+**Purpose:** Implement the feature following TDD discipline, with parallel agent delegation.
+
+**Files created/modified:**
+- Implementation files (modified)
+- `.planning/STATE.md` (phase updated)
+- `.planning/PLAN.md` (tasks marked complete)
+
+**Step-by-step:**
+
+1. The `@orchestrator` reads `PLAN.md` and iterates through waves.
+2. For each wave, it calls `run-pipeline` or `delegate` to invoke specialist agents in parallel:
+   - `@architect` — validates structural decisions before coding
+   - `@coder` — writes implementation following TDD (red/green/refactor)
+   - `@tester` — writes and runs tests alongside each implementation task
+   - `@reviewer` — reviews each completed task
+3. Each agent writes its output to the implementation files and updates `PLAN.md`.
+4. Governance hooks run after every tool execution — patch trust scoring, budget tracking, and deadlock detection.
+5. `STATE.md` is updated — set `phase: execute`, `status: in_progress`. On full completion, set `status: complete`.
+
+If the deadlock detector triggers, execution pauses and the user is notified with the bounce signal.
+
+---
+
+## /fd-verify
+
+**Purpose:** Full verification pipeline — tests, code review, security scan, and deploy check.
+
+**Files created/modified:**
+- Verification reports (printed to console)
+- `.planning/STATE.md` (phase updated)
+- `.codebase/SCORECARDS.jsonl` (new scorecard entry)
+
+**Step-by-step:**
+
+1. Run the full test suite — `@tester` executes all test commands.
+2. Run `@reviewer` on every changed file since the last phase.
+3. Run `@policy-enforcer` to validate architectural constraint compliance.
+4. Run security scan (if configured) and deploy check (if configured).
+5. Compute and print the Workflow Scorecard (10 dimensions).
+6. Write a scorecard entry to `.codebase/SCORECARDS.jsonl`.
+7. Update `STATE.md` — set `phase: verify`, `status: verified` or `status: issues_found`.
+8. If issues are found, the user decides whether to loop back to `/fd-execute` or fix manually.
+
+---
+
+## State Transition Table
+
+The following table shows how the key fields in `STATE.md` change at each phase:
+
+| Field | `/fd-map-codebase` | `/fd-new-feature` | `/fd-discuss` | `/fd-plan` | `/fd-execute` | `/fd-verify` |
+|-------|--------------------|-------------------|---------------|------------|---------------|--------------|
+| `phase` | — | `define` | `discuss` | `plan_confirmed` | `execute` | `verify` |
+| `status` | — | `in_progress` | `ready_to_plan` | `ready_to_execute` | `in_progress` → `complete` | `verified` |
+| `feature` | — | set | — | — | — | — |
+| `planConfirmed` | — | — | — | `true` | — | — |
+| `checkpoint` | — | — | — | — | on `/fd-checkpoint` | — |
+
+---
+
+## Wave-Structured Execution
+
+Wave structure is the mechanism that makes parallel execution safe.
+
+```
+Wave 1 (parallel)
+  ├── Task 1a: Write user model      → @coder
+  ├── Task 1b: Write auth service    → @coder
+  └── Task 1c: Write user tests      → @tester
+
+Wave 2 (parallel, starts after all Wave 1 tasks complete)
+  ├── Task 2a: Integrate auth        → @coder
+  └── Task 2b: Write integration     → @tester
+                tests
+
+Wave 3 (sequential)
+  └── Task 3a: Deploy configuration   → @architect
+```
+
+Dependencies between waves are explicit. Tasks within a wave are independent — no task in Wave 1 depends on another task in Wave 1. This maximizes parallelism while preserving ordering guarantees.
+
+The orchestrator enforces wave ordering. It will not dispatch Wave 2 tasks until all Wave 1 tasks report completion. If a Wave 1 task fails, the orchestrator reports the failure and stops — Wave 2 is not entered.
+
+---
+
+## Mid-Session Checkpointing
+
+Any step can be paused and resumed:
+
+```bash
+/fd-checkpoint   # Save current STATE.md snapshot
+/fd-resume       # Reload latest checkpoint and continue
+```
+
+Checkpoints are written to `.planning/STATE.md`. The `/fd-resume` command reloads `STATE.md` and `PLAN.md` (if present) and reinitializes the context for the next phase step.