@ikon85/agent-workflow-kit 0.27.1 → 0.29.0

package/.claude/skills/orchestrate-wave/references/builder-contract.md

@@ -51,12 +51,14 @@ invocation for each in this prompt so the builder cannot guess a wrong one.
 2. Commit your ONE commit on the slice branch FIRST — before any longer verify
    (verify-then-forget-to-commit leaves the orchestrator hand-committing your
    worktree). Do NOT push. Do NOT `--no-verify` (pre-commit hooks must pass).
-3. Run the commands above. Never end your turn with a background command still
-   running.
+3. Run the commands above IN THE FOREGROUND — never background a test/gate
+   command. Use a generous foreground timeout for a long suite and wait for every
+   completed command result. Never end your turn while a command is still running.
 
 ## Report back (concise)
-Files touched · decisions taken · test results (exact output) · commit SHA ·
-STOP items · what the orchestrator should visually verify.
+Files touched · decisions taken · test results (exact completed command results
+and exit status) · commit SHA · STOP items · what the orchestrator should visually
+verify.
 ```
 
 Orchestrator notes:

package/.claude/skills/retro/SKILL.md

@@ -114,6 +114,25 @@ For **every** friction point (user-reported AND self-found), the agent analyzes:
 
 If the user's description in step 2a is ambiguous, the agent may ask **ONE** clarifying outcome question — e.g. "where was it most annoying — during setup, mid-work, or during cleanup?". Never multiple-choice with memory names, hook paths, or config classes.
 
+### 3a. Mechanical enforcement check (before target + weight)
+
+Before placing a finding on the target/weight ladder, ask for every finding:
+
+> **"Could a machine decide this — with a grep, parser, test, hook, or CI gate?"**
+
+- **Yes, within the current patch:** implement the enforcement. Supporting prose
+  may explain the rule, but prose alone does not resolve a machine-checkable
+  finding.
+- **Yes, but enforcement is too expensive for the current patch:** propose the
+  prose change **plus a tracked enforcement issue** and state the **explicit
+  trade-off** (why enforcement is deferred, what failure remains possible, and
+  when the issue should fire). Do not present the prose-only half as complete.
+- **No:** record why judgment is required, then continue to the target/weight
+  ladder.
+
+This check prevents detection without enforcement: a rule that a machine can
+decide should not depend on a future reader remembering a sentence.
+
 ### 3b. Determine target + weight (threshold ladder)
 
 Before formulating a patch in step 4, place **every** friction point on the threshold ladder. **Weight** = how durable/far-reaching the rule is (drives the visible patch line in step 4 + the user's approval depth). **Target** = where the patch physically goes.
@@ -137,6 +156,10 @@ Before formulating a patch in step 4, place **every** friction point on the thre
 
 **A GitHub issue is NOT a weight tier.** A real follow-up = work to track → `python3 scripts/board-sync.py create` (step-4 table), **orthogonal** to the ladder; its "weight" follows the follow-up scope. The ladder classifies **config patches**, not "turn it into a ticket".
 
+**Kit-repo routing target (always ask; never automatic).** When a finding lands on a kit-shipped file (a consumer-manifest entry with kit origin), ask whether the improvement is generic or project-specific. For a generic improvement, offer to file a lightweight issue against the public kit repo: a title plus a short body that states the finding, affected file, and why it is generic. For a project-specific improvement, recommend `own` (keep it consumer-owned). The consumer user does not need to be the kit maintainer.
+
+Before any `gh issue create --repo <owner>/agent-workflow-kit` runs, show the user a **sanitized preview** of the exact title and body with consumer identifiers and secrets stripped. Create the issue only after the user explicitly approves that exact text; if the title or body changes, show the revised preview and ask again. This approval is additional to the per-patch approval in step 5.
+
 **Target missing in the project — separate two cases cleanly:**
 - **(a) Tier skill missing entirely** (e.g. a foreign project without `spec-self-critique`): no durable spec-time gate exists. **Memory is NOT a substitute** — passive recall doesn't catch a recurring spec defect before building. Report honestly: *"this project has no durable target for this tier"* + propose a `/setup-workflow` follow-up. **No fake guard via memory.**
 - **(b) Skill exists, project-layer file missing** (`docs/agents/skills/<skill>.md`): **create / append** — that is the normal retro-sink behavior that `spec-self-critique` step 0 expects anyway. **No** downgrade.

package/.claude/skills/scale-check/SKILL.md

@@ -119,7 +119,7 @@ One behavior, already clear enough to build — no PRD, no slicing.
 
 ```
 Small change: <one-sentence behavior>.
-`tdd` — one behavior at a time, red → green → refactor. No PRD, no decomposition.
+`implement` — build directly, one behavior at a time (red → green → refactor). No PRD, no decomposition.
 ```
 
 ### Bug (something that used to work)
@@ -134,7 +134,7 @@ Bug: <what's broken — expected vs. actual>.
 ```
 scale-check: verdict=<Program | Feature | Direct-Slice | Bug>
   criteria tripped=<C1,C2,… | none | n/a (bug/direct)>
-  route=<program grill → to-prd → to-waves (all waves execute-ready by default) | grill-with-docs → to-prd → to-issues | tdd | diagnose>
+  route=<program grill → to-prd → to-waves (all waves execute-ready by default) | grill-with-docs → to-prd → to-issues | implement | diagnose>
   start-prompt: <the paste-ready block above, filled in>
 ```
 

package/.claude/skills/setup-workflow/SKILL.md

@@ -27,6 +27,7 @@ This is a prompt-driven skill, not a deterministic script. Explore, present what
 | `.github/workflows/agent-workflow-kit-update.yml` | optional tested Kit update pull request for GitHub consumers (Section A2) |
 | `docs/agents/census.md` | optional-census choice, paths, state, and safe disable contract seeded from [census.md](./census.md) (Section A3) |
 | `docs/agents/workflow-capabilities.json` + capability assets | consumer-owned Worktree Lifecycle, Memory Lifecycle, Workflow Advisories, and Safety Guardrails choices (Sections A4–A7) |
+| `.claude/settings.json` | additive activation of the advisory kit-origin Edit/Write hint (Section A8) |
 
 ## Idempotency contract — read before writing anything
 
@@ -57,7 +58,7 @@ Read the current state; don't assume. For every target file, read its first line
 - `CONTEXT.md`, `CONTEXT-MAP.md`, `docs/adr/` — domain-doc layout.
 - `docs/agents/`, `docs/agents/skills/`, `docs/conventions/` — prior output of this skill.
 - `docs/agents/census.md`, `.census/profile.json`, `.census/active.json` — an existing census choice or consumer-owned census to adopt.
-- `docs/agents/workflow-capabilities.json`, `.claude/settings.json`, `git config --get core.hooksPath` — existing capability choices/profile plus Worktree Lifecycle, Workflow Advisories, and Safety Guardrails wiring to adopt.
+- `docs/agents/workflow-capabilities.json`, `.claude/settings.json`, `git config --get core.hooksPath` — existing capability choices/profile plus Worktree Lifecycle, Workflow Advisories, Safety Guardrails, and kit-origin hint wiring to adopt.
 - `.memory/active/`, `.memory/archive/`, and `.memory/receipts/` — consumer-owned Memory Lifecycle policies or recovery evidence to adopt without normalization.
 - `gh auth status` (if GitHub) — is `gh` authenticated, and with which scopes?
 
@@ -243,6 +244,42 @@ The seed's reference consumer uses the parity-on profile. Other consumers are
 opt-in/manual: never copy its package-manager, path, shim, surface, or outage
 decisions without repository evidence and user confirmation.
 
+### 2g. Section A8 — Advisory kit-origin edit hint (non-interactive)
+
+> The shipped kit-origin hook asks the upstream-or-own question before an agent
+> Edit/Write changes a file recorded with `origin: "kit"` in the consumer
+> manifest. It is advisory only: it never blocks, reads the manifest once, uses
+> no network, and silently fails open when the manifest cannot be read. Shell
+> redirection, formatters, and IDE edits are knowingly outside its coverage; the
+> skills remain the rule's primary carrier.
+
+Activate the shipped hook by reconciling this exact entry into
+`.claude/settings.json`:
+
+```json kit-origin-edit-hook-settings
+{
+  "matcher": "Edit|Write",
+  "hooks": [
+    {
+      "type": "command",
+      "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/kit-origin-edit-hint.py\""
+    }
+  ]
+}
+```
+
+This is an additive, idempotent settings edit, not a settings rewrite:
+
+1. Missing settings → create `{ "hooks": { "PreToolUse": [<entry>] } }`.
+2. Existing valid settings → preserve every consumer key, matcher, command,
+   hook event, ordering, and formatting byte-for-byte; append only `<entry>` to
+   `hooks.PreToolUse`.
+3. If any existing hook already contains the exact command above, do nothing,
+   regardless of its surrounding matcher. A rerun must be byte-identical.
+4. Unreadable/invalid settings, or a non-object `hooks` / non-array
+   `PreToolUse`, are consumer-owned conflicts: leave the file untouched and
+   report the skipped activation. Never replace or normalize them.
+
 ### 3. Section B — Triage labels
 
 > When `triage` processes an incoming issue it applies labels (or your tracker's equivalent). It needs strings you've actually configured, or it creates duplicates.
@@ -341,6 +378,12 @@ Do not copy templates with shell commands or edit the capability profile by
 hand. Report `seeded · adopted · skipped`; do not print memory contents or
 receipt contents.
 
+For `.claude/settings.json`, run the Section A8 reconciliation on fresh and
+already-initialized consumers. Report `activated · already active · skipped
+(consumer-owned conflict)`. Do not make the hook conditional on an optional
+capability choice: its self-filtering, fail-open behavior keeps it inert except
+for matching kit-origin Edit/Write events.
+
 For the **`## Workflow`**, **`## Agent skills`**, and **`## Prod`** blocks, reconcile per section in **both** CLAUDE.md and AGENTS.md that exist:
 
 - If **both** files exist → write/update the block in **both** (keep them coherent — Codex is a first-class surface).

package/.claude/skills/setup-workflow/workflow-overview.md

@@ -11,12 +11,12 @@ Use this section as the entry-point map for agent-assisted work. The individual
 - **Existing plan, PRD, or ready issue:** use `to-issues` to split it into independently buildable tracer-bullet slices.
 - **A Program-PRD with a wave plan:** use `to-waves` to unfold it into named wave stubs + slice leaves on the board, after a chat preview gate that shows the whole plan before any write.
 - **A backlog of open issues needs clustering into themed waves:** use `board-to-waves`.
-- **A whole wave anchor (file-disjoint slices, specs already locked) to build, verify and land end-to-end — often AFK:** use `orchestrate-wave` — it dispatches implementers per slice, integrates serially, verifies centrally, and lands. (A single slice just goes to `tdd`.)
+- **A whole wave anchor (file-disjoint slices, specs already locked) to build, verify and land end-to-end — often AFK:** use `orchestrate-wave` — it dispatches implementers per slice, integrates serially, verifies centrally, and lands. (A single slice just goes to `implement`.)
 - **Bugs or requests piling up that you didn't create:** use `triage` to move them into agent-ready issues.
 - **Bug or regression:** use `diagnose` to reproduce, minimize, hypothesize, instrument, fix, and regression-test.
 - **A design question needs a runnable answer (state, business logic, a UI you have to see):** spike it with `prototype`, then fold what you learned back in.
-- **Multi-session build from a PRD or issue:** use `implement` to drive `tdd` end-to-end, one red-green slice at a time.
-- **Implementation slice:** use `tdd` for one behavior at a time: RED, GREEN, then refactor.
+- **Multi-session build from a PRD or issue:** use `implement` to drive the build end-to-end, one red-green slice at a time.
+- **Implementation slice:** use `implement` for one behavior at a time: RED, GREEN, then refactor.
 - **Build or refresh a project-local census:** use `census-update` to scan facts, resolve ambiguous decisions one at a time, and transactionally activate a counted census.
 - **Preview or restore consumer-owned memories:** use `memory-lifecycle` to classify every configured path without writing, then apply an explicitly approved collision-safe restore with a content-free receipt.
 - **Finished slice:** use `wrapup` to prepare the branch, PR, and cleanup steps your repo expects.
@@ -27,11 +27,11 @@ Use this section as the entry-point map for agent-assisted work. The individual
 
 ## Routing Rule
 
-Prefer the smallest workflow that produces a clear next action. A tiny fix can go straight to `tdd`; a cross-cutting feature should become a PRD and then slices before implementation. When a skill reports missing project context, run `setup-workflow` again and fill only the missing stub.
+Prefer the smallest workflow that produces a clear next action. A tiny fix can go straight to `implement`; a cross-cutting feature should become a PRD and then slices before implementation. When a skill reports missing project context, run `setup-workflow` again and fill only the missing stub.
 
 ## Depth Ladder
 
-- **Light:** direct `tdd` for a small, well-understood change.
+- **Light:** direct `implement` for a small, well-understood change.
 - **Medium:** `to-issues` for a ready artefact that needs slicing.
 - **Deep:** `grill-with-docs` followed by `to-prd` and `to-issues` when terminology, contracts, rollout order, or ownership are still uncertain.
 - **Gate:** insert `verify-spike` or `decision-gate` before any depth level when a slice hinges on an unresolved fact or trade-off.

package/.claude/skills/skill-manifest.json

@@ -150,7 +150,7 @@
     "tdd": {
       "class": "vendored",
       "publish": true,
-      "entryPoint": true,
+      "entryPoint": false,
       "surfaces": [
         "claude",
         "codex"

package/.claude/skills/tdd/SKILL.md

@@ -60,6 +60,8 @@ Before writing any code:
 
 - [ ] Confirm with user what interface changes are needed
 - [ ] Confirm with user which behaviors to test (prioritize)
+- [ ] Find the nearest existing tests for those behaviors
+- [ ] Assign exactly one test-delta decision per behavior
 - [ ] Identify opportunities for [deep modules](deep-modules.md) (small interface, deep implementation)
 - [ ] Design interfaces for [testability](interface-design.md)
 - [ ] List the behaviors to test (not implementation steps)
@@ -69,34 +71,81 @@ Ask: "What should the public interface look like? Which behaviors are most impor
 
 **You can't test everything.** Confirm with the user exactly which behaviors matter most. Focus testing effort on critical paths and complex logic, not every possible edge case.
 
-### 2. Tracer Bullet
-
-Write ONE test that confirms ONE thing about the system:
+### 2. Existing-Test-First Decision
+
+TDD does not imply a new test file or a growing test count. Start at the nearest
+existing behavioral test. For each planned behavior, record exactly one of these
+test-delta decisions:
+
+- **REUSE** — the existing public-behavior test already protects the change.
+- **EXTEND** — add the missing boundary to the nearest suite or parameter table.
+- **REPLACE** — establish equivalent protection at a smaller or more stable level,
+  then retire the duplicate.
+- **NEW** — only for a distinct, previously unprotected risk; name the plausible
+  defect it catches.
+- **RETIRE** — the behavior or contract is intentionally gone or already replaced;
+  delete its obsolete test.
+- **NO-NEW-TEST** — a behavior-neutral refactor or removal without a durable
+  negative contract.
+
+Do not create a new test file until the nearest existing owner has been inspected
+and rejected with a reason. A feature, source file, component, method, or
+acceptance-criterion line is not itself a test boundary.
+
+Every executable new behavior and bug fix must begin with a failing assertion.
+REUSE and NO-NEW-TEST never bypass this RED-first invariant. For a `REUSE`
+candidate, run the existing assertion before implementation: if the requested
+behavior is executable and the assertion is already green, an already-green
+assertion does not prove the requested change; choose `EXTEND`, or choose `NEW`
+after rejecting the nearest owner. `NO-NEW-TEST` is limited to behavior-neutral
+work and removals without a durable absence contract.
+
+For removals, delete the tests that specified the retired behavior. Add or keep a
+negative assertion (`404`, forbidden, hidden) only when absence itself is a durable
+security, API, or compatibility promise. Permanent skipped executable tests are
+retired or moved to a runbook or issue, not parked in the green suite.
+
+### Worked decision matrix
+
+| Behavior situation | Decision | Feedback proof |
+|---|---|---|
+| An existing regression test reproduces the bug | REUSE | Existing assertion is RED, then the minimal fix makes it GREEN |
+| The nearest suite lacks one requested boundary | EXTEND | Added assertion is RED, then the minimal change makes it GREEN |
+| A broad duplicate can become a stable focused check | REPLACE | Equivalent protection is proven before the duplicate is removed |
+| A distinct risk has no suitable owner after documented inspection | NEW | New assertion is RED and names the plausible defect it catches |
+| The specified behavior is intentionally removed | RETIRE | Obsolete test is removed with the obsolete behavior |
+| An internal refactor preserves all observable behavior | NO-NEW-TEST | Relevant existing suite is GREEN before and after the change |
+
+### 3. First Feedback Cycle
+
+Pick ONE behavior and use its decision's feedback loop:
 
 ```
-RED:   Write test for first behavior → test fails
-GREEN: Write minimal code to pass → test passes
+REUSE, executable change: existing assertion → RED → minimal code → GREEN
+EXTEND/NEW:              assertion in nearest suite → RED → minimal code → GREEN
+REUSE, neutral change:  relevant suite GREEN → small refactor → stays GREEN
+REPLACE:                 prove equivalent protection → remove duplicate → GREEN
+RETIRE:                  remove obsolete behavior and its obsolete test → GREEN
+NO-NEW-TEST:             relevant suite GREEN → behavior-neutral change → stays GREEN
 ```
 
-This is your tracer bullet - proves the path works end-to-end.
+The RED-to-GREEN cycle is the tracer bullet for each executable new behavior or
+bug fix. It proves the path end to end without automatically creating another
+test file.
 
-### 3. Incremental Loop
+### 4. Incremental Loop
 
-For each remaining behavior:
-
-```
-RED:   Write next test → fails
-GREEN: Minimal code to pass → passes
-```
+Repeat one behavior at a time, using the matching feedback loop above.
 
 Rules:
 
 - One test at a time
+- Prefer extending the existing owner or parameter matrix over adding a sibling file
 - Only enough code to pass current test
 - Don't anticipate future tests
 - Keep tests focused on observable behavior
 
-### 4. Refactor
+### 5. Refactor
 
 After all tests pass, look for [refactor candidates](refactoring.md):
 
@@ -114,7 +163,12 @@ After all tests pass, look for [refactor candidates](refactoring.md):
 [ ] Test describes behavior, not implementation
 [ ] Test uses public interface only
 [ ] Test would survive internal refactor
+[ ] Exactly one test-delta decision is recorded for this behavior
+[ ] NEW names the distinct plausible defect; a new file has a justified owner boundary
 [ ] Code is minimal for this test
 [ ] No speculative features added
 [ ] Wave slice: a flipped/new assumption affecting an unbuilt sibling issue → log it to ANNAHMEN.md (worktree root; wrapup Step 0c reads it)
 ```
+
+At handoff, list every behavior and its one decision, then report the counted
+test delta: `Reused X · Extended Y · New Z · Replaced/retired W`.

package/.claude/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-codex`), 🔬 **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-codex`), 🔬 **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-codex · 🔬 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-codex · 🔬 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/.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/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/.claude/skills/wrapup/SKILL.md

@@ -39,9 +39,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:
@@ -77,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.