Skip to content

docs(protocol): sweep 20 stale PROPOSED → SHIPPED state lines#199

Merged
NagyVikt merged 1 commit into
mainfrom
agent/claude/protocol-state-drift-sweep-2026-05-18-16-53
May 20, 2026
Merged

docs(protocol): sweep 20 stale PROPOSED → SHIPPED state lines#199
NagyVikt merged 1 commit into
mainfrom
agent/claude/protocol-state-drift-sweep-2026-05-18-16-53

Conversation

@NagyVikt
Copy link
Copy Markdown
Contributor

Summary

Audit pass over docs/future/PROTOCOL.md: every #### X.4.Y improvement
carrying state: PROPOSED was checked against the actual repo + git
history. 20 items have clearly already shipped on main and are flipped
to SHIPPED here. Single-file, fully reversible change.

State counts (before → after)

State Before After
PROPOSED 156 136
ACCEPTED 0 0
SCHEDULED 0 0
IN-PROGRESS 0 0
SHIPPED 0 20
DEFERRED 0 0
REJECTED 0 0

Updates (section → slug → representative PR)

Why bare SHIPPED, not SHIPPED (PR #N)

Both scripts/protocol/check-states.sh and
scripts/protocol/protocol-state.sh parse the state token verbatim:
check-states.sh's awk validates against an exact enum
({PROPOSED, ACCEPTED, SCHEDULED, IN-PROGRESS, SHIPPED, DEFERRED, REJECTED})
and protocol-state.sh counts via ^- state: SHIPPED$. A (PR #N)
suffix would break both. PR refs are captured here in the PR body and
in the commit message instead.

Audit method

For each PROPOSED item I required:

  • (a) every path in the proposal's **References.** block exists in the repo, and
  • (d) the file's content visibly implements the proposal (e.g. the script's
    arg parser handles --help).

I additionally cross-checked with git log -S '--help' -- <path> to find a
representative PR whose theme matches the proposal. For §1.4.1 the
referenced governance tooling (scripts/protocol/{protocol-state,check-states}.sh)
plus the state lines themselves were shipped under PR #171.

Acceptance evidence

$ bash scripts/protocol/check-states.sh
check-states: ok          # exit 0

$ bash scripts/protocol/protocol-state.sh --summary
protocol-state docs/future/PROTOCOL.md
  PROPOSED     136
  ACCEPTED     0
  SCHEDULED    0
  IN-PROGRESS  0
  SHIPPED      20         # 0 → 20
  DEFERRED     0
  REJECTED     0

$ git diff main -- docs/future/PROTOCOL.md | grep -c '^-.*state: PROPOSED'
20
$ git diff main -- docs/future/PROTOCOL.md | grep -c '^+.*state: SHIPPED'
20

Spot-check evidence (3 items)

# §1.4.1
$ bash scripts/protocol/protocol-state.sh --summary
protocol-state docs/future/PROTOCOL.md
  ... SHIPPED 20 ...
exit=0

# §17.4.1
$ bash scripts/codex-fleet/show-fleet.sh --help
Usage: show-fleet.sh [--rebuild] [--no-kitty] [-h|--help]
...
exit=0

# §19.4.1
$ bash scripts/codex-fleet/warm-pool.sh --help
Usage: warm-pool.sh <command>
...
exit=0

Test plan

  • CI: bash scripts/protocol/check-states.sh passes
  • CI: bash scripts/protocol/protocol-state.sh --summary runs without
    error and reports SHIPPED count = 20
  • Diff is exactly 20 lines flipped; no other content change

Risks / follow-ups

  • Items §3.4.1, §4.4.1, §5.4.1, §6.4.1, §8.4.1, §13.4.1, §14.4.1, §15.4.1,
    §16.4.1, §22.4.1, §25.4.1, §26.4.1, §28.4.1, §29.4.1, §30.4.1, §31.4.1,
    §32.4.1, §34.4.1, §35.4.1, §38.4.1, §40.4.1 (--help/--version for other
    scripts) were left as PROPOSED because the target script currently
    lacks --help on main or is in flight on another agent branch. The
    parallel agent A is wiring --help/--version into a few of these
    (cap-probe, score-checkpoint, force-claim); that lane will sweep them
    in a follow-up PR.
  • Item §26.4.1 (claude-spawn.sh) was deliberately skipped — the script
    has a --help flag but a pre-arg-parse env precheck fatals before
    --help is reached.
  • All *.4.2 (structured logging) proposals stay PROPOSED — no script
    emits level= structured lines yet.
  • All rustdoc X.4.1 proposals (43–54.4.1) stay PROPOSED — every crate
    has < 50 lines of //! docs.
  • §1.4.2 (captains), §2.4.1 (full justfile), §2.4.2 (script reorg) stay
    PROPOSED — acceptance criteria not yet met.

…t sweep)

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.
@NagyVikt NagyVikt merged commit 9e1be37 into main May 20, 2026
1 check 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