Skip to content

Roadmap and Agentic Workflow

Jump to bottom
Sasha Lopashev edited this page Jul 19, 2026 · 65 revisions

Roadmap and Agentic Workflow

The roadmap is a live dependency graph, not a flat backlog. Every managed issue has one milestone, one status/priority/kind/risk, at least one area, one concurrency declaration, test/evidence criteria, documentation impact, and GitHub-native blocker relationships. Native dependencies are authoritative; each issue body mirrors them for humans.

Four phases

Phase Outcome Live milestone Current state
1 Complete executable self-hosted behavior over the minimal kernel Phase 1 all, required CI, and the repository agent contract are implemented; protected auto-merge and the remaining algebra are open
2 Make coding-agent evidence reproducible and executable in-session Phase 2 Pilots 001–005 merged; Pilot 006 #21 claimed; adapter/controller work open
3 Compose and enforce monotonic organization/user policy Phase 3 Active design frontier; typed lattice decision #29 is in review
4 Add safe custom syntax and presentation layouts Phase 4 Intentionally blocked behind Phase 3 conformance

Current claimable queue

Priority is considered only among issues with no open native blockers and an available concurrency token.

Required CI and the repository-local operating contract are now merged. The coordinator should establish #14 next, while Phase 2 and Phase 3 review reconciliation proceeds under their retained locks.

Status and dependency rules

  • status:ready: open and every native blocker is closed.
  • status:claimed: authoritative issue/resource refs were atomically acquired.
  • status:blocked: at least one native blocker is open.
  • status:review: implementation is delivered and locks remain held through review.
  • status:done: merged, verified, and closed.
  • status:stale: a claim needs evidence-based recovery; it is not permission to steal a lock.

Blocked issues must not be started early. Closing a blocker promotes a dependent issue to ready only after its remaining blockers and resource capacity are rechecked.

Atomic claims

Labels, assignment, and comments are metadata, not locks. Cross-machine exclusion uses unique remote Git refs:

  • refs/heads/codex-locks/issues/<number> — one worker per issue.
  • refs/heads/codex-locks/mutex/<resource> — exclusive shared resource.
  • refs/heads/codex-locks/semaphore/<resource>/<slot> — bounded capacity, slots 1..N only.

The coordinator creates all required resource refs and the issue ref atomically, then changes the label, assigns the worker, and comments with agent/task, timestamp, branch, worktree, scope, ref paths, exact SHAs, and unique nonces. A worker keeps those refs through review.

Release is a compare-and-delete fenced by the acquired SHA. If the lease fails, ownership was lost: do not delete the newer ref. Stale recovery requires inspecting the claim comment, task, branch, worktree, PR, and recent activity, then documenting the decision.

Delivery loop

  1. Select the highest-priority ready issue whose concurrency token is available.
  2. Atomically claim it and make the metadata match the lock.
  3. Work red-first where practical; keep Rust models, CDDL, SEMANTICS, README, conformance fixtures, and wiki claims aligned.
  4. Run formatting, Clippy with warnings denied, all tests, release build, and issue-specific evidence.
  5. Open a linked PR; move the issue to status:review but retain all locks.
  6. Independently review the exact head SHA. Merge only a green, unchanged head with squash merge and branch deletion.
  7. Close the issue, mark status:done, promote newly unblocked dependents, and release only the exact held refs with fenced deletion.

The reusable project loop is now repository-configured through AGENTS.md and .codex/project-profile.md. Those files are the executable operating contract; this page summarizes them, and live native issue dependencies remain authoritative.

BHCP

Canonical sources

Clone this wiki locally