Commit 63a686e9 authored by Vacaliuc, Bogdan's avatar Vacaliuc, Bogdan
Browse files

plan: dry-run.md — F2/F4/F5 fixes + cadence note + Administrator-first 



Apply the three Analyst-findings harness defects:

- F2 (^{} peel): the §10 monitoring snippet now strips the annotated-
  tag dereference suffix BEFORE filtering, so re-pointed annotated
  tags (e.g. review/<slug>-escalate) don't slip past the suffix
  exclusion as ^{}-peeled false positives.
- F4 (--tags clobber): switched the §10 monitoring example to
  `git ls-remote` with narrow refspecs as the primary discovery
  method; for cases where local fetch is needed, document the
  narrow-refspec form (Option A) and the --force-on-tags fallback
  (Option B) per Analyst findings F4.
- F5 (pipe-mask): replaced the hidden `2>&1 | tail` anti-pattern in
  the cleanup runbook with an explicit `if git push …; then … else
  …; fi` form. Exit-code-masking via tail caused a silent
  analysis-branch push failure during the dry-run gamma-v3 cycle.

Also: §3 cadence note (10s warning, 30s minimum dry-run, 60s
production) and {integrator-test-cmd} knob extending §7 of
orchestration.md per redesign §14.2. §10 reorganized for
Administrator-first launch (Administrator phase 1 absorbs
Initialization; v1 standalone Initialization-prompt.md remains as
fallback per orchestration.md §13.1).

Co-Authored-By: default avatarClaude Opus 4.7 (1M context) <noreply@anthropic.com>
parent 33d82441

plan/dry-run.md

+75 −17
Original line number Diff line number Diff line
@@ -81,7 +81,18 @@ Adds these knobs on top of the production `{remote}`, `{base-branch}`, 
| `{dry-run-prefix}` | Hyphenated ref-name prefix isolating dry-run refs from production (no slashes — see §3.1) | `dry-run-<ISO-date>` (today) | Opening prompt |

| `{dry-run-remote}` | Remote for dry-run pushes (may equal `{remote}`) | `{remote}` | Opening prompt |

| `{dry-run-outcomes}` | Map of slug → outcome for synthetic code (see §4) | See §4 | Opening prompt |

| `TA`/`TD`/`TI` (override) | Poll intervals during dry-run | **10 s** (accelerated) | Opening prompt |

| `TA`/`TD`/`TI` (override) | Poll intervals during dry-run | **30 s** (accelerated; **10 s warning** — see cadence note below) | Opening prompt |

| `{integrator-test-cmd}` | Pixi task name the Integrator runs (extends `orchestration.md` §7) | **`test-dry-run`** in dry-run; **`test-reduction`** in production | Opening prompt; see redesign §14 |



**Cadence note.** The 2026-04-28 dry run set `TA=TD=TI=10 s` and

twice tripped GitHub's HTTPS secondary rate limit (403 with no

`Retry-After`; see `dry-run-Analyst-findings.md` F3). The v2 default

is `30 s minimum` in dry-run mode; **production is 60 s** per

`orchestration.md` §7. Below 30 s, three concurrent agents on one

HTTPS PAT push the steady-state above the secondary-limit threshold.

SSH for `{remote}` is on a different rate-limit bucket and is

operationally tolerable at 10 s — but state-machine fidelity is

unaffected by the slower cadence, so 30 s is the right floor.



`{dry-run-prefix}-{type}/{slug}` replaces the unprefixed protocol

ref `{type}/{slug}`. Example — the dry-run version of
@@ -375,30 +386,77 @@ and what the last observed state was. 


## 10. Running the dry run end-to-end



1. **Initialization first.** In one clone, paste the Initialization

   prompt (§9.4 of the meta-plan) with `DRY_RUN=1` appended to its

   configuration line. Wait for the report; verify all sections

   pass.

2. **Start the three agents concurrently.** In each of the

1. **Administrator first (v2 default; folds Initialization into phase 1).**

   In `<path-to-session-4>`, paste the Administrator prompt (`plan/Administrator-prompt.md`)

   with `DRY_RUN=1` appended to its configuration line. Wait for

   "Phase 1 complete. Ready to launch worker agents." If phase 1

   fails, fix the cited issue and ask the Administrator to re-run.

   (v1 fallback: paste `plan/Initialization-prompt.md` instead.)

2. **Start the three workers concurrently.** In each of the

   designated clones, paste the Analyst, Developer, Integrator

   prompts (§9.1-§9.3) with `DRY_RUN=1`, `{dry-run-prefix}=...`,

   `{dry-run-remote}=...`, and `TA=TD=TI=10` appended.

3. **Monitor.** On any clone:

   prompts (`plan/{Analyst,Developer,Integrator}-prompt.md`) with

   `DRY_RUN=1`, `{dry-run-prefix}=...`, `{dry-run-remote}=...`, and

   `TA=TD=TI=30` appended (30 s minimum per §3 cadence note;

   `{integrator-test-cmd}=test-dry-run` for the Integrator).

3. **Tell the Administrator** (mid-loop) which workers you started

   in which clones, e.g. *"I started Analyst in clone 1, Developer

   in clone 2, Integrator in clone 3."* Administrator enters phase 2

   monitoring.

4. **Monitor.** Use the Administrator's dashboard. Or, ad-hoc on

   any clone, prefer `git ls-remote` over `git fetch --tags`

   (cheaper, doesn't trip the secondary rate limit and doesn't

   trigger F4's "would clobber existing tag"):



   ```bash

   while sleep 15; do

     git fetch --all --prune --tags 2>/dev/null

     echo "=== $(date -u +%H:%M:%S) ==="

     git branch -a --list "{dry-run-prefix}-*/*"

     git tag --list "{dry-run-prefix}-*/*"

     # F2 fix: strip ^{} peel of annotated tags BEFORE filtering

     # F4 fix: ls-remote with narrow refspec — no --tags side effect

     git ls-remote {dry-run-remote} \

         "refs/heads/{dry-run-prefix}-*/*" \

         "refs/tags/{dry-run-prefix}-*/*" \

       | awk '{ sub(/\^\{\}$/, "", $2); print }' \

       | sort -u

   done

   ```



4. **Verify** the state transition table in §6 unfolds as described.

5. **Stop.** When all slugs reach terminal state, ESC all four

   sessions.

6. **Clean up.** Run §9's cleanup block in any clone.

7. If clean, proceed to real orchestration per meta-plan §13.1.

   Alternative (when local refs are needed for inspection): use a

   narrow refspec with `--force` to avoid F4's clobber rejection on

   re-tagged qa/* refs:



   ```bash

   # F4 fix: narrow refspec (no --tags side effect) — Option A from

   # dry-run-Analyst-findings.md F4

   git fetch {dry-run-remote} --prune \

     '+refs/tags/{dry-run-prefix}-review/*:refs/tags/{dry-run-prefix}-review/*'

   # Or, if you do want to mirror all tags: --force is required

   git fetch {dry-run-remote} --prune --tags --force

   ```



5. **Verify** the state transition table in §6 unfolds as described.

6. **Stop.** When all slugs reach terminal state, ESC all four

   sessions (workers first; Administrator last so it can see them

   exit cleanly).

7. **Clean up.** Run §9's cleanup block in any clone (use the

   `if … then … else …` form below for any push you add manually —

   never pipe critical pushes through `tail`/`head`/`tee`, which

   masks `git push`'s exit code from `set -e`; per F5).



   ```bash

   # F5 anti-pattern (do NOT do this — exit code from `git push` is

   # silently swallowed by `tail`'s exit 0):

   #   git push {dry-run-remote} <ref> 2>&1 | tail -3

   #

   # F5 fix — explicit-exit-check form:

   if git push {dry-run-remote} <ref>; then

     echo "push <ref>: ok"

   else

     echo "push <ref>: FAILED — investigate"

     # do NOT lose progress; recover deliberately

   fi

   ```



8. If clean, proceed to real orchestration per meta-plan §13.1.



---