Prove Psyche Build as the first Psyche-conforming reference client

[BunsDev]

Outcome

Prove Psyche Build as the first conforming Psyche reference client through a pinned, versioned adapter and compatibility canary—without rewriting the product or replacing current user workflows in one step.

Parent roadmap: #9
Cross-repository owner: OpenCoven/psyche-build#201
Priority: P1 after #11 publishes a consumable profile
Target phase: Phase 2 — Sep 30–Oct 20, 2026
Accountable owner: @BunsDev

Migration principle

Psyche Build remains the coding cockpit. Psyche becomes the canonical orchestration protocol. Existing pane, task, lane, worktree, branch, tmux, provider, lease, approval, receipt, and recovery behavior is wrapped behind adapters and migrated in bounded slices.

Delivery slices

1. Inventory and mapping

   • map current Psyche Build records/state transitions to Psyche records;
   • classify exact matches, adapters, gaps, and intentional product-local state;
   • identify any current authority inferred from UI/process state.

2. Pinned conformance canary

   • pin one immutable Psyche protocol artifact/profile;
   • run positive and negative vectors in Psyche Build CI;
   • fail on unknown major, widening, stale correlation, ambiguous effect, or incompatible downgrade.

3. Identity adapter

   • introduce protocol-owned task/lane/attempt/action/receipt IDs alongside existing local IDs;
   • preserve current persistence and UI behavior;
   • record reversible migration and rollback.

4. Lifecycle adapter

   • map lease, approval, receipt, cancellation, recovery, and terminal-state semantics;
   • preserve fail-closed behavior and idempotency;
   • remove product-local duplication only after canaries prove equivalence.

5. Reference flow

   • desktop task start → isolated lane → execution/evidence → consequential action/approval → receipt → disconnect/restart → same identity resumes;
   • later extend to iOS observation/approval after the same-LAN readiness train is stable.

Acceptance criteria

• Psyche Build pins an immutable Psyche protocol/profile artifact.
• CI runs positive, denial, restart, ambiguity, and downgrade canaries.
• Product-local pane/worktree/tmux/provider IDs cannot become protocol identity.
• Existing macOS v0.0.1 behavior and support claims remain intact during migration.
• Every migrated mutation retains project scope, authority, approval, idempotency, receipt, revocation, and recovery semantics.
• A failed adapter migration can roll back without data loss or identity fork.
• One executable reference flow preserves identity through restart.
• OpenCoven/psyche-build#201 links the final conformance evidence.

Dependencies

• Publish Psyche protocol v1 schemas, golden vectors, and conformance runner #11 protocol v1 publication.
• Define OpenCoven cross-repository protocol ownership and compatibility #12 ownership and compatibility decision.
• Psyche Build stabilization and contract-preserving decomposition sequencing remain governed by its active roadmap.

Non-goals

• A whole-product rewrite.
• Making Psyche integration an undeclared blocker for already-supported macOS operation.
• Replacing tmux, Git worktrees, or the UI solely for architectural purity.
• Treating Beads as runtime task identity.
• Inferring Threads execution before the protocol adapter actually exists.

Evidence

Link the Psyche release pin, mapping document, focused adapter PRs, cross-repository CI runs, migration/rollback proof, and reference-flow receipt chain.

[BunsDev]

Reference-client work has begun at the mapping layer

The cross-repository mirror is live in OpenCoven/psyche-build#253, with draft PR OpenCoven/psyche-build#254 at head 264a5f68e64cbdc393c1f4a15b6c770da6bdbd5a.

That PR establishes:

• a current-main inventory of product-local task/trace/operation/lane, lease, approval, receipt, journal, fencing, and recovery-related seams;
• an explicit mapping matrix and semantic-gap list;
• a proposed bounded adapter package;
• the staged path: inventory → immutable profile pin → canary → dual identity → lifecycle adapters → restart/reconnect reference flow;
• a hard boundary that Beads, GitHub, panes, tmux, processes, worktrees, provider sessions, transports, and UI selection cannot become protocol identity.

Current status is Stage 0 mapping only. There is no immutable Psyche profile yet, no compatibility pin, no adapter migration, and no conformance claim. Those remain blocked on #11 and #12.