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

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.