task-1(v3.0): the record can finally say which diff it covers

Spec §C says the triage record binds session_id, base_commit and
declared_paths, and the Stop-hook rule task-8 landed reads exactly those to
decide whether a record covers the current diff. The schema is
additionalProperties:false and carried none of them, so no record could express
them and no record could ever cover anything. The gate is off by default, so
nothing was broken — Feature C would simply have shipped inert, a correct
mechanism with nothing to feed it.

WHY each field is shaped the way it is:

* `session_id` is optional and nullable, never required. This engine never sees
  a session; only /v:triage does. Requiring it would invalidate every record the
  scorer writes outside a triage command. Absent or null means the record binds
  no session and therefore covers nothing, which is the fail-closed direction the
  gate's exact-match test already produces. The EMPTY STRING is rejected: it
  looks like a binding and can never match, and that is the one shape that
  misleads a reader.

* `declared_paths` items are constrained to what the consumer can actually read.
  The hook serializes candidates as `tier<US>run_id<US>path` and DROPS any entry
  containing U+001F, LF or CR. Dropping narrows the declared set, which is safe
  for the gate but silent for the producer — so the schema rejects every C0
  control character here, where the producer still finds out. Absolute paths and
  `..` segments are rejected for the same reason: git never reports either, so
  such an entry could only ever match nothing while looking like coverage.

* `base_commit` is expressible and deliberately inert. task-8 reads it and
  derives no freshness rule, because HEAD legitimately advances mid-session —
  /v:triage's own commit of the record moves it — so a mismatch is not evidence
  of staleness. The description says so, and says not to add such a rule without
  evidence that a mismatch correlates with a bad decision.

* `tier` is added and PINNED to `decision` by three conditionals. The hook
  prefers `.tier` over `.decision` when present, so an unconstrained `tier` would
  be a second, higher-priority source of truth for a safety-relevant
  classification: a record could say FULL_PIPELINE and wear `tier: DIRECT` and be
  exempted as the auto-route class. Pinned, the hook's preferred branch is
  provably identical to its fallback instead of a way around it. This is the same
  hazard as override #4 one layer up, and it gets the same answer — make the
  disagreement unrepresentable rather than trusted.

* `build_record` gains an optional `binding` kwarg, and it is a footgun removal
  rather than a convenience. `digest` covers the whole record, so a producer that
  attached these fields after building would ship a record whose self-integrity
  digest silently no longer verifies — silently, because `digest` is optional and
  checked only when present. The kwarg folds the binding in before the digest is
  taken. It does NOT accept `tier`: that is derived from the decision, so the
  producer cannot introduce the disagreement the schema forbids. Without a
  binding the record is byte-for-byte and digest-for-digest what it was.

Verified against the consumer, not just asserted: the hook's own `_TRIAGE_JQ`
was extracted verbatim and run over records built to this schema. All three
decisions map to DIRECT/SCOPED/FULL, a record carrying explicit `tier` produces
output identical to its decision-only twin, and a foreign-session record emits
nothing.

Selftests: preeval 131 -> 174 cases. Covers tier agreement and disagreement for
all three decisions, session_id null/absent/empty, base_commit shapes, the three
declared-path forms the gate understands, twelve rejected path shapes including
the separator and line breaks it would otherwise drop, and the digest staying
correct through build_record while breaking when bolted on afterwards.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: copeus

schemas/pre-eval-record.schema.json

@@ -44,6 +44,36 @@
         "properties": { "decision": { "const": "FULL_PIPELINE" } },
         "required": ["decision"]
       }
+    },
+    {
+      "if": {
+        "properties": { "decision": { "const": "FASTPATH_ELIGIBLE" } },
+        "required": ["decision", "tier"]
+      },
+      "then": {
+        "description": "Tier agreement: `tier` is a readability alias for `decision`, never an independent claim. The triage gate prefers `tier`, so a disagreement would let a record be exempted as a tier its own decision refuses.",
+        "properties": { "tier": { "const": "DIRECT" } }
+      }
+    },
+    {
+      "if": {
+        "properties": { "decision": { "const": "SCOPED_PIPELINE" } },
+        "required": ["decision", "tier"]
+      },
+      "then": {
+        "description": "Tier agreement - see the FASTPATH_ELIGIBLE case above.",
+        "properties": { "tier": { "const": "SCOPED" } }
+      }
+    },
+    {
+      "if": {
+        "properties": { "decision": { "const": "FULL_PIPELINE" } },
+        "required": ["decision", "tier"]
+      },
+      "then": {
+        "description": "Tier agreement - see the FASTPATH_ELIGIBLE case above. This is the case that matters most: a FULL record wearing `tier: DIRECT` would be exempted by the triage gate as if it were the auto-route class.",
+        "properties": { "tier": { "const": "FULL" } }
+      }
     }
   ],
   "properties": {
@@ -99,6 +129,29 @@
       "enum": ["FASTPATH_ELIGIBLE", "SCOPED_PIPELINE", "FULL_PIPELINE"],
       "description": "The triage outcome, one of THREE proportionate tiers (v3.0 spec §A1). FASTPATH_ELIGIBLE = tier DIRECT (implement in place, run the floor, commit on the branch — no manifest, no run dir); SCOPED_PIPELINE = tier SCOPED (manifest, run dir, scope gate, floor, one combined SPEC+QUALITY review; recon and the three pre-flights skipped); FULL_PIPELINE = tier FULL (the whole pipeline). The value is produced by the 3x3 difficulty×impact matrix INSIDE compound-v-preeval.py's `score`, and consumers MUST branch on all three values explicitly — a `== FASTPATH_ELIGIBLE ? A : B` reader is a two-value reader of a three-value enum. Iron-Invariant #4 AS AMENDED (spec §A4): the score OFFERS by default and auto-routes only inside the DIRECT auto-route class, whose membership is decided by mechanically checkable predicates and never by model judgement; every other tier still requires a human offer and acceptance. Any override / unknown axis / missing-or-malformed taxonomy / token-cap overrun ⇒ FULL_PIPELINE (fail-closed), and a non-null `override_fired` ALWAYS pairs with FULL_PIPELINE regardless of the recorded bands."
     },
+    "tier": {
+      "type": "string",
+      "enum": ["DIRECT", "SCOPED", "FULL"],
+      "description": "OPTIONAL, and REDUNDANT BY CONSTRUCTION: the manifest-vocabulary token for `decision` (FASTPATH_ELIGIBLE=DIRECT, SCOPED_PIPELINE=SCOPED, FULL_PIPELINE=FULL - compound-v-preeval.py's DECISION_TO_TIER). The triage gate in `hooks/epic-goal-stop.sh` PREFERS this field over `decision` when it is present, so an unconstrained `tier` would be a second, higher-priority source of truth for a safety-relevant classification: a record could say `decision: FULL_PIPELINE` and `tier: DIRECT` and be exempted as DIRECT. The three tier-agreement conditionals in the top-level `allOf` therefore PIN it to `decision`, which makes the hook's preferred branch provably identical to its fallback rather than a way around it. Carry it for human readability; never as an independent claim. `decision` remains the authority.",
+      "$comment": "Pinned to `decision` by the tier-agreement conditionals in the top-level allOf."
+    },
+    "session_id": {
+      "type": ["string", "null"],
+      "minLength": 1,
+      "description": "The harness session this record was written in - the value on the `Stop` hook's stdin payload, compared EXACTLY by the triage gate in `hooks/epic-goal-stop.sh`. Written by `/v:triage`, the only component that knows it: the scoring engine never sees a session, so a record produced by `compound-v-preeval.py` alone omits this field. ABSENT OR NULL MEANS THE RECORD BINDS NO SESSION AND THEREFORE COVERS NOTHING - the gate's exact-match test cannot succeed against an empty value, which is the fail-closed direction. Never required: requiring it would invalidate every record the engine writes outside a triage command.",
+      "$comment": "minLength applies only to the string form; null passes. The empty string is rejected because it asserts a session binding that can never match."
+    },
+    "base_commit": {
+      "type": ["string", "null"],
+      "pattern": "^[0-9a-f]{7,40}$",
+      "description": "The commit HEAD pointed at when this record was written. RECORDED, NOT DECISIVE: `hooks/epic-goal-stop.sh` reads it and deliberately derives NO freshness rule from it, because HEAD legitimately advances mid-session - any commit moves it, including /v:triage's own commit of this very record - so a mismatch is not evidence that the record is stale. The field exists so a human or a later audit can say which tree the classification was made against. Do not add a staleness check keyed on it without evidence that a mismatch actually correlates with a bad decision. (`pattern` applies only when the value is a string, so null passes.)"
+    },
+    "declared_paths": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/declared_path" },
+      "description": "The repo-relative paths this record's classification actually covers - the field that turns the triage gate from an existence check into a COVERAGE check. `hooks/epic-goal-stop.sh` exempts a changed path only when the record is for the same session AND the path lies inside this set; without it, one triage of 'change the README' would exempt an unrelated later edit to that hook itself. COVERAGE IS THE THREE-WAY MATCH THAT HOOK IMPLEMENTS, and it is deliberately narrow: an exact string match, a DIRECTORY PREFIX only when the entry ends in `/`, or a glob only when the entry contains `*`. A bare `scripts` does NOT cover `scripts/app.py` - write `scripts/` or `scripts/**`. Widening a declared set by accident is the one direction this must not fail in, which is also why the item constraints reject what the hook would otherwise silently drop. Written by `/v:triage`; usually the localization's `resolved_paths`, but kept a separate field because a record may legitimately declare a broader set than triage resolved."
+    },
     "min_sample_status": {
       "type": "string",
       "enum": ["insufficient", "calibrated"],
@@ -111,10 +164,17 @@
     "digest": {
       "type": "string",
       "pattern": "^sha256:[0-9a-f]{64}$",
-      "description": "Self-integrity digest of THIS record: 'sha256:'+sha256(canonical_json(record without `digest`)). Optional; when present, downstream verifies it with compound-v-taxonomy.record_digest(record, exclude_field='digest')."
+      "description": "Self-integrity digest of THIS record: 'sha256:'+sha256(canonical_json(record without `digest`)). Optional; when present, downstream verifies it with compound-v-taxonomy.record_digest(record, exclude_field='digest'). IT COVERS EVERY OTHER FIELD, the Feature-C binding (`session_id`, `base_commit`, `declared_paths`, `tier`) included. A producer that attaches the binding AFTER building the record ships one whose digest no longer verifies, and does so silently because this field is optional and only checked when present. Pass the binding to compound-v-preeval.py `build_record(..., binding={...})`, which folds it in before the digest is taken."
     }
   },
   "$defs": {
+    "declared_path": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[^/\u0000-\u001f][^\u0000-\u001f]*$",
+      "not": { "pattern": "(^|/)\\.\\.(/|$)" },
+      "description": "One entry in `declared_paths`: a repo-relative path, a directory prefix (trailing `/`), or a glob (containing `*`). CONSTRAINED TO MATCH WHAT THE CONSUMER CAN ACTUALLY READ. `hooks/epic-goal-stop.sh` serializes candidates as `tierU+001Frun_idU+001Fpath` lines and DROPS any entry containing U+001F, LF or CR, because a re-escaped path would no longer equal the path git reports. Dropping narrows the declared set, which is the safe direction for the hook but silent for the producer - so this pattern rejects every C0 control character here, where the producer still learns. A leading `/` is rejected because paths are repo-relative and git never reports an absolute one, so such an entry could only ever match nothing while looking like coverage. `..` segments are rejected because an entry that escapes the repo cannot describe a changed path, and normalizing it here would create a second path semantics to keep in sync with the gate's."
+    },
     "band": {
       "type": "string",
       "enum": ["low", "medium", "high", "unknown"],

scripts/compound-v-preeval.py

@@ -701,9 +701,29 @@ def write_taxonomy_snapshot(repo, pre_eval_id, taxonomy_bytes):
 
 
 def build_record(pre_eval_id, request, verdict, localization, taxonomy_version,
-                 taxonomy_ref, taxonomy_digest, ts=None):
+                 taxonomy_ref, taxonomy_digest, ts=None, binding=None):
     """Assemble the write-once pre-eval RECORD (conforms to pre-eval-record.schema.json).
-    `status: PRE_EVAL_DONE` is a RECORD field, not a state.json phase (AC-7/CR2-8)."""
+    `status: PRE_EVAL_DONE` is a RECORD field, not a state.json phase (AC-7/CR2-8).
+
+    binding: the OPTIONAL Feature-C coverage binding (spec §C) — a dict with any of
+        `session_id`, `base_commit`, `declared_paths`. It is what lets the triage gate in
+        `hooks/epic-goal-stop.sh` decide whether this record COVERS the current diff, and
+        only `/v:triage` can supply it: this engine never sees a session. Absent (the
+        default, and every call this module makes) the record is byte-for-byte what it was
+        before v3.0 — no binding keys, and an identical `digest`.
+
+        THE KWARG EXISTS TO REMOVE A FOOTGUN, not merely as a convenience. `digest` is
+        computed over the whole record, so a producer that called `build_record` and THEN
+        attached the binding fields would ship a record whose self-integrity digest no
+        longer verifies — silently, because `digest` is optional and only checked when
+        present. Passing the binding through here keeps the digest correct by construction.
+
+        `tier` is NOT accepted from the caller. It is DERIVED from the decision via
+        DECISION_TO_TIER whenever a binding is supplied, because the triage gate prefers
+        `tier` over `decision`: accepting it as an argument would let a producer hand the
+        gate a tier the record's own decision refuses. The schema pins the two together as
+        well, so the disagreement is unrepresentable on both sides of the boundary.
+    """
     tax = _tax()
     rec = {
         "pre_eval_id": pre_eval_id,
@@ -723,6 +743,18 @@ def build_record(pre_eval_id, request, verdict, localization, taxonomy_version,
         "min_sample_status": verdict["min_sample_status"],
         "confidence": _evidence_confidence(verdict, localization),
     }
+
+    # Feature C coverage binding — added BEFORE the digest, never after (see the docstring).
+    # Each key is emitted only when the caller supplied it, so an unbound record keeps its
+    # pre-3.0 bytes exactly. `tier` rides along derived, never supplied.
+    if binding:
+        for _k in ("session_id", "base_commit", "declared_paths"):
+            if binding.get(_k) is not None:
+                rec[_k] = binding[_k]
+        _tier = DECISION_TO_TIER.get(verdict["decision"])
+        if _tier is not None:
+            rec["tier"] = _tier
+
     rec["digest"] = tax.record_digest(rec, exclude_field="digest")
     return rec
 
@@ -1559,6 +1591,114 @@ def fake_localize_factory(result):
         _schema_check(expect, _null_tax_full, must_validate=True,
                       label="schema ACCEPTS a null-taxonomy FULL_PIPELINE record")
 
+        # ===== (c5) The three fields Feature C's triage gate reads (spec §C) ========= #
+        # `hooks/epic-goal-stop.sh` decides whether a record COVERS the current diff by
+        # reading session_id, declared_paths and (for display) base_commit. The schema is
+        # additionalProperties:false, so until these exist NO record can carry them and NO
+        # record can ever cover a diff — the gate would ship inert. The engine does not
+        # produce them (it never sees a session); /v:triage does. What is tested here is
+        # that they are EXPRESSIBLE and CONSTRAINED, not that this module emits them.
+        _bound = dict(ress["record"],
+                      session_id="sess-abc123",
+                      base_commit="a1b2c3d4e5f60718293a4b5c6d7e8f9012345678",
+                      declared_paths=["scripts/app.py", "scripts/", "docs/**"],
+                      tier="SCOPED")
+        _schema_check(expect, _bound, must_validate=True,
+                      label="schema ACCEPTS session_id + base_commit + declared_paths + tier")
+
+        # `tier` is what the gate PREFERS over `decision`, so a disagreement would exempt a
+        # record as a tier its own decision refuses. Pinned for all three decisions.
+        for _dec, _good, _bad in ((DECISION_FASTPATH, "DIRECT", "FULL"),
+                                  (DECISION_SCOPED, "SCOPED", "DIRECT"),
+                                  (DECISION_FULL, "FULL", "DIRECT")):
+            _rec = dict(_bound, decision=_dec, tier=_good)
+            _schema_check(expect, _rec, must_validate=True,
+                          label="schema ACCEPTS tier %s beside %s" % (_good, _dec))
+            _schema_check(expect, dict(_rec, tier=_bad), must_validate=False,
+                          label="schema REJECTS tier %s beside %s" % (_bad, _dec))
+        # ...and `tier` stays optional: the gate falls back to mapping `decision`.
+        _no_tier = dict(_bound)
+        _no_tier.pop("tier")
+        _schema_check(expect, _no_tier, must_validate=True,
+                      label="schema ACCEPTS a record with no tier (gate maps decision)")
+
+        # session_id: null and absent both mean "binds no session", which the gate can only
+        # read as covering nothing. The EMPTY STRING is rejected — it looks like a binding
+        # and can never match, which is the one shape that misleads a reader.
+        _schema_check(expect, dict(_bound, session_id=None), must_validate=True,
+                      label="schema ACCEPTS session_id null (binds no session)")
+        _schema_check(expect, dict(_bound, session_id=""), must_validate=False,
+                      label="schema REJECTS an empty session_id")
+
+        # base_commit is recorded, not decisive — but it still has to be a commit.
+        _schema_check(expect, dict(_bound, base_commit=None), must_validate=True,
+                      label="schema ACCEPTS base_commit null")
+        _schema_check(expect, dict(_bound, base_commit="a1b2c3d"), must_validate=True,
+                      label="schema ACCEPTS a short base_commit sha")
+        for _badsha in ("HEAD", "A1B2C3D", "a1b2c3", "z" * 40, "a1b2c3d4 "):
+            _schema_check(expect, dict(_bound, base_commit=_badsha), must_validate=False,
+                          label="schema REJECTS base_commit %r" % (_badsha,))
+
+        # declared_paths: exactly the three forms the gate's `_path_covered` understands.
+        _schema_check(expect, dict(_bound, declared_paths=[]), must_validate=True,
+                      label="schema ACCEPTS an empty declared_paths (covers nothing)")
+        for _good_path in ("a.py", "scripts/app.py", "scripts/", "docs/**", "src/*.css"):
+            _schema_check(expect, dict(_bound, declared_paths=[_good_path]),
+                          must_validate=True,
+                          label="schema ACCEPTS declared path %r" % (_good_path,))
+        # The gate DROPS an entry carrying its own separator or a line break, which silently
+        # narrows the set. Rejecting here is where the producer still finds out.
+        for _bad_path in (chr(31) + "x", "a" + chr(31) + "b", "a\nb", "a\rb", chr(0) + "a",
+                          "", "/abs/path", "../escape", "a/../b", "..",
+                          "/", "\ttab"):
+            _schema_check(expect, dict(_bound, declared_paths=[_bad_path]),
+                          must_validate=False,
+                          label="schema REJECTS declared path %r" % (_bad_path,))
+        _schema_check(expect, dict(_bound, declared_paths=["a.py", "a.py"]),
+                      must_validate=False,
+                      label="schema REJECTS duplicate declared paths")
+        _schema_check(expect, dict(_bound, declared_paths="scripts/"), must_validate=False,
+                      label="schema REJECTS a bare-string declared_paths")
+
+        # ===== (c6) build_record's optional binding — the digest stays correct ======== #
+        # The producer is /v:triage, not this engine, but the PRIMITIVE lives here because
+        # `digest` covers the whole record: a producer that attached the binding AFTER
+        # calling build_record would ship a record whose self-integrity digest silently no
+        # longer verifies. Passing it through keeps that impossible.
+        _tax_mod = _tax()
+        _bv = score(_loc(["src/ui/Widget.tsx"], flags=[], fan_out=1), taxonomy)
+        _unbound = build_record("2026-07-12T101600Z-b-a1b2", "bind me", _bv,
+                                _loc(["src/ui/Widget.tsx"], flags=[], fan_out=1),
+                                1, "tax.yaml", "sha256:" + "0" * 64,
+                                ts="2026-07-12T10:16:00Z")
+        expect("build_record without a binding is unchanged (no binding keys)",
+               not any(k in _unbound for k in
+                       ("session_id", "base_commit", "declared_paths", "tier")))
+        _boundrec = build_record("2026-07-12T101600Z-b-a1b2", "bind me", _bv,
+                                 _loc(["src/ui/Widget.tsx"], flags=[], fan_out=1),
+                                 1, "tax.yaml", "sha256:" + "0" * 64,
+                                 ts="2026-07-12T10:16:00Z",
+                                 binding={"session_id": "sess-abc123",
+                                          "base_commit": "a1b2c3d4e5f6",
+                                          "declared_paths": ["src/ui/Widget.tsx"]})
+        expect("build_record carries the binding through",
+               _boundrec["session_id"] == "sess-abc123"
+               and _boundrec["base_commit"] == "a1b2c3d4e5f6"
+               and _boundrec["declared_paths"] == ["src/ui/Widget.tsx"])
+        expect("build_record DERIVES tier from the decision (never taken from the caller)",
+               _boundrec["tier"] == DECISION_TO_TIER[_bv["decision"]])
+        expect("the bound record's digest covers the binding and still verifies",
+               _boundrec["digest"] == _tax_mod.record_digest(_boundrec,
+                                                             exclude_field="digest")
+               and _boundrec["digest"] != _unbound["digest"])
+        _schema_check(expect, _boundrec, must_validate=True,
+                      label="a build_record-produced bound record validates")
+        # The footgun this prevents, demonstrated: bolt the fields on afterwards and the
+        # digest no longer verifies.
+        _bolted = dict(_unbound, session_id="sess-abc123")
+        expect("bolting a binding on AFTER build_record breaks the digest (why the kwarg)",
+               _bolted["digest"] != _tax_mod.record_digest(_bolted, exclude_field="digest"))
+
         # (d) needs_t3 end-to-end: NO record + NO predicted are written; artifacts durable.
         fk_need = fake_localize_factory(_loc(["tools/gen.py"], flags=[], fan_out=1))
         resn = run_preeval("do the mysterious thing", repo=repo, _localize=fk_need,