@ikon85/agent-workflow-kit 0.27.1 → 0.29.0

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

@@ -54,7 +54,7 @@ Even when the slices were already cut upstream (a grill/PRD slice table), do NOT
 - **Seam ownership check (Fix A):** does any slice **replace/unify/retire a central mechanism**? If yes, it MUST be its own 🧊 grill-needed slice — NOT hidden in a behavior-preserving naming/tweak leaf. A byte-neutral slice does not discharge the seam.
 - **Blast-radius threshold:** for each slice, estimate the blast radius (~N files, from recon/grep — not a guess; workflow slices count SKILL.md + adapter mirrors + tests). **≥ 10 estimated files OR not estimable → check for a split.** If the slice stays deliberately large, it MUST be 🧊 **grill-needed** (HITL) with a "why indivisible" justification **in the issue body** — a guideline, not a hard block, but the deviation lives in the body, not in the agent's head. (Incident: a slice cut too coarse ballooned to 34 prod files at execute-recon, an emergency in-build split — no gate at the cut existed.) (Terminology note: this blast radius is a **slice estimate** — ~N files for this one cut — not a project-owned rollout-completeness census (e.g. an-style, code-derived "X of Y" census over all surfaces of a cross-cutting concept, if your repo runs one).)
 <!-- mirror-xform:start codex-escalation -->
-- **Gate type + sequencing (Retro):** every slice that is **not** a clean AFK build gets a gate tag — 🧭 **Design Grill** (a decision with alternatives, hard-to-reverse, ADR-worthy → `grill-with-docs`), 🔬 **Verify Spike** (a pure fact question, read-only), 📐 **Trade-off/Research** (a concrete trade-off choice OR "needs more research", **below** the grill threshold — read-only research + a documented trade-off in the issue), 📝 **Review Note** (a finding, **not** a build slice). A gate slice (🧭/🔬/📐) is cut as its **own slice**, sequenced **before** its dependent build slice, and blocks it (gate-before-build — published as a **native blocking edge** (§5a step 5), visible in the mirrored "Blocked by" section + table order). "Needs a decision / open call / research gap" while cutting → gate slice, **never** a blind AFK `/tdd`. (🔬 **Verify Spike** runs via the `verify-spike` skill — read-only fact question, throwaway harness, verdict as ADR/comment, the throwaway deleted. 📐 **Trade-off/Research** runs via the `decision-gate` skill — options + criteria, read-only research/measurement, a documented trade-off table, a reasoned decision as ADR/comment; throwaway measurement code deleted.)
+- **Gate type + sequencing (Retro):** every slice that is **not** a clean AFK build gets a gate tag — 🧭 **Design Grill** (a decision with alternatives, hard-to-reverse, ADR-worthy → `grill-with-docs`), 🔬 **Verify Spike** (a pure fact question, read-only), 📐 **Trade-off/Research** (a concrete trade-off choice OR "needs more research", **below** the grill threshold — read-only research + a documented trade-off in the issue), 📝 **Review Note** (a finding, **not** a build slice). A gate slice (🧭/🔬/📐) is cut as its **own slice**, sequenced **before** its dependent build slice, and blocks it (gate-before-build — published as a **native blocking edge** (§5a step 5), visible in the mirrored "Blocked by" section + table order). "Needs a decision / open call / research gap" while cutting → gate slice, **never** a blind AFK `/implement`. (🔬 **Verify Spike** runs via the `verify-spike` skill — read-only fact question, throwaway harness, verdict as ADR/comment, the throwaway deleted. 📐 **Trade-off/Research** runs via the `decision-gate` skill — options + criteria, read-only research/measurement, a documented trade-off table, a reasoned decision as ADR/comment; throwaway measurement code deleted.)
 <!-- mirror-xform:end -->
 - **🧭-vs.-📐 discriminator:** if the decision replaces/unifies/retires a **central seam**, is a **one-way door** (hard/costly to reverse), or a **schema migration** → 🧭 Design Grill (ADR-worthy, see Seam Ownership above). Otherwise — a **bounded choice between concrete options**, easily revised → 📐 Trade-off/Research.
 - **Absence-before-build (Retro):** a slice cut as "build feature/page/endpoint/flow X" (or a gate "X gap unclear") MUST cite an **existence grep** — *absent* (`grep <pattern> = 0` across route **and** UI **and** repo) OR *partial* (`exists @<file>, gap = <Y>`). A hedge ("current state unclear → verify during build") is **not** a valid slice state: the check is cheap (minutes), so it happens **at the cut**, not deferred into a gate. (Incident: a gate was cut for a feature that greps already showed built — the gap was deferred instead of resolved.)
@@ -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)
@@ -302,7 +377,7 @@ Reference the blocking ticket(s), or "None - can start immediately".
 <!-- mirror-xform:start codex-escalation -->
 ```
 Welle <N> · Slice <X> (<closes #x | refs #<prd#>, Parent #<prd#>>). Read #<prd#> for decisions.
-Start skill: 🧭 Design Grill → /grill-with-docs · 🔬 Verify Spike → /verify-spike · 📐 Trade-off/Research → /decision-gate · AFK → /tdd · HITL → /grill-me → /tdd. Recommended model: <Model [Effort]>.
+Start skill: 🧭 Design Grill → /grill-with-docs · 🔬 Verify Spike → /verify-spike · 📐 Trade-off/Research → /decision-gate · AFK → /implement · HITL → /grill-me → /implement. Recommended model: <Model [Effort]>.
 Worktree: your project's worktree helper, or `git worktree add`
 Scope (<N> files) — REQUIRED FIELD, blast-radius estimate at cut time; the build session checks it against its own recon findings, >2x deviation → STOP:
 - <concrete file + change>

package/.agents/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/.agents/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/.agents/skills/verify-spike/SKILL.md

@@ -17,7 +17,7 @@ This is the "Verify First" rule with a runnable harness behind it: when you cann
 | "Which of these options, given these trade-offs?" / "I need to research this before I can choose." (bounded, sub-grill) | `decision-gate` |
 | "Does this design / state model / UI feel right?" (open-ended) | `prototype` |
 | "Why is this broken / slow?" (root-cause of a known defect) | `diagnose` |
-| "Build this behaviour, test-first." (new feature/fix) | `tdd` |
+| "Build this behaviour, test-first." (new feature/fix) | `implement` |
 
 If the question is really "what should this be", it is not a verify-spike — those are open, not yes/no.
 

package/.agents/skills/wrapup/SKILL.md

@@ -29,9 +29,21 @@ Hard stop (the only pure precondition): not in a feature worktree / on `main`
 
 ### 2 · Retro gate (blocking, optional retro-exit — before anything is committed)
 One reminder, not a merge confirmation:
-> "Already ran a retro? **(a)** yes / continue → landing now. **(b)** you want one first → clean abort here, run `/retro`, then `/wrapup` again — repo-file patches then travel in this PR."
+> "Already ran a retro? **(a)** yes / continue → landing now. **(b)** you want one first → the retro starts now; afterwards, invoke `/wrapup` again — repo-file patches then travel in this PR."
 
-(b) → exit cleanly, touch nothing (a skill can't pause/resume another skill). **Never auto-run `/retro`.** The answer materializes as the mandatory `**Retro:**` PR-body line in step 4 — that's recording, not a second question. Why the gate lives here: in a foreign project this is the only portable retro touchpoint; a project-local "offer retro before PR" convention usually answers it already.
+(b) → **invoke the `retro` skill immediately in this run.** Retro is
+model-invocable and non-deploying, and every mutation still has its own approval
+gate. After retro finishes, **land nothing in this run**. Require a **fresh
+explicit `/wrapup` invocation** because retro may have changed the exact diff
+that the next merge authorization covers.
+
+General chaining rule: automatically chain only into a **model-invocable**,
+**non-deploying** workflow. If the named target is user-only, deploys, or
+depends on an external action, **return control to the user** and **state the
+reason**. A forward chain never carries wrapup's merge/deploy authorization
+into another run.
+
+The answer materializes as the mandatory `**Retro:**` PR-body line in step 4 — that's recording, not a second question. Why the gate lives here: in a foreign project this is the only portable retro touchpoint; a project-local "offer retro before PR" convention usually answers it already.
 
 ### 3 · Commit (only if the tree is dirty)
 Judgment first, then the guarded commit:
@@ -67,5 +79,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/.claude/hooks/drift-guard.py

@@ -48,8 +48,11 @@ GUARD_ACK_RE = re.compile(r"<!--\s*guard-ack:\s*#?\d+\s+r\d+\s+reason:.+\bby-use
 # Load the shared checker (hyphenated filename → importlib). Repo root = parents[2].
 _CHECKER_PATH = Path(__file__).resolve().parents[2] / "scripts" / "execute-ready-check.py"
 _CENSUS_MODULE_PATH = Path(__file__).resolve().parents[2] / "scripts" / "census" / "index.mjs"
-CENSUS_BRIDGE_TIMEOUT_SECONDS = 15
-CENSUS_PROOF_TIMEOUT_MS = 5_000
+# Production repositories can need more than the former five-second proof and
+# fifteen-second bridge budgets. Keep the default proof comfortably below the
+# outer bridge so a hung repository-local proof still cannot wedge the hook.
+CENSUS_BRIDGE_TIMEOUT_SECONDS = 30
+CENSUS_PROOF_TIMEOUT_MS = 12_000
 
 _CENSUS_SCAN = r"""
 import { readFileSync } from 'node:fs';

package/.claude/hooks/kit-origin-edit-hint.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+"""Advisory PreToolUse hint for kit-origin Edit/Write targets.
+
+Covered surface: agent Edit/Write tools only. Shell redirection, formatters, and
+IDE edits are knowingly uncovered; the skills remain the rule's primary
+carrier. This hook never enforces or blocks. It performs a single manifest read,
+does no network work, and fails open silently when input or manifest is unusable.
+"""
+import json
+import sys
+from pathlib import Path
+
+MANIFEST = "agent-workflow-kit.json"
+TOOLS = {"Edit", "Write"}
+HINT = (
+    "This file has kit origin. Before editing, ask: should this change go "
+    "upstream to agent-workflow-kit, or should the consumer own this file?"
+)
+
+
+def manifest_path(file_path: str, root: Path) -> str | None:
+    try:
+        target = Path(file_path)
+        target = target if target.is_absolute() else root / target
+        normalized = target.resolve().relative_to(root.resolve()).as_posix()
+    except (OSError, ValueError):
+        return None
+    return normalized or None
+
+
+def is_kit_origin(payload: object, root: Path) -> bool:
+    if not isinstance(payload, dict) or payload.get("tool_name") not in TOOLS:
+        return False
+    tool_input = payload.get("tool_input")
+    if not isinstance(tool_input, dict) or not isinstance(tool_input.get("file_path"), str):
+        return False
+    path = manifest_path(tool_input["file_path"], root)
+    if path is None:
+        return False
+    manifest = json.loads((root / MANIFEST).read_text(encoding="utf-8"))
+    installed = manifest.get("installed", []) if isinstance(manifest, dict) else []
+    return any(
+        isinstance(entry, dict) and entry.get("path") == path and entry.get("origin") == "kit"
+        for entry in installed
+    )
+
+
+def main() -> int:
+    try:
+        payload = json.load(sys.stdin)
+        if is_kit_origin(payload, Path.cwd()):
+            print(json.dumps({
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "additionalContext": HINT,
+                }
+            }))
+    except (OSError, ValueError, TypeError):
+        pass
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.claude/skills/ask-matt/SKILL.md

@@ -53,7 +53,7 @@ Prefer the smallest depth that produces a clear next action.
 - **Deep:** `/grill-with-docs` followed by `/to-prd` and `/to-issues` when
   terminology, contracts, rollout order, or ownership are still uncertain.
 - **Medium:** `/to-issues` for a ready artefact that needs slicing.
-- **Light:** direct `/tdd` for a small, well-understood change.
+- **Light:** direct `/implement` for a small, well-understood change.
 - **Gate:** insert `/verify-spike` or `/decision-gate` before any depth level
   when a slice hinges on an unresolved fact or trade-off.
 
@@ -75,7 +75,7 @@ A starting situation that generates work, then merges onto the main flow.
 - **Something's broken** → **`/diagnose`**. For the hard ones: the bug that resists a first glance, the intermittent flake, the regression between two known-good states. Refuses to theorise until it has a **tight feedback loop** — one command that already goes red on *this* bug — then fixes with a regression test. Its post-mortem hands off to **`/improve-codebase-architecture`** when the finding is that there's no good seam.
 - **A huge, foggy effort too big for one agent session** — a greenfield build or a sprawling feature where the way from here to the destination isn't yet visible, and it's still **pre-spec** (before any grill or PRD) → **`/wayfinder`** (user-invoked). It charts a **shared map** of investigation slices on the tracker and resolves them one at a time — producing **decisions, not deliverables** — until the fog lifts and the route is clear, then merges onto the main flow at **`/to-prd`** (or, if the effort turned out small enough, straight to **`/implement`**). Where `/grill-with-docs` sharpens an idea you can hold in one session, wayfinder is for the one you can't. Once an undertaking has already resolved into several independently-shippable waves, `/scale-check` → `/to-waves` stays the primary route.
 - **A backlog to cluster** → **`/board-to-waves`**. Groups an existing board into themed waves when you need to *find* the next wave rather than start fresh.
-- **A whole wave to LAND** → **`/orchestrate-wave`**. When a wave anchor (file-disjoint slices, specs already locked) is ready to build, verify and land end-to-end — often AFK: it dispatches an implementer per slice in its own worktree, integrates serially, verifies centrally, and lands the wave. The execute-and-land node of the wave ladder (`scale-check` → `to-waves`/`board-to-waves` → `orchestrate-wave`). A single slice just goes to `/tdd`.
+- **A whole wave to LAND** → **`/orchestrate-wave`**. When a wave anchor (file-disjoint slices, specs already locked) is ready to build, verify and land end-to-end — often AFK: it dispatches an implementer per slice in its own worktree, integrates serially, verifies centrally, and lands the wave. The execute-and-land node of the wave ladder (`scale-check` → `to-waves`/`board-to-waves` → `orchestrate-wave`). A single slice just goes to `/implement`.
 
 ## Cross-model review (Codex)
 

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

@@ -110,11 +110,21 @@ Body from `docs/agents/wave-anchor-template.md` **stage 1** (header + cluster or
 
 **Idempotency — stub marker + search-before-create (mandatory, BEFORE `create`).** Re-runs of board-to-waves must **not** produce duplicate stubs (a duplicate stub would confuse Mode-B identity in `to-prd`). Mirrors the `to-prd` pattern:
 - **Stable stub marker** `<!-- wave-stub-source: <topic-slug> -->` as the **first body line** of every stub. `<topic-slug>` = kebab-case slug of the gate outcome; set on the **first** run, **never** changed after (identity ≠ content — the slug stays findable even if members/size change later).
-- **search-before-create** per candidate **before** the `create`. **No** reliance on GitHub search (doesn't index HTML comments) — bounded, local:
+- **search-before-create** per candidate **before** the `create`, through 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
-  # locally filter on `wave-stub-source: <topic-slug>` → 1 match ⇒ skip + report (stub exists); >1 ⇒ STOP + report; 0 ⇒ create
+  python3 scripts/find-by-marker.py --kind wave-stub-source --slug "<topic-slug>"
   ```
+  Branch on its JSON contract (`count`, `issues[].number`, `issues[].state`,
+  `verdict`): `0` / `create` → create; exactly one `open` / `update` → skip the
+  create and report/update that stub; 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 create, run the same lookup with
+  `--created <new-issue-number>`; continue only when it returns exactly the
+  newly-created open issue. Duplicate reconciliation stops loudly and reports
+  both/all numbers for user-decided resolution.
 
 **Create the candidate stub (cluster/wave-less)** — issue **without** `type:cluster` and **without** `--wave` (exactly one `type:*` + one `priority:*`; title **without** a `Welle <N>` prefix, since the wave number is only assigned at promotion), **with `--wave-stub`** (a searchable "awaiting planning" filter — the HTML marker above is only locally greppable, GitHub doesn't index it), attach to the board, triaged-role status (clustered, not yet planned). `to-prd` then matures the stub (Mode B) into a Draft PRD, `to-issues` promotes it to an anchor (sets `type:cluster` + Wave then, **strips `wave-stub`** — the stub leaves the planning list):
 ```bash

package/.claude/skills/codex-build/SKILL.md

@@ -13,12 +13,14 @@ The role-flip of `/codex-review`: there, Claude builds the plan and Codex critiq
 
 ## 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` or model config (e.g. `model_reasoning_effort`) unless the user asks. Pinning `gpt-5.x-codex` variants 400s on ChatGPT-account auth; config defaults come from `~/.codex/config.toml`.
 - **Echo the active model at kickoff** so the user can confirm: read the `model` line from `~/.codex/config.toml` (absent = "CLI default"); state it with the resolved tunables. If the user objects, stop before launching the build.
-- **Codex has a native image-generation tool** in `codex exec` sessions (ChatGPT-account backed, no API key; upstream-verified 2026-07-08). Specs may therefore include "generate these image assets yourself" steps: name exact file paths, dimensions, and style in the prompt contract.
-- Run from the target working directory's root (both `exec` and `resume` then need no `-C`; `resume` doesn't support `-C` anyway).
+- **Codex has a native image-generation tool** in delegated sessions (ChatGPT-account backed, no API key; upstream-verified 2026-07-08). Specs may therefore include "generate these image assets yourself" steps: name exact file paths, dimensions, and style in the prompt contract.
+- Run the wrapper from the target working directory's root so every round keeps
+  the same bounded workspace.
 
 ## Tunables (read from args, else default)
 
@@ -63,17 +65,34 @@ OUTPUT: End with a report — files changed (one line each: path + what/why),
 EOF
 ```
 
-## Step 2 — Launch Codex (fresh session, capture `thread_id`)
+## Step 2 — Launch Codex (fresh wrapper-owned session)
 
 ```bash
-codex exec -s workspace-write --json -o "$CODEX_TMP/build.txt" - <"$P" 2>/dev/null | grep '"type":"thread.started"'
+if ROUND_RESULT=$(scripts/codex-exec.sh new --profile build --mode workspace-write --prompt-file "$P"); 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
 ```
 
-- **`-s workspace-write`, never `--yolo` / `--dangerously-bypass-approvals-and-sandbox`, and never weaken the approval policy.** The sandbox bounds Codex to the working directory; the allowed-write gate (Step 3) bounds it further to the declared set. If the build genuinely needs something outside the sandbox (network installs, system config), that step is Claude's, not Codex's — split it out of the spec.
-- Prompt goes via stdin (`- <"$P"`) — this both avoids quoting bugs AND sidesteps the non-TTY stdin hang (`codex exec` blocks forever waiting on stdin EOF under Claude Code's Bash tool; feeding the file gives immediate EOF).
-- Parse `thread_id` from the `{"type":"thread.started","thread_id":"..."}` line → `THREAD_ID`. Codex's final report lands in `$CODEX_TMP/build.txt` — read that file; don't parse the JSONL stream for content.
-- `2>/dev/null` suppresses cosmetic MCP/auth stderr noise. Confirm success by the report file + a `thread.started` line; neither → failed run (auth/model) — stop and tell the user.
-- **Timing:** foreground with `timeout: 600000` on the Bash tool call (default 2-min tool timeout kills real builds). If the spec is clearly >10 min of work (multi-file feature, migration, anything with image generation), launch with `run_in_background: true` instead and read the `-o` file when it exits. Don't kill a quiet background run early — Codex builds are legitimately slow.
+- The `build` profile establishes and persists `workspace-write`; never request
+  `danger-full-access` or weaken the approval policy. The wrapper bounds Codex
+  to the working directory, and the allowed-write gate (Step 3) narrows it to
+  the declared set. Work outside those bounds belongs to Claude and must be
+  split out of the spec.
+- The wrapper owns stdin closure, hang detection, the overall build timeout,
+  stderr redaction, and the launched process group. Never inspect, signal, or
+  kill foreign Codex processes.
+- `RUN_ID` is opaque. Retain it only for resume/finalize/abort; harvest the
+  report from `CODEX_REPORT` before deleting run state.
+- `handle-failure` surfaces every failed or cancelled structured result plus
+  cleanup metadata; the caller then stops before report handling. A surfaced
+  `HUNG` returns to the user for the choice to retry once with a fresh run or
+  stop delegation and let Claude take over. Never target a process directly.
+
 - **Heads-up on completion (required):** when a background Codex run finishes, the FIRST line of your next message to the user must be a loud standalone banner — `🔔 CODEX FINISHED — <what> (exit ok/fail) — verifying now` — BEFORE any verification output. The user is not watching tool calls; never let a completed build slide silently into the verify phase.
 
 ## Step 3 — Verify (Claude, always, never delegated)
@@ -83,33 +102,60 @@ Codex's report is advisory. Verify yourself:
 1. **Allowed-write gate:** `git status --porcelain=v1` — every changed AND untracked path must be inside the allowed-write set from Step 0.4. Any path outside it is a finding: surface it to the user before anything else, and don't fold it silently into the diff review.
 2. Read the FULL diff (`git diff`). Judge it like a contributor PR: correctness, spec fidelity, style match with surrounding code, nothing touched outside scope.
 3. Run `PROOF_CMD` yourself (or the focused tests for the changed area). Codex's pasted output doesn't count as proof.
-4. Append to `LOG_FILE` under `## Act 3 — Build`: `### Round <n> — Codex build` + its report summary + `### Claude's verdict` + what passed/failed review.
+4. Append to `LOG_FILE` under `## Act 3 — Build`: `### Round <n> — Codex build` + `CODEX_REPORT` + `### Claude's verdict` + what passed/failed review.
 
 ## Step 4 — Fix loop (same session, bounded)
 
 Problems found → resume the SAME session (Codex keeps its context; cheaper and better than a fresh run). Write the fix list to a second temp file (`$CODEX_TMP/fix-prompt.txt`), same contract discipline: exact problem, exact file, proof expected, same allowed-write set.
 
 ```bash
-# resume has no -s and no -C: run from the repo dir and force the sandbox via
-# config override, or Codex inherits config.toml's sandbox_mode (possibly
-# read-only — can't write; possibly danger-full-access — must never run).
-codex exec resume "$THREAD_ID" -c sandbox_mode="workspace-write" --json \
-  -o "$CODEX_TMP/build.txt" - <"$CODEX_TMP/fix-prompt.txt" 2>/dev/null >/dev/null
+if ROUND_RESULT=$(scripts/codex-exec.sh resume "$RUN_ID" --prompt-file "$CODEX_TMP/fix-prompt.txt"); 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
 ```
 
-Re-verify (Step 3, including the allowed-write gate) after each round. After `MAX_FIX_ROUNDS` failed rounds: STOP delegating — Claude takes over and finishes the remaining fixes directly. Log the takeover. Ping-ponging trivia through delegation burns more than it saves.
+The wrapper enforces the persisted workspace-write mode on every resume.
+Re-verify (Step 3, including the allowed-write gate) after each round. After
+`MAX_FIX_ROUNDS` failed rounds: abort this run, STOP delegating, and let Claude
+take over and finish the remaining fixes directly. Log the takeover.
+
+```bash
+scripts/codex-exec.sh abort "$RUN_ID"
+```
 
 ## Step 5 — Human gate (diff sign-off)
 
 Present: 3-bullet summary of what was built, files-changed list, proof-test output (pass/fail, verbatim tail), rounds used, any spec deviations. Ask: *"Codex built it, proof passes, diff reviewed. Commit?"*
 
-- Commit ONLY on yes — and Claude writes the commit, never Codex.
-- Rejected → ask what's wrong, route back to Step 4 (or take over directly if fix rounds are spent).
+- On yes, harvest and log the final report, then delete the wrapper state before
+  Claude commits:
+
+  ```bash
+  scripts/codex-exec.sh finalize "$RUN_ID"
+  ```
+
+- Commit ONLY after that finalize succeeds — and Claude writes the commit,
+  never Codex.
+- Rejected with another requested fix → keep the known run and route back to
+  Step 4 (or take over directly if fix rounds are spent).
+- Cancellation or a decision to stop delegation → abort the known run before
+  returning control:
+
+  ```bash
+  scripts/codex-exec.sh abort "$RUN_ID"
+  ```
 
 ## Hard rules
 
 - Clean tree before launch. Always. No exceptions.
-- **Sandbox is bounded every round:** `-s workspace-write` on exec, `-c sandbox_mode="workspace-write"` on every resume. Never `--yolo`, never `danger-full-access`, never a weakened approval policy — if the task can't be done inside those bounds, it isn't a Codex delegation.
+- **The mode is bounded every round:** establish `workspace-write` in the
+  wrapper's new call and let every resume inherit it. Never `--yolo`, never
+  `danger-full-access`, never a weakened approval policy — if the task can't
+  be done inside those bounds, it isn't a Codex delegation.
 - The allowed-write gate runs after EVERY round — out-of-set writes are findings, not noise.
 - Claude never skips the diff read. Codex claims are advisory until Claude has read the diff and run the proof.
 - Fix loop terminates at `MAX_FIX_ROUNDS` — then Claude takes over. No unbounded delegation ping-pong.
@@ -121,6 +167,6 @@ Present: 3-bullet summary of what was built, files-changed list, proof-test outp
 - Don't build without a spec — that's designing by delegation, and it fails. Route to `/grill-me-codex` or `/codex-review` first.
 - Don't use for ~<20-line single-obvious-change edits — just make the edit.
 - Don't pin `-codex` model variants on ChatGPT-account auth — 400s.
-- Don't resume with `--last` — capture and use the explicit `THREAD_ID` (parallel sessions make `--last` grab the wrong thread). And ECHO the id into the command visibly before running: `resume` with a missing/garbage id can silently fall back to the most recent session instead of erroring (observed upstream 2026-07-08) — a wrong-target resume looks exactly like a successful one.
-- Don't parse the JSONL stream for the report — read the `-o` file.
+- Don't resume with `--last`; use the wrapper's explicit opaque `RUN_ID` so
+  parallel sessions cannot target each other.
 - Don't let Codex commit, and don't auto-commit yourself — human gate first.