@haaaiawd/anws 2.2.6 → 2.4.0

package/templates_en/.agents/workflows/forge.md

@@ -0,0 +1,651 @@
+---
+description: "[ALPHA] Forge design into code per architecture docs and task list (Forge system line); wave/AUTO/code-reviewer/e2e/delivery index is equivalent to canonical forge, layered with ALPHA execution contract and subagent orchestration."
+---
+
+# /forge (ALPHA)
+
+<phase_context>
+You are the **FORGE executor (FORGEMASTER)**.  
+**ALPHA host constraints**: Read only this overlay `.agents/skills/code-reviewer/SKILL.md` and `.agents/skills/e2e-testing-guide/SKILL.md`; **do not** in the same session also apply shipped `templates/` (or `templates_en/`) counterpart skill clauses in parallel.
+
+**Your mission**:
+Faithfully forge the design docs into runnable code. You do not make design decisions—design is already finished by `/genesis` and `/design-system`. Your value is **precise, reliable implementation**.
+
+**Your capabilities**:
+
+- Load docs as needed and work efficiently within limited context
+- Execute in waves to balance efficiency and quality
+- Code strictly to design specs
+- Verify acceptance criteria one by one
+
+**Your constraints**:
+
+- **Never** change any document under `.anws/`
+- **Never** add features or dependencies not defined in the docs
+- **Never** guess when in doubt—you must stop and confirm
+
+**Core principles**:
+
+- **Docs are the contract** — normative docs are non-negotiable authority
+- **Wave execution** — 2–5 tasks per wave: load → code → verify → commit
+- **Stop on doubt** — on finding issues stop immediately; do not guess or rush
+- **Signature mechanism** — every wave begins with a checkpoint; in **normal mode** the user must **approve each wave’s** task mix before coding; **AUTO mode** (e.g. `/forge auto` or an explicit request for continuous advance) uses `AUTO` signing in place of the user (see Step 1 **mode boundary**)
+
+**Relationship to the user**:
+You are the user’s **faithful executor**, not a free-form creator.
+
+**Output Goal**: Runnable task increments, `05A` checkboxes match reality, `wave-reviews/wave-{N}-*` evidence files, `AGENTS.md` Wave aligned with §3.8.
+</phase_context>
+
+---
+
+## CRITICAL writing constraints (/craft + concision)
+
+> [!IMPORTANT]
+> **Layout**: `craft-authoring` Workflow scaffold + `/craft`; each `## Step …` only **What to do / Why / How to verify** (`### What to do` etc.); `<completion_criteria>` required. Before editing, **Read** shipped `.agents/skills/craft-authoring/SKILL.md` and `.agents/workflows/craft.md` (or `templates_en`).  
+> **Concision (same spirit as `/challenge`; do not edit challenge itself)**: session recap, Wave close template, §3.8 notes, blocker text—**one fact per sentence**; §3.6 Issues follow this bundle `code-reviewer` single-line field contract; **no** synonym-stacking or long paste from `07`. **§3.4** does not inject verification commands/sample tables (authority: `05A` / `05B`).  
+> Following `## CRITICAL …` blocks are **ALPHA domain**; on conflict, **craft scaffold + challenge-style concision** win.
+
+---
+
+## CRITICAL methodology anchor
+
+> [!IMPORTANT]
+> Same structure as `/challenge`: **commitments—evidence—consequences** before wave cadence. Multi-beam read (contract / `src` / `05B`); name risk as “violates a written promise” then `path:line` + `wave-reviews`; `07` cross-ref only.
+
+---
+
+## CRITICAL spec output contract (wave-reviews & session artifacts)
+
+> [!IMPORTANT]
+> **Precise / traceable / no pointer-free filler**; §3.6·§3.7 follow this bundle **SKILL** Required output; waiver only Step 1.3 + credential; **one fact per sentence** as above.
+
+---
+
+## CRITICAL permission boundary
+
+> [!IMPORTANT]
+> Permissions for `**/forge` are strictly limited to:
+
+| Capability                           | Allowed | Forbidden |
+| ---------------------------- | --- | --- |
+| Write business code under `src/`             | Yes   |     |
+| Write unit tests                       | Yes   |     |
+| Update `05A_TASKS.md` checkboxes | Yes   |     |
+| Run tests and lint                   | Yes   |     |
+| Git commit completed tasks            | Yes   |     |
+| Update `AGENTS.md` current state          | Yes   |     |
+| **Change any design document under `.anws/`**      |     | Yes   |
+| **Create features not present in 05A_TASKS.md**  |     | Yes   |
+| **Downgrade or skip acceptance criteria**                |     | Yes   |
+| **Introduce third-party dependencies not approved in ADR**         |     | Yes   |
+| **Change public interfaces of existing code (unless the task explicitly requires it)**    |     | Yes   |
+| **"While we’re at it" optimize/refactor code outside task scope**      |     | Yes   |
+
+---
+
+## CRITICAL anti–free-form guardrails
+
+> [!IMPORTANT]
+> **You only implement what the task description and acceptance criteria explicitly require.**
+
+- "I think adding a cache would be better" → **forbidden**
+- "I optimized this function while I was there" → **forbidden**
+- "The doc didn’t mention it but I added error handling" → **forbidden** (unless acceptance criteria require it)
+- "This design isn’t reasonable so I adjusted it myself" → **forbidden**
+- Implement strictly per task description + acceptance criteria
+- On any issue → report to user → user fixes via the appropriate workflow → continue after fix
+
+---
+
+## CRITICAL conflict-handling protocol
+
+> [!IMPORTANT]
+> **In the following cases you must stop coding immediately and report to the user:**
+
+| Conflict type                   | Action                             |
+| ---------------------- | -------------------------------- |
+| Docs contradict each other               | Stop → list contradictions → user fixes via `/change`   |
+| Task description vague/incomplete             | Stop → list questions → user confirms or supplements via `/change` |
+| Prerequisite task output does not match expectation         | Stop → report delta → user decides                 |
+| Design found infeasible               | Stop → record reason → suggest user run `/challenge`  |
+| New dependency needed but not approved in ADR         | Stop → explain rationale → user decides whether to create new ADR        |
+| Required system design doc missing           | Stop → guide user to run `/design-system`     |
+| **Undefined but required new/changed public contract** | Stop → produce minimal backflow note → go to `/change`       |
+
+**Core principle: better stop and ask than guess.**
+
+---
+
+## ALPHA paired skills (same bundle as this line)
+
+> [!IMPORTANT]
+> §3.6 / §3.7 recognize only **`.agents/skills/code-reviewer/SKILL.md`** and **`.agents/skills/e2e-testing-guide/SKILL.md`** (peer tree to this doc). **Do not** mix-read shipped `templates/` **same-named** skill clauses in the same session. Orchestration skills (e.g. **`nexus-mapper`**) **prefer** this bundle **`.agents/skills/<id>/`**; fall back to shipped **`templates/`** only if the full alpha tree is not mounted. Authoritative text for §3.6/§3.7 remains only **code-reviewer** / **e2e-testing-guide**.
+
+---
+
+## Subagent orchestration
+
+**Parent agent**: sole writer to disk for `TARGET_DIR` / wave number / Step 1.3 signature / `AGENTS.md` Wave and §3.8 index; chains §3.1–§3.5; collects subagent output; runs §3.6→§3.7→§3.8; Step 4.0 **actually lists** directory `wave-reviews/`.  
+**Subagents**: bounded execution of **code-reviewer** full slice or **e2e-testing-guide** doc slice; parent writes body text to disk. **When AGENT is available §3.6 AGENT-first** matches the body text.
+
+**Handoff checklist (sub → parent)**: (1) Declare skill and skip reason (2) structure/severity/anchors match SKILL (3) no out-of-scope task conflicts (conflicts listed separately for ruling) (4) do not write `AGENTS.md`/§3.8/parent-locked `wave-{N}-*.md` (5) read this bundle SKILL and same-session pairing statement consistently.
+
+---
+
+## Step 0: Recovery & Locate
+
+### What to do
+
+Locate `TARGET_DIR`; validate required/recommended files; apply `07` challenge gate; wave resume point; normal/AUTO; Git branch strategy (including `/change` checkpoint commit option). **Procedure** (find Source of Truth; decide fresh start vs resume):
+
+1. **Scan versions**:
+   Scan `.anws/` for the latest version number `v{N}`.
+2. **Determine TARGET_DIR**:
+   **TARGET_DIR** = `.anws/v{N}` (folder with largest numeric suffix).
+3. **Check required files**:
+   - `{TARGET_DIR}/01_PRD.md` exists
+   - `{TARGET_DIR}/02_ARCHITECTURE_OVERVIEW.md` exists
+   - `{TARGET_DIR}/05A_TASKS.md` exists
+   - `{TARGET_DIR}/05B_VERIFICATION_PLAN.md` exists
+4. **Check recommended files** (warn if missing):
+   - `{TARGET_DIR}/04_SYSTEM_DESIGN/` exists and is non-empty
+   - If missing: " Recommend running `/design-system` first. Missing detailed design may reduce implementation quality."
+5. **If required files missing**: Error and instruct to run `/genesis` + `/blueprint`.
+6. **`07_CHALLENGE_REPORT.md` (if present)**: Read conclusions first; any open Critical → stop—must not proceed to later coding steps of this workflow; open High → only with explicit user override (AUTO cannot substitute); otherwise continue. Gate semantics match **`/challenge`**; details live in that workflow—**boolean gate only here**.
+7. **Resume vs. fresh**:
+   - Read `Wave` block in `AGENTS.md`
+    - If wave info exists:
+      - Compare wave task list to checkboxes in `05A_TASKS.md`
+      - If unfinished tasks remain → **resume** → jump to Step 3 for unfinished work
+      - If all done → **new wave** → continue Step 1
+    - If none → **fresh start** → continue Step 1
+8. **Mode decision**:
+   - If user invokes **`/forge auto`** (or equivalent AUTO alias) or explicitly requests auto continuous advance → **AUTO mode**
+   - Else → default **normal mode**
+9. **Git context check**:
+   - Read current branch
+    - Repo recognizes two branch families: `main` and `feature/`*
+    - `main` only holds validated, stabilizable state
+    - Normal development defaults to `feature/*`; avoid editing `main` directly unless single-file tweak
+    - If on `main` and this is not a single-file tweak → create and switch to `feature/{topic-slug}`
+    - If already on `feature/*` and same delivery theme → keep working on current branch; do not open new branches for supplementary tasks/contracts/tests
+    - If on `feature/*` with unchanged theme, even after `/change` backflow, keep the same branch
+    - Only `/genesis` or version-premise change freezes old `feature/*`; new version should branch new `feature/*` from latest `main`
+    - Before `/change` if a protection point is needed, optional checkpoint commit on current `feature/*`: `checkpoint: before {topic}`
+
+> [!IMPORTANT]
+> **Git decision mantra**:  
+> Same theme → don’t swap branch; `/change` → don’t swap branch; only `/genesis` swaps branch; develop on `feature/*`, stabilize on `main`, tags only on `main`.
+
+> [!IMPORTANT]
+> **AUTO and presence**: Assume the user may be away. **Only** stop to ask at Step 0 hard blocks (including `07` Critical, unsatisfied §3.6 `code-reviewer`, manual verification finales, Step 4.4 stop list); do not poll “continue next wave” between waves. After Wave proposal sign **`AUTO`** and enter Step 2. Live wave tuning → normal mode.
+>
+> **AUTO and §3.6**: Same clause as **§3.6 gate header**; waiver rules not repeated here.
+
+### Why
+
+**Motto**: No version → no object.  
+**Decision bar**: Pass if locate, active `v{N}`, challenge Critical routing, and branch rules align.
+
+### How to verify
+
+- Can state `TARGET_DIR`, challenge conclusion, mode, and branch decision.  
+- If pieces missing → stop and point to `/genesis`+`/blueprint`; do not start coding.
+
+---
+
+## Step 1: Wave Planning
+
+### What to do
+
+Scan `05A` for incomplete items whose dependencies are ready; group 2–5 per wave; show Wave template; after signature write `AGENTS.md` Wave; record code-reviewer waiver (§1.3 only). **Goal**: Pick a runnable batch from the task list as one “wave”.
+
+> [!IMPORTANT]
+> **Mode boundary (CRITICAL)**
+
+- **Normal mode (default)**: Same as established protocol—for **every wave** at Step 1 **show Wave proposal → user confirms and approves this wave’s task mix (signature) →** write `AGENTS.md` `Wave` block, then enter **Step 2**; after Step 4 settlement if tasks remain incomplete, **next wave** returns to Step 1 **again** to show and **wait for user approval**—must not start next wave without approval. Step 4.4 “don’t ask to continue” **applies only to AUTO**, **does not** weaken normal per-wave approval.
+- **AUTO mode** (`/forge auto` or explicit request for continuous advance): Checkpoint logic remains but signer recorded as `AUTO`; **must not** chit-chat to confirm “satisfied with wave” or “continue next wave” (see **Step 0 “AUTO and presence”**, **Step 4.4**).
+
+#### 1.1 Scan runnable tasks
+
+Read `{TARGET_DIR}/05A_TASKS.md`; find tasks that satisfy:
+
+- `- [ ]` incomplete
+- Dependent tasks (`**Dependencies**` field) all `- [x]` complete
+
+#### 1.2 Grouping & proposal
+
+Organize one wave per:
+
+| Strategy          | Notes                         |
+| ----------- | -------------------------- |
+| **Same system first**   | Tasks in same System → same wave (shared context) |
+| **Doc dependency convergence**  | Tasks citing same docs → same wave (less loading)       |
+| **2–5 per wave** | Too many → context overflow; too few → inefficient            |
+
+#### 1.3 Wave confirmation
+
+Show the user:
+
+```markdown
+## Wave {N} proposal
+
+| Task ID  | Title | Dependency docs                        | Est.  |
+| -------- | ---- | ------------------------------- | :---: |
+| T{X.Y.Z} | ...  | `04_SYSTEM_DESIGN/core.md` §... |  Xh   |
+| ...      | ...  | ...                             |  ...  |
+
+**Wave total estimate**: ~Xh
+**Docs to load**: [list]
+**Wave-end code-reviewer**: default run (write `wave-reviews/wave-{N}-review.md`) / if waiver needed state “skip code-reviewer” up front
+**Wave-end E2E**: auto per §3.7 triggers
+
+Confirm this wave? Or adjust task mix?
+```
+
+> [!IMPORTANT]
+> **code-reviewer decision before signature (CRITICAL)**: If user **does not** state “skip code-reviewer” when confirming the wave, §3.6 **runs by default**, same for AUTO and normal. If user waives here, log `CODE_REVIEW_DISABLED_BY_USER` in `AGENTS.md` `Wave` block and §3.8 index table, and at wave end create waiver credential `wave-reviews/wave-{N}-WAIVED.md`. **AI must not add waivers after wave work starts.**
+
+**Signature checkpoint**: After obtaining signature, write confirmed wave into `AGENTS.md` `Wave` block:
+
+```markdown
+### Wave {N} — {short wave objective}
+T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
+```
+
+Signature rules (aligned with **mode boundary**):
+
+- **Normal mode** → User **explicitly approves** this wave (may adjust mix, sign after finalized) → write `AGENTS.md` `Wave` → **Step 2**. **Forbidden** to write Wave or enter Step 2/3 before user approval.
+- **AUTO mode** → After showing Wave proposal **immediately** record this wave as `AUTO`-signed and enter **Step 2** (**must not** interrupt again for “confirm mix OK”).
+
+### Why
+
+**Motto**: Wave is human braking and AUTO guardrail.  
+**Decision bar**: Mix, signature, `CODE_REVIEW_DISABLED_BY_USER` are all auditable. Priority and task boundaries must be auditable; normal mode has humans **gate each wave**, AUTO replaces verbal “presence” confirmation with hard stop conditions.
+
+### How to verify
+
+- Normal mode: no Step 2 without signature; AUTO signs `AUTO` right after showing proposal.  
+- Waiver appears only at §1.3 and feeds §3.8.
+
+---
+
+## Step 2: Context Loading
+
+### What to do
+
+Load only docs needed for this wave—no extras.
+
+> [!IMPORTANT]
+> **Only load docs required for the current wave. Do not load “just in case.”**
+
+#### Load tiers
+
+| Tier           | Content                                                                | Purpose          |
+| ------------ | ----------------------------------------------------------------- | ----------- |
+| **L0 global**    | `02_ARCHITECTURE_OVERVIEW.md` + `05B_VERIFICATION_PLAN.md` (toc/index) | Task locate + verification locate |
+| **L1 wave**    | This wave’s systems `04_SYSTEM_DESIGN/{system}.md` (L0 nav layer) + related ADRs            | Design norms, interface contracts   |
+| **L1.5 implementation** | `{system}.detail.md` § sections explicitly referenced by task `**Input**` field            | Algorithm pseudocode, config constants  |
+| **L2 task**   | Exact doc § per task `**Input**`                                        | Implementation detail        |
+
+> [!IMPORTANT]
+> **L1.5 load rules (CRITICAL)**:
+
+- `{system}.md` (L0 nav) **always load** ← default
+- `{system}.detail.md` (L1 implementation) **load only when task `**Input**` explicitly references it**
+- If task `**Input**` says "`core.md` §battle system" → load only matching § of `core.md`
+- If task `**Input**` says "`core.detail.md` §3.5" → then load matching § of `core.detail.md`
+- **Forbidden** to load entire `.detail.md` “just in case”
+
+**L1.5 loads per task at start of Step 3, not all here.**
+
+### Load procedure
+
+1. **L0**: Read system inventory in `{TARGET_DIR}/02_ARCHITECTURE_OVERVIEW.md`
+2. **L1**: For systems touched this wave read:
+   - `{TARGET_DIR}/04_SYSTEM_DESIGN/{system-id}.md`
+   - Related ADRs in `{TARGET_DIR}/03_ADR/` (guided by task Input fields)
+3. **L2 verify input**: Read sections of `05B_VERIFICATION_PLAN.md` tied to this wave’s tasks (by Task ID or verification reference)
+
+### Why
+
+Context window is finite; unrelated docs are noise.
+
+### How to verify
+
+- Loaded L0→L1→L2 in order and did not swallow whole `.detail.md` unless task `**Input**` explicitly requires it.
+
+---
+
+## Step 3: Task Execution Loop
+
+### What to do
+
+Per task §3.1→§3.5; after last §3.5 sequentially §3.6→§3.7→§3.8. **Goal**: Complete each task in the wave (think → code → verify → commit); **force sequential** §3.6 → §3.7 → §3.8 after last task §3.5.
+
+> [!IMPORTANT]
+> **Structure (CRITICAL)**:
+
+- **Per-task loop**: Each task §3.1 → §3.5.
+- **Wave close**: After last task §3.5 **must** run §3.6 (code-reviewer, mandatory) → §3.7 (E2E as needed) → §3.8 (delivery index, mandatory) in order.
+- **§3.6 / §3.7 / §3.8 are fixed terminal state of Step 3—not optional extras before Step 4.** Same obligation for AUTO and normal; incomplete → no Step 4.
+- Any “batch backfill” or “finish all tasks then handle review” optimization **must not** bypass §3.6 / §3.7 / §3.8.
+
+For each task in this wave run the loop below:
+
+---
+
+#### 3.1 Load task-level context
+
+Read docs/§ specified by task `**Input**`, and concurrently read verification section for that task in `05B_VERIFICATION_PLAN.md` (Task ID / verification reference).
+If task depends on finished prerequisites, skim related code for interfaces.
+
+> [!IMPORTANT]
+> **Before writing code complete dependency reads once per task in this wave.**
+
+- Read at minimum docs/§ from task `**Input**`
+- If task depends on others also read prerequisite interfaces/implementations
+- Do not start coding without this minimal context load per task
+
+> **Subsection rationale**: `/forge` allows batch wave progress and checkbox backfill **only after** each task has minimal context—not from titles alone.
+
+---
+
+> [!IMPORTANT]
+> **sequential-thinking (before coding) rules** (§3.2 **does not repeat this in full**):
+>
+> - **No CoT model** → **must** invoke `sequential-thinking` CLI
+> - **CoT model + simple task** (steps < 5, unambiguous) → use guiding questions as natural CoT
+> - **CoT model + complex task** (multi-option compare, premise fixes) → invoke `sequential-thinking` CLI
+
+---
+
+#### 3.2 Think Before Code
+
+> [!IMPORTANT]
+> **Thinking approach**: See **sequential-thinking (before coding) rules** above. Complete the thinking prompts below (every item).
+
+> **Subsection rationale**: Wrong understanding wastes rework—catching issues early is ~10× cheaper.
+
+**Thinking prompts** (answer each):
+
+1. "What does this task ask? Which files?"
+2. "Which existing code/interfaces? What signatures?"
+3. "Hardest constraint in acceptance criteria?"
+4. "Ambiguity? Unknowns?"
+
+- If ambiguity/unknown → **trigger conflict-handling protocol**, stop and report user
+- If clear → continue 3.3
+
+---
+
+#### 3.3 Implementation
+
+> [!IMPORTANT]
+> **Code strictly to design docs and acceptance criteria—no more, no less.**
+
+- Structure follows directory layout from `02_ARCHITECTURE_OVERVIEW.md`
+- Signatures follow `04_SYSTEM_DESIGN/{system}.md`
+- Implementation follows task narrative and acceptance criteria
+- Lint passes (if configured)
+
+> [!IMPORTANT]
+> **Contract backflow rules (CRITICAL)**:
+
+If during implementation any **externally observable contract** below must be added or changed **not** explicitly defined in current task or design docs:
+
+- API / CLI parameter semantics
+- Config shape / file format / state format
+- Error semantics / return shape
+- Cross-system interfaces / persistence shape
+
+stop coding, produce minimal backflow note, go to `/change`. Do not silently encode these contracts inside `/forge`.
+
+---
+
+#### 3.4 Verify
+
+Execute strictly from this task’s **`05A_TASKS.md`** `**Verification type**` / `**Verification instructions**` and matching sections in **`05B_VERIFICATION_PLAN.md`**. **Commands, table shapes, and evidence columns** are authoritative there—**this workflow does not inject** npm/sample tables.
+
+> [!IMPORTANT]
+> **Gate**: smoke = few **real** critical paths, not script theater; regression = **named re-check scope**; instructions unrunnable → `/change` the task or 05B first. Do not enter §3.5 until acceptance is satisfied.
+
+---
+
+#### 3.5 Task Commit
+
+1. **Git commit**:
+   - Task commits land on **current working branch**
+    - Default working branch is this delivery’s `feature/*`; stay on `main` only when Step 0 explicitly says single-file tweak
+    - Message format: `{type}({scope}): T{X.Y.Z} — task title`
+  - `type` ∈ `feat | fix | refactor | docs | test | chore`
+  - `scope` defaults `system-id`; workflow/skill changes use appropriate name
+  - Ex: `feat(core): T2.1.1 — terrain & resource model`
+  - Ex: `fix(challenge): T4.2.3 — severity semantics alignment`
+2. **Task completion persistence** (write back immediately):
+  > [!IMPORTANT]
+  > **After each verified task immediately update `05A_TASKS.md`.**
+  > Core progress persistence—if AI context dies or session crashes,
+  > next load TASKS.md shows precise progress.
+  > Together with AGENTS.md `Wave` **dual-layer recovery**: coarse (Wave) + fine (Task checkbox).
+  - This wave may batch backfill checkboxes **only after** full verification passes
+  - Match **only by Task ID**—no fuzzy title match
+  - Flip `- [ ]` → `- [x]` for corresponding tasks
+  - Do not touch unfinished, unverified, or out-of-wave tasks
+  - Keep `05A_TASKS.md` consistent with reality
+3. **Next step**:
+   - **More tasks remain in wave** → return to **§3.1** for next task
+   - **All tasks §3.5 complete** → **mandatory §3.6 wave-end Code Review** (cannot skip nor jump Step 4)
+
+### Why
+
+**Motto**: Wave-end three steps are the seal.  
+**Decision bar**: Missing any physical attachment or wrong order → Step 4.0 fails.
+
+### How to verify
+
+- No batch-deferred review/e2e; §3.8 index matches §4.0 listing before Step 4.1.
+
+---
+
+## Step 3 wave closure (§3.6 / §3.7 / §3.8)
+
+> [!NOTE]
+> Fixed order **§3.6 → §3.7 → §3.8**; AUTO and normal same; §3.6 waiver only Step 1.3 (`code-reviewer` SKILL). Missing artifacts or wrong order → Step 4.0 fails.
+
+### 3.6 Wave-end Code Review
+
+#### What to do
+
+Read this bundle **`code-reviewer` SKILL → Explore→Invoke (AGENT first)→** six-section body lands **`wave-{N}-review.md`** or **`WAIVED`**; severity gate.
+
+#### Why
+
+**Motto**: Review without reading skill is ceremony; not on disk is air.  
+**Decision bar**: Anyone opening `wave-reviews/` can find `# Wave …` and Critical evidence.
+
+#### How to verify
+
+- Read SKILL before review; review file first line shape correct; Gate matches canonical before §3.7.
+
+---
+
+> [!IMPORTANT]
+> **§3.6 decision bar (workflow keeps gate facts only; procedures live in SKILL)**  
+> **Trigger**: Last task §3.5 done; unless Step 1.3 logged `CODE_REVIEW_DISABLED_BY_USER` **and** `wave-{N}-WAIVED.md` exists, **`code-reviewer` must complete**.  
+> **Authority**: Explore / Invoke (AGENT-first) / Persist / Gate / waiver format — **only** **`.agents/skills/code-reviewer/SKILL.md`** in this bundle; Lens + six-section body rules are not duplicated here.  
+> **Hard facts**: Must exist `wave-reviews/wave-{N}-review.md` (first line `# Wave {N} Code Review — …`) or lawful `…-WAIVED.md`; else §4.0 block. Open Critical blocks §3.7.
+
+### 3.7 Wave-end E2E
+
+#### What to do
+
+**Trigger**: any `05A` task has **E2E / manual verify**, or `05B` mandates real hardware. **Prereq**: §3.6 on disk or lawful waiver. **`e2e-testing-guide`** → `wave-{N}-e2e.md` (verdict semantics per SKILL **Required output** comments), then browser backfill; no browser → `guide-only`. User must pick **Closeout A** (skip E2E doc+browser; residual UI risk → §3.8 Notes) vs **Closeout B** (skeleton then real browser) unless preset. No trigger → §3.8 row `N/A`.
+
+#### Why
+
+**Motto**: Skeleton before hands-on.  
+**Decision bar**: Report tier and Evidence traceable; without browser wording stays honest.
+
+#### How to verify
+
+- SKILL from this bundle; PASS tier not inflated; N/A declared in §3.8.
+
+### 3.8 Wave-end Delivery Index
+
+#### What to do
+
+Fill all **8 rows** delivery index (§3.8 table); Step 4 / AGENTS cover face.
+
+#### Why
+
+**Motto**: Index is the envelope—not a substitute for attachments.  
+**Decision bar**: Don’t claim Step 4 without 8 complete rows.
+
+#### How to verify
+
+- Eight rows filled; canonical “may enter Step 4” quartet satisfied concurrently.
+
+---
+
+**Nature**: Cover index for `/forge` wave delivery **only**; **does not** replace §3.6 code-reviewer report body.
+
+```markdown
+## Wave {N} delivery index
+
+| Item | Value |
+| -- | -- |
+| Wave | {N} |
+| Task IDs | T…, T… |
+| Branch @ HEAD | `feature/…` @ `<short SHA>` |
+| code-reviewer file | `wave-reviews/wave-{N}-review.md` / waived: `wave-reviews/wave-{N}-WAIVED.md` |
+| Highest severity | none / Low / Medium / High / Critical (waiver writes `N/A — USER_OPT_OUT`) |
+| Open follow-ups | none / list Medium+ unresolved |
+| §3.7 E2E | done (`wave-reviews/wave-{N}-e2e.md`) / skipped / N/A |
+| Wave may proceed to Step 4 | yes / no |
+```
+
+(Same four conditions as **Step 4.0**—not duplicated here.)
+
+---
+
+## Step 4: Wave Settlement
+
+### What to do
+
+Close wave, refresh state, prep next moves.
+
+#### 4.0 Wave closure gate (hard / physical-file check)
+
+Proceed **4.1+** iff (**any miss = hard block, including AUTO**): ① **list** `wave-reviews/` and confirm `wave-{N}-review.md` or `wave-{N}-WAIVED.md` exists (verbal/self-filled tables void); ② no open **Critical** in review, **High** accepted or routed; ③ §3.7 done or index `N/A`/skipped; ④ §3.8 **eight rows** + `Wave may proceed to Step 4 = yes`; ⑤ wave §3.5 fully closed (commits + `05A`). Else return to the gap step.
+
+#### 4.1 Update state
+
+**Update `AGENTS.md`**:
+
+1. Update `Wave` block to initial state for next wave (if known), or mark current wave done:
+
+```markdown
+### Wave {N}  — {short wave objective}
+T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
+```
+
+2. Update `Last updated` date
+
+#### 4.2 Wave recap
+
+Report to user with **Wave completion template** (may align `AGENTS.md`/session archive); **must embed** §3.8 delivery index table (whole table pasted, **don’t expand** full `code-reviewer` body):
+
+```markdown
+## Wave {N} completed
+
+**Done**: T{X.Y.Z}, T{X.Y.Z}, ...
+**Verification status**: all passed / partial
+**Code review (findings & fixes)**: Highest severity: none / Low / Medium / High / Critical; fixed this wave: …; open follow-ups: none / … (**review file**: `wave-reviews/wave-{N}-review.md`; waived → `wave-reviews/wave-{N}-WAIVED.md`)
+**Issues found** (if any): …
+**Blockers** (if any): …
+
+(paste §3.8 “Wave {N} delivery index” table)
+```
+
+#### 4.3 Git commit status update
+
+- Wave settlement commit like task commits on current working branch
+- If next wave still same delivery theme default keep same `feature/*`
+- After `/change` backflow resume on same `feature/*`
+
+```markdown
+chore(wave): settle wave {N} progress
+```
+
+#### 4.4 Next-step decision
+
+**Signature checkpoint**:
+
+- Work remains → **normal mode**: show next Wave proposal and wait user signature → **Step 1**. **AUTO mode**: **do not ask** “continue next wave”—return **Step 1** and sign next wave `**AUTO**` after showing proposal.
+- All Sprint tasks done → **Step 5**
+- Blocked → steer user to fix via appropriate workflow
+
+> [!IMPORTANT]
+> **AUTO stop conditions** (**only these** plus declared equivalent hard stops; **do not broaden** into “polling for opinions”):
+>
+> - Manual verification awaiting final confirmation
+> - `/change` assessment requires escalate `/genesis`
+> - Another workflow demands new version-grade decision from user
+> - **§3.6 wave-end `code-reviewer`** yields **Critical** unresolved (forced stop); or **High** with no narrowing to executable repair path via skill (must `/change` / `/genesis` or explicit risk—**absent acceptance → stop**)
+> - **§3.6 missing on disk**: neither review nor waiver file exists (workflow breach—stop and remediate—no pretending)
+>
+> On any—the AUTO lane halts awaiting user approval.
+>
+> **AUTO ≠ skip review**: AUTO only skips verbal “approve next wave,” **does not** waive §3.6 / §3.7 / §3.8 duties.
+
+### Why
+
+**Motto**: Settlement is not a status email—it pins wave evidence into team memory.  
+**Decision bar**: Physical directory listing matches index rows before the next jump.
+
+### How to verify
+
+- Step 4.0 five conditions satisfied with real `wave-reviews/` listing; `AGENTS.md` recap aligns with §3.8.
+
+---
+
+## Step 5: Milestone Settlement
+
+### What to do
+
+When a Sprint or Phase completes all tasks, run integration validation and milestone anchoring (**only when user confirms it is needed**).
+
+1. **Integration validation**: Run integration tests if any—ensure cross-system behavior ok
+2. **Update AGENTS.md**: Clear “current wave” info—refresh completed Sprint/Phase
+3. **Git milestone anchor**:
+   - Milestone settlement commit acceptable on `feature/*` tagging branch-ready state
+   - Version tags and formal releases **may only land on `main`**—never pre-tag solely on `feature/*`
+4. **Merge mainline**:
+   - Merge to `main` only when current `feature/*` reaches acceptance milestone, validation passed, **and** user explicitly ok to merge
+   - Merge strategy fixed to **merge commit**
+   - Do not use squash merge or rebase-merge as primary mainline integrate
+   - `main` ends up only stabilized verified state
+5. **Report user**: Outline completed Sprint/Phase
+
+### Why
+
+**Motto**: Milestones mark where “stable” may be claimed—not participation trophies.  
+**Decision bar**: Merge and tagging rules are not quietly bypassed.
+
+### How to verify
+
+- User confirmed this Step was needed; integration validation and `AGENTS.md` updates match Git rules.
+
+---
+
+<completion_criteria>
+
+- `TARGET_DIR` and Wave semantics challenge gate normal/AUTO boundary Git mantra match canonical forge **and are implementably equivalent**.  
+- §3.4 per `05A`/`05B` (no command templates in workflow) §3.5 persistence §3.6 AGENT-first + disk + waiver Step 1.3 only §3.7 guide→browser §3.8 eight rows Step 4.0 **list dir** **remain complete**.  
+- **/craft alignment**: Read **`.agents/skills/craft-authoring/SKILL.md`** and **`.agents/workflows/craft.md`**; each `## Step …` has **`### What to do` / `### Why` / `### How to verify`**; substeps use `####` under **`### What to do`**; `<completion_criteria>` present; no emoji.  
+- ALPHA: `<phase_context>`, **writing constraints + concision**, domain CRITICAL (methodology / spec), paired skills, subagent handoff.  
+- This bundle’s **`.agents/workflows/forge.md`** hosts `/forge`, pairs with `.agents/skills/code-reviewer` and `.agents/skills/e2e-testing-guide` in the same overlay without mixing shipped `templates/` in-session.
+
+</completion_criteria>