Tracking: Deliver the Codex Git macOS MVP

[codeacme17]

Summary

Deliver the first macOS MVP of Codex Git: a top-level Git page inside Codex Desktop that shows the Current Project's Repository and every registered Worktree, then supports the ordinary review, Stage, Commit, Branch switch, Fetch, fast-forward Pull, normal Push, and Publish Branch loop.

Single-Worktree users and developers coordinating multiple manual, Permanent, Codex-managed, Scheduled, detached, custom-root, or otherwise Unclassified Worktrees are equal-priority users.

MVP scope

• One Codex sidebar Git entry and one adaptive full-page master-detail surface.
• Current local macOS Project Repository only.
• Main Worktree plus every valid Worktree returned by git worktree list --porcelain -z.
• Optional provenance labels only when stable Codex-owned metadata proves them.
• Worktree summaries, truthful change groups, file diffs, file-level Stage/Unstage, Commit Drafts, Commit, existing Branch switching, Fetch, fast-forward Pull, normal Push, and Publish Branch.
• Automatic/manual local refresh, stale-state rejection, operation lanes, post-operation reconciliation, and safe supporting navigation.
• Supported release fixture: 25 active Worktrees, 2,000 Changed Files, and 5,000 Local/Remote-tracking refs.

Non-goals

• Windows, Linux, or remote Git execution environments.
• Worktree or general Branch create/delete/rename/move/prune workflows.
• Hunk staging, discard, stash, reset, clean, merge, rebase, cherry-pick, conflict resolution, graph, blame, history, or generalized undo.
• Force push, tag push, remote Branch deletion, pull requests, checks, GitHub APIs, credential setup, submodule workflows, or Git LFS management.
• Modifying the Codex task list.

Architecture constraints

• Keep the unsupported Codex CDP/DOM integration behind a replaceable Host Adapter with a standalone fallback adapter.
• Run all Git reads and mutations in a local Repository Engine; the browser UI must not execute a shell or construct Git arguments.
• Use opaque IDs and versioned snapshots. UI state never authorizes a mutation without fresh server-side precondition checks.
• Discover Worktrees from Git registration. Provenance never filters inclusion or capabilities.
• Serialize local mutations per Worktree, all Branch switches per Repository, and all remote operations per Repository. Do not silently queue user mutations.
• Reconcile HEAD, Index, refs, and Upstream after every attempted mutation, including interruption and timeout.
• Never remove external locks, rewrite history, auto-stash, or collect credentials.

Development roadmap

Phase 0 — Record decisions and establish the workspace

1. Add the decision-complete MVP product and architecture documentation #2 checks the decision-complete PRD, domain language, architecture, and ADRs into the repository.
2. Bootstrap the TypeScript workspace and standalone runtime #3 establishes the Node.js/TypeScript workspace, placeholder surface, loopback server scaffold, public module boundaries, and baseline verification.

Exit: a clean checkout installs, checks, tests, and builds without containing Git product behavior.

Phase 1 — Retire the highest-risk integration boundaries

After #3, run these in parallel:

• Prove the Codex sidebar and standalone Host Adapters #4 proves both Host Adapters, Codex sidebar mounting, remount/cleanup, and fail-closed standalone fallback.
• Implement the versioned loopback protocol and security boundary #5 implements the versioned loopback protocol, opaque targets, instance security, typed outcomes, and redaction boundary.

Exit: the placeholder page can run through a safe local protocol in standalone mode and can be mounted/removed safely in supported Codex builds.

Phase 2 — Deliver the read-only vertical slice

1. Discover registered Worktrees with generation-safe identity #6 resolves the Current Project and discovers every registered Worktree with generation-safe identity.
2. Implement versioned refresh, operation lanes, and reconciliation #7 adds coherent snapshots, refresh generations, operation lanes, and reconciliation primitives.
3. Build the adaptive Repository and Worktree overview #8 builds the adaptive Repository/Worktree overview against those snapshots.
4. Implement truthful change classification and diff review #9 adds truthful Change Groups and on-demand diff review.

Exit: AC-01 through AC-06 and the read-only portions of AC-21 through AC-24 pass in both standalone and supported Codex-hosted surfaces.

Phase 3 — Complete MVP workflows in parallel lanes

Once #9 is available, four lanes can progress independently where their listed dependencies are satisfied:

• Local Index/Commit: Implement safe file-level Stage and Unstage #10 → Implement Worktree-scoped Commit and outcome recovery #11
• Branch switching: Implement Branch discovery, occupancy, and safe switching #12
• Remote operations: Implement Remote discovery and Fetch #13 → Implement fast-forward Pull, normal Push, and Publish Branch #14
• Host navigation/provenance: Add exact-target navigation and optional Codex provenance #15

Exit: every mutation has fresh preconditions, scoped coordination, typed results, and post-operation reconciliation; AC-07 through AC-23 pass.

Phase 4 — Converge, harden, and package

1. Enforce the MVP acceptance, performance, accessibility, and security gate #16 integrates AC-01 through AC-24 into the release gate and proves performance, accessibility, host compatibility, race safety, and security.
2. Package and document the signed macOS application #17 packages the already-proven runtime as a signed/notarized macOS application and runs the same release gate against the package.

Exit: the complete MVP definition of done below is satisfied.

Dependency graph

flowchart TD
  I2["#2 Product and architecture docs"] --> I3["#3 Workspace bootstrap"]
  I3 --> I4["#4 Host Adapters"]
  I3 --> I5["#5 Protocol and security"]
  I3 --> I6["#6 Worktree discovery"]
  I5 --> I6
  I5 --> I7["#7 Refresh and concurrency"]
  I6 --> I7
  I4 --> I8["#8 Overview UI"]
  I5 --> I8
  I6 --> I8
  I7 --> I8
  I6 --> I9["#9 Change review"]
  I7 --> I9
  I8 --> I9
  I7 --> I10["#10 Stage and Unstage"]
  I9 --> I10
  I7 --> I11["#11 Commit"]
  I10 --> I11
  I6 --> I12["#12 Branch switching"]
  I7 --> I12
  I8 --> I12
  I6 --> I13["#13 Fetch"]
  I7 --> I13
  I8 --> I13
  I7 --> I14["#14 Pull, Push, Publish"]
  I13 --> I14
  I4 --> I15["#15 Navigation and provenance"]
  I6 --> I15
  I8 --> I15
  I9 --> I15
  I4 --> I16["#16 MVP release gate"]
  I5 --> I16
  I6 --> I16
  I7 --> I16
  I8 --> I16
  I9 --> I16
  I10 --> I16
  I11 --> I16
  I12 --> I16
  I13 --> I16
  I14 --> I16
  I15 --> I16
  I4 --> I17["#17 macOS package"]
  I5 --> I17
  I16 --> I17

Loading

The dependency-critical chain is #2 → #3 → #5 → #6 → #7 → #8 → #9 → #10 → #11 → #16 → #17. This is a sequencing constraint, not a duration estimate; #4, #12, #13–14, and #15 should run in parallel when unblocked.

Dependency matrix

Issue	Primary deliverable	Hard dependencies	Unblocks
#2	Product, domain, architecture, and ADR record	None	#3
#3	Runnable initial workspace	#2	#4, #5, #6
#4	Codex and standalone Host Adapters	#3	#8, #15, #16, #17
#5	Local protocol and security boundary	#3	#6, #7, #8, #16, #17
#6	Repository/Worktree discovery and identity	#3, #5	#7, #8, #9, #12, #13, #15, #16
#7	Versioned refresh, operation lanes, reconciliation	#5, #6	#8–14, #16
#8	Adaptive overview UI	#4, #5, #6, #7	#9, #12, #13, #15, #16
#9	Change classification and diff review	#6, #7, #8	#10, #15, #16
#10	Safe Stage/Unstage	#7, #9	#11, #16
#11	Commit and outcome recovery	#7, #10	#16
#12	Branch discovery, occupancy, switching	#6, #7, #8	#16
#13	Remote discovery and Fetch	#6, #7, #8	#14, #16
#14	Fast-forward Pull, normal Push, Publish	#7, #13	#16
#15	Exact-target navigation and optional provenance	#4, #6, #8, #9	#16
#16	Complete MVP release gate	#4–15	#17
#17	Signed macOS package and release docs	#4, #5, #16	MVP release

Delivery rules

• A dependent implementation may be explored early, but it must not merge before every hard dependency it consumes has landed.
• Keep each issue independently testable, reviewable, revertible, and within the repository's PR size budget.
• Use issue branches named <type>/<short-description>-<issue-number>.
• Each PR must list its acceptance criteria, focused verification, dependency state, and known out-of-scope defects with tracking links.
• Git inclusion/capability must never wait on Codex provenance work in Add exact-target navigation and optional Codex provenance #15.
• Packaging work must not duplicate or fork Repository Engine behavior.
• Closing Enforce the MVP acceptance, performance, accessibility, and security gate #16 requires evidence for every AC-01 through AC-24 row; closing Package and document the signed macOS application #17 requires rerunning that gate against the packaged artifact.

Release acceptance

The MVP is complete only when all linked implementation issues are closed and the release suite proves:

• non-repositories and missing/prunable Worktrees degrade without mutation;
• Main and all valid linked Worktrees appear exactly once;
• staged/unstaged dual-state paths, renames, deletions, binary, oversized, undecodable, and untracked files render truthfully;
• stale file, Index, HEAD, ref, occupancy, and Upstream observations cannot authorize writes;
• Initial and Detached HEAD Commit behavior, hooks/signing failures, locks, and ambiguous outcomes are safe;
• Branch occupancy and clean-switch rules are enforced;
• Fetch partial success, fast-forward-only Pull, exact-Upstream Push, and Publish Branch never escalate to history rewriting;
• offline/auth/permission/policy failures are distinct and secrets are redacted;
• independent Worktrees may mutate concurrently while Repository-wide conflicts cannot;
• Worktree disappearance/restoration and navigation races fail safely;
• timing, keyboard, focus, assistive-technology, and non-color requirements pass at the supported scale.

Progress checklist

Product and architecture record

• Add the decision-complete MVP product and architecture documentation #2

Runtime foundation and host boundary

• Bootstrap the TypeScript workspace and standalone runtime #3
• Prove the Codex sidebar and standalone Host Adapters #4
• Implement the versioned loopback protocol and security boundary #5

Read-only Repository vertical slice

• Discover registered Worktrees with generation-safe identity #6
• Implement versioned refresh, operation lanes, and reconciliation #7
• Build the adaptive Repository and Worktree overview #8
• Implement truthful change classification and diff review #9

Git mutations and remote workflows

• Implement safe file-level Stage and Unstage #10
• Implement Worktree-scoped Commit and outcome recovery #11
• Implement Branch discovery, occupancy, and safe switching #12
• Implement Remote discovery and Fetch #13
• Implement fast-forward Pull, normal Push, and Publish Branch #14

Integration and release

• Add exact-target navigation and optional Codex provenance #15
• Enforce the MVP acceptance, performance, accessibility, and security gate #16
• Package and document the signed macOS application #17

Definition of done

• Every child issue has focused automated verification and stays within the repository PR size budget.
• All release-blocking acceptance scenarios pass on the supported macOS reference machine.
• The standalone surface remains functional if the Codex Host Adapter is removed.
• Installation clearly discloses the local CDP trust boundary and unsupported host integration.