forge-orkes 0.55.0 → 0.58.2

package/template/.claude/settings.json

@@ -1,6 +1,6 @@
 {
   "forge": {
-    "version": "0.1.0",
+    "version": "0.58.2",
     "default_tier": "standard",
     "beads_integration": false,
     "context_gates": {

package/template/.claude/skills/forge/SKILL.md

@@ -71,7 +71,7 @@ Cross-machine note: the flag file is machine-local, so a worktree (or the primar
 
 ### 1.0 State Rollup (index.yml is derived)
 
-`index.yml` is a **derived registry** — regenerate it from the milestone files before reading, and after any milestone CRUD (promote/defer/resume/delete). **Never hand-edit `index.yml`.** Since 0.53.0 it is a **git-ignored render-on-read cache** (never committed): rendering it here is a local-cache write, so it never conflicts and never needs the orchestrator-only guard for *safety* — any session may render its own copy. The rollup below is unchanged; only the storage is (see FORGE.md → State Ownership, Derived class).
+`index.yml` is a **derived registry** — regenerate it from the milestone files (plus each row's git-computed `release_state`, step 4) before reading, and after any milestone CRUD (promote/defer/resume/delete). **Never hand-edit `index.yml`.** Since 0.53.0 it is a **git-ignored render-on-read cache** (never committed): rendering it here is a local-cache write, so it never conflicts and never needs the orchestrator-only guard for *safety* — any session may render its own copy. The rollup below is unchanged; only the storage is (see FORGE.md → State Ownership, Derived class).
 
 Rollup procedure (deterministic + idempotent):
 1. Glob `.forge/state/milestone-*.yml`.
@@ -81,7 +81,9 @@ Rollup procedure (deterministic + idempotent):
    - **complete** — `current.status == complete`
    - **not_started** — `current.status == not_started`
    - **active** — otherwise
-4. Rewrite `index.yml` `milestones:` (sorted by id) as `{id, name, status, last_updated}` (date from step 2's fallback). No other keys.
+4. Render each row's `release_state`, then rewrite `index.yml` `milestones:` (sorted by id) as `{id, name, status, last_updated, release_state}` (date from step 2's fallback). No other keys.
+   - **Fold is the source.** Run `.claude/hooks/forge-release-fold.sh m-{id}` per row and write its stdout `release_state=` value verbatim (`unmerged|merged|validated`) — agent prose never re-derives `release_state`; the fold binary is the only source.
+   - **Degrade, don't block.** Hook missing or exit 2 → write `release_state: unknown`, emit ONE advisory line — *"release fold unavailable for m-{id} — release_state: unknown"* — and continue. A broken fold must never break boot.
 
 Output is a pure function of the milestone files, so two sessions regenerating it produce identical bytes — it never needs a hand-merge. **Only the main/orchestrator session runs rollup; worktree agents never write `index.yml`** (they edit only their own `milestone-{id}.yml`).
 

package/template/.claude/skills/reviewing/SKILL.md

@@ -408,7 +408,7 @@ If the milestone's phases produced `contract.md` files (planning Step 6.1 Tier 1
 ## Phase Handoff
 
 1. Confirm report + backlog
-2. **Human Verification Gate (hard block)** — Read `current.human_verified` from `milestone-{id}.yml`. If **absent/null** → **do not complete the milestone.** Code-clean + review-clean is not enough to close (FORGE.md → Human Verification Gate). The milestone needs an explicit human sign-off, normally captured by `verifying`. Either route the user back to verify (then re-review) or capture the sign-off / recorded override here and write `current.human_verified` before proceeding. A recorded override (`method: override`) satisfies this check but **must** be surfaced in the health report. Never silently complete past an unset gate. *(Attended lane: the recorded `current.human_verified` — or a recorded override — **is** the gate, exactly as today. The M0 `verify-signoff` **forward-gate is not wired here** — that is autonomous-lane. Where an M0 `signoff/<wu-id>` tag does exist, treat `human_verified` as a **rendered echo** of that signature and surface the tag in the report; where none exists it is the stored attestation. A pre-existing tagless `complete` milestone reads complete — grandfathered, never re-gated.)*
+2. **Human Verification Gate (hard block)** — binding-dispatched (B5): read `forge.validation_event` from `.forge/project.yml` first (absent ⇒ `in_session_signoff`). Under **`promotion_approval`** the human gate lives at the deploy boundary, not here: `current.status: complete` is allowed **machine-verified** (no in-session sign-off required), and the health report MUST carry the line *"human gate: at promotion (B5) — unit renders merged until the CI-signed promotion tag validates it"*. The mode is not agent-flippable: `validation_event`/`project.yml` is on the step-2 **protected-paths** hold list, so a diff flipping it blocks auto-merge for operator review (F4/F5; hold machinery is the sibling merge-policy build — handoff-step2-merge-release-policy.md). Under **`in_session_signoff`** (default) the gate runs exactly as follows, unchanged: Read `current.human_verified` from `milestone-{id}.yml`. If **absent/null** → **do not complete the milestone.** Code-clean + review-clean is not enough to close (FORGE.md → Human Verification Gate). The milestone needs an explicit human sign-off, normally captured by `verifying`. Either route the user back to verify (then re-review) or capture the sign-off / recorded override here and write `current.human_verified` before proceeding. A recorded override (`method: override`) satisfies this check but **must** be surfaced in the health report. Never silently complete past an unset gate. *(Attended lane: the recorded `current.human_verified` — or a recorded override — **is** the gate, exactly as today. The M0 `verify-signoff` **forward-gate is not wired here** — that is autonomous-lane. Where an M0 `signoff/<wu-id>` tag does exist, treat `human_verified` as a **rendered echo** of that signature and surface the tag in the report; where none exists it is the stored attestation. A pre-existing tagless `complete` milestone reads complete — grandfathered, never re-gated.)*
 3. **Run promoted-milestone completion hook** (above) if `milestone.origin` set
 4. **Run Contract Landing** (above) for any cross-layer phases — fold ratified contracts into their ADRs
 5. Set `current.status: complete` and `current.completed_at: "<ISO 8601 timestamp>"` in `milestone-{id}.yml`, then regenerate `index.yml` via the `forge` **Rollup**

package/template/.claude/skills/upgrading/SKILL.md

@@ -40,6 +40,7 @@ Read the source version (`{source}/packages/create-forge/package.json` `version`
 | **Import-managed** | `CLAUDE.md` | Never overwrite content; migrate legacy forge sections + guarantee the `@.forge/FORGE.md` import line (Step 5) |
 | **Merge-owned** | `.claude/settings.json` | Smart-merge `forge.*` keys only (Step 5) |
 | **Template-only** | `.forge/templates/**`, `.forge/migrations/**`, `.forge/gitignore` → `.forge/.gitignore` | Overwrite |
+| **Additive-sync** | `.claude/hooks/**` (incl. `tests/`), `.claude/rules/**`, `.forge/checks/**` (incl. `tests/`) | Add + overwrite template-shipped files; never delete local extras (Step 4a) |
 
 **Never touch** user-generated files: `.forge/project.yml`, `.forge/state/`, `.forge/constitution.md`, `.forge/context.md`, `.forge/requirements/`, `.forge/roadmap.yml`, `.forge/design-system.md`, `.forge/refactor-backlog.yml`.
 
@@ -87,6 +88,22 @@ Same process as Step 3 for `.forge/templates/**`, `.forge/migrations/**`, and `.
 
 **Sync the framework prose file `.forge/FORGE.md`** (framework-owned single file — it holds the `# Forge` prose, formerly embedded in CLAUDE.md). Copy/refresh `{source}/packages/create-forge/template/.forge/FORGE.md` → `.forge/FORGE.md` (overwrite when different; report added/updated/unchanged). **Run this BEFORE the Step 5 CLAUDE.md pass** so a migrated import line never points at a missing file.
 
+## Step 4a: Sync Hooks + Rules + Checks (additive — mirrors the npm bin)
+
+The template ships the safety-guardrail hook scripts (ADR-017), the always-on rules layer (ADR-018), and — since 0.58.2 — the merge-floor CI check scripts: `.claude/hooks/**` — **including the `tests/` subtree** — `.claude/rules/**`, and `.forge/checks/**` (incl. `tests/`). The npm bin has additively synced hooks + rules since those ADRs landed (`upgradeAdditiveDir`); this skill previously synced neither, so a project upgraded only via `/upgrading` never received `.claude/hooks/` at all — while its settings.json wires guards like `protect-files.sh` and skills invoke `forge-release-fold.sh`, none of which existed on disk.
+
+For every file under `{source}/packages/create-forge/template/.claude/hooks/`, `.../.claude/rules/`, and `.../.forge/checks/` (recursive):
+
+1. Absent locally → copy, report **added**.
+2. Present but differs → overwrite, report **updated**.
+3. Identical → report **unchanged**.
+4. **Additive only** — never delete a local file the template lacks. Project-local and experimental hooks (e.g. M10 `forge-claim-check*.sh`) and pack-installed path-scoped rules are preserved; no "removed from template" verdicts in this pass.
+5. `chmod +x` every synced `*.sh` (a copy can strip the execute bit; guard hooks and CI checks must be runnable).
+
+The two subtrees differ in tracked-ness, and the sync respects it: `.forge/checks/**` is **committed** project content (CI must clone it; the hold check's protected set guards `.forge/checks/**`), while `.claude/hooks/**` is a **machine-local carve-out** in many projects (gitignored as per-developer files — host-verified on ptnrkit). Sync both to disk identically; stage only what the project's own `.gitignore` admits — never `git add -f` a hook file past a project's ignore rules. The old `.claude/hooks/` copies of `forge-hold-check.sh` / `forge-check-lint.sh` (+ their two `tests/*.test.sh` suites) are relocation leftovers on upgraded projects — the migration guide `0.58.2-merge-floor-checks-relocation.md` covers removing them and re-pointing CI.
+
+The settings.json *wiring* for these hooks is not written here — Step 5's smart-merge owns it.
+
 ## Step 4b: Codex Adapter (presence-gated — detect + offer, never auto)
 
 Forge ships a **Codex/AGENTS adapter** (`.agents/skills/` + `.codex/` wiring) for projects run on Codex. It is a *derived translation* of the canonical `.claude/` skills (ADR-014) and drifts whenever core moves — but `upgrading` syncs only `.claude/`, so the Codex adapter would silently rot. This step makes that staleness visible and one-keystroke-fixable, **without** ever generating it here (only an agent-as-Codex can author it natively).
@@ -120,6 +137,7 @@ No manual-merge prompt for forge sections; migration is silent except the report
 2. Compare `forge.*` keys only
 3. If different → update `forge.*` keys in local, preserve user's `hooks` and custom keys
 4. Set `forge.version` to match the source package version
+5. **Additively merge the template's framework hook wiring** (ADR-017, mirrors the bin's `upgradeSettingsHooks`): for each hook group in the template's `hooks`, add it to the local `hooks` unless a deep-equal group already exists. Never remove or rewrite a user's own hook entries. Without this, the scripts synced in Step 4a exist on disk but never fire on projects whose settings.json predates the wiring.
 
 ## Step 6: Report
 

package/template/.claude/skills/verifying/SKILL.md

@@ -248,6 +248,13 @@ Items that can't be verified automatically (visual appearance, real-time behavio
 
 Code-level PASS is necessary but **not sufficient** to close a milestone. Before handing off, capture an explicit human sign-off — this is the hard gate that `reviewing`-complete and `orchestrating`-teardown both check (see FORGE.md → Human Verification Gate). It is a precondition, not a peer option: never present milestone close / teardown as an alternative to running this.
 
+**Binding dispatch (B5).** Read `forge.validation_event` from `.forge/project.yml` at gate time (absent ⇒ `in_session_signoff`):
+
+- **`in_session_signoff` (default)** → run the capture below exactly as written — behavior unchanged from before the binding existed.
+- **`promotion_approval`** → the human gate is **relocated to the deploy boundary**: do NOT require sign-off capture for close. Surface instead: *"human gate relocated to promotion — milestone will render merged until the CI-signed promotion tag exists"* (the derived `release_state` stays `merged` until the host-recorded promotion validates it; `.claude/hooks/forge-release-fold.sh` computes it). Skip the capture steps below and continue the handoff — close is machine-verified under this binding.
+
+An agent cannot flip the mode: `validation_event` / `project.yml` is on the step-2 **protected-paths** hold list — a diff touching it blocks auto-merge for operator review (findings F4/F5; the hold machinery is the sibling merge-policy build, see handoff-step2-merge-release-policy.md).
+
 Run on a PASSED verdict (and after any **HUMAN VERIFICATION NEEDED** items are resolved):
 
 1. Surface what the human should confirm — the Observable Truths, any "Human Verification Items", and any milestone-specific manual check (device session, visual pass, real-device / e2e walk).
@@ -296,7 +303,7 @@ After verification completes (PASSED or GAPS FOUND), run a quick retrospective o
 
 After PASSED verdict:
 
-1. **Human Verification Gate** — capture explicit sign-off and write `current.human_verified` (see "Human Verification Gate" above). If the human answers **not yet** → STOP here; do not advance to reviewing. The milestone stays open until sign-off (or a recorded override) exists.
+1. **Human Verification Gate** — binding-dispatched (see "Human Verification Gate" above). Default (`in_session_signoff`): capture explicit sign-off and write `current.human_verified`; if the human answers **not yet** → STOP here; do not advance to reviewing. The milestone stays open until sign-off (or a recorded override) exists. `promotion_approval`: no capture — surface the relocation line and continue.
 2. **Persist** — Confirm verification report documented, desire-path files written to `.forge/state/desire-paths/`
 3. **Update state** — Set `current.status` to `reviewing` in `.forge/state/milestone-{id}.yml`
 4. **State-sync commit** (State Commit Protocol): `git add .forge/` then `git commit -m "chore(forge): sync state after verifying — m{N} {phase-name}"` (scoped; never `git add .`).
@@ -310,7 +317,7 @@ If GAPS found, route back to planning in gap-closure mode. Context clear applies
 Realizes producer-side continuous integration (FORGE.md → Stream Integration Checkpoints). Runs at Phase Handoff step 5, **only when all hold**:
 
 - the phase's plan frontmatter has `integration_checkpoint: true`;
-- the verdict is PASSED — never publish unverified work. (`current.human_verified` gates milestone **close**, *not* per-checkpoint publish: a non-final checkpoint phase publishes on PASS alone; the milestone's **final** checkpoint coincides with close, where the Human Verification Gate applies — so in practice only the last checkpoint also requires `human_verified`.)
+- the verdict is PASSED — never publish unverified work. (`current.human_verified` gates milestone **close**, *not* per-checkpoint publish: a non-final checkpoint phase publishes on PASS alone; the milestone's **final** checkpoint coincides with close, where the Human Verification Gate applies — so in practice only the last checkpoint also requires `human_verified`. On a `promotion_approval` repo even the final checkpoint publishes on PASS alone — close is machine-verified under that binding; the human gate lives at promotion.)
 - the session is a **worktree** (`git rev-parse --git-dir` ≠ `--git-common-dir`). In a single checkout, skip — there is no main to fast-forward into.
 
 **Strand guard — never push past the operator's local main (forge#13).** `git push origin HEAD:main` is fast-forward-only *relative to `origin/main`* — but `origin/main` is **not** the operator's canonical checkout. The local `main` ref (shared across this machine's worktrees via the common git dir) can carry commits that were never pushed — another stream's merge, a framework bump, the state-sync commits from step 4. If you push the worktree tip onto an `origin/main` that is *behind* local main, origin fast-forwards but **local main is left diverged** (it has commits origin's new tip lacks, and vice versa). The closing report then mis-reads this as "local main is behind — `git pull`", and `git pull --ff-only` *fails* on divergence while a bare `git pull` makes a surprise merge commit — the exact failure the merge discipline exists to prevent. So gate the push on local main being in the publish's direct line:

package/template/.forge/FORGE.md

@@ -232,7 +232,8 @@ State lives in `.forge/`:
 - `design-system.md` — Component mapping table
 - `requirements/m{N}.yml` — Per-milestone structured requirements with `[NEEDS CLARIFICATION]` markers. **FR-IDs, DEF-IDs, and NFR-IDs are globally unique across all milestone files** — `FR-001` may exist in exactly one `m{N}.yml`. Before adding a new ID, **reserve it via the ID Reservation Protocol** — run `forge-reserve fr|nfr|def --milestone <id>` and use the id it prints (the helper dual-writes the machine-local ledger + `.forge/reservations.yml`; you commit `reservations.yml` with the work). The next number is `max(ledger ∪ in-tree ∪ main:reservations.yml) + 1`. The machine-local ledger is what makes the shared ID space safe across **concurrent worktrees**: bare scan-and-increment (or a branch-local `reservations.yml`) sees only committed/merged state, so two worktrees branched from one baseline claim the same number and collide silently until merge (see ADR-021, supersedes ADR-016). On a residual collision (legacy/un-reserved, e.g. during a migration), keep the older milestone's ID and renumber the newer. Concurrent milestones each own their file — no cross-stream contention on file writes, but ID space is shared. Functional requirements may carry M9 e2e gate fields (`e2e`, `observable_outcome`, `observable_outcome_hash`, `validated`) — lazy migration, absent fields default to `e2e:false`/`validated:false`.
 - `roadmap.yml` — Phases, milestones, dependencies
-- `state/index.yml` — DERIVED registry rolled up from milestone files (id, name, status, last_updated). Never hand-edited; never written by worktree agents. **Git-ignored render-on-read cache (0.53.0): regenerated at every boot from the milestone files, never committed** — so a committed projection can never drift stale from its source, and any session can render it locally without touching `main`. Absent on a fresh clone until the first boot renders it (the project sentinel is `project.yml`, not this file).
+- `state/index.yml` — DERIVED registry rolled up from milestone files (id, name, status, last_updated). Never hand-edited; never written by worktree agents. **Git-ignored render-on-read cache (0.53.0): regenerated at every boot from the milestone files, never committed** — so a committed projection can never drift stale from its source, and any session can render it locally without touching `main`. Absent on a fresh clone until the first boot renders it (the project sentinel is `project.yml`, not this file). The boot rollup also renders each unit's **derived `release_state`** into this cache (see below).
+- **Derived `release_state` (0.56.0, [ADR-024](../docs/decisions/ADR-024-merged-validated-fold.md))** — a unit's `release_state ∈ {unmerged, merged, validated}` is **computed at rollup, never stored** (never an enum on `current.status`, never a committed field) and rendered only into the git-ignored cache. `merged` = the unit's landed SHA is an ancestor of the mainline; `validated` requires `merged` plus the repo's configured approval. Computed by the fold-of-record `.claude/hooks/forge-release-fold.sh` (git-only, offline, main-checkout-resolvable — all field reads via `git show main:`). Validation is dispatched on `forge.validation_event` in `project.yml`: `in_session_signoff` (**default**, absent ⇒ this — `human_verified`/M0 signoff, legacy-complete grandfathered) or `promotion_approval` (a CI-signed `promotion/{sha}` tag verified offline via `git tag -v` + allowed-signers, validated by containment). Inert by default — every repo unchanged until it opts in. The gate-relocation consequence lives in the Human Verification Gate section; the full spec lives in ADR-024 + the fold header (not duplicated here — Article XII).
 - `state/milestone-{id}.yml` — Per-milestone cursor (single source of truth): position, progress, decisions, blockers. One owner at a time.
 - `state/desire-paths/` — Append-only framework-usage observations, one file per observation. Occurrence counts derived by globbing (no mutable counter). Each carries `scope: project | framework` (set at capture; absent ⇒ project). **`forge` boot is the single review owner**: at 3+ occurrences it surfaces a concrete fix from the co-located suggestion table, persists declines to `declined/` (no re-nag), and for `scope: framework` signals routes them upstream — a portable block to `upstream/` plus a `gh issue` offer against `forge.upstream_repo`. This closes Principle 7's capture→act loop; `verifying` captures but no longer surfaces. See [ADR-012](../docs/decisions/ADR-012-upstream-desire-path-feedback-channel.md).
 - `context.md` — Active locked decisions + deferred ideas (target <=12KB)
@@ -285,7 +286,7 @@ with the work it describes. Every artifact has a sharing class:
 |---|---|---|
 | **Single-owner mutable** | `state/milestone-{id}.yml`, `phases/milestone-{id}/`, `research/milestone-{id}.md` | Exactly one writer at a time — the worktree (or main session) currently driving that milestone. **Other worktrees never touch it**, not even to read-then-write — they pull from main if they need it. |
 | **Single-owner mutable (per stream)** | `streams/{stream}.yml`, `streams/{stream}/brief.md`, `streams/{stream}/packages/*.yml` | The stream's **current driver** writes them — one writer at a time, like the milestone file. Distinct streams own distinct files (no cross-stream contention). `active.yml` is **derived** from them: a worktree driving a stream may write its own stream file but **never** `active.yml` or a peer stream's file. |
-| **Derived (git-ignored render-on-read cache)** | `state/index.yml`, `streams/active.yml` | Never hand-edited, **never committed** — git-ignored local caches (0.53.0), regenerated by rollup from their sources (`index.yml` ← `milestone-*.yml` via Rollup 1.0; `active.yml` ← per-stream files + active milestones via the Stream Rollup) at every boot. Because the value is computed on read and never stored in git, a committed projection cannot drift stale from its source, and **any** session (not just the orchestrator) may render them locally without a `main` write. Absent on a fresh clone until the first boot; readers must render-then-read and must **not** use their absence as a "not a Forge project" sentinel (that is `project.yml`). |
+| **Derived (git-ignored render-on-read cache)** | `state/index.yml`, `streams/active.yml`, the **`release_state`** column rendered into `index.yml` (ADR-024) | Never hand-edited, **never committed** — git-ignored local caches (0.53.0), regenerated by rollup from their sources (`index.yml` ← `milestone-*.yml` via Rollup 1.0; `active.yml` ← per-stream files + active milestones via the Stream Rollup; `release_state` ← `forge-release-fold.sh` over git truth) at every boot. Because the value is computed on read and never stored in git, a committed projection cannot drift stale from its source, and **any** session (not just the orchestrator) may render them locally without a `main` write. Absent on a fresh clone until the first boot; readers must render-then-read and must **not** use their absence as a "not a Forge project" sentinel (that is `project.yml`). |
 | **Append-only shared** | `releases.yml` (version reservations), `reservations.yml` (ADR/DEF/FR/NFR id **audit trail + cross-machine floor**), `state/desire-paths/*` (one file per observation) | Many writers OK; structure prevents collision. `releases.yml` uses the Version Reservation Protocol (append + commit + push). `reservations.yml` is written by `forge-reserve` (ADR-021) and committed with the caller's work — it is no longer the id *coordination* point (the machine-local ledger is), just the durable committed shadow. Desire-paths use distinct filenames so two writers never touch the same file. |
 | **Machine-local runtime** | `.git/forge/id-reservations` (id-reservation ledger), `.git/forge/integration-pending` (integration flag) | In the git common dir, shared across a repo's worktrees on one machine, **not** git-tracked. `forge-reserve` writes the ledger under a `mkdir` lock; excluded from framework context. Machine-local by design (cross-machine falls back to the `main:reservations.yml` floor). |
 | **Shared mutable** | `context.md`, `refactor-backlog.yml`, `requirements/m{N}.yml` (ID space `FR-`/`DEF-`/`NFR-` is globally shared even though each milestone owns its file) | Write only to your milestone/stream block. Within a block, append-only; strike through instead of rewriting. |
@@ -378,11 +379,15 @@ Plans MAY declare a per-truth `check:` shell command in `must_haves.truths` (exi
 **No milestone reaches `complete` and no orchestration worktree is torn down until a human has explicitly signed off** — recorded as `current.human_verified` in `milestone-{id}.yml`. Code-level verification (tests, lint, type-check, the 3-level goal-backward pass) is necessary but **never sufficient** to close a milestone. A human must confirm the work in whatever form fits the milestone — device session, visual check, e2e walk, smoke test ("of some sorts").
 
 - **Captured** by `verifying` — after the verdict it prompts for explicit sign-off and writes `current.human_verified: {at, method, notes}`. If the human can't verify yet (e.g. a device session is still pending), the field stays unset and downstream close blocks.
-- **Enforced (hard block)** at both close points — `reviewing` refuses to set `current.status: complete`, and `orchestrating` Step 5 refuses teardown, unless `current.human_verified` is present.
+- **Enforced (hard block)** at both close points — `reviewing` refuses to set `current.status: complete`, and `orchestrating` Step 5 refuses teardown of **un-merged** work (see the teardown split below), unless `current.human_verified` is present.
 - **Recorded override** is the only bypass. A human may explicitly close without verifying, but the skill writes `human_verified: {method: override, override: true, reason}` and surfaces it in the report. Silent close is impossible — an agent must **never** present milestone close / orchestration teardown as a peer alternative to "do the verification". The verification is a precondition, not an option.
 
 Lazy migration: milestones with no `human_verified` field (pre-0.27.0) simply hit the prompt on their next close transition; already-`complete` milestones are never re-gated.
 
+**Per-binding relocation (B5, operator-ratified 2026-07-15).** The gate above is the **`in_session_signoff`** binding — the default (`forge.validation_event` absent ⇒ this), preserved exactly. A repo that opts into **`validation_event: promotion_approval`** relocates the human gate to the **deploy boundary**: `complete` becomes the machine/code-verified state (`reviewing` closes without in-session sign-off, its health report noting *"human gate: at promotion (B5)"*), and the derived `release_state: validated` — computed by `forge-release-fold.sh` when a CI-signed promotion tag covers the unit — **is** the human gate (the full release_state ladder lands in State Management with phase 52). The mode is **not agent-flippable**: `validation_event`/`project.yml` sits on the step-2 **protected-paths** hold (F4/F5), so a diff flipping it blocks auto-merge for operator review.
+
+**Teardown splits on merged-ness (operator ruling 2026-07-16 — binding-independent).** Worktree teardown auto-proceeds when the unit renders `merged`/`validated` via `forge-release-fold.sh` — the work is on main; removing the worktree loses nothing. The human gate applies only to **un-merged** teardown. The close gate is unaffected by this split — it keeps the per-binding rule above.
+
 **Grandfather (legacy-complete marker).** A milestone already stored `current.status: complete` with **no** `signoff/<wu-id>` tag (the pre-M0 history — 26 milestones as of 0.53.0) is **grandfathered**: readers honor it as complete and it is **never re-gated** by any later sign-off convention. "Complete with no signoff tag" **is** the legacy-complete marker — no field is stamped onto those files. Only *new* completions going forward can be asked to carry a signature (that forward-gate is autonomous-lane and is **not** wired in the attended lane — see below).
 
 **Where the Contract M0 sign-off convention is adopted, `human_verified` is a derived echo, not the source of truth.** The authoritative predicate becomes `verify-signoff <wu-id>` exiting 0 — an SSH-signed `signoff/<wu-id>` tag an agent cannot forge (see `docs/sign-off-convention.md` and `.claude/hooks/{verify-signoff,wu-done}.sh`). `current.human_verified` may still be written for human-readable display, but treat it as a cache of the signature check, never the gate itself. Core does not yet wire this predicate into `verifying`/`reviewing`'s own hard-block logic automatically — that remains a flagged follow-up (Contract M0 §D2 scoped to a minimal fold stub, not the full skill wiring).

package/template/.forge/checks/forge-check-lint.sh

@@ -0,0 +1,383 @@
+#!/usr/bin/env sh
+# forge-check-lint — the merge-floor check-quality lint (m-31, Brief-R2 step 2 Track A).
+#
+# M23 promoted to the merge floor: a check that cannot fail manufactures fake
+# evidence — worse than no check. This lints the PR diff's CI/check/test
+# definitions with the planning skill's heuristics ported to an executable
+# (a SECOND CONSUMER of the same rules — the planning-time prose stays where it
+# is). P16's teeth. HONEST LIMIT: the lint is line/unit-heuristic over YAML and
+# diffs, not a parser — what it can't catch, your UAT stands behind.
+#
+#   forge-check-lint.sh <base>...<head>
+#
+#   stdout (machine-parseable):
+#     lint=clean
+#     lint=fail                                     + finding=<rule>:<file>[:<line>]
+#     lint=justified justify="<trailer line>"       + finding=<rule>:<file>[:<line>] justified
+#     rule ∈ cannot-fail|silent-fail|existence-only|deleted-assertion|feature-removal|skip-marker
+#   exit: 0 = clean or justified; 1 = fail; 2 = bad invocation. Logs → stderr.
+#
+# Targets (nothing else is scanned):
+#   CI definitions (.github/workflows/*.yml|yaml, .gitlab-ci.yml) — check UNITS
+#     (a `run:` scalar, a `run: |` block, a `script:` list) parsed from the HEAD
+#     side of each changed file, REPORTED only when the unit's lines intersect
+#     the diff's added lines (lint the diff, not the world).
+#   Test files (*_test.*, *.test.*, test_*.*, *.spec.*) — added/removed diff lines.
+#
+# Rules:
+#   (a) cannot-fail   — every command in the unit is `true`, `:`, `exit 0`, or an
+#                       echo/printf-only pipeline. ALWAYS a failure — the
+#                       Lint-Justify trailer NEVER lifts it (M23 rule a verbatim).
+#   (c) existence-only— every command is a bare file-existence test (test -f/-e/-d).
+#   (b) silent-fail   — every command is silent conjuncts (grep -q / diff -q /
+#                       test / [) with no `||` diagnostic branch. Checked after (c).
+#   deleted-assertion — NET loss of assertion-bearing lines in a gating test
+#                       (base-side hold-config `gating_tests:` globs when present,
+#                       else EVERY test file in the diff — raise-only default).
+#                       Net-count, so a moved/edited line that keeps its assertion
+#                       does not fire.
+#   feature-removal   — a deleted-assertion whose test correlates with a same-stem
+#                       source FILE deletion in the same diff. Reclassified from
+#                       test-gaming to "feature removal — confirm intended". A
+#                       CLASSIFIER, not an allowlist: the finding still fires and
+#                       still requires the recorded operator act (Lint-Justify / PR
+#                       approval) — only the label changes, so the operator confirms
+#                       an intended removal instead of being warned of gaming.
+#                       Bright line (raise-only): only a WHOLE matching-stem source
+#                       *file* deletion downgrades the label; a partial source
+#                       shrink is ambiguous and keeps the stricter deleted-assertion.
+#   skip-marker       — an ADDED .only( / .skip( / it.skip / describe.only / xit( /
+#                       xdescribe( / @pytest.mark.skip / t.Skip() line.
+#
+# Justification channel (pure git, host-agnostic): a commit-message trailer
+#   Lint-Justify: <one line>
+# in ANY commit of merge-base..head lifts (b)/(c)/deleted-assertion/feature-removal/
+# skip-marker → exit 0 `lint=justified`. It never lifts (a).
+#
+# Host-agnostic + offline (NFR-032): POSIX sh over git plumbing only.
+set -u
+
+usage() { printf 'usage: forge-check-lint.sh <base>...<head>\n' >&2; }
+
+RANGE="${1:-}"
+[ $# -le 1 ] || { printf 'forge-check-lint: unexpected arguments\n' >&2; usage; exit 2; }
+[ -n "$RANGE" ] || { usage; exit 2; }
+case "$RANGE" in
+  *...*) : ;;
+  *) printf 'forge-check-lint: range must be three-dot BASE...HEAD (got: %s)\n' "$RANGE" >&2; exit 2 ;;
+esac
+BASE_REF="${RANGE%%...*}"
+HEAD_REF="${RANGE#*...}"
+[ -n "$BASE_REF" ] && [ -n "$HEAD_REF" ] || { usage; exit 2; }
+
+git rev-parse --verify --quiet "$BASE_REF^{commit}" >/dev/null 2>&1 \
+  || { printf 'forge-check-lint: cannot resolve base ref: %s\n' "$BASE_REF" >&2; exit 2; }
+git rev-parse --verify --quiet "$HEAD_REF^{commit}" >/dev/null 2>&1 \
+  || { printf 'forge-check-lint: cannot resolve head ref: %s\n' "$HEAD_REF" >&2; exit 2; }
+MB="$(git merge-base "$BASE_REF" "$HEAD_REF" 2>/dev/null)" \
+  || { printf 'forge-check-lint: no merge-base for %s\n' "$RANGE" >&2; exit 2; }
+
+# Justification trailer (first one wins), from commit messages in the range.
+# Strip any embedded double-quote: it is echoed inside justify="..." on stdout,
+# and an unescaped " from an attacker-authored commit would produce malformed,
+# machine-parseable output a downstream CI parser could mis-read.
+JUSTIFY="$(git log --format=%B "$MB..$HEAD_REF" 2>/dev/null \
+  | sed -n 's/^Lint-Justify:[[:space:]]*//p' | head -1 | tr '"' "'")"
+
+# Base-side gating_tests globs (same additive config the hold check reads).
+GATING="$(git show "$MB:.forge/hold-config.yml" 2>/dev/null \
+  | awk '
+      /^[A-Za-z_]+:/ { insec = (index($0, "gating_tests:") == 1) ? 1 : 0; next }
+      insec && /^[[:space:]]*-[[:space:]]*/ {
+        v = $0
+        sub(/^[[:space:]]*-[[:space:]]*/, "", v)
+        gsub(/["\047]/, "", v)
+        sub(/[[:space:]]*(#.*)?$/, "", v)
+        if (v != "") print v
+      }')"
+
+in_gating() { # path → 0 when gating set is empty (default: everything gates) or a glob matches
+  [ -n "$GATING" ] || return 0
+  ig_path="$1"
+  while IFS= read -r ig_g; do
+    [ -n "$ig_g" ] || continue
+    case "$ig_path" in
+      $ig_g) return 0 ;;
+    esac
+  done <<EOF
+$GATING
+EOF
+  return 1
+}
+
+added_lines() { # file → new-side line numbers added by the diff, one per line
+  git diff --unified=0 "$MB" "$HEAD_REF" -- "$1" 2>/dev/null | awk '
+    /^@@/ {
+      plus = $3
+      sub(/^\+/, "", plus)
+      n = split(plus, a, ",")
+      start = a[1] + 0
+      count = (n > 1) ? a[2] + 0 : 1
+      for (i = 0; i < count; i++) print start + i
+    }'
+}
+
+# Test-file basename → feature stem (drops the test marker + extension). Used to
+# correlate a shrinking test with its source going away.
+stem_of_test() { # basename
+  awk -v b="$1" 'BEGIN {
+    if (b ~ /\.(test|spec)\.[^.]+$/)  sub(/\.(test|spec)\.[^.]+$/, "", b)
+    else if (b ~ /_test\.[^.]+$/)     sub(/_test\.[^.]+$/, "", b)
+    else if (b ~ /^test_/)          { sub(/^test_/, "", b); sub(/\.[^.]+$/, "", b) }
+    else                              sub(/\.[^.]+$/, "", b)
+    print b
+  }'
+}
+
+# Correlated source deletion? True when the diff DELETES a whole non-test, non-CI
+# file whose basename stem matches the test's — the signal that a shrinking test
+# reflects a feature being removed, not a gating test being gamed. Whole-file
+# deletion is the deliberate bright line (raise-only): a partial source shrink is
+# ambiguous and keeps the stricter deleted-assertion label. Classifier, not
+# allowlist — the caller still emits a finding either way.
+has_correlated_source_deletion() { # stem (non-empty)
+  git diff --diff-filter=D --name-only "$MB" "$HEAD_REF" 2>/dev/null | awk -v stem="$1" '
+    function base(p,  b) { b = p; sub(/^.*\//, "", b); return b }
+    function is_test(b) { return (b ~ /_test\./ || b ~ /\.test\./ || b ~ /\.spec\./ || b ~ /^test_/) }
+    function is_ci(p) { return (p ~ /^\.github\/workflows\/.*\.(yml|yaml)$/ || p == ".gitlab-ci.yml") }
+    function srcstem(b,  s) { s = b; sub(/\.[^.]+$/, "", s); return s }
+    { b = base($0); if (is_test(b) || is_ci($0)) next; if (srcstem(b) == stem) { found = 1; exit } }
+    END { exit(found ? 0 : 1) }
+  '
+}
+
+# Parse the HEAD side of a CI definition file into check units and classify each.
+# Emits: <class> <startline> <endline> per unit (class: cannot-fail|existence-only|silent-fail|clean).
+classify_units() { # file
+  git show "$HEAD_REF:$1" 2>/dev/null | awk '
+    function indent_of(s,  t) { t = s; sub(/[^ ].*$/, "", t); return length(t) }
+    function trim(s) { sub(/^[[:space:]]+/, "", s); sub(/[[:space:]]*$/, "", s); return s }
+    # Drop a trailing shell comment before classification so a cosmetic "# note"
+    # cannot slip a cannot-fail command past rule (a) (raise-only: the evasion
+    # must not make a fact disappear). Only strips a # preceded by whitespace or
+    # at line start — never a # mid-token (e.g. a URL fragment). Safe for echo/
+    # printf units too: the classifier keys on the command PREFIX, which survives.
+    function strip_comment(s) { sub(/[ \t]#.*$/, "", s); sub(/^#.*$/, "", s); return s }
+    function strip_quotes(s) {
+      if (s ~ /^".*"$/ || s ~ /^\047.*\047$/) s = substr(s, 2, length(s) - 2)
+      return s
+    }
+    # --- per-command predicates (heuristic, documented in the header) ---------
+    function seg_split(cmd, segs) { return split(cmd, segs, /&&|\|\||;|\|/) }
+    # cannot-fail = EVERY non-empty segment is one of the enumerated trivial
+    # commands {true, :, exit 0} or echo/printf-only. Per-segment (not a
+    # whole-string exact match) so a trailing separator ("exit 0 ;") or a
+    # multi-trivial form ("true || true") cannot evade the enumerated set. Scope
+    # is the ratified set ONLY — a real command guarded by "|| true" is NOT
+    # rule (a) (its non-trivial segment fails the test), matching the contract.
+    function is_cannot(cmd,  segs, n, i, s, any) {
+      cmd = trim(strip_comment(trim(cmd)))
+      n = seg_split(cmd, segs); any = 0
+      for (i = 1; i <= n; i++) {
+        s = trim(segs[i]); if (s == "") continue
+        any = 1
+        # Whitespace/zero-tolerant so "exit  0" (doubled space/tab) and "exit 00"
+        # cannot evade — both always exit 0, so both ARE rule (a).
+        if (s == "true" || s == ":") continue
+        if (s ~ /^exit[ \t]+0+$/) continue
+        if (s ~ /^(echo|printf)([ \t]|$)/) continue
+        return 0
+      }
+      return any
+    }
+    function is_exist(cmd,  segs, n, i, s, any) {
+      cmd = trim(cmd)
+      if (cmd ~ /\|\|/) return 0
+      n = seg_split(cmd, segs); any = 0
+      for (i = 1; i <= n; i++) {
+        s = trim(segs[i]); if (s == "") continue
+        any = 1
+        if (s !~ /^(test|\[\[?)[ \t]+-[efd][ \t]/) return 0
+      }
+      return any
+    }
+    function is_silent(cmd,  segs, n, i, s, any, sig) {
+      cmd = trim(cmd)
+      if (cmd ~ /\|\|/) return 0
+      n = seg_split(cmd, segs); any = 0; sig = 0
+      for (i = 1; i <= n; i++) {
+        s = trim(segs[i]); if (s == "") continue
+        any = 1
+        if (s ~ /^(grep[ \t]+(-[A-Za-z]+[ \t]+)*-q|diff[ \t]+(-[A-Za-z]+[ \t]+)*-q)/) { sig = 1; continue }
+        if (s ~ /^(test|\[\[?)[ \t]/) continue
+        return 0
+      }
+      return any && sig
+    }
+    # --- unit lifecycle -------------------------------------------------------
+    function flush(  i, c, all_cannot, all_exist, all_silent, cls) {
+      if (ucount == 0) { inunit = 0; return }
+      all_cannot = 1; all_exist = 1; all_silent = 1
+      for (i = 1; i <= ucount; i++) {
+        c = ucmd[i]
+        if (!is_cannot(c)) all_cannot = 0
+        if (!is_exist(c))  all_exist = 0
+        if (!is_silent(c) && !is_exist(c)) all_silent = 0
+      }
+      if (all_cannot) cls = "cannot-fail"
+      else if (all_exist) cls = "existence-only"
+      else if (all_silent) cls = "silent-fail"
+      else cls = "clean"
+      print cls, ustart, uend
+      ucount = 0; inunit = 0
+    }
+    BEGIN { inunit = 0; ucount = 0; mode = ""; uind = 0 }
+    {
+      line = $0
+      ind = indent_of(line)
+      t = trim(line)
+
+      if (inunit) {
+        if (mode == "block") {
+          if (t == "" || ind > uind) {
+            if (t != "") { ucmd[++ucount] = strip_quotes(t); uend = NR }
+            next
+          }
+          flush()
+        } else if (mode == "list") {
+          if (t == "" || (ind > uind && t ~ /^-[ \t]/)) {
+            if (t != "") { sub(/^-[ \t]+/, "", t); ucmd[++ucount] = strip_quotes(t); uend = NR }
+            next
+          }
+          flush()
+        }
+      }
+
+      # run: scalar or block start (optional leading "- ")
+      if (match(t, /^(-[ \t]+)?run:[ \t]*/)) {
+        rest = substr(t, RSTART + RLENGTH)
+        rest = trim(rest)
+        # Block scalar header: |, >, and their chomping/explicit-indent forms
+        # (|-, |+, |2, >2-, ...). An explicit-indent header like "|2" must open a
+        # block, not be read as a bogus inline command (which would flush clean
+        # and skip the real body — a cannot-fail body could then slip through).
+        if (rest == "" || rest ~ /^[|>][0-9]*[+-]?$/) {
+          inunit = 1; mode = "block"; uind = ind; ustart = NR; uend = NR; ucount = 0
+        } else {
+          inunit = 1; mode = ""; ustart = NR; uend = NR; ucount = 0
+          ucmd[++ucount] = strip_quotes(rest)
+          flush()
+        }
+        next
+      }
+      # script: list start (gitlab; also before_script/after_script)
+      if (t ~ /^(before_|after_)?script:[ \t]*$/) {
+        inunit = 1; mode = "list"; uind = ind; ustart = NR; uend = NR; ucount = 0
+        next
+      }
+    }
+    END { if (inunit) flush() }'
+}
+
+FINDINGS=""
+HAS_A=0
+add_finding() { # rule, file, line("" ok)
+  if [ -n "$3" ]; then
+    FINDINGS="${FINDINGS}${1}:${2}:${3}
+"
+  else
+    FINDINGS="${FINDINGS}${1}:${2}
+"
+  fi
+  [ "$1" = "cannot-fail" ] && HAS_A=1
+}
+
+CHANGED="$(git diff --name-only "$MB" "$HEAD_REF" 2>/dev/null)" \
+  || { printf 'forge-check-lint: git diff failed for %s\n' "$RANGE" >&2; exit 2; }
+
+while IFS= read -r path; do
+  [ -n "$path" ] || continue
+  base_name="$(basename "$path")"
+
+  # --- CI definition files: unit-classify HEAD side, report diff-touched units
+  case "$path" in
+    .github/workflows/*.yml|.github/workflows/*.yaml|.gitlab-ci.yml)
+      ADDED="$(added_lines "$path")"
+      [ -n "$ADDED" ] || continue
+      classify_units "$path" | while IFS=' ' read -r cls ustart uend; do
+        [ "$cls" != "clean" ] || continue
+        hit=""
+        while IFS= read -r ln; do
+          [ -n "$ln" ] || continue
+          if [ "$ln" -ge "$ustart" ] && [ "$ln" -le "$uend" ]; then hit=1; break; fi
+        done <<EOF2
+$ADDED
+EOF2
+        [ -n "$hit" ] && printf '%s %s %s\n' "$cls" "$path" "$ustart"
+      done > "${TMPDIR:-/tmp}/fcl_units.$$" || true
+      while IFS=' ' read -r cls p ln; do
+        [ -n "$cls" ] && add_finding "$cls" "$p" "$ln"
+      done < "${TMPDIR:-/tmp}/fcl_units.$$"
+      rm -f "${TMPDIR:-/tmp}/fcl_units.$$"
+      continue
+      ;;
+  esac
+
+  # --- test files: skip-markers on added lines; NET assertion loss on gating tests
+  case "$base_name" in
+    *_test.*|*.test.*|test_*.*|*.spec.*)
+      DIFF="$(git diff --unified=0 "$MB" "$HEAD_REF" -- "$path" 2>/dev/null)"
+      [ -n "$DIFF" ] || continue
+
+      added_body="$(printf '%s\n' "$DIFF" | grep '^+' | grep -v '^+++' | sed 's/^+//')"
+      removed_body="$(printf '%s\n' "$DIFF" | grep '^-' | grep -v '^---' | sed 's/^-//')"
+
+      if printf '%s\n' "$added_body" \
+        | grep -qE '\.only\(|\.skip\(|it\.skip|describe\.only|xit\(|xdescribe\(|@pytest\.mark\.skip|t\.Skip\(\)'; then
+        add_finding skip-marker "$path" ""
+      fi
+
+      if in_gating "$path"; then
+        removed_asserts=$(printf '%s\n' "$removed_body" \
+          | grep -cE 'assert|expect\(|\.should|\.to(Be|Equal)|t\.(Error|Fatal)' || true)
+        added_asserts=$(printf '%s\n' "$added_body" \
+          | grep -cE 'assert|expect\(|\.should|\.to(Be|Equal)|t\.(Error|Fatal)' || true)
+        if [ "$removed_asserts" -gt "$added_asserts" ]; then
+          hcs_stem="$(stem_of_test "$base_name")"
+          if [ -n "$hcs_stem" ] && has_correlated_source_deletion "$hcs_stem"; then
+            printf 'forge-check-lint: %s: assertion loss correlates with deletion of same-stem source (%s) — classified as feature removal, confirm intended (NOT test-gaming); the operator act is still required\n' "$path" "$hcs_stem" >&2
+            add_finding feature-removal "$path" ""
+          else
+            add_finding deleted-assertion "$path" ""
+          fi
+        fi
+      fi
+      ;;
+  esac
+done <<EOF
+$CHANGED
+EOF
+
+FINDINGS="$(printf '%s' "$FINDINGS" | sort -u)"
+
+if [ -z "$FINDINGS" ]; then
+  printf 'lint=clean\n'
+  exit 0
+fi
+
+if [ "$HAS_A" -eq 0 ] && [ -n "$JUSTIFY" ]; then
+  printf 'lint=justified justify="%s"\n' "$JUSTIFY"
+  printf '%s\n' "$FINDINGS" | while IFS= read -r f; do
+    [ -n "$f" ] && printf 'finding=%s justified\n' "$f"
+  done
+  exit 0
+fi
+
+[ "$HAS_A" -eq 1 ] && [ -n "$JUSTIFY" ] \
+  && printf 'forge-check-lint: Lint-Justify present but rule (a) cannot-fail is never justifiable\n' >&2
+
+printf 'lint=fail\n'
+printf '%s\n' "$FINDINGS" | while IFS= read -r f; do
+  [ -n "$f" ] && printf 'finding=%s\n' "$f"
+done
+exit 1