feat(graph): Implement Graph View with Dagre Layout and Epic Scope (bb-18e)

docs/plans/2026-02-13-multi-project-ui-contract.md

@@ -0,0 +1,139 @@
+# Multi-Project UI Contract (bb-6aj.6)
+
+Date: 2026-02-13  
+Owner: `bb-6aj.6`  
+Scope: Convert existing registry/scanner backend into stable, user-facing project scope workflows for Kanban and Graph.
+
+## 1) Product Workflow Contract
+
+Primary user flow:
+1. Select project scope (`local` or one registry project).
+2. View project-scoped issues in Kanban and Graph using the same selected scope.
+3. Manage registry roots (add/remove) from a single shared manager panel.
+4. Discover import candidates from safe scan roots and add selected projects to registry.
+5. (Later phase) Optionally switch to aggregate mode for cross-project read-only views.
+
+Rules:
+- Project scope is always explicit in URL query (`?project=`).
+- Scope change affects reads only; mutations continue to target current scope root.
+- Project scope must persist when navigating between `/` and `/graph`.
+- No direct JSONL writes at any point.
+
+## 2) Screen Ownership
+
+Kanban (`/`):
+- Primary triage and mutation workspace.
+- Owns project scope picker entry point and registry manager entry.
+- Displays selected project context in header.
+
+Graph (`/graph`):
+- Readability-first dependency exploration for selected scope.
+- Shares same project scope query + model as Kanban.
+- Must preserve current scope when linking back to Kanban.
+
+Shared controls:
+- Project scope resolver utility (server-safe).
+- URL serialization/parsing for project selection.
+- Scope badge/pill visual token (consistent across pages).
+
+Out of scope for this contract:
+- Timeline/session epics behavior changes.
+- Full graph redesign beyond scope persistence/read correctness.
+
+## 3) URL and State Contract
+
+Query key:
+- `project`: scope key string.
+
+Key encoding:
+- `local`: current workspace (`process.cwd()`).
+- registry project: `windowsPathKey(project.path)` derived from registry entry.
+
+Resolution behavior:
+1. Build scope options: `local` + registry projects (dedup by key).
+2. If `project` query matches an option key, use that root.
+3. If missing or invalid, fallback to `local`.
+4. Reads use resolved root; returned issues include resolved `project` context.
+
+Navigation behavior:
+- `Kanban -> Graph` carries `?project=<key>`.
+- `Graph -> Kanban` carries `?project=<key>`.
+- Any scope picker action rewrites URL query without losing active route.
+
+## 4) Aggregate Mode Contract (Deferred to bb-6aj.11)
+
+- Aggregate mode is read-only across multiple project roots.
+- Aggregate mode does not become default.
+- Aggregate mode must visually mark per-project source on each card/row.
+- Mutations from aggregate mode are disabled until explicit target scope is chosen.
+
+## 5) Empty and Error States
+
+No projects in registry:
+- Show local project as selected.
+- Show non-blocking empty hint in manager panel.
+
+Invalid query key:
+- Fallback to local scope.
+- Keep page functional; do not hard fail.
+
+Read failure for selected root:
+- Preserve selected scope in UI.
+- Show actionable error card with path and retry affordance.
+
+Scanner failures:
+- Show root-level failure summary with skipped/error counts.
+- Do not alter current selection automatically.
+
+## 6) Phased Execution Plan
+
+Phase A (`bb-6aj.7`): Shared scope model + URL persistence
+- Add server utility to resolve active scope from query + registry.
+- Wire `/` and `/graph` to resolved scope.
+- Ensure cross-links preserve `?project=`.
+
+Phase B (`bb-6aj.8`): Registry manager panel
+- List registry projects with add/remove actions.
+- Validate Windows absolute paths with clear error text.
+
+Phase C (`bb-6aj.9`): Scanner UX
+- Scan safe roots with mode/depth controls.
+- Allow selective import to registry.
+
+Phase D (`bb-6aj.10`): Project-scoped reads in core views
+- Ensure all read endpoints/components use selected scope root.
+- Validate no regressions in local-only flow.
+
+Phase E (`bb-6aj.11`): Aggregate mode
+- Add cross-project read view with project badges.
+- Keep mutations disabled without explicit project selection.
+
+Phase F (`bb-6aj.12`): Verification and guardrails
+- Typecheck + tests + Playwright evidence at required breakpoints.
+
+## 7) Acceptance Criteria Matrix
+
+Functional:
+- Same `project` key yields same root and same issue set on both pages.
+- Invalid `project` key falls back to local root cleanly.
+- Route transitions preserve selected scope.
+
+Boundary safety:
+- No direct `.beads/issues.jsonl` writes.
+- Existing mutation API boundaries unchanged.
+
+Verification:
+- Unit tests for scope resolution and URL behavior.
+- Existing tests remain green.
+- Playwright captures prove scope persistence on `/` and `/graph`.
+
+## 8) Risks and Mitigations
+
+Risk: Query value leaks absolute paths.
+- Mitigation: use opaque normalized key, not raw path.
+
+Risk: Registry drift vs URL key stale.
+- Mitigation: deterministic fallback to local + visible selected-scope indicator.
+
+Risk: UX churn from adding controls too early.
+- Mitigation: enforce phase order and keep Phase A minimal.