@jualopezmo/codeforge 0.4.0

package/src/shared/rules/ship-gates.md

@@ -0,0 +1,164 @@
+# Ship Gates
+
+Which boxes are required before an outward action (`git commit`, `git push`,
+`gh pr create`) depends on the **gate profile** of the active workflow. The skill records
+its profile in `.workflow/state.md`; `finish-branch` validates the active profile before
+shipping.
+
+## Gate profiles
+
+### `standard` — used by `new-feature`, `fix-bug`
+
+- [ ] On a feature branch (not `main`)
+- [ ] Plan written and design-reviewed (cross-engine — see single-engine fallback below).
+      **`N/A: <reason>` is allowed for a simple `fix-bug`** (1–2 files, not a high-impact
+      surface) — the failing test + code review still apply. `new-feature` and high-impact
+      fixes always require it.
+- [ ] Tests written (TDD) and passing
+- [ ] Code review clean — no open P0/P1/P2 (`severity.md`), cross-engine
+- [ ] E2E verified via verify-e2e (report: docs/e2e/reports/<...>.md) — `N/A: <reason>` allowed for purely internal changes (migration, refactor, tooling) and UI-only changes (no v1 adapter)
+- [ ] `.workflow/state.md` updated
+
+> The `E2E verified` box is an **Attested** signal: it asserts that a verify-e2e run
+> produced a `VERDICT: PASS` report committed under `docs/e2e/reports/`. `check-gates`
+> binds the box to that artifact, but the report is still the agent's own output — it is
+> not the Verified tier (which requires an out-of-turn recompute in CI). See the
+> Verified / Attested / Advisory ladder below.
+
+#### E2E evidence binding
+
+When the `E2E verified` box is checked as a **real run** (not an `— N/A:` escape), it must
+carry the concrete report path it produced:
+
+`- [x] E2E verified via verify-e2e (report: docs/e2e/reports/<file>.md)`
+
+`check-gates` validates the report **named in the box** — not just "any report in the
+directory". For the checked box, the line itself must name **exactly one** report (more
+than one `(report: …)` group on the line is rejected as ambiguous — see below), and that
+named path must:
+
+1. **match a strict whitelist** — `^docs/e2e/reports/[A-Za-z0-9._-]+\.md$` (a bare filename
+   directly under `docs/e2e/reports/`, no `..`, no subdirectories, no absolute path). This
+   also rejects the `<...>` placeholder, since `<`/`>` fall outside the allowed charset;
+2. **be a regular file, not a symlink** — resolved against the git toplevel, not the
+   current directory; a symlink at the named path (e.g. pointing outside the repo at a
+   fabricated report) is rejected before existence is even checked;
+3. **exist** as that regular file;
+4. **carry a top-level `VERDICT: PASS`** — the *first* `VERDICT:` line must be exactly
+   `VERDICT: PASS` (a per-UC `PASS` under a top-level `FAIL`, or `VERDICT: PASS extra`, fails);
+5. **be fresh on this branch** — the path must be new work (committed since the branch
+   point, staged, an unstaged tracked edit, or untracked).
+
+The branch **base is auto-detected** by the *closest* merge-base among
+`dev`, `main`, `master`, and their `origin/…` counterparts (plus `origin/HEAD`), so it
+works whether the repo integrates on `dev` or `main`. Freshness is **best-effort**: if no
+base ref resolves (single-branch or detached HEAD), freshness is skipped **with a note to
+stderr** — but the whitelist, symlink-rejection, existence, and top-level `PASS` checks are
+*always* enforced regardless of freshness.
+
+**Scope of the guarantee — be precise, not sweeping.** This closes a specific, named set of
+bypasses on the *record*: a checked box can't point at a placeholder, a path outside
+`docs/e2e/reports/` (traversal or absolute), a subdirectory, a **leaf symlink** at the named
+path, or an ambiguous multi-report line — and it can't point at a stale/inherited report once
+a base resolves. That is the full extent of what `check-gates` proves. It does **not** prove
+the report's *content* is true: the file at that path still says whatever an agent or human
+wrote into it. It also does not defend against filesystem indirection such as a symlinked
+ancestor directory. A committed report with a hand-typed `VERDICT: PASS` and no verify-e2e run
+behind it satisfies every check above. This is the **Attested** tier (see the Verified /
+Attested / Advisory ladder below) — the record's *shape* is validated, not the underlying
+claim. Only the **Verified** tier — an out-of-turn CI job that re-runs `verify-e2e` itself
+against the PR commit, independent of the agent's say-so — is bypass-proof against a
+bad-faith or mistaken attestation.
+
+The `— N/A:` escape is an **exact em-dash form** (em-dash, space, `N/A:`, non-empty reason).
+A bare `N/A:`, a `- N/A:`, or a backticked `` `N/A:` `` inside explanatory text does **not**
+count as the escape — those fall through to the report-path checks above.
+
+The active workflow records its profile in `.workflow/state.md` (the **Profile** field —
+see `shared/state.template.md`); `finish-branch` validates that profile's boxes before shipping.
+
+### `light` — used by `quick-fix`
+
+- [ ] On a feature branch (not `main`)
+- [ ] Change verified (ran it, or the relevant test passes)
+- [ ] Still trivial (<3 files, no behavior risk) — otherwise **escalate** to `new-feature`/`fix-bug` and switch to the `standard` profile
+
+### No gate — `prd`, `research`, `plan`, `index`, `checkpoint`, `review`, `council`
+
+These produce an artifact or advice and don't ship on their own; they feed a workflow that
+carries one of the profiles above.
+
+## Single-engine fallback (the cross-engine review items)
+
+The `standard` profile's review items assume **≥2 engines are available**. Most users run
+one CLI, so this must degrade honestly instead of becoming unsatisfiable:
+
+If no second engine is available, satisfy the review items by either:
+- a **delayed self-review** — step away, then re-read the plan/diff fresh against
+  `severity.md` as if it were someone else's; or
+- a **human reviewer**.
+
+Then log a waiver in `.workflow/state.md`, e.g.:
+`Review: single-engine self-review (no second engine available) — <date>`
+
+Cross-engine review is the default and preferred (real model diversity). The waiver just
+makes the degradation **explicit and auditable**, never silent.
+
+## What a gate can honestly claim — Verified / Attested / Advisory
+
+Be precise about the strength of each gate signal. A claim is only as strong as what
+produced it:
+
+- **Verified** — an out-of-turn check *recomputed* the fact, independent of the agent's
+  say-so. Example: CI ran the test suite at the exact PR commit and it passed. This is the
+  strongest signal, and the only one that survives a bad-faith or mistaken agent.
+- **Attested** — an agent or human *claimed* it and something validated the claim's *shape*,
+  not its truth. A `- [x]` box in `.workflow/state.md`, or `check-gates.sh` reporting the
+  checklist is complete, is attested: it confirms the record says "done", not that the work
+  was done. A file that says `reviewer_engine: codex` is not proof Codex reviewed anything.
+- **Advisory** — present only as an instruction the agent is asked to follow. The workflow
+  skills and this rules file are advisory.
+
+**Never present an attested checkbox as if it were verified.** The honest upgrade path is to
+move a claim up the ladder — e.g. bind "tests passing" to CI (verified) rather than a box
+someone ticked (attested).
+
+## How enforcement works here (advisory + Tier-B check + native prompt)
+
+**Be honest about what this is: discipline, not a hard gate.** Nothing conditionally
+blocks a commit when a box is unchecked. Three things stand in — none of them a hard block:
+
+1. **Advisory (all engines):** you are instructed — here and in the workflow skill — not
+   to ship until the profile's boxes pass. Honor it.
+2. **Deterministic Tier-B check (all engines):** `finish-branch` runs
+   `shared/scripts/check-gates.sh` (`.ps1` on Windows), which reads `.workflow/state.md` and
+   exits non-zero listing any unchecked box. This turns "eyeball the file" into "run a
+   command that fails loudly" — a much harder thing to rationalize past, and the *same*
+   command a human or CI can run. It is still **attested** (it validates the record, not the
+   work) and still **skippable** (Tier B runs only when invoked — it is not a hook). For a
+   real *verified* gate, run it in CI with branch protection so the check binds to the PR
+   commit outside the agent's turn.
+3. **Best-effort native prompt (per engine):** each engine can prompt for human approval
+   on outward commands — but it reads **no** gate state and matches commands by pattern,
+   so it is bypassable (e.g. `git -C . push`, a PR via API, another tool):
+   - **Claude Code** — `git push` / `gh pr create` are `ask`-tier in `.claude/settings.json`.
+   - **Codex** — `approval_policy` in `.codex/config.toml` asks when a command crosses the
+     sandbox boundary (not before every command).
+   - **OpenCode** — `permission.bash` in `opencode.json` sets `git push*` / `gh pr create*`
+     to `ask` (force-push `deny`).
+
+The prompt shows the human a generic "allow this command?", **not** the checklist — so it
+is a commit-confirmation, not proof the gates are green. The approver must
+**independently check `.workflow/state.md` before approving** (or run `check-gates.sh`).
+
+### Opt-in hard block (Tier C, Claude Code only)
+
+For the one engine that supports it, `install.sh --with-hooks` (`-WithHooks` on PowerShell)
+installs a Claude Code `PreToolUse` hook into `.claude/settings.local.json` that runs
+`shared/scripts/claude-gate-hook.sh` — the same `check-gates.sh` behind a hook — and **exits 2
+to actually block** `git commit` / `git push` / `gh pr create` when the gates are incomplete.
+This is the only place codeforge can hard-block. It is deliberately **not the default**: it's
+per-developer (the local settings file is gitignored), Claude-Code-specific (breaks the
+cross-engine promise, so it stays opt-in), and fails **open** if it can't verify. The gate is
+still *attested* — it confirms the recorded boxes, not the underlying work. Codex/OpenCode have
+the mechanism (see `docs/extending.md` Tier C) but no adapter ships yet.

package/src/shared/rules/tdd.md

@@ -0,0 +1,20 @@
+# TDD
+
+Write the test before the implementation. Non-negotiable for any behavior change.
+
+## Red → Green → Refactor
+
+1. **Red** — write a test that fails for the right reason (the behavior doesn't exist yet,
+   or the bug is present). Run it; confirm it fails with the expected message.
+2. **Green** — write the minimum code to make it pass. No extra scope.
+3. **Refactor** — clean up with the test still green. Improve names/structure, remove
+   duplication.
+
+## Rules
+
+- One behavior per test; name it `test_<action>_<scenario>_<expected>`.
+- Test both the success path and the meaningful error/edge cases.
+- Mock only external systems (network, third-party APIs, time) — never your own code.
+- A test you never saw fail proves nothing. If it passed the first time, break the code
+  on purpose and confirm the test catches it.
+- Never commit with a failing or skipped test unless the skip is justified in writing.

package/src/shared/rules/workflow.md

@@ -0,0 +1,38 @@
+# Workflow
+
+Use a workflow skill for any non-trivial change. Follow its steps in order.
+
+## Which skill
+
+| Scenario | Skill |
+| --- | --- |
+| Define what/why before building | `prd` |
+| Check current docs / prior art | `research` |
+| Design: compare approaches, write a plan | `plan` |
+| New feature / behavior change | `new-feature` |
+| Bug fix | `fix-bug` |
+| Trivial change (<3 files) | `quick-fix` |
+| Cross-engine second opinion (plan or diff) | `review` |
+| Verify a user-facing change end to end | `verify-e2e` |
+| Hard, expensive decision fork | `council` |
+| Wrap up + open PR | `finish-branch` |
+| Session handoff before closing | `checkpoint` |
+| Project map for orientation | `index` |
+
+## Phases (shared shape)
+
+1. **Brainstorm** — clarify intent, constraints, success criteria before designing.
+2. **Plan** — write the approach; identify files, edge cases, tests.
+3. **Design review** — get a second opinion from a *different* engine (any of Claude
+   Code / Codex / OpenCode; models in `models.md`) before implementing. Cross-engine
+   diversity is the point.
+4. **TDD** — red → green → refactor. Write the failing test first.
+5. **Code review** — dual review (the other engine + self) against the diff; fix all
+   P0/P1/P2 before shipping (see `severity.md`).
+6. **Verify** — actually exercise the change, don't just trust tests.
+7. **Ship** — only when `.workflow/state.md` gates pass (see `ship-gates.md`).
+
+## Tracking
+
+Keep `.workflow/state.md` current: check boxes as phases complete, record the active
+branch and the review iterations. It is the source of truth the ship-gate checklist reads.

package/src/shared/scripts/check-gates.ps1

@@ -0,0 +1,197 @@
+# check-gates.ps1 — deterministic ship-gate checklist validator (Tier B).
+#
+# PowerShell parity of shared/scripts/check-gates.sh. Reads .workflow/state.md and
+# confirms every ship-gate box for the active profile is checked (or N/A).
+#
+#   pwsh shared/scripts/check-gates.ps1                 # reads .workflow/state.md
+#   pwsh shared/scripts/check-gates.ps1 path\to\state.md
+#
+# HONESTY: verifies the RECORD, not the underlying work — a checked box is an
+# attestation, not proof. See shared/rules/ship-gates.md (Verified / Attested /
+# Advisory). Advisory (Tier B): it does not block a commit on its own.
+#
+# Exit codes: 0 = complete · 1 = unmet boxes · 3 = cannot read state/checklist.
+[CmdletBinding()]
+param([string]$StatePath = ".workflow/state.md")
+
+$ErrorActionPreference = "Stop"
+# Parity with sh's masked git failures (`|| echo ""` / `2>$null`): explicitly set
+# $PSNativeCommandUseErrorActionPreference = $false (defensive: guards against upstream
+# configs that enable it) so native git non-zero exits are handled via $LASTEXITCODE, not thrown.
+$PSNativeCommandUseErrorActionPreference = $false
+
+if (-not (Test-Path -LiteralPath $StatePath -PathType Leaf)) {
+    [Console]::Error.WriteLine("check-gates: no state file at '$StatePath' — cannot verify gates.")
+    [Console]::Error.WriteLine("  Start a workflow (copy shared/state.template.md) before shipping.")
+    exit 3
+}
+
+$lines = Get-Content -LiteralPath $StatePath
+
+$profile = "(unknown)"
+foreach ($line in $lines) {
+    $m = [regex]::Match($line, 'Profile:[*]*\s*([A-Za-z][A-Za-z-]*)')
+    if ($m.Success) { $profile = $m.Groups[1].Value; break }
+}
+
+$inList = $false
+$total = 0
+$unmetLines = @()
+foreach ($line in $lines) {
+    if ($line -match '^##\s+Ship-gate checklist') { $inList = $true; continue }
+    elseif ($line -match '^##\s')                 { $inList = $false }
+    if (-not $inList) { continue }
+    if ($line -match '^- \[[ xX]\]') { $total++ }
+    if ($line -match '^- \[ \]')     { $unmetLines += ("  " + [char]0x2717 + $line.Substring(5)) }
+}
+
+if ($total -eq 0) {
+    [Console]::Error.WriteLine("check-gates: no '## Ship-gate checklist' boxes found in '$StatePath'.")
+    [Console]::Error.WriteLine("  Is this a real workflow state file?")
+    exit 3
+}
+
+# Validate the checklist carries the REQUIRED gates for its profile (standard = 6, light = 3,
+# per shared/rules/ship-gates.md) — otherwise a state file that deletes gates reads green.
+$required = switch ($profile) {
+    'standard' { 6; break }
+    'light'    { 3; break }
+    default {
+        [Console]::Error.WriteLine("check-gates: unknown gate profile '$profile' — can't determine required gates.")
+        [Console]::Error.WriteLine("  Set Profile to 'standard' or 'light' in the Active workflow section.")
+        exit 3
+    }
+}
+if ($total -lt $required) {
+    [Console]::Error.WriteLine("check-gates: profile '$profile' requires $required gates but the checklist has only $total —")
+    [Console]::Error.WriteLine("  required ship-gate boxes are missing. Restore them from shared/state.template.md.")
+    exit 1
+}
+
+$unmet = $unmetLines.Count
+if ($unmet -gt 0) {
+    [Console]::Error.WriteLine("check-gates: profile '$profile' — $($total - $unmet)/$total boxes checked — UNMET.")
+    [Console]::Error.WriteLine("Unchecked ship-gate boxes (do NOT ship):")
+    foreach ($l in $unmetLines) { [Console]::Error.WriteLine($l) }
+    [Console]::Error.WriteLine("Confirms the recorded checklist, not the work itself (ship-gates.md:")
+    [Console]::Error.WriteLine("Verified / Attested / Advisory). Finish the boxes, then re-run.")
+    exit 1
+}
+
+# --- E2E evidence check (Attested) --------------------------------------------
+$e2eLine = $null
+$inE = $false
+foreach ($line in $lines) {
+    if ($line -match '^##\s+Ship-gate checklist') { $inE = $true; continue }
+    elseif ($line -match '^##\s')                 { $inE = $false }
+    if ($inE -and $line -cmatch '^- \[[xX]\]\s+E2E verified') { $e2eLine = $line; break }
+}
+if ($e2eLine) {
+    if ($e2eLine -cmatch '— N/A:') {
+        $reason = ([regex]::Match($e2eLine, 'N/A:\s*(.*)$')).Groups[1].Value.Trim()
+        if ([string]::IsNullOrEmpty($reason)) {
+            [Console]::Error.WriteLine("check-gates: 'E2E verified' uses 'N/A:' with no reason — treated as unmet.")
+            exit 1
+        }
+    } else {
+        # 0. Reject an ambiguous line carrying more than one "(report:" group — one report
+        #    per box. Without this, sh's greedy extraction (rightmost group) and ps1's
+        #    leftmost-first regex Match could disagree on WHICH path is checked; refusing
+        #    the ambiguous line outright removes the divergence entirely.
+        $reportGroups = ([regex]::Matches($e2eLine, '\(report:')).Count
+        if ($reportGroups -gt 1) {
+            [Console]::Error.WriteLine("check-gates: 'E2E verified' line names more than one (report: ...) group — ambiguous.")
+            [Console]::Error.WriteLine("  A checked box must name exactly one report.")
+            exit 1
+        }
+        # 1. Parse the report path named in the box: (report: <PATH>).
+        $reportPath = ''
+        $mrp = [regex]::Match($e2eLine, '\(report:\s*([^)]*)\)')
+        if ($mrp.Success) { $reportPath = $mrp.Groups[1].Value.TrimEnd() }
+        if ([string]::IsNullOrEmpty($reportPath)) {
+            [Console]::Error.WriteLine("check-gates: 'E2E verified' is checked but names no report path.")
+            [Console]::Error.WriteLine("  Put the real report path in the box: (report: docs/e2e/reports/<file>.md).")
+            exit 1
+        }
+        # 1b. Whitelist the path shape: it must be a bare filename directly under
+        #     docs/e2e/reports/ — no '..', no subdirectories, no absolute paths. Since '<'
+        #     and '>' fall outside the allowed charset, this also subsumes the previous
+        #     placeholder-only rejection with one strict allowlist.
+        if ($reportPath -cnotmatch '^docs/e2e/reports/[A-Za-z0-9._-]+\.md$') {
+            [Console]::Error.WriteLine("check-gates: 'E2E verified' names report path '$reportPath', which is not a")
+            [Console]::Error.WriteLine("  real report under docs/e2e/reports/. The box must name a real file directly")
+            [Console]::Error.WriteLine("  under docs/e2e/reports/ (e.g. docs/e2e/reports/<feature>.md) — no '..', no")
+            [Console]::Error.WriteLine("  subdirectories, no absolute paths, no placeholders.")
+            exit 1
+        }
+        # 2. Resolve against the git toplevel (not cwd), and require a REGULAR FILE — a
+        #    symlink at the named path (e.g. pointing outside the repo at a fabricated
+        #    report) must never satisfy the gate. Checked BEFORE the existence check so a
+        #    symlink can never count as "exists".
+        $toplevel = (git rev-parse --show-toplevel 2>$null)
+        if ($toplevel) { $absReport = Join-Path $toplevel $reportPath } else { $absReport = $reportPath }
+        $absItem = Get-Item -LiteralPath $absReport -Force -ErrorAction SilentlyContinue
+        if ($absItem -and $absItem.LinkType) {
+            [Console]::Error.WriteLine("check-gates: 'E2E verified' names report '$reportPath' but that path is a")
+            [Console]::Error.WriteLine("  symlink, not a regular file. Reports must be real files under docs/e2e/reports/.")
+            exit 1
+        }
+        if (-not (Test-Path -LiteralPath $absReport -PathType Leaf)) {
+            [Console]::Error.WriteLine("check-gates: 'E2E verified' names report '$reportPath' but that file does not exist.")
+            [Console]::Error.WriteLine("  Run the verify-e2e skill to produce it, or use '— N/A: <reason>'.")
+            exit 1
+        }
+        # 3. Top-level verdict must be exactly PASS (the FIRST "VERDICT:" line only, so a
+        #    per-UC "VERDICT: PASS" below a top-level FAIL can never satisfy the gate).
+        $firstVerdict = (Get-Content -LiteralPath $absReport | Where-Object { $_ -cmatch '^VERDICT:' } | Select-Object -First 1)
+        if (-not ($firstVerdict -cmatch '^VERDICT:\s+PASS\s*$')) {
+            [Console]::Error.WriteLine("check-gates: report '$reportPath' top-level verdict is not 'VERDICT: PASS'.")
+            [Console]::Error.WriteLine("  The first VERDICT: line must be exactly 'VERDICT: PASS'.")
+            exit 1
+        }
+        # 4. Freshness (best-effort, never silently passes): the named path must be new
+        #    work on this branch. Base = closest merge-base among dev/main/master/origin.
+        $inRepo = $false
+        try { git rev-parse --is-inside-work-tree *> $null; if ($LASTEXITCODE -eq 0) { $inRepo = $true } } catch {}
+        if ($inRepo) {
+            $current = (git rev-parse --abbrev-ref HEAD 2>$null)
+            $originHead = (git rev-parse --abbrev-ref origin/HEAD 2>$null)
+            $base = ''
+            $bestCount = -1
+            $cands = @('dev','main','master','origin/dev','origin/main','origin/master')
+            if ($originHead) { $cands += $originHead }
+            foreach ($ref in $cands) {
+                if (-not $ref) { continue }
+                if ($ref -eq $current) { continue }
+                git rev-parse --verify --quiet $ref *> $null
+                if ($LASTEXITCODE -ne 0) { continue }
+                $mb = (git merge-base HEAD $ref 2>$null)
+                if (-not $mb) { continue }
+                $count = (git rev-list --count "$mb..HEAD" 2>$null)
+                if (-not $count) { continue }
+                $c = [int]$count
+                if ($bestCount -lt 0 -or $c -lt $bestCount) { $bestCount = $c; $base = $mb }
+            }
+            if ($base) {
+                $committed = (git diff --name-only "$base..HEAD" -- $reportPath 2>$null)
+                $staged    = (git diff --cached --name-only -- $reportPath 2>$null)
+                $unstaged  = (git diff --name-only -- $reportPath 2>$null)
+                $untracked = (git ls-files --others --exclude-standard -- $reportPath 2>$null)
+                if (-not $committed -and -not $staged -and -not $unstaged -and -not $untracked) {
+                    [Console]::Error.WriteLine("check-gates: report '$reportPath' is not fresh on this branch (base $base).")
+                    [Console]::Error.WriteLine("  It is unchanged from the base — a stale or inherited report cannot satisfy the gate.")
+                    [Console]::Error.WriteLine("  Run the verify-e2e skill to produce a report for THIS change.")
+                    exit 1
+                }
+            } else {
+                [Console]::Error.WriteLine("check-gates: note — no base branch (dev/main/master/origin) resolved; report")
+                [Console]::Error.WriteLine("  freshness could not be checked. Existence + VERDICT: PASS were enforced for '$reportPath'.")
+            }
+        }
+    }
+}
+# --- end E2E evidence check ---------------------------------------------------
+
+Write-Output "check-gates: profile '$profile' — all $total recorded boxes checked."
+Write-Output "Attested-complete: a checked box is an attestation, not independent proof."
+exit 0

package/src/shared/scripts/check-gates.sh

@@ -0,0 +1,201 @@
+#!/bin/sh
+# check-gates.sh — deterministic ship-gate checklist validator (Tier B).
+#
+# Reads .workflow/state.md and confirms every ship-gate box for the active
+# profile is checked (or explicitly N/A). Exit 0 = the recorded checklist is
+# complete; non-zero + a list = unmet boxes.
+#
+#   sh shared/scripts/check-gates.sh                 # reads .workflow/state.md
+#   sh shared/scripts/check-gates.sh path/to/state.md
+#
+# HONESTY: this verifies the RECORD, not the underlying work. A checked box is an
+# *attestation* by whoever checked it — the script confirms the checklist is
+# complete, it cannot confirm the tests really passed or the change was really
+# exercised. See shared/rules/ship-gates.md (Verified / Attested / Advisory).
+# It runs only when the agent (or a human, or CI) chooses to call it — Tier B is
+# deterministic but still advisory; it does not block a commit on its own.
+#
+# Exit codes: 0 = complete · 1 = unmet boxes · 3 = cannot read state/checklist.
+set -eu
+
+STATE="${1:-.workflow/state.md}"
+
+if [ ! -f "$STATE" ]; then
+  echo "check-gates: no state file at '$STATE' — cannot verify gates." >&2
+  echo "  Start a workflow (copy shared/state.template.md) before shipping." >&2
+  exit 3
+fi
+
+profile=$(sed -n 's/.*[Pp]rofile:[*]*[[:space:]]*\([A-Za-z][A-Za-z-]*\).*/\1/p' "$STATE" | head -n1)
+[ -n "$profile" ] || profile="(unknown)"
+
+# Walk only the "## Ship-gate checklist" section; tally checked vs unmet boxes.
+# A box is unmet only when it is literally "- [ ]" (unchecked). "- [x]" counts as
+# satisfied, including an "- [x] ... N/A: <reason>" line. Counts come out on one
+# line (kept free of embedded newlines); the unmet box text is a separate pass.
+counts=$(awk '
+  /^##[[:space:]]+Ship-gate checklist/ { inlist = 1; next }
+  /^##[[:space:]]/                     { inlist = 0 }
+  inlist && /^- \[[ xX]\]/             { total++ }
+  inlist && /^- \[ \]/                 { unmet++ }
+  END { printf "%d %d", total + 0, unmet + 0 }
+' "$STATE")
+total=${counts% *}
+unmet=${counts#* }
+
+if [ "$total" -eq 0 ]; then
+  echo "check-gates: no '## Ship-gate checklist' boxes found in '$STATE'." >&2
+  echo "  Is this a real workflow state file?" >&2
+  exit 3
+fi
+
+# Validate the checklist actually carries the REQUIRED gates for its profile — otherwise a
+# state file that deletes required gates (or claims a profile it doesn't satisfy) reads green.
+# Required counts mirror shared/rules/ship-gates.md (standard = 6, light = 3).
+case "$profile" in
+  standard) required=6 ;;
+  light)    required=3 ;;
+  *)        echo "check-gates: unknown gate profile '$profile' — can't determine required gates." >&2
+            echo "  Set Profile to 'standard' or 'light' in the Active workflow section." >&2
+            exit 3 ;;
+esac
+if [ "$total" -lt "$required" ]; then
+  echo "check-gates: profile '$profile' requires $required gates but the checklist has only $total —" >&2
+  echo "  required ship-gate boxes are missing. Restore them from shared/state.template.md." >&2
+  exit 1
+fi
+
+if [ "$unmet" -gt 0 ]; then
+  echo "check-gates: profile '$profile' — $((total - unmet))/$total boxes checked — UNMET." >&2
+  echo "Unchecked ship-gate boxes (do NOT ship):" >&2
+  awk '
+    /^##[[:space:]]+Ship-gate checklist/ { inlist = 1; next }
+    /^##[[:space:]]/                     { inlist = 0 }
+    inlist && /^- \[ \]/                 { print "  \342\234\227" substr($0, 6) }
+  ' "$STATE" >&2
+  echo "Confirms the recorded checklist, not the work itself (ship-gates.md:" >&2
+  echo "Verified / Attested / Advisory). Finish the boxes, then re-run." >&2
+  exit 1
+fi
+
+# --- E2E evidence check (Attested) --------------------------------------------
+# When the "E2E verified" box is checked as a real run (not "— N/A: <reason>"),
+# bind it to the report PATH NAMED in the box. That named file must EXIST, carry a
+# top-level VERDICT: PASS, and (best-effort) be fresh on this branch. A checked box
+# NEVER passes the gate without its named PASS report — no silent fail-open. Base is
+# auto-detected by closest merge-base among dev/main/master/origin (this repo
+# integrates on dev, not main). Freshness uses git, not mtime (clone/checkout resets
+# mtimes); it degrades to a stderr note only when no base ref resolves.
+e2e_line=$(awk '
+  /^##[[:space:]]+Ship-gate checklist/ { inlist = 1; next }
+  /^##[[:space:]]/                     { inlist = 0 }
+  inlist && /^- \[[xX]\][[:space:]]+E2E verified/ { print; exit }
+' "$STATE")
+
+if [ -n "$e2e_line" ]; then
+  case "$e2e_line" in
+    *"— N/A:"*)
+      # N/A escape must carry a non-empty reason.
+      reason=$(printf '%s' "$e2e_line" | sed -n 's/.*N\/A:[[:space:]]*\(.*\)$/\1/p')
+      if [ -z "$reason" ]; then
+        echo "check-gates: 'E2E verified' uses 'N/A:' with no reason — treated as unmet." >&2
+        exit 1
+      fi
+      ;;
+    *)
+      # 0. Reject an ambiguous line carrying more than one "(report:" group — one report
+      #    per box. Without this, sh's greedy extraction (rightmost group) and ps1's
+      #    leftmost-first regex Match could disagree on WHICH path is checked; refusing
+      #    the ambiguous line outright removes the divergence entirely.
+      report_groups=$(printf '%s' "$e2e_line" | grep -o '(report:' | wc -l | tr -d '[:space:]')
+      if [ "$report_groups" -gt 1 ]; then
+        echo "check-gates: 'E2E verified' line names more than one (report: ...) group — ambiguous." >&2
+        echo "  A checked box must name exactly one report." >&2
+        exit 1
+      fi
+      # 1. Parse the report path named in the box: (report: <PATH>).
+      report_path=$(printf '%s' "$e2e_line" | sed -n 's/.*(report:[[:space:]]*\([^)]*\)).*/\1/p' | head -n1)
+      report_path=$(printf '%s' "$report_path" | sed 's/[[:space:]]*$//')
+      if [ -z "$report_path" ]; then
+        echo "check-gates: 'E2E verified' is checked but names no report path." >&2
+        echo "  Put the real report path in the box: (report: docs/e2e/reports/<file>.md)." >&2
+        exit 1
+      fi
+      # 1b. Whitelist the path shape: it must be a bare filename directly under
+      #     docs/e2e/reports/ — no '..', no subdirectories, no absolute paths. Since '<'
+      #     and '>' fall outside the allowed charset, this also subsumes the previous
+      #     placeholder-only rejection with one strict allowlist.
+      if ! printf '%s' "$report_path" | grep -Eq '^docs/e2e/reports/[A-Za-z0-9._-]+\.md$'; then
+        echo "check-gates: 'E2E verified' names report path '$report_path', which is not a" >&2
+        echo "  real report under docs/e2e/reports/. The box must name a real file directly" >&2
+        echo "  under docs/e2e/reports/ (e.g. docs/e2e/reports/<feature>.md) — no '..', no" >&2
+        echo "  subdirectories, no absolute paths, no placeholders." >&2
+        exit 1
+      fi
+      # 2. Resolve against the git toplevel (not cwd), and require a REGULAR FILE — a
+      #    symlink at the named path (e.g. pointing outside the repo at a fabricated
+      #    report) must never satisfy the gate. Checked BEFORE the existence check so a
+      #    symlink can never count as "exists".
+      toplevel=$(git rev-parse --show-toplevel 2>/dev/null || echo "")
+      if [ -n "$toplevel" ]; then abs_report="$toplevel/$report_path"; else abs_report="$report_path"; fi
+      if [ -L "$abs_report" ]; then
+        echo "check-gates: 'E2E verified' names report '$report_path' but that path is a" >&2
+        echo "  symlink, not a regular file. Reports must be real files under docs/e2e/reports/." >&2
+        exit 1
+      fi
+      if [ ! -f "$abs_report" ]; then
+        echo "check-gates: 'E2E verified' names report '$report_path' but that file does not exist." >&2
+        echo "  Run the verify-e2e skill to produce it, or use '— N/A: <reason>'." >&2
+        exit 1
+      fi
+      # 3. Top-level verdict must be exactly PASS (the FIRST "VERDICT:" line only, so a
+      #    per-UC "VERDICT: PASS" below a top-level FAIL can never satisfy the gate).
+      first_verdict=$(awk '/^VERDICT:/{print; exit}' "$abs_report")
+      if ! printf '%s' "$first_verdict" | grep -Eq '^VERDICT:[[:space:]]+PASS[[:space:]]*$'; then
+        echo "check-gates: report '$report_path' top-level verdict is not 'VERDICT: PASS'." >&2
+        echo "  The first VERDICT: line must be exactly 'VERDICT: PASS'." >&2
+        exit 1
+      fi
+      # 4. Freshness (best-effort, never silently passes): the named path must be new
+      #    work on this branch. Base = closest merge-base among dev/main/master/origin.
+      if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+        current=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+        origin_head=$(git rev-parse --abbrev-ref origin/HEAD 2>/dev/null || echo "")
+        base=""
+        best_count=""
+        for ref in dev main master origin/dev origin/main origin/master "$origin_head"; do
+          [ -n "$ref" ] || continue
+          [ "$ref" != "$current" ] || continue
+          git rev-parse --verify --quiet "$ref" >/dev/null 2>&1 || continue
+          mb=$(git merge-base HEAD "$ref" 2>/dev/null || echo "")
+          [ -n "$mb" ] || continue
+          count=$(git rev-list --count "$mb"..HEAD 2>/dev/null || echo "")
+          [ -n "$count" ] || continue
+          if [ -z "$best_count" ] || [ "$count" -lt "$best_count" ]; then
+            best_count="$count"; base="$mb"
+          fi
+        done
+        if [ -n "$base" ]; then
+          committed=$(git diff --name-only "$base"..HEAD -- "$report_path" 2>/dev/null || echo "")
+          staged=$(git diff --cached --name-only -- "$report_path" 2>/dev/null || echo "")
+          unstaged=$(git diff --name-only -- "$report_path" 2>/dev/null || echo "")
+          untracked=$(git ls-files --others --exclude-standard -- "$report_path" 2>/dev/null || echo "")
+          if [ -z "$committed" ] && [ -z "$staged" ] && [ -z "$unstaged" ] && [ -z "$untracked" ]; then
+            echo "check-gates: report '$report_path' is not fresh on this branch (base $base)." >&2
+            echo "  It is unchanged from the base — a stale or inherited report cannot satisfy the gate." >&2
+            echo "  Run the verify-e2e skill to produce a report for THIS change." >&2
+            exit 1
+          fi
+        else
+          echo "check-gates: note — no base branch (dev/main/master/origin) resolved; report" >&2
+          echo "  freshness could not be checked. Existence + VERDICT: PASS were enforced for '$report_path'." >&2
+        fi
+      fi
+      ;;
+  esac
+fi
+# --- end E2E evidence check ---------------------------------------------------
+
+echo "check-gates: profile '$profile' — all $total recorded boxes checked."
+echo "Attested-complete: a checked box is an attestation, not independent proof."
+exit 0

package/src/shared/scripts/claude-gate-hook.ps1

@@ -0,0 +1,35 @@
+# claude-gate-hook.ps1 — Claude Code PreToolUse adapter (opt-in Tier-C hardening).
+#
+# PowerShell parity of claude-gate-hook.sh. Installed only by `install.ps1 -WithHooks`
+# into .claude/settings.local.json. On a Bash ship action it runs check-gates.ps1 and
+# exits 2 (BLOCK) if the ship-gate boxes are incomplete. Claude Code only, per-developer
+# opt-in, not portable. Fails OPEN if it can't verify. See shared/rules/ship-gates.md.
+$ErrorActionPreference = "Stop"
+
+# NOTE: read into a non-reserved variable — assigning to the automatic $input in -File mode
+# yields an empty string, which silently turned this hook into a no-op.
+$payload = [Console]::In.ReadToEnd()
+
+if ($payload -notmatch 'git commit|git push|gh pr create') { exit 0 }
+
+$hookDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$gates = Join-Path $hookDir 'check-gates.ps1'
+if (-not (Test-Path -LiteralPath $gates -PathType Leaf)) {
+    [Console]::Error.WriteLine("codeforge gate-hook: check-gates.ps1 not found next to the hook; allowing (fail-open).")
+    exit 0
+}
+
+& pwsh -NoProfile -File $gates *> $null
+$rc = $LASTEXITCODE
+if ($rc -eq 0) { exit 0 }   # gates complete → allow
+if ($rc -ne 1) {            # can't verify (e.g. no workflow state, exit 3) → fail OPEN, never block
+    [Console]::Error.WriteLine("codeforge gate-hook: could not verify gates (check-gates exit $rc); allowing (fail-open).")
+    exit 0
+}
+
+[Console]::Error.WriteLine("codeforge gate: ship BLOCKED — ship-gate boxes are not complete.")
+$detail = & pwsh -NoProfile -File $gates 2>&1
+foreach ($line in $detail) { [Console]::Error.WriteLine("  $line") }
+[Console]::Error.WriteLine("  (opt-in -WithHooks gate; Claude Code only. Finish the boxes in")
+[Console]::Error.WriteLine("   .workflow/state.md, then retry. This checks the record, not the work.)")
+exit 2