fix(#2785): implement missing gate predicate evaluators (#2816)

* fix(#2785): implement missing gate predicate evaluators

* fix(#2785): gate predicate numerical coercion

* fix(#2785): address evaluator review findings

* fix(#2785): use safe frontmatter read seam

---------

Co-authored-by: Tom Boucher <trekkie@nomorestars.com>

docs/adr/2008-command-exit-zero-gate.md

@@ -1,4 +1,4 @@
-# ADR-2008: Generic gate-predicate evaluator (`command-exit-zero`)
+# ADR-2008: Generic gate-predicate evaluator
 
 | | |
 |---|---|
@@ -39,8 +39,8 @@ The maintainer chose **Option 2** (issue comment, 2026-07-04).
 
 ## Decision
 
-Add a **generic gate-predicate evaluation path** with one built-in kind,
-`command-exit-zero`, scoped as follows.
+Add a **generic gate-predicate evaluation path** with two built-in kinds,
+`command-exit-zero` and `artifact-frontmatter-equals`, scoped as follows.
 
 ### Declaration shape
 
@@ -140,9 +140,6 @@ hiding the mechanism.
 
 ## Out of scope
 
-- Implementing the `artifact-frontmatter-equals` kind (the maintainer chose
-  Option 2 over Option 1; the kind table is structured for it but it is not
-  registered).
 - Retiring the hard-coded `security` branch in `ship.md`.
 - `check.agentVerdict` evaluation (advisory, `blocking:false`-forced, separate
   concern).

docs/adr/README.md

@@ -169,7 +169,7 @@ These govern the system as it stands. Cite these.
 | [ADR-1820](1820-spec-optional-predicate-rail.md) | Spec-Optional Predicate Rail — the Spec-Section Detection Module, the fallback toggle, and the SPEC↔probe precedence contract | Accepted | — |
 | [ADR-1866](1866-agent-skills-dual-injection-contract.md) | agent_skills dual injection — orchestrator-side + agent-side self-load | Accepted | — |
 | [ADR-1990](1990-existing-code-onboarding.md) | Existing Code Onboarding Module owns deterministic repo-state detection and onboarding route selection | Accepted | — |
-| [ADR-2008](2008-command-exit-zero-gate.md) | Generic gate-predicate evaluator (`command-exit-zero`) | Accepted | — |
+| [ADR-2008](2008-command-exit-zero-gate.md) | Generic gate-predicate evaluator | Accepted | — |
 | [ADR-2121](2121-phase-identifier-parsing-consolidation.md) | Phase-Identifier Parsing Consolidation | Accepted | — |
 | [ADR-2143](2143-markdown-table-and-mutation-consolidation.md) | Markdown Table Model, Bounded Mutation, and Fail-Loud Consolidation (#1372 part 2) | Accepted | — |
 | [ADR-2164](2164-statusline-scope-boundary.md) | Statusline draws its data boundary at local, read-only sources | Accepted | — |

docs/reference/gate-predicates.md

@@ -102,6 +102,32 @@ model".
 - `timeout` present but not a positive finite number.
 - Unknown `kind`.
 
+### `artifact-frontmatter-equals`
+
+Reads a Markdown file with YAML frontmatter from the current phase directory (or falls back to the project root for project-level artifacts) and compares a field's value to the declared expectation. The value is matched using loosely typed string comparison or exact matching, where numeric expectations will safely match stringified numeric frontmatter values.
+
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `kind` | string | yes | — | Must be `"artifact-frontmatter-equals"` |
+| `artifact` | string | yes | — | Suffix or exact filename (e.g. `WINDOWS.md`) |
+| `field` | string | yes | — | Frontmatter key to read |
+| `equals` | any | yes | — | Expected value (compared with string coercion) |
+
+**Result mapping.**
+
+| Command outcome | `block` | `message` |
+|---|---|---|
+| Value matches `equals` | `false` | `Frontmatter field "<field>" matches expected value (<expected>)` |
+| Value mismatch | `true` | `Frontmatter field "<field>" in <artifact> is <actual>, expected <expected>` |
+| Artifact file not found | `true` | `Artifact matching <artifact> not found in <targetDir>` |
+
+**Validation errors (throw → check-command failure → Step-1 / `onError`).**
+
+- Missing or empty `artifact` string.
+- Missing or empty `field` string.
+- Missing `equals` value.
+- File read or YAML parsing failure (I/O errors).
+
 ## Extensibility
 
 The evaluator dispatches through a `KIND_TABLE`. Adding a new built-in kind is