From 03d9de81d9a4b4580fd32a92b429f79cd09208fa Mon Sep 17 00:00:00 2001
From: Tri Lam <tri@maydow.com>
Date: Mon, 1 Jun 2026 15:03:42 -0700
Subject: [PATCH] refactor(cut-criteria): unify 3 bash scripts into one Python
 module
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace `scripts/cut-criteria-{status,render,status_test}.sh` with a
single `scripts/cut_criteria.py` exposing `status`, `render`, `check`,
and `test` subcommands. Output is byte-identical for the same YAML +
repo state (the only deliberate diff is the script-name reference line
in the rendered legend).

Drops:
- The base64-over-TSV plumbing in cut-criteria-status.sh. It existed
  only to survive embedded newlines through a bash `read` loop, a
  macOS-3.2 compat tax. subprocess.run(snippet, shell=True) passes
  multi-line YAML block scalars to /bin/bash directly, no encoding
  hop. A regression fixture (`multiline-shell-no-base64`) locks this
  in: a future refactor that reintroduces a TSV/base64 round-trip
  without honoring newlines goes red.
- The per-shell-invocation Python heredocs in render.sh (196 LOC) and
  status.sh (75 LOC). Three Makefile shell-outs to one module now
  replace three bash scripts that each shelled out to python3.
- The separate `*_test.sh` test harness (160 LOC). The fixture suite
  is now a `cut_criteria.py test` subcommand using the same in-process
  status_rows() the production path uses.

Adds (per issue ask):
- YAML schema validation at parse time (required keys, allowed tiers,
  duplicate-id check) — surfaces malformed spec at `make
  cut-criteria-status` instead of producing a quietly-wrong markdown.
- `check` subcommand that renders in-process and diffs against the
  on-disk markdown; no `mktemp`/`diff -u`/`rm -f` choreography. The
  Makefile target collapsed from 11 lines to 1.

Closes #386.

Signed-off-by: Tri Lam <tri@maydow.com>
---
 Makefile                            |  17 +-
 docs/cut-criteria.yaml              |   2 +-
 docs/cut-criteria.yaml.md           |  20 +-
 docs/v1-rc1-cut-criteria.md         |   2 +-
 scripts/cut-criteria-render.sh      | 240 -----------
 scripts/cut-criteria-status.sh      | 122 ------
 scripts/cut-criteria-status_test.sh | 160 -------
 scripts/cut_criteria.py             | 642 ++++++++++++++++++++++++++++
 8 files changed, 660 insertions(+), 545 deletions(-)
 delete mode 100755 scripts/cut-criteria-render.sh
 delete mode 100755 scripts/cut-criteria-status.sh
 delete mode 100755 scripts/cut-criteria-status_test.sh
 create mode 100755 scripts/cut_criteria.py

diff --git a/Makefile b/Makefile
index 9bcccd2b..436aeea5 100644
--- a/Makefile
+++ b/Makefile
@@ -223,25 +223,16 @@ deprecation-check:  ## Enforce the deprecation policy at docs/DEPRECATION.md (v1
 	@bash scripts/deprecation-check.sh
 
 cut-criteria-status:  ## Compute the live status of every v1.0-rc1 cut criterion from docs/cut-criteria.yaml. Prints `id\tstatus\ttitle` per row; read-only, never gates.
-	@bash scripts/cut-criteria-status.sh
+	@python3 scripts/cut_criteria.py status
 
 cut-criteria-render:  ## Regenerate docs/v1-rc1-cut-criteria.md from docs/cut-criteria.yaml. Source of truth is the YAML; the markdown is rendered.
-	@bash scripts/cut-criteria-render.sh
+	@python3 scripts/cut_criteria.py render
 
 cut-criteria-check:  ## Drift gate: rendered docs/v1-rc1-cut-criteria.md must match what `make cut-criteria-render` would produce against the current docs/cut-criteria.yaml. Catches PRs that ship a criterion's artifact without re-rendering.
-	@# Render to a tempfile and diff against the on-disk copy. Both
+	@# Renders in-process and diffs against the on-disk copy. Both
 	@# the YAML source and the live repo state feed the render: a PR
 	@# that updates either without re-rendering trips this gate.
-	@tmp=$$(mktemp); \
-	bash scripts/cut-criteria-render.sh docs/cut-criteria.yaml "$$tmp" >/dev/null; \
-	if ! diff -u docs/v1-rc1-cut-criteria.md "$$tmp"; then \
-	  rm -f "$$tmp"; \
-	  echo ""; \
-	  echo "cut-criteria-check: docs/v1-rc1-cut-criteria.md is out of sync with docs/cut-criteria.yaml."; \
-	  echo "Run \`make cut-criteria-render\` and commit the result."; \
-	  exit 1; \
-	fi; \
-	rm -f "$$tmp"
+	@python3 scripts/cut_criteria.py check
 
 verify: check license-check generate-fixtures-check build-tags nccl-fr-rce-gate register-lint actionlint zizmor doc-check deprecation-check no-autoupdate-check  ## Pre-push gate. Medium (<30s); CI handles heavy gates (test, coverage, govulncheck, fuzz, build).
 
diff --git a/docs/cut-criteria.yaml b/docs/cut-criteria.yaml
index 609b8fd6..f34e323d 100644
--- a/docs/cut-criteria.yaml
+++ b/docs/cut-criteria.yaml
@@ -5,7 +5,7 @@
 # `docs/v1-rc1-cut-criteria.md`. CI fails any PR that lands a feature
 # without re-rendering, so the markdown can never drift from this spec.
 #
-# Status (☑ / ⧗ / ☐) is COMPUTED, not stored. `scripts/cut-criteria-status.sh`
+# Status (☑ / ⧗ / ☐) is COMPUTED, not stored. `scripts/cut_criteria.py status`
 # runs each criterion's `rubric_check.artifact_exists` (and optional
 # `rubric_check.gate_script`) against the live repo state and renders
 # the result inline. The per-PR ☐→☑ flip dance is gone: a PR that ships
diff --git a/docs/cut-criteria.yaml.md b/docs/cut-criteria.yaml.md
index 41df0542..a218c587 100644
--- a/docs/cut-criteria.yaml.md
+++ b/docs/cut-criteria.yaml.md
@@ -56,7 +56,7 @@ Inspirations:
 
 ## Status computation
 
-`scripts/cut-criteria-status.sh` runs each criterion's `rubric_check`
+`scripts/cut_criteria.py status` runs each criterion's `rubric_check`
 against the live repo. The decision table is:
 
 | artifact_exists | gate_script         | computed status |
@@ -100,8 +100,8 @@ but forgets to re-render the markdown will fail CI.
 |-------------------------------------------------|-----------------------------------|
 | Rubric, citation, narrative, ownership          | `docs/cut-criteria.yaml`          |
 | Status (☐ / ⧗ / ☑)                            | Don't — it's computed.            |
-| Static framing prose (intro, legend, out-of-scope, drift policy) | `scripts/cut-criteria-render.sh` |
-| Status decision table / glyph bytes             | `scripts/cut-criteria-status.sh`  |
+| Static framing prose (intro, legend, out-of-scope, drift policy) | `scripts/cut_criteria.py` (`render()`) |
+| Status decision table / glyph bytes             | `scripts/cut_criteria.py` (`status_for()`) |
 | Rendered markdown                               | Never. Run `make cut-criteria-render`. |
 
 ## Adding a new criterion
@@ -114,9 +114,13 @@ but forgets to re-render the markdown will fail CI.
    `rubric_check.gate_script` so the status walks `☐ → ⧗ → ☑`.
 3. Run `make cut-criteria-render` and commit both files.
 
-## Why bash + YAML, not Go
+## Why Python + YAML, not Go
 
-The render path is a 200-line problem with no performance budget. Bash
-+ `python3 -c yaml.safe_load` is portable, requires no build step, and
-makes the rubric checks themselves first-class shell — operators can
-copy a single line out of the YAML and run it locally.
+The render path is a 300-line problem with no performance budget.
+`python3` + `PyYAML` is portable, requires no build step, and makes the
+rubric checks themselves first-class shell — operators can copy a
+single block out of the YAML and run it locally. A single Python
+module (`scripts/cut_criteria.py`) carries `status`, `render`, `check`,
+and `test` subcommands, replacing the earlier three-script bash setup
+whose base64-over-TSV plumbing existed only to survive embedded
+newlines through a shell pipeline.
diff --git a/docs/v1-rc1-cut-criteria.md b/docs/v1-rc1-cut-criteria.md
index cad8e653..d8f1c3ef 100644
--- a/docs/v1-rc1-cut-criteria.md
+++ b/docs/v1-rc1-cut-criteria.md
@@ -26,7 +26,7 @@ gate matrix that mirrors the criteria below.
 - ⧗ in progress — actively being developed (PR open or branch landed against rubric)
 - ☑ shipped — merged on `main` and the falsifiable rubric is provably satisfied
 
-Status is COMPUTED by `scripts/cut-criteria-status.sh` against the live
+Status is COMPUTED by `scripts/cut_criteria.py status` against the live
 repo state at render time; never hand-edited in this file.
 
 ---
diff --git a/scripts/cut-criteria-render.sh b/scripts/cut-criteria-render.sh
deleted file mode 100755
index 96331714..00000000
--- a/scripts/cut-criteria-render.sh
+++ /dev/null
@@ -1,240 +0,0 @@
-#!/usr/bin/env bash
-# cut-criteria-render.sh — regenerate `docs/v1-rc1-cut-criteria.md`
-# from `docs/cut-criteria.yaml` + the live `cut-criteria-status.sh`
-# output. The rendered file is AUTO-GENERATED; never edit it by hand.
-#
-# Pattern overview: docs/cut-criteria.yaml.md. Inspired by Kubernetes
-# KEP frontmatter `status:` + Bazel `bazel run //docs:gen-status`.
-#
-# Usage:
-#   bash scripts/cut-criteria-render.sh                    # default paths
-#   bash scripts/cut-criteria-render.sh SPEC OUT           # explicit paths
-#
-# Exit codes:
-#   0  rendered file written
-#   2  spec missing / malformed
-
-set -euo pipefail
-
-spec_path="${1:-docs/cut-criteria.yaml}"
-out_path="${2:-docs/v1-rc1-cut-criteria.md}"
-status_script="$(cd "$(dirname "$0")" && pwd)/cut-criteria-status.sh"
-
-if [ ! -f "$spec_path" ]; then
-  echo "cut-criteria-render: spec not found: $spec_path" >&2
-  exit 2
-fi
-if [ ! -f "$status_script" ]; then
-  echo "cut-criteria-render: status script not found: $status_script" >&2
-  exit 2
-fi
-
-# Compute the live status table once. Each line: id<TAB>status<TAB>title.
-status_tmp=$(mktemp)
-trap 'rm -f "$status_tmp"' EXIT
-bash "$status_script" "$spec_path" >"$status_tmp"
-
-# Hand the spec + status table to Python; Python emits the rendered
-# markdown directly (jinja-free: pure string templating keeps the
-# rendering trivially inspectable). Static framing prose (intro, legend,
-# Out-of-scope, drift policy) is embedded in this script — those
-# sections rarely change and live one-edit-away here rather than as
-# a third file to keep in sync.
-python3 - "$spec_path" "$status_tmp" >"$out_path" <<'PY'
-import sys, yaml
-
-spec_path, status_path = sys.argv[1], sys.argv[2]
-
-with open(spec_path, "r", encoding="utf-8") as fh:
-    spec = yaml.safe_load(fh) or []
-
-# id -> "<glyph> <label>"
-status_map = {}
-with open(status_path, "r", encoding="utf-8") as fh:
-    for line in fh.read().splitlines():
-        if not line.strip():
-            continue
-        parts = line.split("\t")
-        if len(parts) >= 2:
-            status_map[parts[0]] = parts[1]
-
-def status_for(cid):
-    return status_map.get(str(cid), "☐ planned")
-
-def emit_rubric(rubric):
-    """Render a multi-line rubric block as a single Markdown bullet,
-    preserving line breaks via two-space continuation. The first line
-    is the bullet body; subsequent lines indent two spaces (markdown
-    list continuation)."""
-    lines = (rubric or "").rstrip().splitlines()
-    if not lines:
-        return ""
-    out = ["- **Falsifiable rubric:** " + lines[0]]
-    for ln in lines[1:]:
-        out.append("  " + ln if ln else "")
-    return "\n".join(out)
-
-def emit_notes(notes):
-    """Render the notes block as the continuation of the Status bullet.
-    First line of notes joins the status glyph with an em-dash; remaining
-    lines indent two spaces."""
-    lines = (notes or "").rstrip().splitlines()
-    if not lines:
-        return ""
-    head = lines[0]
-    out = [head]
-    for ln in lines[1:]:
-        out.append("  " + ln if ln else "")
-    return "\n".join(out)
-
-tier1 = [c for c in spec if c.get("tier", 1) == 1]
-tier2 = [c for c in spec if c.get("tier") == 2]
-
-# Header — note the AUTO-GENERATED banner. Operators editing cut
-# criteria edit docs/cut-criteria.yaml, never this file.
-out = []
-out.append("<!--")
-out.append("AUTO-GENERATED from docs/cut-criteria.yaml. Do not edit by hand.")
-out.append("Run `make cut-criteria-render` to regenerate. Pattern overview:")
-out.append("docs/cut-criteria.yaml.md.")
-out.append("-->")
-out.append("")
-out.append("# v1.0-rc1 cut criteria")
-out.append("")
-out.append("The twelve falsifiable gates that promote tracecore from the v0.3.x")
-out.append("pivot-shipped state to a tagged `v1.0.0-rc1`. \"rc1 ready\" means: every")
-out.append("NORTHSTAR objective (O1-O7) has a binding rubric the release-prep PR")
-out.append("can be measured against, and the only work remaining between rc1 and")
-out.append("GA is external-clock (third-party audit, real-operator integration,")
-out.append("externally verified reproducibility) rather than more dev work in this")
-out.append("repo.")
-out.append("")
-out.append("Read [`NORTHSTARS.md`](NORTHSTARS.md) for the objectives this")
-out.append("document derives from, [`MILESTONES.md`](MILESTONES.md) (`M22`) for")
-out.append("the lane-and-status view, and")
-out.append("[`docs/RELEASE-CHECKLIST.md`](RELEASE-CHECKLIST.md) for the RC-tier")
-out.append("gate matrix that mirrors the criteria below.")
-out.append("")
-out.append("## Status legend")
-out.append("")
-out.append("- ☐ planned — committed; not yet started")
-out.append("- ⧗ in progress — actively being developed (PR open or branch landed against rubric)")
-out.append("- ☑ shipped — merged on `main` and the falsifiable rubric is provably satisfied")
-out.append("")
-out.append("Status is COMPUTED by `scripts/cut-criteria-status.sh` against the live")
-out.append("repo state at render time; never hand-edited in this file.")
-out.append("")
-out.append("---")
-out.append("")
-out.append("## The twelve cut criteria")
-out.append("")
-
-def emit_criterion(c):
-    cid = c.get("id", "")
-    title = c.get("title", "")
-    owner = c.get("owner", "")
-    rubric = c.get("rubric", "")
-    citations = c.get("citation") or []
-    notes = c.get("notes", "")
-    status = status_for(cid)
-
-    out.append(f"### {cid}. {title}")
-    out.append("")
-    if owner:
-        out.append(f"- **Owner objective:** {owner}")
-    rubric_block = emit_rubric(rubric)
-    if rubric_block:
-        out.append(rubric_block)
-    if citations:
-        # Render as a single bullet whose continuation lines wrap the
-        # second-and-later citation entries. We join with " and " so the
-        # rendered bullet reads as prose; YAML stores them as a list so
-        # editors can add/remove without messing with markdown punctuation.
-        joined = " and ".join(citations)
-        out.append(f"- **Citation:** {joined}.")
-    status_line_body = status
-    notes_block = emit_notes(notes)
-    if notes_block:
-        status_line_body = f"{status} — {notes_block}"
-    # The status line is a single bullet; multi-line notes already
-    # indent properly via emit_notes().
-    out.append(f"- **Status:** {status_line_body}")
-    out.append("")
-
-for c in tier1:
-    emit_criterion(c)
-
-out.append("---")
-out.append("")
-out.append("## Tier 2: GA path-clearing")
-out.append("")
-out.append("These are not rc1 blockers. They run in parallel with the criteria")
-out.append("above so GA blocks only on external clocks (audit weeks-to-months,")
-out.append("partner engagement partner-paced) rather than more dev work in this")
-out.append("repo.")
-out.append("")
-
-for c in tier2:
-    emit_criterion(c)
-
-out.append("---")
-out.append("")
-out.append("## Out of scope for rc1")
-out.append("")
-out.append("Explicitly deferred to v1.1 or later. Listing these here so reviewers")
-out.append("do not file rc1-blocker issues against them.")
-out.append("")
-out.append("- **Patterns #12-#15 frontier (v2/v3 scope per O1 caveats).** Loss")
-out.append("  spike → NaN (#12), silent data corruption (#13), FP8 numerics,")
-out.append("  RLHF reward-model failure, MoE expert-routing degradation. Tracked")
-out.append("  as v2/v3 differentiators in")
-out.append("  [`NORTHSTARS.md` §O1](NORTHSTARS.md#o1-coverage)")
-out.append("  (M18 / M24 horizon).")
-out.append("- **Non-NVIDIA stack receivers as in-tree code.** AMD MI300X / RCCL,")
-out.append("  AWS Trainium, Google TPU, Intel Gaudi — coverage delivered via the")
-out.append("  Prometheus-scrape recipe (already shipped) against vendor exporters;")
-out.append("  in-tree receivers are explicitly out per")
-out.append("  [`RFC-0013 §6`](rfcs/0013-distro-first-pivot.md#6-what-tracecore-still-builds-the-moat).")
-out.append("- **`tracecore-cli verify-cluster` (roadmap item B13).** Re-evaluated")
-out.append("  as a krew plugin after rc1; tracked in")
-out.append("  [project memory `horizon-roadmap`](../README.md).")
-out.append("- **Pattern marketplace, ML-anomaly detector recipe, Beyla/Pixie")
-out.append("  integration spike, cross-cluster federation v1 (write-path dedup),")
-out.append("  cost attribution, LLM-summarized verdict MCP server, runbook")
-out.append("  auto-execution.** Backlog items C1-C9 in `horizon-roadmap`; revisit")
-out.append("  after GA.")
-out.append("- **Inference-cluster scope expansion.** The northstar is training;")
-out.append("  inference is named in")
-out.append("  [`NORTHSTARS.md` \"What we explicitly do not chase\"](NORTHSTARS.md#what-we-explicitly-do-not-chase)")
-out.append("  and remains out until a separate RFC opens that scope.")
-out.append("")
-out.append("---")
-out.append("")
-out.append("## How this doc is kept honest")
-out.append("")
-out.append("Status here is computed, not stored. The source of truth is")
-out.append("[`docs/cut-criteria.yaml`](cut-criteria.yaml); this markdown is the")
-out.append("rendered view. Operators editing cut criteria edit the YAML; CI")
-out.append("(`make cut-criteria-check`) fails any PR that lands a feature without")
-out.append("re-rendering this file.")
-out.append("")
-out.append("- A PR that ships a criterion's artifact automatically flips the")
-out.append("  computed status on the next render. The per-PR `☐ → ⧗ → ☑` flip")
-out.append("  dance against this markdown is gone.")
-out.append("- A PR that changes a criterion's rubric, citation, or narrative")
-out.append("  edits [`docs/cut-criteria.yaml`](cut-criteria.yaml) and re-runs")
-out.append("  `make cut-criteria-render` in the same commit. The drift gate")
-out.append("  (`make cut-criteria-check`) catches PRs that forget.")
-out.append("- The rc1 release-prep PR (per agent memory `release-prep-required`)")
-out.append("  MUST verify every criterion shows ☑ before the tag is cut. A")
-out.append("  criterion still at ⧗ blocks the tag; a criterion at ☐ blocks the")
-out.append("  tag with reason `cut-criterion-missing`.")
-out.append("- Status drift between this doc and")
-out.append("  [`docs/RELEASE-CHECKLIST.md`](RELEASE-CHECKLIST.md) is a review")
-out.append("  blocker — the checklist is the tag-cut gate, this doc is the")
-out.append("  rubric definition; they must agree on what \"rc1 ready\" means.")
-
-sys.stdout.write("\n".join(out) + "\n")
-PY
-
-echo "cut-criteria-render: wrote $out_path"
diff --git a/scripts/cut-criteria-status.sh b/scripts/cut-criteria-status.sh
deleted file mode 100755
index 6a1ac134..00000000
--- a/scripts/cut-criteria-status.sh
+++ /dev/null
@@ -1,122 +0,0 @@
-#!/usr/bin/env bash
-# cut-criteria-status.sh — compute the status (☑ / ⧗ / ☐) of every
-# v1.0-rc1 cut criterion declared in `docs/cut-criteria.yaml`.
-#
-# Status is derived from the criterion's `rubric_check` block:
-#
-#   - `artifact_exists` (shell, exit 0 = pass) — does the artifact this
-#     criterion claims exist on disk?
-#   - `gate_script` (shell, optional; exit 0 = pass) — is the artifact
-#     binding / production-grade by the criterion's stricter rubric?
-#
-# Decision table:
-#
-#   artifact_exists | gate_script  | status
-#   ----------------|--------------|------------------
-#   pass            | pass / empty | ☑ shipped
-#   pass            | fail         | ⧗ in progress
-#   fail            | any          | ☐ planned
-#
-# Output: one row per criterion, tab-separated:
-#
-#   <id>\t<status-glyph + label>\t<title>
-#
-# Usage:
-#   bash scripts/cut-criteria-status.sh                 # default spec
-#   bash scripts/cut-criteria-status.sh path/to/spec.yaml
-#
-# Exit code is always 0 unless the spec file is missing or malformed —
-# this script reports state, it does not gate.
-
-set -euo pipefail
-
-spec_path="${1:-docs/cut-criteria.yaml}"
-
-if [ ! -f "$spec_path" ]; then
-  echo "cut-criteria-status: spec not found: $spec_path" >&2
-  exit 2
-fi
-
-# Parse YAML once via python3 (PyYAML is the only host dep; available
-# on every Linux CI runner + macOS dev box we ship against). Emit
-# one TSV row per criterion: id<TAB>title<TAB>artifact_cmd<TAB>gate_cmd.
-# The shell loop then re-evaluates each command in the current $PWD
-# so checks resolve against the live repo state.
-#
-# A null byte (\0) separates rows so shell commands embedded in the
-# YAML can contain literal newlines without confusing the row parser
-# (`read -d ''`); within-row fields stay tab-separated.
-rows_tmp=$(mktemp)
-trap 'rm -f "$rows_tmp"' EXIT
-# Emit one row per criterion, four tab-separated fields:
-#   <id>\t<title>\t<base64(artifact_cmd)>\t<base64(gate_cmd)>
-# Base64-encoding the shell commands lets them contain arbitrary
-# newlines/tabs/quotes without colliding with the row format. The bash
-# loop decodes each field before evaluating it.
-python3 - "$spec_path" >"$rows_tmp" <<'PY'
-import sys, yaml, base64
-path = sys.argv[1]
-with open(path, "r", encoding="utf-8") as fh:
-    spec = yaml.safe_load(fh) or []
-if not isinstance(spec, list):
-    print(f"cut-criteria-status: spec root must be a list, got {type(spec).__name__}", file=sys.stderr)
-    sys.exit(2)
-def b64(s):
-    return base64.b64encode(str(s).encode("utf-8")).decode("ascii")
-for item in spec:
-    if not isinstance(item, dict):
-        continue
-    cid = str(item.get("id", ""))
-    title = str(item.get("title", "")).replace("\t", " ")
-    rc = item.get("rubric_check") or {}
-    artifact = rc.get("artifact_exists", "")
-    gate = rc.get("gate_script", "") or ""
-    print(f"{cid}\t{title}\t{b64(artifact)}\t{b64(gate)}")
-PY
-
-# Glyphs — kept inline so the script has no docs-side dependency. The
-# legend in docs/v1-rc1-cut-criteria.md must agree with these byte
-# sequences; the render script copies them through.
-SHIPPED=$'\xe2\x98\x91 shipped'        # ☑
-PROGRESS=$'\xe2\xa7\x97 in progress'   # ⧗
-PLANNED=$'\xe2\x98\x90 planned'        # ☐
-
-first=1
-# Each line of $rows_tmp is one criterion: id<TAB>title<TAB>b64(art)<TAB>b64(gate).
-while IFS=$'\t' read -r cid title art_b64 gate_b64; do
-  [ -z "$cid" ] && continue
-  # Decode the per-criterion shell snippets. base64 -d failing here means
-  # the python emitter above produced a corrupt row — that's a script bug,
-  # not a "criterion is planned" signal, so we fail loudly with the
-  # criterion id instead of treating it as artifact-missing.
-  if ! artifact=$(printf '%s' "$art_b64" | base64 -d 2>/dev/null); then
-    echo "cut-criteria-status: failed to decode artifact_exists for criterion $cid" >&2
-    exit 3
-  fi
-  if ! gate=$(printf '%s' "$gate_b64" | base64 -d 2>/dev/null); then
-    echo "cut-criteria-status: failed to decode gate_script for criterion $cid" >&2
-    exit 3
-  fi
-
-  if [ -z "$artifact" ]; then
-    # No artifact check declared — treat as planned (cannot prove).
-    status="$PLANNED"
-  elif bash -c "$artifact" >/dev/null 2>&1; then
-    if [ -z "$gate" ]; then
-      status="$SHIPPED"
-    elif bash -c "$gate" >/dev/null 2>&1; then
-      status="$SHIPPED"
-    else
-      status="$PROGRESS"
-    fi
-  else
-    status="$PLANNED"
-  fi
-
-  if [ "$first" -eq 1 ]; then
-    first=0
-  else
-    printf '\n'
-  fi
-  printf '%s\t%s\t%s' "$cid" "$status" "$title"
-done < "$rows_tmp"
diff --git a/scripts/cut-criteria-status_test.sh b/scripts/cut-criteria-status_test.sh
deleted file mode 100755
index 69d81a5b..00000000
--- a/scripts/cut-criteria-status_test.sh
+++ /dev/null
@@ -1,160 +0,0 @@
-#!/usr/bin/env bash
-# cut-criteria-status_test.sh — regression test for the executable
-# cut-criteria status computation. Exercises the status script against
-# fixture YAMLs that mimic minimal criterion blocks, asserting it
-# produces the right status (☑ / ⧗ / ☐) for the three rubric-check
-# outcome shapes:
-#
-#   1. artifact_exists pass + gate_script pass  → ☑ shipped
-#   2. artifact_exists pass + gate_script fail  → ⧗ in progress
-#   3. artifact_exists fail                     → ☐ planned
-#   4. artifact_exists pass + gate_script ""    → ☑ shipped (no gate)
-#
-# Output format: `id<TAB>status<TAB>title` one row per criterion.
-#
-# Run from the repo root: `bash scripts/cut-criteria-status_test.sh`.
-
-set -euo pipefail
-
-gate="$(cd "$(dirname "$0")" && pwd)/cut-criteria-status.sh"
-
-if [ ! -f "$gate" ]; then
-  echo "FAIL: gate script not found: $gate"
-  exit 1
-fi
-
-run_gate() {
-  ( cd "$1" && bash "$gate" "$2" 2>/dev/null )
-}
-
-assert_row() {
-  local fixture_label="$1" cwd="$2" yaml_path="$3" want="$4"
-  local got
-  got=$(run_gate "$cwd" "$yaml_path" || true)
-  if [ "$got" != "$want" ]; then
-    echo "FAIL [$fixture_label]:"
-    echo "  want: $(printf '%s' "$want")"
-    echo "  got:  $(printf '%s' "$got")"
-    return 1
-  fi
-  echo "ok: $fixture_label"
-}
-
-failures=0
-
-# Fixture 1: artifact_exists passes, gate_script passes -> ☑ shipped.
-f1=$(mktemp -d)
-cat > "$f1/spec.yaml" <<'EOF'
-- id: 1
-  title: "Both pass -> shipped"
-  rubric: "shipped"
-  citation: []
-  rubric_check:
-    artifact_exists: "true"
-    gate_script: "true"
-EOF
-# shellcheck disable=SC2059
-assert_row "both-pass-shipped" "$f1" "spec.yaml" "$(printf '1\t\xe2\x98\x91 shipped\tBoth pass -> shipped')" \
-  || failures=$((failures + 1))
-rm -rf "$f1"
-
-# Fixture 2: artifact_exists passes, gate_script fails -> ⧗ in progress.
-f2=$(mktemp -d)
-cat > "$f2/spec.yaml" <<'EOF'
-- id: 2
-  title: "Gate fails -> in progress"
-  rubric: "wip"
-  citation: []
-  rubric_check:
-    artifact_exists: "true"
-    gate_script: "false"
-EOF
-assert_row "gate-fails-in-progress" "$f2" "spec.yaml" "$(printf '2\t\xe2\xa7\x97 in progress\tGate fails -> in progress')" \
-  || failures=$((failures + 1))
-rm -rf "$f2"
-
-# Fixture 3: artifact_exists fails -> ☐ planned.
-f3=$(mktemp -d)
-cat > "$f3/spec.yaml" <<'EOF'
-- id: 3
-  title: "Artifact missing -> planned"
-  rubric: "planned"
-  citation: []
-  rubric_check:
-    artifact_exists: "false"
-    gate_script: ""
-EOF
-assert_row "artifact-missing-planned" "$f3" "spec.yaml" "$(printf '3\t\xe2\x98\x90 planned\tArtifact missing -> planned')" \
-  || failures=$((failures + 1))
-rm -rf "$f3"
-
-# Fixture 4: artifact_exists passes, gate_script empty -> ☑ shipped.
-f4=$(mktemp -d)
-cat > "$f4/spec.yaml" <<'EOF'
-- id: 4
-  title: "No gate -> shipped on artifact"
-  rubric: "shipped-no-gate"
-  citation: []
-  rubric_check:
-    artifact_exists: "true"
-    gate_script: ""
-EOF
-assert_row "no-gate-shipped" "$f4" "spec.yaml" "$(printf '4\t\xe2\x98\x91 shipped\tNo gate -> shipped on artifact')" \
-  || failures=$((failures + 1))
-rm -rf "$f4"
-
-# Fixture 5: multi-criterion file, mixed statuses. Validates the script
-# emits one row per criterion in YAML order with correct status each.
-f5=$(mktemp -d)
-cat > "$f5/spec.yaml" <<'EOF'
-- id: 10
-  title: "first shipped"
-  rubric: "x"
-  citation: []
-  rubric_check:
-    artifact_exists: "true"
-    gate_script: ""
-- id: 11
-  title: "second in progress"
-  rubric: "x"
-  citation: []
-  rubric_check:
-    artifact_exists: "true"
-    gate_script: "false"
-- id: 12
-  title: "third planned"
-  rubric: "x"
-  citation: []
-  rubric_check:
-    artifact_exists: "false"
-    gate_script: ""
-EOF
-want=$(printf '10\t\xe2\x98\x91 shipped\tfirst shipped\n11\t\xe2\xa7\x97 in progress\tsecond in progress\n12\t\xe2\x98\x90 planned\tthird planned')
-assert_row "multi-criterion-order" "$f5" "spec.yaml" "$want" \
-  || failures=$((failures + 1))
-rm -rf "$f5"
-
-# Fixture 6: gate_script absent (key omitted) -> treated same as "".
-f6=$(mktemp -d)
-cat > "$f6/spec.yaml" <<'EOF'
-- id: 6
-  title: "Gate key absent -> shipped on artifact"
-  rubric: "x"
-  citation: []
-  rubric_check:
-    artifact_exists: "true"
-EOF
-assert_row "gate-key-absent-shipped" "$f6" "spec.yaml" "$(printf '6\t\xe2\x98\x91 shipped\tGate key absent -> shipped on artifact')" \
-  || failures=$((failures + 1))
-rm -rf "$f6"
-
-# Summary --------------------------------------------------------------
-
-if [ "$failures" -ne 0 ]; then
-  echo
-  echo "$failures test(s) failed."
-  exit 1
-fi
-
-echo
-echo "All cut-criteria-status tests passed."
diff --git a/scripts/cut_criteria.py b/scripts/cut_criteria.py
new file mode 100755
index 00000000..dee98e1d
--- /dev/null
+++ b/scripts/cut_criteria.py
@@ -0,0 +1,642 @@
+#!/usr/bin/env python3
+# cut_criteria.py — unified status + render + check for the v1.0-rc1
+# cut-criteria spec at docs/cut-criteria.yaml.
+#
+# Replaces the previous three-script shell setup (status.sh, render.sh,
+# status_test.sh). The shell version base64-encoded each rubric_check
+# snippet to survive embedded newlines through a TSV round-trip — a
+# bash macOS-3.2 compat tax that this module deletes by keeping every
+# value as a native Python string until subprocess.run() invokes the
+# user's shell directly.
+#
+# Pattern overview lives at docs/cut-criteria.yaml.md.
+#
+# Subcommands:
+#   status            Print one `id<TAB>status<TAB>title` row per criterion.
+#   render            Write the rendered markdown to docs/v1-rc1-cut-criteria.md.
+#   check             Render to a string + diff against the on-disk markdown.
+#                     Exits non-zero (with the diff) when stale.
+#   test              Run the fixture-based regression suite for status().
+#
+# Conventions:
+#   - Status is COMPUTED, never stored. The rubric_check.artifact_exists
+#     and rubric_check.gate_script shell snippets are executed against
+#     the live repo state at $PWD; exit 0 = pass.
+#   - Output of `status` is stable across runs for the same input
+#     (deterministic ordering = YAML list order).
+#   - `render` and `check` are byte-identical for the same YAML +
+#     repo state. CI's drift gate relies on this.
+
+from __future__ import annotations
+
+import argparse
+import difflib
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any, Iterable
+
+try:
+    import yaml
+except ImportError as exc:  # pragma: no cover - exercised only on bare hosts
+    sys.stderr.write(
+        "cut_criteria: PyYAML is required (pip install pyyaml). "
+        f"Import error: {exc}\n"
+    )
+    sys.exit(2)
+
+
+# Glyph bytes — must agree with the legend rendered into
+# docs/v1-rc1-cut-criteria.md. Kept here so the module has no docs-side
+# dependency.
+SHIPPED = "☑ shipped"  # ☑
+PROGRESS = "⧗ in progress"  # ⧗
+PLANNED = "☐ planned"  # ☐
+
+DEFAULT_SPEC = "docs/cut-criteria.yaml"
+DEFAULT_OUT = "docs/v1-rc1-cut-criteria.md"
+
+# Required keys per spec item; absent keys are a malformed-spec error
+# rather than a silent "treated as planned" — drift between the YAML
+# and the renderer is the bug class this gate exists to catch.
+REQUIRED_KEYS = ("id", "title", "rubric_check")
+ALLOWED_TIERS = (1, 2)
+
+
+# ---------------------------------------------------------------------
+# Spec parsing + schema validation
+# ---------------------------------------------------------------------
+
+
+def load_spec(spec_path: str) -> list[dict[str, Any]]:
+    """Read + schema-validate the YAML spec. Raises SystemExit on error."""
+    p = Path(spec_path)
+    if not p.is_file():
+        sys.stderr.write(f"cut_criteria: spec not found: {spec_path}\n")
+        sys.exit(2)
+    try:
+        with p.open("r", encoding="utf-8") as fh:
+            spec = yaml.safe_load(fh) or []
+    except yaml.YAMLError as exc:
+        sys.stderr.write(f"cut_criteria: YAML parse error in {spec_path}: {exc}\n")
+        sys.exit(2)
+    if not isinstance(spec, list):
+        sys.stderr.write(
+            "cut_criteria: spec root must be a list, "
+            f"got {type(spec).__name__}\n"
+        )
+        sys.exit(2)
+    _validate_schema(spec, spec_path)
+    return spec
+
+
+def _validate_schema(spec: list[Any], spec_path: str) -> None:
+    """Reject malformed spec items. The renderer + status loop assume a
+    fixed shape; surface schema bugs at parse time instead of producing
+    a quietly-wrong markdown."""
+    seen_ids: set[str] = set()
+    for idx, item in enumerate(spec):
+        if not isinstance(item, dict):
+            sys.stderr.write(
+                f"cut_criteria: {spec_path}[{idx}] must be a mapping, "
+                f"got {type(item).__name__}\n"
+            )
+            sys.exit(2)
+        for key in REQUIRED_KEYS:
+            if key not in item:
+                sys.stderr.write(
+                    f"cut_criteria: {spec_path}[{idx}] missing required "
+                    f"key '{key}'\n"
+                )
+                sys.exit(2)
+        cid = str(item.get("id", ""))
+        if not cid:
+            sys.stderr.write(
+                f"cut_criteria: {spec_path}[{idx}] has empty id\n"
+            )
+            sys.exit(2)
+        if cid in seen_ids:
+            sys.stderr.write(
+                f"cut_criteria: duplicate id '{cid}' in {spec_path}\n"
+            )
+            sys.exit(2)
+        seen_ids.add(cid)
+        tier = item.get("tier", 1)
+        if tier not in ALLOWED_TIERS:
+            sys.stderr.write(
+                f"cut_criteria: {spec_path}[{idx}] (id={cid}) has invalid "
+                f"tier {tier!r}; expected one of {ALLOWED_TIERS}\n"
+            )
+            sys.exit(2)
+        rc = item.get("rubric_check")
+        if not isinstance(rc, dict):
+            sys.stderr.write(
+                f"cut_criteria: {spec_path}[{idx}] (id={cid}) rubric_check "
+                f"must be a mapping, got {type(rc).__name__}\n"
+            )
+            sys.exit(2)
+        if "artifact_exists" not in rc:
+            sys.stderr.write(
+                f"cut_criteria: {spec_path}[{idx}] (id={cid}) rubric_check "
+                "missing 'artifact_exists'\n"
+            )
+            sys.exit(2)
+
+
+# ---------------------------------------------------------------------
+# Status computation
+# ---------------------------------------------------------------------
+
+
+def _run_shell(snippet: str) -> bool:
+    """Run a shell snippet; return True iff exit 0. Empty snippet = pass.
+
+    subprocess.run() with `shell=True` runs the snippet through /bin/sh,
+    so a multi-line YAML block scalar lands intact — no base64 hop
+    needed. stdout/stderr are discarded; this is a probe, not a logger.
+    """
+    if not snippet or not snippet.strip():
+        return True
+    result = subprocess.run(
+        snippet,
+        shell=True,
+        executable="/bin/bash",
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        check=False,
+    )
+    return result.returncode == 0
+
+
+def status_for(item: dict[str, Any]) -> str:
+    """Return the status glyph+label for a single criterion."""
+    rc = item.get("rubric_check") or {}
+    artifact = rc.get("artifact_exists", "") or ""
+    gate = rc.get("gate_script", "") or ""
+    if not str(artifact).strip():
+        # No artifact check declared — cannot prove; treat as planned.
+        return PLANNED
+    if not _run_shell(str(artifact)):
+        return PLANNED
+    if not str(gate).strip():
+        return SHIPPED
+    return SHIPPED if _run_shell(str(gate)) else PROGRESS
+
+
+def status_rows(spec: list[dict[str, Any]]) -> list[tuple[str, str, str]]:
+    """Compute (id, status, title) for every criterion in YAML order."""
+    rows: list[tuple[str, str, str]] = []
+    for item in spec:
+        cid = str(item.get("id", ""))
+        title = str(item.get("title", "")).replace("\t", " ")
+        rows.append((cid, status_for(item), title))
+    return rows
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    spec = load_spec(args.spec)
+    rows = status_rows(spec)
+    sys.stdout.write(
+        "\n".join(f"{cid}\t{stat}\t{title}" for cid, stat, title in rows)
+    )
+    return 0
+
+
+# ---------------------------------------------------------------------
+# Render
+# ---------------------------------------------------------------------
+
+
+def _emit_rubric(rubric: str) -> str:
+    """Render a multi-line rubric block as a single Markdown bullet,
+    preserving line breaks via two-space continuation."""
+    lines = (rubric or "").rstrip().splitlines()
+    if not lines:
+        return ""
+    out = ["- **Falsifiable rubric:** " + lines[0]]
+    for ln in lines[1:]:
+        out.append("  " + ln if ln else "")
+    return "\n".join(out)
+
+
+def _emit_notes(notes: str) -> str:
+    """Render a multi-line notes block, used as the continuation of the
+    Status bullet."""
+    lines = (notes or "").rstrip().splitlines()
+    if not lines:
+        return ""
+    out = [lines[0]]
+    for ln in lines[1:]:
+        out.append("  " + ln if ln else "")
+    return "\n".join(out)
+
+
+def render(spec: list[dict[str, Any]]) -> str:
+    """Render the full markdown for the given spec against the live
+    repo state. Pure function: same (spec, repo state) → same bytes."""
+    status_map = {cid: stat for cid, stat, _ in status_rows(spec)}
+
+    def status_lookup(cid: object) -> str:
+        return status_map.get(str(cid), PLANNED)
+
+    tier1 = [c for c in spec if c.get("tier", 1) == 1]
+    tier2 = [c for c in spec if c.get("tier") == 2]
+
+    out: list[str] = []
+    out += [
+        "<!--",
+        "AUTO-GENERATED from docs/cut-criteria.yaml. Do not edit by hand.",
+        "Run `make cut-criteria-render` to regenerate. Pattern overview:",
+        "docs/cut-criteria.yaml.md.",
+        "-->",
+        "",
+        "# v1.0-rc1 cut criteria",
+        "",
+        "The twelve falsifiable gates that promote tracecore from the v0.3.x",
+        "pivot-shipped state to a tagged `v1.0.0-rc1`. \"rc1 ready\" means: every",
+        "NORTHSTAR objective (O1-O7) has a binding rubric the release-prep PR",
+        "can be measured against, and the only work remaining between rc1 and",
+        "GA is external-clock (third-party audit, real-operator integration,",
+        "externally verified reproducibility) rather than more dev work in this",
+        "repo.",
+        "",
+        "Read [`NORTHSTARS.md`](NORTHSTARS.md) for the objectives this",
+        "document derives from, [`MILESTONES.md`](MILESTONES.md) (`M22`) for",
+        "the lane-and-status view, and",
+        "[`docs/RELEASE-CHECKLIST.md`](RELEASE-CHECKLIST.md) for the RC-tier",
+        "gate matrix that mirrors the criteria below.",
+        "",
+        "## Status legend",
+        "",
+        "- ☐ planned — committed; not yet started",
+        "- ⧗ in progress — actively being developed (PR open or branch landed against rubric)",
+        "- ☑ shipped — merged on `main` and the falsifiable rubric is provably satisfied",
+        "",
+        "Status is COMPUTED by `scripts/cut_criteria.py status` against the live",
+        "repo state at render time; never hand-edited in this file.",
+        "",
+        "---",
+        "",
+        "## The twelve cut criteria",
+        "",
+    ]
+
+    def emit_criterion(c: dict[str, Any]) -> None:
+        cid = c.get("id", "")
+        title = c.get("title", "")
+        owner = c.get("owner", "")
+        rubric = c.get("rubric", "")
+        citations = c.get("citation") or []
+        notes = c.get("notes", "")
+        status = status_lookup(cid)
+
+        out.append(f"### {cid}. {title}")
+        out.append("")
+        if owner:
+            out.append(f"- **Owner objective:** {owner}")
+        rubric_block = _emit_rubric(rubric)
+        if rubric_block:
+            out.append(rubric_block)
+        if citations:
+            # Single bullet whose continuation lines wrap the
+            # second-and-later citation entries. " and " keeps the prose
+            # natural; YAML stores them as a list so editors can add or
+            # remove entries without juggling markdown punctuation.
+            joined = " and ".join(citations)
+            out.append(f"- **Citation:** {joined}.")
+        status_line_body = status
+        notes_block = _emit_notes(notes)
+        if notes_block:
+            status_line_body = f"{status} — {notes_block}"
+        out.append(f"- **Status:** {status_line_body}")
+        out.append("")
+
+    for c in tier1:
+        emit_criterion(c)
+
+    out += [
+        "---",
+        "",
+        "## Tier 2: GA path-clearing",
+        "",
+        "These are not rc1 blockers. They run in parallel with the criteria",
+        "above so GA blocks only on external clocks (audit weeks-to-months,",
+        "partner engagement partner-paced) rather than more dev work in this",
+        "repo.",
+        "",
+    ]
+
+    for c in tier2:
+        emit_criterion(c)
+
+    out += [
+        "---",
+        "",
+        "## Out of scope for rc1",
+        "",
+        "Explicitly deferred to v1.1 or later. Listing these here so reviewers",
+        "do not file rc1-blocker issues against them.",
+        "",
+        "- **Patterns #12-#15 frontier (v2/v3 scope per O1 caveats).** Loss",
+        "  spike → NaN (#12), silent data corruption (#13), FP8 numerics,",
+        "  RLHF reward-model failure, MoE expert-routing degradation. Tracked",
+        "  as v2/v3 differentiators in",
+        "  [`NORTHSTARS.md` §O1](NORTHSTARS.md#o1-coverage)",
+        "  (M18 / M24 horizon).",
+        "- **Non-NVIDIA stack receivers as in-tree code.** AMD MI300X / RCCL,",
+        "  AWS Trainium, Google TPU, Intel Gaudi — coverage delivered via the",
+        "  Prometheus-scrape recipe (already shipped) against vendor exporters;",
+        "  in-tree receivers are explicitly out per",
+        "  [`RFC-0013 §6`](rfcs/0013-distro-first-pivot.md#6-what-tracecore-still-builds-the-moat).",
+        "- **`tracecore-cli verify-cluster` (roadmap item B13).** Re-evaluated",
+        "  as a krew plugin after rc1; tracked in",
+        "  [project memory `horizon-roadmap`](../README.md).",
+        "- **Pattern marketplace, ML-anomaly detector recipe, Beyla/Pixie",
+        "  integration spike, cross-cluster federation v1 (write-path dedup),",
+        "  cost attribution, LLM-summarized verdict MCP server, runbook",
+        "  auto-execution.** Backlog items C1-C9 in `horizon-roadmap`; revisit",
+        "  after GA.",
+        "- **Inference-cluster scope expansion.** The northstar is training;",
+        "  inference is named in",
+        "  [`NORTHSTARS.md` \"What we explicitly do not chase\"](NORTHSTARS.md#what-we-explicitly-do-not-chase)",
+        "  and remains out until a separate RFC opens that scope.",
+        "",
+        "---",
+        "",
+        "## How this doc is kept honest",
+        "",
+        "Status here is computed, not stored. The source of truth is",
+        "[`docs/cut-criteria.yaml`](cut-criteria.yaml); this markdown is the",
+        "rendered view. Operators editing cut criteria edit the YAML; CI",
+        "(`make cut-criteria-check`) fails any PR that lands a feature without",
+        "re-rendering this file.",
+        "",
+        "- A PR that ships a criterion's artifact automatically flips the",
+        "  computed status on the next render. The per-PR `☐ → ⧗ → ☑` flip",
+        "  dance against this markdown is gone.",
+        "- A PR that changes a criterion's rubric, citation, or narrative",
+        "  edits [`docs/cut-criteria.yaml`](cut-criteria.yaml) and re-runs",
+        "  `make cut-criteria-render` in the same commit. The drift gate",
+        "  (`make cut-criteria-check`) catches PRs that forget.",
+        "- The rc1 release-prep PR (per agent memory `release-prep-required`)",
+        "  MUST verify every criterion shows ☑ before the tag is cut. A",
+        "  criterion still at ⧗ blocks the tag; a criterion at ☐ blocks the",
+        "  tag with reason `cut-criterion-missing`.",
+        "- Status drift between this doc and",
+        "  [`docs/RELEASE-CHECKLIST.md`](RELEASE-CHECKLIST.md) is a review",
+        "  blocker — the checklist is the tag-cut gate, this doc is the",
+        "  rubric definition; they must agree on what \"rc1 ready\" means.",
+    ]
+
+    return "\n".join(out) + "\n"
+
+
+def cmd_render(args: argparse.Namespace) -> int:
+    spec = load_spec(args.spec)
+    rendered = render(spec)
+    Path(args.out).write_text(rendered, encoding="utf-8")
+    sys.stderr.write(f"cut_criteria: wrote {args.out}\n")
+    return 0
+
+
+# ---------------------------------------------------------------------
+# Check (drift gate)
+# ---------------------------------------------------------------------
+
+
+def cmd_check(args: argparse.Namespace) -> int:
+    """Render to a string + diff against the on-disk markdown. Exit
+    non-zero (with the diff) when stale. CI runs this; locally it tells
+    you whether `make cut-criteria-render` would change anything."""
+    spec = load_spec(args.spec)
+    rendered = render(spec)
+    out_path = Path(args.out)
+    if not out_path.is_file():
+        sys.stderr.write(
+            f"cut_criteria-check: {args.out} missing. "
+            "Run `make cut-criteria-render` and commit.\n"
+        )
+        return 1
+    on_disk = out_path.read_text(encoding="utf-8")
+    if on_disk == rendered:
+        return 0
+    diff = difflib.unified_diff(
+        on_disk.splitlines(keepends=True),
+        rendered.splitlines(keepends=True),
+        fromfile=str(out_path),
+        tofile=f"{out_path} (would render)",
+    )
+    sys.stdout.writelines(diff)
+    sys.stderr.write("\n")
+    sys.stderr.write(
+        f"cut_criteria-check: {args.out} is out of sync with {args.spec}.\n"
+        "Run `make cut-criteria-render` and commit the result.\n"
+    )
+    return 1
+
+
+# ---------------------------------------------------------------------
+# Test (fixture suite, replaces cut-criteria-status_test.sh)
+# ---------------------------------------------------------------------
+
+
+def _fixture(spec_yaml: str, expected_rows: Iterable[tuple[str, str, str]]) -> tuple[bool, str]:
+    """Write a one-shot YAML to a temp dir, run status_rows from that
+    cwd, return (ok, message)."""
+    with tempfile.TemporaryDirectory() as tmp:
+        p = Path(tmp) / "spec.yaml"
+        p.write_text(spec_yaml, encoding="utf-8")
+        # cd into tmp so any shell snippet that references the repo root
+        # is evaluated against the fixture's $PWD — matches the bash
+        # test harness behaviour and keeps fixtures self-contained.
+        prev_cwd = os.getcwd()
+        try:
+            os.chdir(tmp)
+            spec = load_spec(str(p))
+            got = status_rows(spec)
+        finally:
+            os.chdir(prev_cwd)
+    want = list(expected_rows)
+    if got == want:
+        return True, ""
+    return False, f"\n  want: {want}\n  got:  {got}"
+
+
+def cmd_test(_args: argparse.Namespace) -> int:
+    """Run the fixture suite. Mirrors the three decision-table outcomes
+    plus a multi-criterion ordering case + a missing-gate-key case."""
+    cases: list[tuple[str, str, list[tuple[str, str, str]]]] = [
+        (
+            "both-pass-shipped",
+            """\
+- id: 1
+  title: "Both pass -> shipped"
+  rubric: "shipped"
+  citation: []
+  rubric_check:
+    artifact_exists: "true"
+    gate_script: "true"
+""",
+            [("1", SHIPPED, "Both pass -> shipped")],
+        ),
+        (
+            "gate-fails-in-progress",
+            """\
+- id: 2
+  title: "Gate fails -> in progress"
+  rubric: "wip"
+  citation: []
+  rubric_check:
+    artifact_exists: "true"
+    gate_script: "false"
+""",
+            [("2", PROGRESS, "Gate fails -> in progress")],
+        ),
+        (
+            "artifact-missing-planned",
+            """\
+- id: 3
+  title: "Artifact missing -> planned"
+  rubric: "planned"
+  citation: []
+  rubric_check:
+    artifact_exists: "false"
+    gate_script: ""
+""",
+            [("3", PLANNED, "Artifact missing -> planned")],
+        ),
+        (
+            "no-gate-shipped",
+            """\
+- id: 4
+  title: "No gate -> shipped on artifact"
+  rubric: "shipped-no-gate"
+  citation: []
+  rubric_check:
+    artifact_exists: "true"
+    gate_script: ""
+""",
+            [("4", SHIPPED, "No gate -> shipped on artifact")],
+        ),
+        (
+            "multi-criterion-order",
+            """\
+- id: 10
+  title: "first shipped"
+  rubric: "x"
+  citation: []
+  rubric_check:
+    artifact_exists: "true"
+    gate_script: ""
+- id: 11
+  title: "second in progress"
+  rubric: "x"
+  citation: []
+  rubric_check:
+    artifact_exists: "true"
+    gate_script: "false"
+- id: 12
+  title: "third planned"
+  rubric: "x"
+  citation: []
+  rubric_check:
+    artifact_exists: "false"
+    gate_script: ""
+""",
+            [
+                ("10", SHIPPED, "first shipped"),
+                ("11", PROGRESS, "second in progress"),
+                ("12", PLANNED, "third planned"),
+            ],
+        ),
+        (
+            "gate-key-absent-shipped",
+            """\
+- id: 6
+  title: "Gate key absent -> shipped on artifact"
+  rubric: "x"
+  citation: []
+  rubric_check:
+    artifact_exists: "true"
+""",
+            [("6", SHIPPED, "Gate key absent -> shipped on artifact")],
+        ),
+        (
+            "multiline-shell-no-base64",
+            # Regression for the base64-drop refactor: a multi-line shell
+            # snippet must reach /bin/bash intact via subprocess. If a
+            # future refactor reintroduces a TSV/base64 hop without
+            # honoring newlines, this fixture goes red.
+            """\
+- id: 7
+  title: "Multiline shell snippet passes through"
+  rubric: "x"
+  citation: []
+  rubric_check:
+    artifact_exists: |
+      n=2
+      m=2
+      test "$n" -eq "$m"
+    gate_script: ""
+""",
+            [("7", SHIPPED, "Multiline shell snippet passes through")],
+        ),
+    ]
+
+    failures = 0
+    for label, spec_yaml, expected in cases:
+        ok, msg = _fixture(spec_yaml, expected)
+        if ok:
+            sys.stdout.write(f"ok: {label}\n")
+        else:
+            sys.stdout.write(f"FAIL [{label}]:{msg}\n")
+            failures += 1
+
+    sys.stdout.write("\n")
+    if failures:
+        sys.stdout.write(f"{failures} test(s) failed.\n")
+        return 1
+    sys.stdout.write("All cut-criteria tests passed.\n")
+    return 0
+
+
+# ---------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="cut_criteria.py",
+        description="Unified status + render + check for docs/cut-criteria.yaml.",
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_status = sub.add_parser("status", help="Print id<TAB>status<TAB>title rows.")
+    p_status.add_argument("--spec", default=DEFAULT_SPEC)
+    p_status.set_defaults(func=cmd_status)
+
+    p_render = sub.add_parser("render", help="Render the markdown to OUT.")
+    p_render.add_argument("--spec", default=DEFAULT_SPEC)
+    p_render.add_argument("--out", default=DEFAULT_OUT)
+    p_render.set_defaults(func=cmd_render)
+
+    p_check = sub.add_parser(
+        "check",
+        help="Diff the rendered markdown against OUT; non-zero on drift.",
+    )
+    p_check.add_argument("--spec", default=DEFAULT_SPEC)
+    p_check.add_argument("--out", default=DEFAULT_OUT)
+    p_check.set_defaults(func=cmd_check)
+
+    p_test = sub.add_parser("test", help="Run the fixture-based regression suite.")
+    p_test.set_defaults(func=cmd_test)
+
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())