plan: redesign §17.1 SUPERSEDED + §17.7 v2.2 walk-back + §10 status

| 1 — protocol doc + prompts | ✓ done | `361da1c` orchestration.md v2; `305fc4c` Analyst/Developer/Integrator prompt sync; `33d8244` Administrator-prompt.md; `63a686e` dry-run.md F2/F4/F5 + cadence; `b8186ea` initialization.md §0 banner + §11 verification; `3fea979` Initialization-prompt.md (v1 fallback) + §0 banner |

| 2 — supporting scripts | ✓ done | `~/.claude/state/agent-statusline.sh` (user-scoped, mode 700, not committed); `511590f` plan/scripts/poll-wrapper-{Analyst,Developer,Integrator,Administrator}.sh (mode 700) |

| 3 — Stop hook + recap-key discovery | ✓ done | `~/.claude/settings.json` Stop hook + `~/.claude/state/restore-statusline.sh` (user-scoped, not committed); §4.4 addendum + §11.2 resolution annotation in this doc |

| **v2.1 — reviewer-feedback follow-on** | ✓ done | `26e6173` orch v2.1; `98ec73e` Administrator read-only; `fdf3749` Developer triage cleanup + /effort medium + initialization.md §0 split; `410b2b6` cleanup-dry-run-refs.sh. **See §17 of this doc for the design change.** |

| 4 — second dry run | pending | (next session — do not start without re-reading §10.5; dry-run will leave a cleaner end-state under v2.1 because triage/* are now deleted post-merge) |

| **v2.1 — reviewer-feedback follow-on** | ✓ done (Administrator-allowlist part SUPERSEDED by v2.2 §17.7; the rest stands) | `26e6173` orch v2.1; `98ec73e` Administrator read-only [SUPERSEDED]; `fdf3749` Developer triage cleanup + /effort medium + initialization.md §0 split; `410b2b6` cleanup-dry-run-refs.sh. **See §17 of this doc.** |

| **v2.2 — Administrator allowlist re-scoped to Phase 1** | ✓ done | `67d1276` orch v2.2; `11d1708` Administrator-prompt.md v2.2; `6061a71` initialization.md + Initialization-prompt.md v2.2 banners; `620513c` communication-paths.md (NEW). **See §17.7 of this doc.** |

| 4 — second dry run | pending | (next session — do not start without re-reading §10.5; dry-run will leave a cleaner end-state under v2.2 because triage/* are now deleted post-merge and Administrator Phase 1 self-verifies §2.5) |

| 5 — production orchestration | pending | (after phase 4 is clean) |

### 10.1 Phase 0 — review and approve (this session, immediate)

moved between v2 and v2.1 without having to diff the protocol docs

against this redesign plan.

### 17.1 Administrator is read-only on the repository

### 17.1 Administrator is read-only on the repository (SUPERSEDED — see §17.7)

**Change.** The Administrator agent's allowlist (was: `init-check-*`

+ optional `admin-status-<ISO-date>-<host>`) becomes **empty**. No

push, no delete, no fetch (cheap `git ls-remote` only). The

allowlist documented in §5.2 of this plan is therefore obsolete

under v2.1; orchestration.md §8 v2.1 is the new canonical spec.

**v2.1 change.** The Administrator agent's allowlist (was:

`init-check-*` + optional `admin-status-<ISO-date>-<host>`)

becomes **empty**. No push, no delete, no fetch (cheap

`git ls-remote` only).

**Why.** Reviewer: *"I do not want the Administrator to write

anything to the repository."* Spirit: minimize the Administrator's

blast radius, since its job is reporting and the rest of the

protocol does not depend on it writing anything.

**Consequence for §15.2 verification block.** Initialization.md

§2.5 (write-capability verification: push + delete a scratch

`init-check-*` ref) cannot be performed by Administrator phase 1

under v2.1. Resolution: §2.5 becomes the responsibility of the

user (manual run of the seven §2.5 commands) OR the v1 standalone

`Initialization-prompt.md` session (which retains its narrow

`init-check-*` push allowlist and is now the canonical

agent-driven path for §2.5). Administrator phase 1 asks the user

to confirm "verified" before entering phase 2.

**Consequence at v2.1.** Initialization.md §2.5 (write-capability

verification: push + delete a scratch `init-check-*` ref) cannot

be performed by Administrator Phase 1 under v2.1. Resolution: §2.5

becomes the responsibility of the user (manual run of the seven

§2.5 commands) OR the v1 standalone `Initialization-prompt.md`

session (which retains its narrow `init-check-*` push allowlist

and is now the canonical agent-driven path for §2.5).

Administrator Phase 1 asks the user to confirm "verified" before

entering Phase 2.

> **SUPERSEDED by v2.2 (see §17.7).** The reviewer walked this

> back on second look: the user-confirmation gate and the

> dependency on the v1 fallback for routine startup were

> ergonomically expensive for a small "blast radius" win. v2.2

> restores Phase 1 push capability under a strictly **phase-scoped**

> `init-check-*` allowlist (dropped at the Phase 1 → Phase 2

> boundary, irrevocably); Phase 2 stays strictly read-only. The

> spirit of the original concern — bound the Administrator's blast

> radius — is preserved by the phase-scope and the irrevocable

> transition. orchestration.md §8 v2.2 is the canonical spec; this

> §17.1 is preserved as historical record only.

### 17.2 Minimize ref detritus — Developer triage cleanup

### 17.6 Open items for the next session

- §5.2 of this plan (Administrator's old allowlist) is left

  in-place as historical record but is no longer the canonical

  spec under v2.1. If the v3 pass revisits Administrator's role

  (e.g. bounded autonomous recovery), §5.2 is the place to start

  reasoning from.

- §5.2 of this plan (Administrator's old v2 allowlist) is left

  in-place as historical record. Under v2.2 it is *partially*

  reinstated: Phase 1 has the `init-check-*` allowlist;

  `admin-status-<ISO-date>-<host>` (the multi-machine

  peer-discovery tag) was dropped in v2.1 and stayed dropped in

  v2.2. If a v3 pass needs cross-machine peer-Administrator

  awareness, §5.2 is the place to start reasoning from.

- §15.2 verification block (already canonicalized in

  initialization.md §11) remains read-only; the §2.5 split is

  documented in initialization.md §0 banner.

- Phase 4 (second dry run) is unchanged — it just now runs

  against the v2.1 protocol and should leave a cleaner end-state

  (no triage/* survivors).

  initialization.md §11) is now performed by Administrator

  Phase 1 itself under the v2.2 phase-scoped allowlist, in

  addition to all the read-only checks. The §2.5 split (which

  v2.1 had) collapses back into "Administrator does the whole

  thing during Phase 1" under v2.2.

- Phase 4 (second dry run) is unchanged — it just now runs against

  the v2.2 protocol and should leave a cleaner end-state (no

  triage/* survivors, no admin-status-* survivors, no init-check-*

  survivors).

### 17.7 v2.2 walk-back (Administrator allowlist re-scoped to Phase 1)

**Reviewer reflection (second pass on §17.1).** *"I wonder if my

knee-jerk reaction and statement 'I do not want the Administrator

to write anything to the repository' was ill-conceived. It seems

the exception is overly cumbersome. Would a cleaner resolution be

to allow the Administrator to write to the repository during its

Phase 1? Then in Phase 2 remove that authorization?"*

**v2.2 change.** Administrator's push allowlist becomes

**phase-scoped**:

- **Phase 1:** `init-check-<YYYYMMDD-HHMMSS>-*` branches and tags

  (and their deletions) — the same allowlist as the v1 standalone

  Initialization session. All such refs are deleted at the end of

  Phase 1.

- **Phase 2:** **empty.** Strictly read-only on `{remote}` —

  `git ls-remote` only.

- The Phase 1 → Phase 2 transition is **irrevocable**: once the

  Administrator declares "Phase 1 complete," the in-memory

  allowlist drops to empty for the rest of the session. Re-init

  after credential rotation goes through the v1 fallback session,

  not Administrator re-entry.

**Why this is the right size.**

- *Spirit preserved.* The reviewer's original concern (bound the

  Administrator's blast radius) is honored: Phase 2 — which is

  most of the session's wall-clock time — has zero push capability.

  Phase 1 is short, agent-driven, and the namespace is narrow,

  ephemeral, and self-cleaning.

- *Ergonomics restored.* Routine startup is fully agentic: the

  user launches Administrator, it walks §1-§11 including §2.5,

  reports "Phase 1 complete," and enters Phase 2. No

  user-confirmation gate, no dependency on the v1 fallback for

  the routine path.

- *V1 fallback narrowed but retained.* The v1

  Initialization-prompt.md session still has its place: re-verify

  write capability after a credential rotation **without

  disturbing a running Phase 2 loop** (since the transition is

  irrevocable, you can't ask the running Administrator to re-do

  §2.5). Three-session-only deployments can also use it.

- *No new failure modes.* The Phase 1 cleanup pass (delete every

  init-check-* ref before declaring "Phase 1 complete") plus the

  cleanup-dry-run-refs.sh helper for human-driven mop-up cover the

  abnormal-exit edge case.

**Concurrency note.** The reviewer also asked about same-file

concurrent writes. **Answer: by construction there are none.**

Each `agent-state-<role>.json` has exactly one writer (the role

itself, on the one machine where it runs). Writes are atomic

(`.tmp.$$` + `mv -f`); the Administrator's reads of the worker

state files see either the prior or the new full file, never a

partial write. The full file-by-file concurrency analysis is in

the new `plan/communication-paths.md` §4.3.

**Documentation outcome.** A new `plan/communication-paths.md`

enumerates every channel (git refs cross-machine; local filesystem

per-machine), every per-ref/per-file writer and reader, the

concurrency model, and multi-machine semantics. Cross-referenced

from orchestration.md §6 preamble and from each role prompt's

"Read these in order" list, so future readers find it on first

scan.

**v2.2 commits (this session, on top of the v2.1 set):**

- `67d1276` — orchestration.md v2.2 (phase-scoped Administrator

  allowlist; §3 / §5 / §6.4 / §8 / §9.5 / §13.1 updates).

- `11d1708` — Administrator-prompt.md v2.2 (Phase 1 walks

  initialization.md §1-§11 in full including §2.5; explicit cleanup

  pass; irrevocable Phase 1 → Phase 2 transition).

- `6061a71` — initialization.md + Initialization-prompt.md v2.2

  banner sync (v1 fallback use-case re-narrowed to "re-verify

  after credential rotation without disturbing a running Phase 2

  loop").

- `620513c` — new plan/communication-paths.md plus cross-references

  from orchestration.md §6 preamble and all four role prompts.

- (this commit) — §17.1 marked SUPERSEDED; §17.6 updated; §17.7

  added.