task-pipeline-skill 1.72.0 → 1.74.0

package/plugins/task-pipeline/skills/task-pipeline/scripts/graph.py

@@ -515,6 +515,139 @@ def verdict_violations(v):
     return out
 
 
+# --- certification: three tiers, one node ------------------------------------
+#
+# One verifier reads the diff it was handed. That is the whole limitation this
+# section exists for: a change can be correct where it was made, and wrong one
+# level out — a caller whose contract moved, a module whose invariant the new
+# branch breaks, a documented behaviour nobody re-read. The single verdict cannot
+# see any of it, because the context it was given was the change.
+#
+# So a node is closed by THREE reports at escalating visibility, produced
+# independently and blind to each other:
+#
+#   unit     the code that changed — the functions, classes and branches in the
+#            diff, and the node's own `check`
+#   seam     one level out — callers, callees, shared state, the contracts and
+#            tests of the neighbours the change can reach
+#   product  one level out again — the documentation, the scenarios, how this
+#            behaviour interacts with the rest of the product
+#
+# **All three must pass, and blind is the point.** Three agents that read each
+# other's reports are one opinion with three signatures; the disagreement is the
+# instrument. `certify` refuses a report that cites another tier's verdict.
+#
+# **A tier cannot pass on an empty `scope`.** This is the rule the rest is built
+# around: a report that names nothing it read is a rubber stamp, and a rubber
+# stamp at three levels is worse than one verifier, because it costs three times
+# as much and reads as three times the assurance.
+TIERS = ("unit", "seam", "product")
+TIER_KEYS = ("node", "tier", "verdict", "scope", "confirms", "findings",
+             "evidence", "not_examined")
+TIER_VERDICTS = ("pass", "fail")
+SEVERITIES = ("breaks", "risk")
+# A tier report that quotes another tier's verdict was not written blind. Cheap
+# to detect and worth detecting: the failure it prevents is three reports that
+# agree because the second two read the first.
+CROSS_TIER = re.compile(r"\b(?:unit|seam|product)\s+tier\s+(?:passed|failed|says)"
+                        r"|\btier\s+\d\s+(?:passed|failed)"
+                        r"|as\s+the\s+(?:unit|seam|product)\s+tier", re.I)
+
+
+def tier_violations(t):
+    """Everything wrong with one tier report, in a stable order.
+
+    Same law as `verdict_violations`: the shape is checked rather than trusted,
+    and every refusal names the key, because a report rejected without naming its
+    fault is a report the next attempt reproduces.
+    """
+    out = []
+    if not isinstance(t, dict):
+        return ["tier report is not an object"]
+
+    for k in TIER_KEYS:
+        if k not in t:
+            out.append("tier report has no `%s` — all eight are required, because a "
+                       "report that omits one is silent about it rather than clear" % k)
+    if out:
+        return out
+
+    if not isinstance(t["node"], str) or not t["node"].startswith(NODE_ID):
+        out.append("tier report `node` is %r, which is not a node id" % (t["node"],))
+    if t["tier"] not in TIERS:
+        out.append("tier report `tier` is %r — it must be one of %s"
+                   % (t["tier"], ", ".join(TIERS)))
+    if t["verdict"] not in TIER_VERDICTS:
+        out.append("tier report `verdict` is %r — it must be `pass` or `fail`, because "
+                   "a certification that admits a third state admits a maybe"
+                   % (t["verdict"],))
+
+    for k in ("scope", "confirms", "findings", "evidence", "not_examined"):
+        if not isinstance(t[k], list):
+            out.append("tier report `%s` must be a list" % k)
+    if out:
+        return out
+
+    for k in ("scope", "confirms", "evidence", "not_examined"):
+        for i, e in enumerate(t[k]):
+            if not isinstance(e, str) or not e.strip():
+                out.append("tier report `%s[%d]` is %r — every entry must be a non-empty "
+                           "string, and a list of blanks is the shape a script emitting "
+                           "empty output produces" % (k, i, e))
+
+    findings = []
+    for i, f in enumerate(t["findings"]):
+        if not isinstance(f, dict):
+            out.append("tier report `findings[%d]` is not an object" % i)
+            continue
+        for k in ("what", "where", "severity"):
+            if not str(f.get(k, "")).strip():
+                out.append("tier report `findings[%d]` does not say `%s`" % (i, k))
+        sev = f.get("severity")
+        if sev is not None and sev not in SEVERITIES:
+            out.append("tier report `findings[%d].severity` is %r — it must be `breaks` "
+                       "(the node is not done) or `risk` (found, judged survivable, and "
+                       "named)" % (i, sev))
+        # A break has to say how its fix will be PROVEN, for the same reason
+        # `replan.add` does: the node it creates is one the next certification has
+        # to close, and handing it the absence is how the defect returns a round
+        # later.
+        if sev == "breaks" and not str(f.get("check", "")).strip():
+            out.append("tier report `findings[%d]` breaks the node and names no `check` "
+                       "— the fix node it becomes has to say how IT will be closed" % i)
+        findings.append(f)
+
+    breaks = [f for f in findings if isinstance(f, dict) and f.get("severity") == "breaks"]
+    if t["verdict"] == "pass":
+        # The two rules that make a pass mean something.
+        if not t["scope"]:
+            out.append("tier report `%s` passes on an empty `scope` — a report that names "
+                       "nothing it read is a rubber stamp, and three of those cost three "
+                       "times one verifier and read as three times the assurance"
+                       % t["tier"])
+        if not t["evidence"]:
+            out.append("tier report `%s` passes with empty `evidence` — the field exists "
+                       "for exactly this" % t["tier"])
+        if breaks:
+            out.append("tier report `%s` passes while carrying %d finding(s) at severity "
+                       "`breaks`: %s. Those two cannot both be true"
+                       % (t["tier"], len(breaks),
+                          "; ".join(str(f.get("what")) for f in breaks)))
+    elif t["verdict"] == "fail":
+        if not breaks:
+            out.append("tier report `%s` fails and names no finding at severity `breaks` "
+                       "— a fail that does not say what broke is a fail the next round "
+                       "cannot act on" % t["tier"])
+
+    # Blind, and checked. Only the prose fields can carry it.
+    for k in ("confirms", "evidence", "not_examined"):
+        for i, e in enumerate(t[k]):
+            if isinstance(e, str) and CROSS_TIER.search(e):
+                out.append("tier report `%s[%d]` cites another tier's verdict (%r) — the "
+                           "three run blind, because three reports that read each other "
+                           "are one opinion with three signatures" % (k, i, e.strip()[:70]))
+    return out
+
 # --- verbs --------------------------------------------------------------------
 
 def cmd_validate(graph, args):
@@ -909,13 +1042,21 @@ def cmd_producer(graph, args):
 def cmd_doctrine(graph, args):
     """Which doctrine this run actually read — B-061.
 
-    The bundle is 34 reference files. A run reads some subset and nothing recorded which,
+    The bundle is 36 reference files. A run reads some subset and nothing recorded which,
     so **a skipped file and a read one were indistinguishable** — the class every guard in
     this repository exists to catch, left standing over the doctrine itself.
 
-    `read:` lines in the run ledger are written by a hook, never by the agent, for the same
-    reason `gate:` is: a claim about what somebody read, written by the party the claim is
-    about, is not evidence.
+    `read:` lines are written by a hook rather than by the agent, for the same reason `gate:`
+    is: a claim about what somebody read, written by the party the claim is about, is not
+    evidence.
+
+    **And that is an intent, not a proof, so every line here is reported as UNATTESTED.**
+    The ledger is `.task-pipeline/run.md` — the file the agent appends to at every stage —
+    so nothing in it distinguishes a hook-written line from one an agent typed. The doctrine
+    said *hook-written, never agent-written*, which is a provenance claim this script cannot
+    check and no format here carries; B-014's class, committed by the mechanism built to
+    close it. Until the ledger can attest a writer, the honest output is the count plus the
+    word: read as *this is what the ledger says, and the ledger cannot say who wrote it*.
 
     **The one rule that matters here: no `read:` lines means UNMEASURED, never «read
     nothing».** Zero would be the reassuring answer to a question nobody asked, and this
@@ -958,7 +1099,10 @@ def cmd_doctrine(graph, args):
         return 0
 
     unread = [r for r in refs if r not in read]
-    print(f"doctrine: {len(read)} of {len(refs)} reference files read")
+    print(f"doctrine: {len(read)} of {len(refs)} reference files read — unattested")
+    print("          unattested: the ledger is the file the agent appends to at every stage, "
+          "so nothing in it proves the hook wrote these lines rather than an agent. The "
+          "count is what the ledger says; who wrote it is not recorded.")
     print("          a disclosure: no floor, no direction, never a target. A run that needs "
           "four files and reads four is not worse than one that reads thirty.")
     for r in unread:
@@ -966,6 +1110,170 @@ def cmd_doctrine(graph, args):
     return 0
 
 
+def cmd_certify(graph, args):
+    """Require three independent tier reports, then emit the verdict `close` consumes.
+
+    This is a gate in FRONT of `close`, not a replacement for it. `close`'s contract
+    is unchanged and its seven keys are still the only thing that moves the graph —
+    what changed is that the verdict is now assembled from three readings at
+    different distances instead of written from one.
+
+    **The round is recorded whether it passes or fails.** A failing round that
+    wrote nothing would erase the only evidence that a node is churning, which is
+    the number the ceiling below reads. The node stays `pending` on a failure; the
+    round count is the trail.
+
+    **The ceiling measures rather than stops** — `references/loop-guard.md`. At the
+    ceiling `certify` still runs and still tells the truth about the tiers; what it
+    adds is the name of the tier that keeps failing, because a run spinning on one
+    level needs the operator to see WHICH level, not to be halted.
+    """
+    guard(graph, args.graph)
+
+    nid = args.node
+    by_id = {n.get("id"): n for n in graph.get("nodes") or []}
+    node = by_id.get(nid)
+    if node is None:
+        die("no node %s in this graph — nothing was written" % nid)
+    if node.get("status") in TERMINAL:
+        die("%s is already %s — certifying it again would overwrite the record of the "
+            "close that already happened" % (nid, node.get("status")))
+    open_blockers = [b for b in node.get("blocked_by") or []
+                     if by_id.get(b, {}).get("status") not in TERMINAL]
+    if open_blockers:
+        die("%s waits on %s, which %s not closed — certifying work that could not have "
+            "run certifies nothing" % (nid, ", ".join(open_blockers),
+                                       "is" if len(open_blockers) == 1 else "are"))
+
+    reports, bad = {}, []
+    for path in args.tier:
+        try:
+            with open(path, encoding="utf-8") as fh:
+                t = json.load(fh)
+        except OSError as e:
+            die("cannot read the tier report at %s — %s" % (path, e), 2)
+        except ValueError as e:
+            die("%s: not readable as JSON — %s" % (path, e))
+        v = tier_violations(t)
+        if v:
+            bad += ["%s: %s" % (os.path.basename(path), line) for line in v]
+            continue
+        if t["node"] != nid:
+            bad.append("%s: reports on %s while this certification is for %s — a report "
+                       "about another node is not evidence about this one"
+                       % (os.path.basename(path), t["node"], nid))
+            continue
+        if t["tier"] in reports:
+            bad.append("%s: a second `%s` report — the three tiers are three distances, "
+                       "and two readings at one distance leave another unread"
+                       % (os.path.basename(path), t["tier"]))
+            continue
+        reports[t["tier"]] = t
+    if bad:
+        die("the tier reports are malformed — nothing was written:\n  " + "\n  ".join(bad))
+
+    missing = [x for x in TIERS if x not in reports]
+    if missing:
+        die("certification is missing the %s report(s) — all three are required, because "
+            "the level nobody read is the level the defect survives at"
+            % ", ".join("`%s`" % m for m in missing))
+
+    # The stamp, read here and never accepted from a report — same law as `close`.
+    import subprocess
+    try:
+        r = subprocess.run(["git", "rev-parse", "HEAD"], capture_output=True, text=True)
+        head = r.stdout.strip() if r.returncode == 0 else ""
+    except OSError:
+        head = ""
+
+    prior = node.get("certification") or {}
+    round_no = int(prior.get("round") or 0) + 1
+    tiers_now = {x: reports[x]["verdict"] for x in TIERS}
+    history = list(prior.get("history") or []) + [tiers_now]
+    node["certification"] = {
+        "round": round_no,
+        "tiers": tiers_now,
+        "at": head or "unavailable — not inside a git checkout",
+        "history": history,
+    }
+
+    failed = [x for x in TIERS if tiers_now[x] == "fail"]
+
+    # Churn, measured. A tier that has failed in every round so far is the one the
+    # operator needs named; counting it here is what makes the loop visible.
+    churning = [x for x in TIERS
+                if len(history) >= 2 and all(h.get(x) == "fail" for h in history)]
+
+    save(args.graph, graph)
+
+    if failed:
+        print("%s: certification round %d FAILED at %s"
+              % (nid, round_no, ", ".join("`%s`" % f for f in failed)), file=sys.stderr)
+        for tier in failed:
+            for f in reports[tier]["findings"]:
+                if f.get("severity") != "breaks":
+                    continue
+                print("  [%s] %s — %s" % (tier, f["where"], f["what"]), file=sys.stderr)
+                print("      fix:   %s" % f.get("fix", "(not stated)"), file=sys.stderr)
+                print("      check: %s" % f["check"], file=sys.stderr)
+        if round_no >= args.ceiling:
+            print("\n%s has been certified %d time(s), at or over the ceiling of %d."
+                  % (nid, round_no, args.ceiling), file=sys.stderr)
+            if churning:
+                print("The same tier has failed every round: %s. That is not a fix "
+                      "away — the level itself is being misread, or the node is the "
+                      "wrong shape. references/loop-guard.md."
+                      % ", ".join("`%s`" % c for c in churning), file=sys.stderr)
+            else:
+                print("No single tier is failing every round, so this is churn across "
+                      "levels rather than one stuck level.", file=sys.stderr)
+        print("\nThe node stays open. Round %d is recorded on it." % round_no,
+              file=sys.stderr)
+        return 1
+
+    # Passed at all three. Assemble the canonical verdict.
+    #
+    # The mapping is deliberate and uses no field for something it does not mean:
+    #   confirms      -> done          (asked for, and now true)
+    #   not_examined  -> not_verified  (present, and no check touched it)
+    #   risk findings -> blockers      (found, judged survivable, and named, which is
+    #                                   exactly what `can_continue_around: true` says)
+    verdict = {
+        "node": nid,
+        "done": [c for x in TIERS for c in reports[x]["confirms"]],
+        "not_done": [],
+        "not_verified": ["%s: %s" % (x, n)
+                         for x in TIERS for n in reports[x]["not_examined"]],
+        "blockers": [
+            {"what": "%s (%s, found by the `%s` tier)" % (f["what"], f["where"], x),
+             "blocks": [], "can_continue_around": True}
+            for x in TIERS for f in reports[x]["findings"]
+            if f.get("severity") == "risk"
+        ],
+        "replan": {"possible": True, "add": [], "park": [],
+                   "why": "certified at all three tiers in round %d" % round_no},
+        "evidence": ["%s: %s" % (x, e) for x in TIERS for e in reports[x]["evidence"]],
+    }
+    # Checked against the same gate `close` will apply, HERE, so a certification
+    # cannot hand the run a verdict its own consumer refuses.
+    broken = verdict_violations(verdict)
+    if broken:
+        die("all three tiers passed and the assembled verdict is still malformed — this "
+            "is a defect in `certify`, not in the reports:\n  " + "\n  ".join(broken))
+
+    out = args.verdict_out or os.path.join(os.path.dirname(args.graph) or ".",
+                                          "verdict-%s.json" % nid)
+    tmp = out + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as fh:
+        json.dump(verdict, fh, indent=2, ensure_ascii=False)
+        fh.write("\n")
+    os.replace(tmp, out)
+    print("%s: certified at unit, seam and product in round %d" % (nid, round_no))
+    print("verdict written to %s — close it with:" % out)
+    print("  graph.py close --verdict %s" % out)
+    return 0
+
+
 def cmd_close(graph, args):
     """Consume a verdict, close one node, and re-plan — T-5, REQ-007.
 
@@ -1094,6 +1402,8 @@ VERBS = {
     "coverage": (cmd_coverage, "every requirement and the nodes serving it; exits 1 on a gap"),
     "add": (cmd_add, "add a node mid-run"),
     "park": (cmd_park, "park a node, carrying the reason"),
+    "certify": (cmd_certify, "require three independent tier reports, then emit "
+                             "the verdict `close` consumes"),
     "close": (cmd_close, "consume a verdict, close one node and re-plan"),
 }
 
@@ -1136,6 +1446,16 @@ def main(argv=None):
     made["close"].add_argument("--verdict", required=True,
                                help="path to the verifier's seven-key verdict JSON")
 
+    p_cert = made["certify"]
+    p_cert.add_argument("--node", required=True, help="the node being certified")
+    p_cert.add_argument("--tier", action="append", required=True, default=[],
+                        help="path to one tier report; pass three times, one per tier")
+    p_cert.add_argument("--verdict-out", dest="verdict_out", default=None,
+                        help="where to write the assembled verdict (default: beside the graph)")
+    p_cert.add_argument("--ceiling", type=int, default=3,
+                        help="rounds after which the output names the churning tier; it "
+                             "measures rather than stops (references/loop-guard.md)")
+
     p_park = made["park"]
     p_park.add_argument("node")
     # `required=True` makes the MISSING flag a usage error (exit 2). The empty and
@@ -1147,7 +1467,7 @@ def main(argv=None):
     verbs = {k: v[0] for k, v in VERBS.items()}
     if args.verb in NO_GRAPH:
         return verbs[args.verb](None, args)
-    if args.verb in ("add", "park", "close"):
+    if args.verb in ("add", "park", "close", "certify"):
         # The READ happens inside the lock too. Loading first and locking second is the
         # same lost update with an extra step: the stale copy is already in memory.
         with held(args.graph):

package/plugins/task-pipeline/skills/task-pipeline/templates/retro.md

@@ -31,7 +31,7 @@ has not fired in the last five run stamps, or in the last sixty days. At eleven
 rows, the oldest never-fired
 row goes — the cap is not negotiable, ranking is.
 
-## Recent log — entries from the last five run stamps (newest first)
+## Recent log — narrative entries, uncapped and queried rather than read (newest first)
 
 Older entries and every retirement **move** to `docs/evidence/retro/YYYY-QN.md`
 at the prune. Moving is not deleting: the archive is append-only and holds the

package/plugins/task-pipeline/skills/task-pipeline/templates/run.md

@@ -20,23 +20,35 @@ Run: `<topic>` · started `<YYYY-MM-DD>` · module map: `<path or "none">`
 
 ## `read:` — which doctrine this run actually opened
 
-The bundle is 34 reference files and nothing recorded which of them a run read, so **a
+The bundle is 36 reference files and nothing recorded which of them a run read, so **a
 skipped file and a read one were indistinguishable** — the class every guard in this
 pipeline exists to catch, left standing over the doctrine itself.
 
-`read:` is **hook-written, never agent-written**, for the same reason `gate:` is: a claim
-about what somebody read, written by the party the claim is about, is not evidence. The
+`read:` is **written by a hook rather than by the agent**, for the same reason `gate:` is: a
+claim about what somebody read, written by the party the claim is about, is not evidence. The
 hook is in `hooks.example.json`, matches `Read`, records the path only
 when it is inside the bundle's `references/`, deduplicates, and **always exits 0** — a hook
 that can fail a `Read` would break every turn in every session.
 
+**That is an intent, not a proof, and the line says so.** This file is the one the agent
+appends to at every stage, so nothing in it distinguishes a hook-written line from one an
+agent typed: there is no writer field, and `scripts/graph.py` has no provenance check
+because the format gives it nothing to check. The doctrine here said *hook-written, never
+agent-written* until 2026-08-20 — a provenance claim in the file whose whole subject is that
+a claim by the interested party is not evidence, which is B-014's class committed by the
+mechanism built to close it. So `doctrine` and the `gate:` reader both report **`unattested`**
+beside their counts, and the two claims that survive are the ones the ledger can support:
+*this line is in the ledger*, and *nobody recorded who wrote it*. Attesting a writer needs a
+field this format does not have; inventing one that an agent can also fill would restate the
+same claim one level down.
+
 `scripts/graph.py doctrine` reads these lines and prints one of three things:
 
 | It prints | When | Why not just a number |
 |---|---|---|
 | `unmeasured — no run ledger` | there is no ledger | nothing to read from |
 | `unmeasured — the ledger carries no read: lines` | the hook is absent, **or** the run opened no doctrine | two opposite facts, and the ledger cannot separate them, so neither is claimed |
-| `N of 34 reference files read`, then each unread one | the hook is installed and fired | the count alone says there is a gap, not where |
+| `N of 36 reference files read — unattested`, then each unread one | the hook is installed and fired | the count alone says there is a gap, not where — and `unattested` says the ledger cannot name who wrote the lines |
 
 **It is a disclosure: no floor, no direction, never a target.** A run that needs four files
 and reads four is not worse than one that reads thirty — and the moment the number becomes
@@ -58,15 +70,17 @@ hand:  <N|10> — task "<quoted>" — done <n> — surfaced <n> — decisions <n
 holds: <stage id> — <n> (<class: what, owner>; … or "none") — enumerated <n>/8 classes, <unlooked: classes not enumerable>
 gate:  <stage id> — command "<cmd>" — exit <N> — <ISO-8601>
 event: <compact|session-end|subagent> — <detail> — <ISO-8601>
-read:  references/<file>.md            # hook-written, deduplicated, one per file opened
+read:  references/<file>.md            # hook-appended, deduped, UNATTESTED (no writer field)
 ```
 
 - **`stage:`** — written when a gate **returns**, not when the stage is entered. The
   rail's `✓` is derived from this line and from nothing else; a glyph set from memory
   is a summary that is confidently wrong exactly when it matters.
-- **`gate:`** — written by `hooks/gate-observer.sh`, never by an agent. It is the
-  only line here that records what a command **did** rather than what somebody
-  concluded: the exit code of the stage's declared `gate.command`, observed. The
+- **`gate:`** — appended by `hooks/gate-observer.sh` rather than by an agent, and
+  **unattested** for the reason `read:` is: this file is agent-written at every stage
+  and carries no writer field, so the line's provenance is an intent the format cannot
+  prove. It is the only line here that records what a command **did** rather than what
+  somebody concluded: the exit code of the stage's declared `gate.command`, observed. The
   `stage:` line above it is the agent's claim, and the release gate requires the
   two to agree — without this, a gate reads a claim written by the party it
   constrains and confirms an assertion with itself. Absent where the project

package/plugins/task-pipeline/skills/task-pipeline/templates/verification.md

@@ -41,6 +41,7 @@ worse than saying nothing.
 ## Contents
 
 - [Staleness — a row is true about the tree it OBSERVED](#staleness--a-row-is-true-about-the-tree-it-observed)
+- [Environment — a proof is only valid where it ran](#environment--a-proof-is-only-valid-where-it-ran)
 - the ledger itself — one row per REQ, appended by stage 8
 - [What `Human` means, and what it does not](#what-human-means-and-what-it-does-not)
 
@@ -71,11 +72,39 @@ one. Four things overtake a row, and naming which one applies is the note's job:
 change in what it covers, a **dependency** change, an **environment** change, and a
 **policy** change — the last being the rule under which the evidence was accepted.
 
-| REQ | What | Run | Shipped in | Observed at | Auto | Human | Note |
-|---|---|---|---|---|---|---|---|
-| REQ-001 | CSV export from a report | `2026-07-28-export` | v1.4.0 | `5f21ac3` | pass | 2026-07-30 | opened the deployed page, exported, opened the file |
-| REQ-004 | XLSX export | `2026-07-28-export` | v1.4.0 | `5f21ac3` | pass | **never** | — |
-| REQ-007 | Export respects active filters | `2026-07-28-export` | v1.4.0 | `5f21ac3` | partial | **never** | CSV path only |
+## Environment — a proof is only valid where it ran
+
+`Observed at` says which tree the check saw. It does not say **where**, and without that a
+smoke test against a preview URL enters the record in a shape indistinguishable from one
+against production, and a suite green on a laptop with accumulated state is
+indistinguishable from one green on a runner that started clean. Those are the two halves
+of the same question, and only one was instrumented.
+
+**`Environment` is a required cell on every row.** Its vocabulary is the project's own,
+declared in the runbook and not invented per row — this file ships with four, and a project
+that deploys differently declares different ones:
+
+| Value | What it means |
+|---|---|
+| `production` | the deployed target real users reach |
+| `preview` | a per-branch or per-PR deployment; proves the build, never the release |
+| `ci` | a clean runner, no accumulated state |
+| `local` | a developer machine, with whatever state it has |
+| `—` | **recorded absence** — a row written before this column existed, or one whose environment nobody recorded. Not a value, and never a default to reach for |
+
+A missing cell is not the same as `—`: the first is a row that forgot the question, and it is
+**refused**. The second is an answer.
+
+**A REQ claiming production behaviour may not be closed on a non-production
+observation.** Stage 8 writes the row and refuses that pairing rather than recording it —
+`pass` in `ci` against a requirement about the deployed product is the exact substitution
+this column exists to make visible.
+
+| REQ | What | Run | Shipped in | Observed at | Environment | Auto | Human | Note |
+|---|---|---|---|---|---|---|---|---|
+| REQ-001 | CSV export from a report | `2026-07-28-export` | v1.4.0 | `5f21ac3` | production | pass | 2026-07-30 | opened the deployed page, exported, opened the file |
+| REQ-004 | XLSX export | `2026-07-28-export` | v1.4.0 | `5f21ac3` | ci | pass | **never** | — |
+| REQ-007 | Export respects active filters | `2026-07-28-export` | v1.4.0 | `5f21ac3` | preview | partial | **never** | CSV path only |
 
 ## Columns
 
@@ -86,6 +115,10 @@ change in what it covers, a **dependency** change, an **environment** change, an
 - **Run** — the brief's topic slug, so the context is one file away.
 - **Shipped in** — the tag or commit that carried it. Where a project does not tag,
   the commit, and the same value every row of that run carries.
+- **Observed at** — the commit the check ran against. `—` where nobody recorded one.
+- **Environment** — where it ran, from the project's declared vocabulary. Required; `—` is
+  the recorded absence and an omitted cell is refused. See *Environment — a proof is only
+  valid where it ran*.
 - **Auto** — what the run's own gate said: `pass` · `partial` · `none`. Copied from the
   coverage table rather than re-derived; where the two disagree the coverage table wins
   and the disagreement is a finding. A coverage verdict of **`review`** — *no check can