plan: redesign §17 — v2.1 addendum (reviewer feedback)

| 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 |

| 4 — second dry run | pending | (next session — do not start without re-reading §10.5) |

| **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) |

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

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

If anything in §10.2 (commits 1-6) is incomplete or deferred, the

new session reports it explicitly so phase 4 can plan around it.

---

## 17. v2.1 addendum (2026-05-02 reviewer feedback)

After the v2 implementation pass landed (commits `361da1c` through

`138588d`), the reviewer raised four points. This section records

the resulting v2.1 design change so a future reader knows what

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

**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.

**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.

### 17.2 Minimize ref detritus — Developer triage cleanup

**Change.** Developer state machine §6 / §9.2 step 6 now does

`git push --delete {remote} triage/{slug}[-v{N}]` after merging

the triage branch into the analysis branch. Push allowlist §8

extended to include this delete.

**Why.** Reviewer: *"In my ideal, following a fully successful

operation, for every issue entered in issue.md, there should be a

branch and PR or a branch and an {slug}-escalate tag."* Triage

branches are intermediate signals; once merged into analysis, they

have no further purpose — leaving them on the remote is detritus.

**End-state contract (now codified in orchestration.md §3 / §8).**

After a fully successful run, for every slug:

- one `feature/{slug}` branch (PR basis)

- *either* an open PR/MR pointing to it *or* a

  `review/{slug}-escalate` annotated tag

- no `qa/{slug}` (consumed and deleted)

- no non-escalate `review/{slug}` (consumed and deleted)

- no `triage/{slug}*` (deleted post-merge per this change)

- `analysis/{effort-name}` retained as historical record

### 17.3 `/effort default` is invalid

**Change.** Every `/effort default` and table cell `\`default\``

that the v2 pass wrote has been replaced with a valid CLI option:

- Sonnet-procedural roles (Administrator, deprecated v1

  Initialization): `medium`.

- Opus-spec-driven roles (Developer, Integrator): `xhigh` (matches

  the existing role prompt files the reviewer was already running).

- Analyst: `max` (unchanged).

**Why.** Reviewer's `/effort default` invocation in their session

returned: *"Invalid argument: default. Valid options are: low,

medium, high, xhigh, max, auto"*. The v1 documentation used

`default` colloquially as "the natural balanced setting"; that is

not a valid CLI option.

The §9.5 model/effort table now includes a one-paragraph "Effort

levels" note documenting the valid CLI set and the v2.1 mapping.

### 17.4 cleanup-dry-run-refs.sh

**Change.** New script at

`tasking/plan/scripts/cleanup-dry-run-refs.sh` (mode 700). Lists

(default) every ref on `{remote}` matching `{dry-run-prefix}-*` (as

both branches and tags) and, with `--apply`, deletes them

(remote first via `git push --delete`, then local tracking via

`git update-ref -d`).

**Why.** Reviewer: *"design a script that I can run after a

dry-run effort to identify any tags that are left with a

{dry-run-prefix} in the repository and an (optional) parameter to

remove them."*

**Tested** against the live `agentic` remote with

`PREFIX=dry-run-2026-04-28` — found 14 distinct refs from the

2026-04-28 dry run residue (after dedup-by-name; raw ls-remote

shows 15 because the annotated `review/dry-run-gamma-escalate`

appears twice — tag-object SHA + peeled-commit SHA).

### 17.5 v2.1 commits (this session)

- `26e6173` — orchestration.md v2.1 (Administrator read-only +

  triage cleanup + /effort fix + ref-namespace cleanup)

- `98ec73e` — Administrator-prompt.md v2.1 (read-only)

- `fdf3749` — Developer-prompt.md + Initialization-prompt.md +

  initialization.md (v2.1 prompt syncs)

- `410b2b6` — `plan/scripts/cleanup-dry-run-refs.sh`

- (this commit) — §17 addendum

### 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.

- §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).