Skip to content

feat(parity): CI-enforced multi-surface parity harness#591

Merged
bborn merged 1 commit into
mainfrom
feat/parity-harness
Jun 11, 2026
Merged

feat(parity): CI-enforced multi-surface parity harness#591
bborn merged 1 commit into
mainfrom
feat/parity-harness

Conversation

@bborn

@bborn bborn commented Jun 11, 2026

Copy link
Copy Markdown
Owner

Makes CLI/TUI/GUI parity drift a build failure instead of a thing to watch for.

How it works

  1. The TUI's capability surface is derived mechanically from ui.KeyMap — every exported key.Binding field is a user-facing action (38 today). No manual list to forget to update.
  2. Every action must be either covered in desktop/capabilities.json or explicitly ignored in parity-ignore.json with a written reason. An uncovered action fails CI with instructions:
    GUI parity gap: TUI action "Routines" is not covered by desktop/capabilities.json.
    Either implement it in the GUI and add it to the manifest, or explicitly skip it
    by adding it to parity-ignore.json with a reason.
    
  3. Capabilities may declare the API routes they use ("api": ["POST /api/tasks/{id}/execute"]); these are verified against the routes actually registered in internal/web/server.go (AST-parsed). The manifest can't reference endpoints that don't exist — and deleting a route the GUI depends on fails too.
  4. Stale entries fail: covering or ignoring an action that no longer exists in the keymap is an error, so the files can't rot.

Runs as a plain go test in the existing Test job — no new CI wiring.

Current state, encoded honestly

  • Routines → ignored with a dated reason (GUI view not built yet; needs /api/routines first). Removing the ignore entry is the signal the gap closed.
  • SpotlightSync, ToggleShellPane → deliberate non-goals with reasons (the GUI terminal shows the whole tmux window; Spotlight export is local-indexing).
  • Everything else (35 actions) is covered.

AGENTS.md codifies the underlying rule: a feature isn't done until its logic lives below internal/ui and is reachable through the API — UIs are thin views.

Both failure modes verified by mutation (removed an ignore → gap failure; pointed a capability at a fake route → route failure).

🤖 Generated with Claude Code

With CLI, TUI, and GUI sharing one core, parity drift is now a build
failure instead of a thing to remember:

- internal/parity derives the TUI's capability surface mechanically
  from ui.KeyMap (every exported key.Binding field is an action)
- every action must be covered in desktop/capabilities.json or
  explicitly skipped in parity-ignore.json with a written reason —
  uncovered actions fail CI with instructions
- capabilities may declare the API routes they use; these are verified
  against the routes registered in internal/web/server.go (parsed via
  AST), so the manifest can't reference endpoints that don't exist
- stale covers/ignores (actions that no longer exist) also fail, so
  the files can't rot

Current state encoded honestly: Routines is an acknowledged ignore
(GUI view not built yet); SpotlightSync and ToggleShellPane are
deliberate non-goals with reasons. AGENTS.md codifies the rule:
a feature isn't done until its logic lives below internal/ui and is
reachable through the API.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@bborn bborn merged commit e23de2f into main Jun 11, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant