@ikon85/agent-workflow-kit 0.28.0 → 0.29.0

package/.claude/skills/grill-me-codex/SKILL.md

@@ -41,7 +41,7 @@ For a cross-cutting plan, run `python3 .claude/hooks/drift-guard.py --census-sta
 
 When the decision tree is resolved and we're aligned, **write the agreed plan to `PLAN.md`** in this structure, then move to Act 2:
 
-> **Where to write it:** `PLAN.md` + `PLAN-REVIEW-LOG.md` are per-session scratch — write them in the working directory the implementing session will actually use, and run Codex from there (`-C <dir>` on the round-1 `exec`; `exec resume` rejects both `-C` and `-s`, so run resume from that cwd and force read-only via `-c sandbox_mode="read-only"`). A project may gitignore these files, so don't rely on git to carry them across checkouts/worktrees. In worktree-based repos, create the issue worktree BEFORE this write and plan inside it.
+> **Where to write it:** `PLAN.md` + `PLAN-REVIEW-LOG.md` are per-session scratch — write them in the working directory the implementing session will actually use, and invoke the wrapper from that directory. A project may gitignore these files, so don't rely on git to carry them across checkouts/worktrees. In worktree-based repos, create the issue worktree BEFORE this write and plan inside it.
 
 ```markdown
 # Plan: <task>
@@ -76,8 +76,9 @@ Act 1 (grill) complete — plan locked with the user. MAX_ROUNDS=<n>.
 Now hand the locked plan to Codex for adversarial review. Same engine, mechanics verified end-to-end (2026-06-04).
 
 ### Prerequisites (verify once, fast)
-- `codex --version` ≥ 0.130 (older CLIs error on the default `gpt-5.5` model).
-- Codex authenticated (prior `codex login`; ChatGPT account is fine). On auth/model error, surface it — don't silently retry.
+- Let `scripts/codex-exec.sh` preflight Codex before launch. It enforces the
+  exact tested-version allowlist, authentication, platform, and capabilities;
+  surface any failure rather than retrying silently.
 - Do NOT pin `-m`. Use the config default. Pinning `gpt-5.x-codex` variants 400s on ChatGPT-account auth.
 - **Echo the active model before Round 1** so the user can confirm: read the `model` line from `~/.codex/config.toml` (absent = "CLI default"); state it alongside the resolved tunables. If the user objects, stop before burning a round.
 
@@ -93,50 +94,59 @@ If invoked with e.g. `rounds=3`, use that for `MAX_ROUNDS`. Echo resolved values
 ### The review prompt (sent each round)
 > You are an adversarial reviewer for an implementation plan. Be skeptical and specific — your job is to find what breaks, not to be agreeable. Read the plan at `PLAN.md` and any repo files you need (you are read-only). Identify concrete flaws: security holes, race conditions, missing edge cases, schema conflicts, wrong assumptions, observability gaps, simpler alternatives. For each, give a one-line fix. Do NOT modify any files. End your reply with EXACTLY one line: `VERDICT: APPROVED` if the plan is sound enough to implement, or `VERDICT: REVISE` if it still has material problems.
 
-### Round 1 — fresh session (capture `thread_id`)
-Stream `--json` to a FILE, never pipe to `grep` — `codex exec --json | grep` deadlocks on codex-cli ≥0.137. **Always launch with `< /dev/null`** — a backgrounded `codex exec … &` without it blocks on stdin and sits at **0 CPU / 0 bytes** forever (the #1 cause of the "silent hang"; verified 2026-06-09). Background it so a **90s liveness probe** still catches a genuine sandbox deadlock.
+### Round 1 — fresh wrapper-owned session
+
 ```bash
-CODEX_TMP="/tmp/codex-$(pwd | sha1sum | cut -c1-8)"; mkdir -p "$CODEX_TMP"   # run-unique per worktree cwd: STABLE across round-1+resume turns, collision-free under parallel sessions
-codex exec -s read-only --json -o $CODEX_TMP/verdict.txt "$(cat REVIEW_PROMPT)" \
-  < /dev/null > $CODEX_TMP/r1.jsonl 2>/dev/null &
-CODEX_PID=$!
-sleep 90                                          # liveness probe (REQUIRED)
-if kill -0 "$CODEX_PID" 2>/dev/null; then
-  CPU=$(ps -o time= -p "$CODEX_PID" 2>/dev/null | tr -dc '0-9:')   # cumulative CPU, e.g. 00:00:00
-  BYTES=$(wc -c < $CODEX_TMP/r1.jsonl 2>/dev/null || echo 0)
-  if [ "${CPU:-00:00:00}" = "00:00:00" ] && [ "${BYTES:-0}" -eq 0 ]; then
-    kill -9 "$CODEX_PID" 2>/dev/null; echo "CODEX-HUNG"   # alive + 0 CPU + 0 bytes = blocked, NOT working
-  fi
+if ROUND_RESULT=$(scripts/codex-exec.sh new --profile review --mode read-only --prompt "$REVIEW_PROMPT"); then
+  RUN_ID=$(printf '%s\n' "$ROUND_RESULT" | python3 -c 'import json,sys; print(json.load(sys.stdin)["runId"])')
+  CODEX_REPORT=$(printf '%s\n' "$ROUND_RESULT" | python3 -c 'import json,sys; print(json.load(sys.stdin)["verdict"])')
+else
+  FAILURE_RESULT=$(scripts/codex-exec.sh handle-failure --result "$ROUND_RESULT") || :
+  printf '%s\n' "$FAILURE_RESULT" >&2
+  exit 1
 fi
-wait "$CODEX_PID" 2>/dev/null
-THREAD_ID=$(grep -o '"thread_id":"[^"]*"' $CODEX_TMP/r1.jsonl | head -1 | cut -d'"' -f4)
 ```
-- **`CODEX-HUNG` printed** (alive + 0 CPU + 0 bytes at 90s) → **first suspect the stdin block**: confirm the launch has `< /dev/null` and retry. That fixes it in nearly every case. **NEVER `pgrep`/`kill` codex procs to "clear contention"** — that murders the user's live, unrelated codex sessions and does **not** fix a stdin hang. Only if `< /dev/null` is present and it still hangs (genuine sandbox deadlock) → **STOP Act 2**: tell the user, offer to sign off without the cross-model review or retry once. Don't touch other codex processes.
-- **Healthy:** CPU climbs past `00:00:00` and/or `$CODEX_TMP/r1.jsonl` grows; `THREAD_ID` parses; critique lands in `$CODEX_TMP/verdict.txt`. `2>/dev/null` hides cosmetic MCP/auth noise.
-- **Clean finish but no verdict file + no `THREAD_ID`** = auth/model failure → stop, tell the user.
 
-### Rounds 2..MAX — resume the SAME session (Codex remembers its prior critiques)
+### Rounds 2..MAX — resume the SAME session
+
 ```bash
-# resume REJECTS -s. Force read-only via -c sandbox_mode, or Codex inherits
-# config.toml (possibly danger-full-access) and could WRITE files. This is the
-# single most important safety line in the skill — verified 2026-06-04.
-CODEX_TMP="/tmp/codex-$(pwd | sha1sum | cut -c1-8)"; mkdir -p "$CODEX_TMP"   # run-unique per worktree cwd: STABLE across round-1+resume turns, collision-free under parallel sessions
-codex exec resume "$THREAD_ID" -c sandbox_mode="read-only" --json \
-  -o $CODEX_TMP/verdict.txt \
-  "I revised the plan. Re-review PLAN.md — check whether your prior findings are addressed and flag anything new. End with VERDICT: APPROVED or VERDICT: REVISE." \
-  < /dev/null 2>/dev/null >/dev/null &
+if ROUND_RESULT=$(scripts/codex-exec.sh resume "$RUN_ID" --prompt "I revised the plan. Re-review PLAN.md — check whether your prior findings are addressed and flag anything new. End with VERDICT: APPROVED or VERDICT: REVISE."); then
+  CODEX_REPORT=$(printf '%s\n' "$ROUND_RESULT" | python3 -c 'import json,sys; print(json.load(sys.stdin)["verdict"])')
+else
+  FAILURE_RESULT=$(scripts/codex-exec.sh handle-failure --result "$ROUND_RESULT" --run-id "$RUN_ID") || :
+  printf '%s\n' "$FAILURE_RESULT" >&2
+  exit 1
+fi
 ```
-Wrap resume in the **same 90s liveness probe** (background + `wait`). Resume discards the `--json` stream, so probe on the verdict file: `BYTES=$(wc -c < $CODEX_TMP/verdict.txt)` plus the `CPU` check — `00:00:00` CPU + empty verdict at 90s → kill, treat as `CODEX-HUNG`, same STOP path as round 1. Both `codex exec` and `codex exec resume` support `--json` and `-o/--output-last-message`.
 
-**Overall ceiling (both rounds):** the 90s probe catches silent hangs, not long stuck runs. Cap every `codex exec` / `codex exec resume` at **10 minutes** — via Claude Code's Bash tool pass `timeout: 600000` on the tool call (the default 2-minute tool timeout would kill real reviews mid-run); in a plain shell prefix `timeout 600` (macOS: `gtimeout 600` via coreutils). If the ceiling trips, treat it as a failed round: stop and tell the user rather than retrying blind.
+The wrapper persists read-only mode and owns stdin closure, hang detection, the
+overall timeout, stderr redaction, and its process group. `handle-failure`
+surfaces the structured status and cleanup metadata, then the caller stops
+before report handling. A surfaced `HUNG` returns to the user for the choice to
+retry once with a fresh run or sign off without cross-model review. Never
+inspect, signal, or kill foreign Codex processes.
+
+Separately, cancellation or a decision to stop orchestration after an OK round
+but before normal finalize must abort the known run:
+
+```bash
+scripts/codex-exec.sh abort "$RUN_ID"
+```
 
 ### Each round, after Codex returns
-1. Read `$CODEX_TMP/verdict.txt`; append to `LOG_FILE`: `## Round <n> — Codex` + the full critique.
+1. Read `CODEX_REPORT`; append to `LOG_FILE`: `## Round <n> — Codex` + the full critique.
 2. Grep the last line for the verdict:
    - `VERDICT: APPROVED` → break to Resolution (converged).
    - `VERDICT: REVISE` → Claude decides **what's actually worth acting on** (Claude is final arbiter — Codex advises, doesn't command). Revise `PLAN_FILE`. Append `### Claude's response` to `LOG_FILE`: what changed, what was rejected, why. Increment round.
 3. If round > `MAX_ROUNDS` → break to Resolution (deadlock).
 
+After harvesting the final report and updating the log, delete the successful
+run state:
+
+```bash
+scripts/codex-exec.sh finalize "$RUN_ID"
+```
+
 ### Resolution (you sign off — final gate)
 - **APPROVED:** present the final `PLAN_FILE`, a 3-bullet summary of what the two acts improved, and the round count. Ask: *"Grilled + survived N rounds of Codex. Implement it now — Codex builds it (`/codex-build`), Claude builds it, or stop here?"* Code only on a yes. **No code is written during either act.**
 - **MAX_ROUNDS hit without APPROVED (deadlock):** do NOT fake convergence. List each unresolved point + Claude's counter-position; hand it to the user to break the tie. A flagged disagreement beats a false "approved."
@@ -149,7 +159,8 @@ If the user picks Codex: invoke the `codex-build` skill with `SPEC_FILE=PLAN.md`
 
 ## Hard rules
 - Act 1 always precedes Act 2 — don't write `PLAN.md` until the grill has actually resolved the decision tree with the user.
-- Codex is read-only EVERY round — `-s read-only` first call, `-c sandbox_mode="read-only"` on every resume (resume has no `-s`). It never writes.
+- Codex is read-only EVERY round — establish it once through the wrapper's
+  `review` + `read-only` new call; every resume inherits it.
 - The loop ALWAYS terminates at `MAX_ROUNDS`.
 - Claude is final arbiter on every REVISE — incorporate good critiques, reject bad ones *with a logged reason*. Don't cave to everything (defeats the cross-model check) and don't ignore it (defeats the point).
 - Code only after the user's final sign-off.

package/.claude/skills/grill-with-docs-codex/SKILL.md

@@ -125,7 +125,7 @@ For a cross-cutting plan, run `python3 .claude/hooks/drift-guard.py --census-sta
 
 When the decision tree is resolved, the glossary/ADRs are updated, and we're aligned, **write the agreed plan to `PLAN.md`** (use the canonical terms from `CONTEXT.md`), then run Act 2:
 
-> **Where to write it:** `PLAN.md` + `PLAN-REVIEW-LOG.md` are per-session scratch — write them in the working directory the implementing session will actually use, and run Codex from there (`-C <dir>` on the round-1 `exec`; `exec resume` rejects both `-C` and `-s`, so run resume from that cwd and force read-only via `-c sandbox_mode="read-only"`). A project may gitignore these files, so don't rely on git to carry them across checkouts/worktrees. In worktree-based repos, create the issue worktree BEFORE this write and plan inside it.
+> **Where to write it:** `PLAN.md` + `PLAN-REVIEW-LOG.md` are per-session scratch — write them in the working directory the implementing session will actually use, and invoke the wrapper from that directory. A project may gitignore these files, so don't rely on git to carry them across checkouts/worktrees. In worktree-based repos, create the issue worktree BEFORE this write and plan inside it.
 
 ```markdown
 # Plan: <task>
@@ -160,8 +160,9 @@ Act 1 (grill-with-docs) complete — plan locked, CONTEXT.md/ADRs updated. MAX_R
 Hand the locked plan to Codex for adversarial review. Mechanics verified end-to-end (2026-06-04).
 
 ### Prerequisites
-- `codex --version` ≥ 0.130 (older CLIs error on the default `gpt-5.5` model).
-- Codex authenticated (`codex login`; ChatGPT account fine). On auth/model error, surface it — don't silently retry.
+- Let `scripts/codex-exec.sh` preflight Codex before launch. It enforces the
+  exact tested-version allowlist, authentication, platform, and capabilities;
+  surface any failure rather than retrying silently.
 - Do NOT pin `-m` (config default is used; `gpt-5.x-codex` variants 400 on ChatGPT-account auth).
 - **Echo the active model before Round 1** so the user can confirm: read the `model` line from `~/.codex/config.toml` (absent = "CLI default"); state it alongside the resolved tunables. If the user objects, stop before burning a round.
 
@@ -177,48 +178,57 @@ Invoked with e.g. `rounds=3` → use it. Echo resolved values first.
 ### Review prompt (each round)
 > You are an adversarial reviewer for an implementation plan. Be skeptical and specific — your job is to find what breaks, not to be agreeable. Read the plan at `PLAN.md` (and `CONTEXT.md`/ADRs for the domain language) and any repo files you need (you are read-only). Identify concrete flaws: security holes, race conditions, missing edge cases, schema conflicts, domain-language mismatches, wrong assumptions, observability gaps, simpler alternatives. For each, give a one-line fix. Do NOT modify any files. End with EXACTLY one line: `VERDICT: APPROVED` or `VERDICT: REVISE`.
 
-### Round 1 — fresh session (capture `thread_id`)
-Stream `--json` to a FILE, never pipe to `grep` — `codex exec --json | grep` deadlocks on codex-cli ≥0.137. **Always launch with `< /dev/null`** — a backgrounded `codex exec … &` without it blocks on stdin and sits at **0 CPU / 0 bytes** forever (the #1 cause of the "silent hang"; verified 2026-06-09). Launch in the background so a **90s liveness probe** still catches a genuine sandbox deadlock.
+### Round 1 — fresh wrapper-owned session
+
 ```bash
-CODEX_TMP="/tmp/codex-$(pwd | sha1sum | cut -c1-8)"; mkdir -p "$CODEX_TMP"   # run-unique per worktree cwd: STABLE across round-1+resume turns, collision-free under parallel sessions
-codex exec -s read-only --json -o $CODEX_TMP/verdict.txt "$(cat REVIEW_PROMPT)" \
-  < /dev/null > $CODEX_TMP/r1.jsonl 2>/dev/null &
-CODEX_PID=$!
-sleep 90                                          # liveness probe (REQUIRED)
-if kill -0 "$CODEX_PID" 2>/dev/null; then
-  CPU=$(ps -o time= -p "$CODEX_PID" 2>/dev/null | tr -dc '0-9:')   # cumulative CPU, e.g. 00:00:00
-  BYTES=$(wc -c < $CODEX_TMP/r1.jsonl 2>/dev/null || echo 0)
-  if [ "${CPU:-00:00:00}" = "00:00:00" ] && [ "${BYTES:-0}" -eq 0 ]; then
-    kill -9 "$CODEX_PID" 2>/dev/null; echo "CODEX-HUNG"   # alive + 0 CPU + 0 bytes = blocked, NOT working
-  fi
+if ROUND_RESULT=$(scripts/codex-exec.sh new --profile review --mode read-only --prompt "$REVIEW_PROMPT"); then
+  RUN_ID=$(printf '%s\n' "$ROUND_RESULT" | python3 -c 'import json,sys; print(json.load(sys.stdin)["runId"])')
+  CODEX_REPORT=$(printf '%s\n' "$ROUND_RESULT" | python3 -c 'import json,sys; print(json.load(sys.stdin)["verdict"])')
+else
+  FAILURE_RESULT=$(scripts/codex-exec.sh handle-failure --result "$ROUND_RESULT") || :
+  printf '%s\n' "$FAILURE_RESULT" >&2
+  exit 1
 fi
-wait "$CODEX_PID" 2>/dev/null
-THREAD_ID=$(grep -o '"thread_id":"[^"]*"' $CODEX_TMP/r1.jsonl | head -1 | cut -d'"' -f4)
 ```
-- **`CODEX-HUNG` printed** (alive + 0 CPU + 0 bytes at 90s) → **first suspect the stdin block**: confirm the launch has `< /dev/null` and retry. That fixes it in nearly every case (verified 2026-06-09). **NEVER `pgrep`/`kill` codex procs to "clear contention"** — that murders the user's live, unrelated codex sessions and does **not** fix a stdin hang. If `< /dev/null` is already present and it still hangs (genuine sandbox deadlock) → **STOP Act 2**: append the hang to `LOG_FILE`, tell the user, and offer to (a) proceed to sign-off **without** the cross-model review, or (b) retry once more. Do **not** keep waiting minutes, and do **not** touch other codex processes.
-- **Healthy:** CPU climbs past `00:00:00` and/or `$CODEX_TMP/r1.jsonl` grows; `THREAD_ID` parses; critique lands in `$CODEX_TMP/verdict.txt`.
-- **Clean finish but no verdict file + no `THREAD_ID`** = auth/model failure → stop, tell the user. `2>/dev/null` hides cosmetic MCP/auth noise.
 
 ### Rounds 2..MAX — resume SAME session
+
 ```bash
-# resume REJECTS -s. Force read-only via -c sandbox_mode, or Codex inherits
-# config.toml (possibly danger-full-access) and could WRITE files. Critical
-# safety line — verified 2026-06-04.
-CODEX_TMP="/tmp/codex-$(pwd | sha1sum | cut -c1-8)"; mkdir -p "$CODEX_TMP"   # run-unique per worktree cwd: STABLE across round-1+resume turns, collision-free under parallel sessions
-codex exec resume "$THREAD_ID" -c sandbox_mode="read-only" --json \
-  -o $CODEX_TMP/verdict.txt \
-  "I revised the plan. Re-review PLAN.md — check prior findings + flag anything new. End with VERDICT: APPROVED or VERDICT: REVISE." \
-  < /dev/null 2>/dev/null >/dev/null &
+if ROUND_RESULT=$(scripts/codex-exec.sh resume "$RUN_ID" --prompt "I revised the plan. Re-review PLAN.md — check prior findings + flag anything new. End with VERDICT: APPROVED or VERDICT: REVISE."); then
+  CODEX_REPORT=$(printf '%s\n' "$ROUND_RESULT" | python3 -c 'import json,sys; print(json.load(sys.stdin)["verdict"])')
+else
+  FAILURE_RESULT=$(scripts/codex-exec.sh handle-failure --result "$ROUND_RESULT" --run-id "$RUN_ID") || :
+  printf '%s\n' "$FAILURE_RESULT" >&2
+  exit 1
+fi
 ```
-Wrap resume in the **same 90s liveness probe** (background + `wait`). Resume discards the `--json` stream, so probe on the verdict file instead: `BYTES=$(wc -c < $CODEX_TMP/verdict.txt)` plus the `CPU` check — `00:00:00` CPU + empty verdict at 90s → kill, treat as `CODEX-HUNG`, same STOP path as round 1.
 
-**Overall ceiling (both rounds):** the 90s probe catches silent hangs, not long stuck runs. Cap every `codex exec` / `codex exec resume` at **10 minutes** — via Claude Code's Bash tool pass `timeout: 600000` on the tool call (the default 2-minute tool timeout would kill real reviews mid-run); in a plain shell prefix `timeout 600` (macOS: `gtimeout 600` via coreutils). If the ceiling trips, treat it as a failed round: stop and tell the user rather than retrying blind.
+The wrapper persists read-only mode and owns stdin closure, hang detection, the
+overall timeout, stderr redaction, and its process group. `handle-failure`
+surfaces the structured status and cleanup metadata for `LOG_FILE`, then the
+caller stops before report handling. A surfaced `HUNG` returns to the user for
+the choice to retry once with a fresh run or proceed without cross-model
+review. Never inspect, signal, or kill foreign Codex processes.
+
+Separately, cancellation or a decision to stop orchestration after an OK round
+but before normal finalize must abort the known run:
+
+```bash
+scripts/codex-exec.sh abort "$RUN_ID"
+```
 
 ### Each round
-1. Read verdict file; append `## Round <n> — Codex` + critique to `LOG_FILE`.
+1. Read `CODEX_REPORT`; append `## Round <n> — Codex` + critique to `LOG_FILE`.
 2. Last line verdict: `APPROVED` → Resolution (converged); `REVISE` → Claude decides what's worth acting on (final arbiter), revise `PLAN_FILE`, append `### Claude's response` (what changed/rejected + why), increment.
 3. round > `MAX_ROUNDS` → Resolution (deadlock).
 
+After harvesting the final report and updating the log, delete the successful
+run state:
+
+```bash
+scripts/codex-exec.sh finalize "$RUN_ID"
+```
+
 ### Resolution (you sign off)
 - **APPROVED:** present final plan + 3-bullet summary of what the two acts improved + round count. Ask: implement now — Codex builds it (`/codex-build`), Claude builds it, or stop? No code during either act.
 - **Deadlock (cap hit, no APPROVED):** list unresolved points + Claude's counter-position; hand to user. Don't fake convergence.
@@ -228,9 +238,11 @@ Wrap resume in the **same 90s liveness probe** (background + `wait`). Resume dis
 
 ## Hard rules
 - Act 1 precedes Act 2. `CONTEXT.md` stays a glossary only — no implementation details.
-- Codex read-only EVERY round (`-s read-only` first, `-c sandbox_mode="read-only"` on resume — resume has no `-s`). Never writes.
+- Codex is read-only EVERY round — establish it once through the wrapper's
+  `review` + `read-only` new call; every resume inherits it.
 - Loop ALWAYS terminates at `MAX_ROUNDS`. Claude is final arbiter on REVISE (reject with logged reason). Code only after sign-off. `LOG_FILE` is the deliverable.
-- EVERY codex round runs behind the **90s liveness probe** (background + CPU/output check). Never let a silent codex hang burn minutes — kill at 90s if 0 CPU + 0 output, surface it, give the user the proceed-without / retry choice.
+- A `HUNG` wrapper result always returns to the user for the proceed-without or
+  retry-once choice.
 
 ## What NOT to do
 - Don't review already-written code (`/codex:review`). Don't pin `-codex` variants on ChatGPT auth. Don't let Codex edit files. Don't skip Act 1.

package/.claude/skills/to-issues/SKILL.md

@@ -143,33 +143,108 @@ else
   WAVE="$CURRENT"                                    # Stufe-1p Program-stub — reuse
 fi
 
-# 2. render the LEAN Tier-2 anchor body from docs/agents/wave-anchor-template.md into /tmp/anchor.md:
-#    body header `**Welle $WAVE — <Thema>**`, **plan_revision:** r<N> at top (before the first
-#    heading), the FILLED Slices table (you know the cut), the To-Do checklist collapsed to its
-#    one-line summary. The full grilled PRD does NOT go into the body (: every slice
-#    session's `--json body` read loads the whole body — a <details> block collapses only in
-#    the browser). Save it to /tmp/prd-archive.md instead — **with ALL embedded PRD markers
-#    stripped** (`plan_revision`, `prd-source-id`, `prd-content-fp`,
-#    `<!-- prd: awaiting-decomposition -->`; a stray second `plan_revision` on the issue is
-#    exactly the Retro confusion) — posted as ISSUE COMMENT #1 in step 2b.
-#    The anchor carries its own markers at the head. The issue TITLE is rewritten to
-#    `Welle N — <Thema>` by the promote step below (step 3) — do NOT set it here; promote
-#    prepends the wave prefix (and strips any `fix:`/`feat:` prefix) idempotently.
-#    Rewrite the PRD body via skill-prose gh (body-fill is issue CONTENT, NOT a board write — the
-#    helper owns board state only; cf. test_plan_body_fill_is_not_a_board_sync_op; gh-lint allows a
-#    non-workflow-label `gh issue edit`). Content-edit FIRST so a failure stops before board mutation:
-gh issue edit <prd#> --body-file /tmp/anchor.md
-
-# 2b. archive the full PRD as comment #1 on the anchor: one click away for a human,
-#     loaded only on demand by an agent (`--json body` never fetches comments). First line:
-#     `📄 Full PRD (archive, r<N>) — the body carries navigation/decisions only`.
-#     Idempotent re-run: a comment already starting with `📄 Full PRD (archive` → skip, never duplicate:
-gh issue comment <prd#> --body-file /tmp/prd-archive.md
-
-# 3. set the board state (type:cluster + Wave). If THIS fails AFTER the body edit, the title/body are
-#    already rewritten → STOP, report "board state incomplete (body/title already changed)", and
-#    re-run the idempotent promote (do not leave a silent partial state):
-python3 scripts/board-sync.py promote --issue <prd#> --wave "$WAVE"   # sets type:cluster + Wave + title `Welle N — …`
+# 2. Fill /tmp/anchor-template.md from docs/agents/wave-anchor-template.md (Tier 2):
+#    body header `**Welle $WAVE — <Topic>**`, anchor-owned markers at the head,
+#    filled Slices table, and the To-Do checklist collapsed to one line. Save the
+#    unchanged source PRD body as /tmp/source-prd.md. The renderer reads only those
+#    two files and writes only stdout: no GitHub/network call and no mutation.
+python3 scripts/render-anchor.py --template /tmp/anchor-template.md \
+  --prd /tmp/source-prd.md --document anchor > /tmp/anchor.md
+python3 scripts/render-anchor.py --template /tmp/anchor-template.md \
+  --prd /tmp/source-prd.md --document archive > /tmp/prd-archive.md
+```
+
+The anchor output is the filled template byte-for-byte. The archive starts with
+the stable `📄 Full PRD` marker and strips every canonical marker line
+(`plan_revision`, `prd-source-id`, `prd-content-fp`, `<!-- prd: … -->`) only
+from the source body's head block. Marker-looking text in a quote, fence, or
+later section is content and remains untouched.
+
+Promotion uses the remote issue itself as its journal. Classify four
+observations before every resume. Before transition 1, `S=yes|no` compares a
+freshly fetched remote body byte-for-byte with `/tmp/source-prd.md`, the source
+snapshot that produced both rendered outputs. Once `B=yes`, that source
+snapshot is no longer active and `S=n/a`. `B=yes|no` says whether the fetched
+issue body is byte-identical to `/tmp/anchor.md`.
+`C=0|exact-1|wrong-1|duplicates(<ids>)` classifies stable-marker comments:
+none; exactly one whose whole body is byte-identical to
+`/tmp/prd-archive.md`; exactly one with different bytes; or multiple matches
+with every comment ID retained. `P=absent|complete|partial` classifies only
+promotion-owned board state. `P=absent` accepts either an
+ordinary pre-state (no `type:cluster`, Wave unset, no `Welle` title prefix) or a
+valid Stufe-1p pre-state (`wave-stub` present, no `type:cluster`, and the
+pre-stamped Wave/title match `$WAVE`). `P=complete` requires `type:cluster`, the
+expected Wave/title, and no remaining `wave-stub`. Every other combination —
+including a different Wave — is `P=partial`. Fetch comments with the paginated
+API, never the first page alone:
+
+```bash
+gh api --paginate --slurp \
+  "repos/<owner>/<repo>/issues/<prd#>/comments?per_page=100"
+```
+
+Flatten every returned page, retain the comment `id`, and exact-match the
+start-of-body marker. The four valid states and their sole resume action are:
+
+<!-- promotion-board-observation-table:start -->
+| Scenario | Observable board facts | P classification |
+|---|---|---|
+| `ordinary-prestate` | no cluster; Wave unset; no Wave title | `absent` |
+| `stufe-1p-prestate` | wave-stub; no cluster; expected Wave/title | `absent` |
+| `promoted` | cluster; expected Wave/title; no wave-stub | `complete` |
+| `cluster-only` | cluster; Wave/title missing | `partial` |
+| `wrong-wave` | any different Wave value | `partial` |
+<!-- promotion-board-observation-table:end -->
+
+<!-- promotion-state-table:start -->
+| State | Observable predicates | Resume action |
+|---|---|---|
+| `initial` | `S=yes`, `B=no`, `C=0`, `P=absent` | render + write body |
+| `body-written` | `S=n/a`, `B=yes`, `C=0`, `P=absent` | reconcile + write archive comment |
+| `comment-written` | `S=n/a`, `B=yes`, `C=exact-1`, `P=absent` | promote board state |
+| `promoted` | `S=n/a`, `B=yes`, `C=exact-1`, `P=complete` | no-op; continue publish audit |
+<!-- promotion-state-table:end -->
+
+Each transition is idempotent and has an explicit contract:
+
+1. **Write body (`initial → body-written`).** Pre: `S=yes`, `B=no`, `C=0`,
+   `P=absent`. Fetch the remote body again immediately before the command and
+   recompute `S`; a prior fetch is not sufficient.
+   Run `gh issue edit <prd#> --body-file /tmp/anchor.md`, refetch the body, and
+   require a byte match. Post: `S=n/a`, `B=yes`, `C=0`, `P=absent`.
+2. **Write archive (`body-written → comment-written`).** Pre: `S=n/a`, `B=yes`,
+   `C=0`, `P=absent`. Re-run the pagination-aware lookup immediately before
+   create; if it now yields `C=exact-1`, classify as `comment-written` and do
+   not create. `C=wrong-1` or `C=duplicates(<ids>)` is drift and enters repair,
+   never create. Only `C=0` runs `gh issue comment <prd#> --body-file
+   /tmp/prd-archive.md`, then immediately paginate and reconcile again. Post:
+   `S=n/a`, `B=yes`, `C=exact-1`, `P=absent`.
+3. **Promote (`comment-written → promoted`).** Pre: `S=n/a`, `B=yes`,
+   `C=exact-1`, `P=absent`. Run `python3 scripts/board-sync.py promote --issue <prd#> --wave
+   "$WAVE"`, refetch body, comments, labels, Wave, and title. Post: `S=n/a`,
+   `B=yes`, `C=exact-1`, `P=complete`. Re-running `promote` with the same Wave
+   is the repair for `P=partial`; a different Wave remains a hard stop.
+
+Any other predicate combination is drift, not a fifth state. Repair it
+explicitly, then reclassify. `S=no` before transition 1 means **STOP**: report
+the diff between the fresh remote body and `/tmp/source-prd.md`, never write the
+stale render, re-fetch the remote body into a reviewed source snapshot, and
+rerender both outputs before recomputing `S`. `B=no` outside the valid `initial` tuple
+means **STOP**, report the body diff against `/tmp/anchor.md`, and require
+an explicit operator decision to restore the rendered anchor or adopt the remote
+edit and rerender both outputs; never overwrite remote journal evidence automatically.
+Only transition 1 performs the approved source-to-anchor body write without
+this drift gate. `C=wrong-1` → report its ID and explicitly update it to the
+rendered archive; `P=complete` with `C=0` → create/reconcile the archive without
+demoting. For `P=partial`, a different Wave is a hard stop; otherwise rerun
+same-Wave `promote`. `C=duplicates(<ids>)` always means **STOP and report every
+comment ID**. An operator must choose and explicitly delete/update the
+duplicates, then rerun the paginated lookup; never select the first match or
+silently discard one. No local operation journal is written: these
+observations are the journal.
+
+```bash
+# 3. Continue only from the `promoted` state.
 
 # 4. create each child (dependency order), then link it under the anchor — BEFORE the §7 exit audit,
 #    so the checker sees the anchor's children (a childless type:cluster anchor mis-reads as a leaf)

package/.claude/skills/to-prd/SKILL.md

@@ -49,11 +49,21 @@ gh project item-list 1 --owner <owner> --limit 500 --format json   # check targe
 - **Mode A — idempotency via two separate markers in the body:**
   - **Stable source identity** `<!-- prd-source-id: <id> -->` — **never** changes across plan content edits (otherwise search-before-create misses the changed re-run → duplicate). **Default rule** for `<id>` (identity ≠ content; set on the **first** to-prd run, **never** changed after — the slug then lives in the issue body and is discoverable via search-before-create): kebab-case slug of the plan topic. Priority: **(1)** explicitly passed ID / durable issue number → **(2)** existing slug from a prior run (found via search-before-create) → **(3)** new kebab-case slug from the plan/title topic. The `PLAN.md` path is only a **secondary hint** (not stable across worktrees; external specs have none), **never** the identity itself.
   - **Separate content fingerprint** `<!-- prd-content-fp: <hash> -->` — only for diff/audit/bump decisions, **not** for identity.
-- **search-before-create:** **no** reliance on GitHub Search (doesn't index HTML comments). Bounded, local:
+- **search-before-create:** use the shared all-state exact-marker lookup (it uses
+  `gh api --paginate`, discards REST pull-request items, and never relies on
+  GitHub Search or a capped issue list):
   ```bash
-  gh issue list --repo <owner>/<repo> --state open --limit 500 --json number,body,labels
-  # filter locally on `prd-source-id: <id>` → 1 match ⇒ update; >1 ⇒ STOP+report; 0 ⇒ create
+  python3 scripts/find-by-marker.py --kind prd-source-id --slug "<id>"
   ```
+  Branch on its JSON contract (`count`, `issues[].number`, `issues[].state`,
+  `verdict`): `0` / `create` → create; exactly one `open` / `update` → update
+  that issue; exactly one `closed` / `user-decision` → ask the user whether to
+  reopen, use a new identity, or stop; `>1` / `STOP` → stop and report every
+  number/state. Never auto-delete or silently replace a closed/duplicate identity.
+  Immediately after a Mode-A create, run the same lookup with
+  `--created <new-issue-number>`. Continue only when it returns exactly the
+  newly-created open issue; duplicate reconciliation is a loud `STOP` that
+  reports both/all numbers for user-decided resolution.
 
 ## 4. Write the Draft PRD (deliverable)
 

package/.claude/skills/to-waves/SKILL.md

@@ -192,10 +192,22 @@ A re-run of to-waves on the same program is **delta-apply** and doubles as
   bottom-up `wave-stub-source` marker; `<prd-source-id>` is the PRD's own source
   slug). These never change across revisions — they are the identity for
   search-before-create.
-- **Delta apply.** Filter existing issues locally by their source marker
-  (`gh issue list --json number,body` + a local filter, no reliance on GitHub search —
-  it does not index HTML comments). For each planned stub/leaf: **match** → update in
-  place (never duplicate); **missing** → create; a live issue carrying a
+- **Delta apply.** Resolve every planned identity through the shared all-state,
+  exact-marker CLI (it uses `gh api --paginate`, discards REST pull-request
+  items, and does not rely on GitHub Search or a capped issue list):
+  ```bash
+  python3 scripts/find-by-marker.py --kind program-stub-source --slug "<prd-source-id>/w<N>"
+  python3 scripts/find-by-marker.py --kind program-leaf-source --slug "<prd-source-id>/<local-id>"
+  ```
+  Branch on each JSON result (`count`, `issues[].number`, `issues[].state`,
+  `verdict`): `0` / `create` → create; exactly one `open` / `update` → update in
+  place; exactly one `closed` / `user-decision` → ask the user whether to reopen,
+  use a new identity, or stop; `>1` / `STOP` → stop and report every number/state.
+  Never auto-delete or silently replace a closed/duplicate identity. Immediately
+  after every create, run the same lookup with `--created <new-issue-number>` and
+  continue only when exactly the newly-created open issue is returned; a duplicate
+  reconciliation stops loudly with both/all numbers for user-decided resolution.
+  A live issue carrying a
   `program-*-source` for this program that the current plan no longer references →
   report as **orphaned** (do not auto-close — closing is the abort convention, §8).
   Cross-check the native children (`children-of <prd#>` and each stub) against the

package/.claude/skills/wrapup/SKILL.md

@@ -89,5 +89,4 @@ STOP → diagnose in the main conversation, fix, re-run `land` (an already-merge
 
 ## Out of scope
 - Live-verify / DoD: must happen **before** `/wrapup` — this skill lands, it does not verify.
-- `/retro`: offered before landing (step 2), never run by this skill.
 - Other worktrees / their servers stay untouched.

package/README.md

@@ -348,6 +348,29 @@ concurrency-safe. Do not run manifest-mutating commands concurrently. Flags:
 
 ## Release notes
 
+### 0.29.0
+
+- added: `scripts/codex-exec.sh`
+- added: `scripts/codex_proc.py`
+- added: `scripts/find-by-marker.py`
+- added: `scripts/marker_lib.py`
+- added: `scripts/render-anchor.py`
+- changed: `.agents/skills/board-to-waves/SKILL.md`
+- changed: `.agents/skills/to-issues/SKILL.md`
+- changed: `.agents/skills/to-prd/SKILL.md`
+- changed: `.agents/skills/to-waves/SKILL.md`
+- changed: `.agents/skills/wrapup/SKILL.md`
+- changed: `.claude/skills/board-to-waves/SKILL.md`
+- changed: `.claude/skills/codex-build/SKILL.md`
+- changed: `.claude/skills/codex-review/SKILL.md`
+- changed: `.claude/skills/grill-me-codex/SKILL.md`
+- changed: `.claude/skills/grill-with-docs-codex/SKILL.md`
+- changed: `.claude/skills/to-issues/SKILL.md`
+- changed: `.claude/skills/to-prd/SKILL.md`
+- changed: `.claude/skills/to-waves/SKILL.md`
+- changed: `.claude/skills/wrapup/SKILL.md`
+- changed: `scripts/board-sync.py`
+
 ### 0.28.0
 
 - added: `.claude/hooks/kit-origin-edit-hint.py`