docs(future): 12k-line PROTOCOL.md cataloging per-subsystem improvements#171
Merged
Conversation
…vements Adds docs/future/PROTOCOL.md as a long-horizon, subsystem-by-subsystem improvement protocol covering every bash script, Rust crate, and cross-cutting concern in codex-fleet. Each section follows the same schema (mission, current state, pain points, improvement protocols, backlog, open questions, dependencies, risks, migration plan, out-of-scope) and every improvement carries a lifecycle state plus verification, acceptance, rollback, and metrics. Closes with section-status snapshot, dependency matrix seed, and maintainer index for fast rg lookup.
Implements the foundational governance lane of the future protocol:
the scaffolding that makes every other proposed improvement enforceable.
Tooling under scripts/protocol/:
- protocol-state.sh: lifecycle-state counts / table / list per state
- check-states.sh: assert every improvement carries one valid state line
- check-refs.sh: assert every improvement cites >=1 real path
- check-budget.sh: warn when a section exceeds 1.5x its declared budget
Templates and indices:
- docs/future/decisions/{README,_template}.md: ADR-lite scaffolding
- docs/future/reviews/{README,_template}.md: bi-weekly review scaffolding
Top-level workflow:
- justfile: protocol-state, protocol-check, protocol-check-*, ci recipes
- .editorconfig: shared editor defaults (utf-8, lf, trim trailing ws)
PROTOCOL.md gains an Implementation Log appendix that records SHIPPED
governance entries, their artifacts, and the known gaps (no ADR backfill
yet, no first review held yet, CI wiring still pending).
All four governance scripts pass against the current PROTOCOL.md.
3 tasks
NagyVikt
added a commit
that referenced
this pull request
May 20, 2026
…t sweep) (#199) Audited docs/future/PROTOCOL.md against the actual repo + git history and flipped 20 stale `state: PROPOSED` lines to `state: SHIPPED` for items whose implementation has clearly landed on main. Each item's acceptance verification command runs green and the touched script/file already implements the proposal. Updates (section → slug → representative PR): - 1.4.1 Formal lifecycle states for every improvement entry → PR #171 (scripts/protocol/{protocol-state,check-states}.sh + state lines) - 7.4.1 --help/--version on stall-watcher.sh → PR #1 - 9.4.1 --help/--version on plan-watcher.sh → PR #46 - 10.4.1 --help/--version on review-queue.sh → PR #37 - 11.4.1 --help/--version on review-pane-scanner.sh → PR #41 - 12.4.1 --help/--version on auto-reviewer.sh → PR #99 - 17.4.1 --help/--version on show-fleet.sh → PR #139 - 18.4.1 --help/--version on token-meter.sh → PR #17 - 19.4.1 --help/--version on warm-pool.sh → PR #1 - 20.4.1 --help/--version on spawn-fleet.sh → PR #1 - 21.4.1 --help/--version on dispatch-plan.sh → PR #133 - 23.4.1 --help/--version on proactive-probe.sh → PR #1 - 24.4.1 --help/--version on claim-trigger.sh → PR #1 - 27.4.1 --help/--version on claude-supervisor.sh → PR #116 - 33.4.1 --help/--version on plan-tree-pin.sh → PR #1 - 36.4.1 --help/--version on supervisor.sh → PR #1 - 37.4.1 --help/--version on patch-codex-prompts.sh → PR #1 - 39.4.1 --help/--version on down.sh → PR #1 - 41.4.1 --help/--version on add-workers.sh → PR #1 - 42.4.1 --help/--version on codex-fleet-2.sh → PR #1 Diff is exactly 20 `- state: PROPOSED` → `- state: SHIPPED` line edits in docs/future/PROTOCOL.md; nothing else touched. Both governance checks still pass: bash scripts/protocol/check-states.sh # exit 0 bash scripts/protocol/protocol-state.sh --summary # SHIPPED: 0 → 20 PR refs live in this commit body / PR description rather than inline in the state line, because both check-states.sh and protocol-state.sh require the state token to be the bare enum value (e.g. `SHIPPED`); any suffix breaks both checks. Co-authored-by: NagyVikt <nagy.viktordp@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/future/PROTOCOL.md(~12,000 lines) as a long-horizon, subsystem-by-subsystem improvement protocol for codex-fleet.scripts/codex-fleet/, every Rust crate underrust/, plus 18 cross-cutting concerns (OpenSpec, Colony, accounts, observability, security, perf, resilience, cost, UI, i18n, versioning, etc.).Notes
refsto keep entries grounded.unassignedby default and should be filled in at first review.Test plan
docs/future/PROTOCOL.mdin a markdown renderer and spot-check section anchors.wc -l docs/future/PROTOCOL.mdand confirm it lands near 12,000.refs:entries against the working tree.Generated by Claude Code