139 lines
4.9 KiB
Markdown
139 lines
4.9 KiB
Markdown
# 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.
|