refact(comments): state the mechanism, not the incident

Every comment that invoked a 'law' (50 word-boundary sites across 28
tracked files) now states what is going on and why, in terms that
transfer to any project: gate twins drift until one side greenlights
what the other refuses; a tag re-points while a digest pins; a
restrictive engine behavior belongs to the runtime that imposed it and
must be re-tested, not inherited; a speculative head is tensors in the
file, not a flag; snapshot links dangle where the container resolves
them; exit 0 is a clean stop to systemd, so a self-exiting daemon on
on-failure goes dark reporting success. Event narratives and dates are
gone from these comments; the mechanics carry the argument.

Behavior-identical: bash -n, py_compile, yaml parse, full bats suite
408/408 green. One symbol rename rides along (stack script local
scale_law -> scale_contract, with its log text).

tests/frank_archon_unit.bats

@@ -13,10 +13,10 @@
 # the serve script ENFORCES it, the served window is what models.yml must
 # quote, the host-networking contract (no --publish), the image gate on a
 # name@sha256 ref, the .rad payload gate with its size floor, the
-# chat-template override mount, the self-healing law (the run returns before
-# the engine is up, so the serve script must wait on the container for
-# Restart=always to mean anything), the deployer's false-green MainPID check,
-# the vendored hfget fetch path (no token for this ungated repo), and the
+# chat-template override mount, the self-healing contract (`podman run`
+# returns before the engine is up, so the serve script must stay attached
+# for Restart=always to mean anything), the deployer's false-green MainPID
+# check, the vendored hfget fetch path (no token for this ungated repo), and the
 # client contract (reasoning auto -> reasoning_content; models.yml maps the
 # field on the harness side, not here).
 # The serve script is EXECUTED against fixtures (stub podman, stub device
@@ -253,11 +253,11 @@ serve_run() {
     [ "$ml" -ge 177356 ]
     # Concurrency: 2 slots x the served window is the capacity contract, and
     # the fused TP all-reduce is declared over seqs x (1 + spec) = 6 rows,
-    # under the 25-row bound at which the wht6 wire stays bit-exact. The
-    # "seqs 2 cannot boot" law belongs to the retired tcclaviger vLLM fork
-    # (torch.compile query_start_loc constraint, 2026-10-02); radiance booted
-    # seqs 2 in the fp8-native era and the 2026-10-06 sweep had seqs 2 and 3
-    # tied inside the +-3% noise floor.
+    # under the 25-row bound at which the wht6 wire stays bit-exact. A
+    # "this slot count cannot boot" refusal is per-runtime (compiler shape
+    # specialization rejects counts the engine running here accepts), so it
+    # must be re-tested, not inherited; measurements here put seqs 2 and 3
+    # inside each other's noise floor.
     grep -q '^FRANK_ARCHON_MAX_SEQS=2$' "$ENV_FILE"
     grep -q '^FRANK_ARCHON_TP=2$' "$ENV_FILE"
     grep -q '^FRANK_ARCHON_TP_WIRE=wht6$' "$ENV_FILE"
@@ -265,8 +265,8 @@ serve_run() {
     # expert_tiered placement: vram_weights + the pinned host pool serve the
     # per-rank resident set TOGETHER, so cutting the VRAM slab to pay for the
     # KV pool moves the pool with it. KV is UNQUANTIZED bf16 (the engine takes
-    # only bf16|fp8 — no per-tensor K/V split), the PLE n-gram table is pinned
-    # in host RAM per Frank's law.
+    # only bf16|fp8 — no per-tensor K/V split), the PLE n-gram table rides
+    # pinned host RAM per the placement knob.
     grep -q '^FRANK_ARCHON_PLACEMENT=expert_tiered$' "$ENV_FILE"
     grep -q '^FRANK_ARCHON_HOST_POOL_MIB=44928$' "$ENV_FILE"
     grep -q '^FRANK_ARCHON_VRAM_WEIGHTS_MIB=[1-9]' "$ENV_FILE"

tests/frank_dragoon_unit.bats

@@ -10,11 +10,11 @@
 # exact strings the engine reads: the image DIGEST, the checkpoint/n-gram/
 # vision file names AND byte counts inside the /models mount, and the
 # tokenizer's flat-file shape (a HF cache snapshot's symlinks dangle inside
-# the container). A serve gate and a deployer gate that disagree is the
-# 2026-10-01 crash-loop; both sides are pinned here, plus the one engine
-# law the card is emphatic about: HALOGEN_SPEC_ADAPT=0 — the default
-# adaptive policy silently disables the MTP head per request and HALVES
-# decode.
+# the container). A serve gate and a deployer gate that disagree let a
+# deploy pass what the unit would refuse, so both sides are pinned here —
+# plus the one engine behavior the card is emphatic about:
+# HALOGEN_SPEC_ADAPT=0 — the default adaptive policy silently disables the
+# MTP head per request and HALVES decode.
 #
 # Everything is tested from what an operator or supervisor can observe —
 # the command line podman would run, the exit code, the deployer's error
@@ -117,10 +117,11 @@ good_env() {
 
 @test "the head stays on: adaptive spec must stay 0 and the window shape pinned" {
     # The card is emphatic: the default adaptive policy turns the MTP head
-    # off for whole requests after low acceptance and HALVES decode. The
-    # two-slot law does NOT carry over from the 27B engine — on this line
-    # batching and speculation coexist (the card's quickstart ships 2
-    # slots WITH the head), so 2 is concurrent capacity, not a tax.
+    # off for whole requests after low acceptance and HALVES decode. A
+    # "slots > 1 disables drafting" restriction belongs to the engine
+    # generation that imposed it — on this line batching and speculation
+    # coexist (the card's quickstart ships 2 slots WITH the head), so 2 is
+    # concurrent capacity, not a tax.
     grep -qE '^HALOGEN_SPEC_ADAPT=0$' "$ENV_FILE"
     grep -qE '^HALOGEN_KV_SLOTS=2$' "$ENV_FILE"
     # The cap/timeout pair is coupled (FLAGS.md table): a request at the
@@ -186,7 +187,7 @@ good_env() {
 
 @test "the serve script refuses a checkpoint of the wrong byte count" {
     # A truncated curl exit-0 artifact must not boot; the Hub's byte
-    # count is the contract (fleet fetch law).
+    # count is the contract, any other size is a broken artifact.
     podman_stub
     good_env
     run env PATH="$TEST_TMP/bin:$PATH" "${GOOD_ENV[@]}" \
@@ -287,16 +288,16 @@ $(cat "$TEST_TMP/serve.log")"
     ! grep -q 'PODMAN wait' "$TEST_TMP/serve.log"
 }
 
-@test "the shipped env keeps the harness fit law inside the ceiling" {
+@test "the shipped env keeps the harness fit margin inside the ceiling" {
     # 262144 (the checkpoint's native window) is the per-slot hard ceiling
     # (a longer prompt is a 400 naming the limit, never a silent
     # truncation). The harness clamps max_tokens = min(45056, 217088 − est
     # − 4096), compacts at 85 % of its declared 217088 window, and its
     # chars/4 est UNDER-counts the rendered prompt by ~3 % on code/agent
-    # traffic (measured 4,450 tokens at est 152,938 on 2026-10-07 — with
-    # window == ceiling, every request over ~146k est was a guaranteed
-    # 400 before compaction could fire at 85 %). The 45k gap between the
-    # harness window and the engine ceiling must absorb that error at
+    # traffic — so a harness window equal to the engine ceiling would make
+    # every long request a guaranteed 400 before compaction could fire.
+    # The 45k gap between the harness window and the engine ceiling must
+    # absorb that error at
     # both monotone maxima of est + budget (est ≤ 217088 − 4096):
     #   full budget at the compaction threshold: 1.03*184524 + 45056
     #   clamped budget at the clamp's zero point: 1.03*212992 + 0

tests/llm_deploy_gates.bats

@@ -35,8 +35,8 @@ teardown() { sandbox_teardown; }
 }
 
 @test "the dragoon handler refuses a symlinked tokenizer file" {
-    # The flat-tokenizer law: a HuggingFace cache snapshot links its
-    # members, and the link dangles inside the container mount.
+    # Snapshot layouts link their members into place, and the link dangles
+    # inside the container mount — only regular files are servable.
     rm "$STAGE/models/tokenizer/vocab.json"
     ln -s /nowhere/vocab.json "$STAGE/models/tokenizer/vocab.json"
     run_handler dankclaw frank-dragoon

tests/llm_gates.bats

@@ -1,11 +1,11 @@
 #!/usr/bin/env bats
 # Seam: the shared artifact gates every LLM endpoint runs before it starts.
 #
-# The fleet law these encode: a serve script and the deployer must refuse the
-# SAME missing/truncated artifact, and they must refuse it the same way,
-# because the 2026-10-01 crash-loop was exactly those two gates disagreeing
-# mid-cutover (green deploy, red unit). The library is the one place the
-# refusal lives; both callers source it.
+# The rule these encode: a serve script and the deployer must refuse the
+# SAME missing/truncated artifact, and they must refuse it the same way.
+# Two hand-written copies of the same gates drift apart until a deploy
+# passes what the unit would refuse; the library is the one place the
+# refusal lives, and both callers source it.
 #
 # Everything here is observable: arguments in, exit status and stderr out.
 # Nothing inspects the library's internals.

tests/llm_units.bats

@@ -85,9 +85,9 @@ unit_repo_path() {
     # Restart=always, not on-failure. Every endpoint here is a container
     # runner (podman run) or a server whose front end can exit 0 on a
     # control-plane event; systemd treats exit 0 as a CLEAN stop and
-    # on-failure leaves the endpoint dark until the next boot, with the unit
-    # reporting success. frank-archon learned this on 2026-10-04; the fleet
-    # law is that no LLM unit may ship the weaker policy.
+    # on-failure leaves the endpoint dark until the next boot, with the
+    # unit reporting success. No LLM unit may ship the weaker policy: a
+    # single endpoint on on-failure is a daemon that goes dark silently.
     local unit
     while IFS= read -r unit; do
         grep -qx 'Restart=always' "$unit" || {

tests/service_inventory.bats

@@ -125,8 +125,8 @@ PYEOF
 }
 
 @test "inventory: the node-exporter unit is a per-host rendered template" {
-    # Rank 6: the two node-exporter quadlets were a MIRROR pair kept in
-    # step by a comment. The render is now the law on both hosts.
+    # Both quadlets are rendered artifacts: the render — not a hand-edited
+    # mirror kept in step by a comment — defines the unit on every host.
     for host in dankclaw dankserver; do
         run bash -c "cd '$REPO_ROOT' && python3 scripts/service-map.py render node-exporter-unit --host $host | \
             diff -u $host/observability/quadlet/node-exporter.container -"