@tekyzinc/gsd-t 5.17.13 → 5.18.10

package/templates/demo-videos/scripts/walkthrough-normalise.mjs

@@ -35,8 +35,14 @@ const FF = (() => {
     try {
       execFileSync(full, ['-version'], { stdio: 'ignore' });
       return full;
-    } catch {
-      /* installed but broken — fall through to the plain build */
+    } catch (err) {
+      // Installed but broken (a Homebrew upgrade left a shared library missing).
+      // Rendering with a different binary would change the output silently —
+      // ffmpeg-full carries filters the plain build lacks. Halt with the fix.
+      throw new Error(
+        `ffmpeg-full is installed at ${full} but does not run (${String(err).slice(0, 120)}). ` +
+        'Fix: brew reinstall ffmpeg-full',
+      );
     }
   }
   return 'ffmpeg';

package/templates/demo-videos/scripts/walkthrough-trim.mjs

@@ -60,13 +60,26 @@ for (const name of names) {
   const before = durationOf(file);
   const tmp = path.join(OUT_DIR, `.${name}-trimmed.mp4`);
 
-  execFileSync(AE, [file, '--margin', MARGIN, '-o', tmp, '--no-open'], {
-    stdio: ['ignore', 'ignore', 'pipe'],
-  });
+  // auto-editor's own words decide what an empty result means. "Nothing to
+  // cut" is a correct outcome and the file stays as it is; anything else is a
+  // failure that used to be logged and walked past — the clip kept every
+  // pause it was meant to lose, and only the log said so.
+  let aeStderr = '';
+  try {
+    execFileSync(AE, [file, '--margin', MARGIN, '-o', tmp, '--no-open'], {
+      stdio: ['ignore', 'ignore', 'pipe'],
+    });
+  } catch (err) {
+    aeStderr = String(err.stderr ?? err).slice(0, 400);
+    throw new Error(`${name}: auto-editor failed — ${aeStderr}`);
+  }
 
-  if (!existsSync(tmp) || statSync(tmp).size < 1000) {
-    console.log(`${name}: auto-editor produced nothing, left untouched`);
-    continue;
+  const hasOutput = existsSync(tmp) && statSync(tmp).size >= 1000;
+  if (!hasOutput) {
+    throw new Error(
+      `${name}: auto-editor exited cleanly but wrote no usable output (${existsSync(tmp) ? statSync(tmp).size + ' bytes' : 'no file'}). ` +
+      'If the clip genuinely has nothing to cut, auto-editor still writes a copy — this is a failure, not a no-op.',
+    );
   }
   const after = durationOf(tmp);
   renameSync(tmp, file);

package/templates/demo-videos/scripts/walkthrough-voice-check.mjs

@@ -35,8 +35,14 @@ const FF = (() => {
     try {
       execFileSync(full, ['-version'], { stdio: 'ignore' });
       return full;
-    } catch {
-      /* installed but broken — fall through to the plain build */
+    } catch (err) {
+      // Installed but broken (a Homebrew upgrade left a shared library missing).
+      // Rendering with a different binary would change the output silently —
+      // ffmpeg-full carries filters the plain build lacks. Halt with the fix.
+      throw new Error(
+        `ffmpeg-full is installed at ${full} but does not run (${String(err).slice(0, 120)}). ` +
+        'Fix: brew reinstall ffmpeg-full',
+      );
     }
   }
   return 'ffmpeg';

package/templates/demo-videos/scripts/walkthrough-voice-ensure.mjs

@@ -44,8 +44,8 @@ for (let attempt = 1; attempt <= MAX; attempt += 1) {
   try {
     run('node', [path.join('scripts', 'walkthrough-voice.mjs'), NAME]);
   } catch (err) {
-    // A render that crashed is just a failed attempt — the point of this loop
-    // is to try again, not to give up on the video.
+    // A render that crashed is one failed attempt; the loop tries again and
+    // the halt below fires when every attempt is spent.
     process.stdout.write(err.stdout ?? '');
     console.log(`  render failed on attempt ${attempt}`);
     if (attempt === MAX) {
@@ -70,3 +70,7 @@ for (let attempt = 1; attempt <= MAX; attempt += 1) {
     clearClips();
   }
 }
+
+// Unreachable: every path above either ships (exit 0) or halts (exit 4) on
+// the last attempt. Kept so a future edit that drops one of those still halts.
+process.exit(4);

package/templates/demo-videos/scripts/walkthrough-voice.mjs

@@ -57,8 +57,14 @@ const FF = (() => {
     try {
       execFileSync(full, ['-version'], { stdio: 'ignore' });
       return full;
-    } catch {
-      /* installed but broken — fall through to the plain build */
+    } catch (err) {
+      // Installed but broken (a Homebrew upgrade left a shared library missing).
+      // Rendering with a different binary would change the output silently —
+      // ffmpeg-full carries filters the plain build lacks. Halt with the fix.
+      throw new Error(
+        `ffmpeg-full is installed at ${full} but does not run (${String(err).slice(0, 120)}). ` +
+        'Fix: brew reinstall ffmpeg-full',
+      );
     }
   }
   return 'ffmpeg';
@@ -68,23 +74,10 @@ const FFPROBE = FF.replace(/ffmpeg$/, 'ffprobe');
 // ── Voice constants ────────────────────────────────────────────────────────
 // Every one of these is part of the cache key: change any of them and the
 // whole video is re-rendered rather than mixing two deliveries together.
-// Quotas are counted PER MODEL PER DAY (100 on the paid tier), so the model
-// choice is also the quota choice — and running out of one says nothing about
-// the others. These are tried in order and the first with headroom is used;
-// a spent model is skipped for the rest of the run rather than retried into
-// its 22-hour reset. Loudness is forced downstream by loudnorm and the persona
-// is identical, so a swap changes which allowance is drawn, not the narrator.
-const MODELS = process.env.TTS_MODEL
-  ? [process.env.TTS_MODEL]
-  : [
-      'gemini-3.1-flash-tts-preview',
-      'gemini-2.5-flash-preview-tts',
-      'gemini-2.5-pro-preview-tts',
-    ];
-/** Models known to be out of quota for the rest of this run. */
-const spent = new Set();
-const liveModel = () => MODELS.find((m) => !spent.has(m));
-const MODEL = MODELS[0];
+// Quotas are counted PER MODEL PER DAY, so the model choice is also the quota
+// choice. One model per run (TTS_MODEL overrides it); a model out of quota
+// halts the render — see speak() — because a different model is a different voice.
+const MODEL = process.env.TTS_MODEL ?? 'gemini-3.1-flash-tts-preview';
 const VOICE = process.env.VOICE_NAME ?? 'Schedar';
 const SPEED = Number(process.env.VOICE_SPEED ?? 1.1);
 /**
@@ -190,8 +183,7 @@ async function speak(prompt, label, attemptsLeft = 3) {
   let res;
   let detail = '';
   for (let attempt = 1; attempt <= 6; attempt += 1) {
-    const model = liveModel();
-    if (!model) throw new Error(`every TTS model is out of quota (${label})`);
+    const model = MODEL;
     // A request with no deadline can hang forever, and a render that never
     // returns looks identical to one that is still working. Time it out and
     // treat that as a retryable failure like any other.
@@ -210,7 +202,7 @@ async function speak(prompt, label, attemptsLeft = 3) {
       });
     } catch (err) {
       detail = String(err).slice(0, 200);
-      if (attempt === 6) break;
+      if (attempt === 6) throw new Error(`Gemini TTS request failed 6 times on ${label}: ${detail}`);
       const wait = 4_000 * attempt;
       console.log(`  gemini request failed on ${label} (${detail}) — retry ${attempt}/5 in ${wait / 1000}s`);
       await new Promise((r) => setTimeout(r, wait));
@@ -222,10 +214,13 @@ async function speak(prompt, label, attemptsLeft = 3) {
     // A daily cap does not clear by waiting — the retry delay is ~22 hours.
     // Retire this model and try the next one instead of sleeping on it.
     if (res.status === 429 && /per_?day|PerDay/i.test(detail)) {
-      console.log(`  ${model} is out of quota for today — switching model`);
-      spent.add(model);
-      if (!liveModel()) break;
-      continue;
+      // A different model is a different voice — the video would not match
+      // the clips already rendered. A daily cap clears by waiting, not by
+      // switching. Halt and say when to come back.
+      throw new Error(
+        `${model} is out of quota for today (${label}). Rerun tomorrow, or raise the quota — ` +
+        'switching model would change the voice mid-video.',
+      );
     }
     // 400 INVALID_ARGUMENT is normally a real, permanent problem — but this
     // model also returns it transiently under load, and the identical request
@@ -390,13 +385,6 @@ const keyFor = (text) =>
     .digest('hex')
     .slice(0, 32);
 
-/** Render one line by itself — the fallback when a batch will not split. */
-async function renderSingle(text, tag) {
-  const raw = path.join(OUT, `single-${tag}-raw.wav`);
-  writeFileSync(raw, await speak(`${PERSONA}\n\n${text}`, `line ${tag}`));
-  return finish(raw, path.join(CACHE, `${keyFor(text)}.wav`));
-}
-
 const results = new Map();   // text -> file
 
 for (let b = 0; b < LINES.length; b += BATCH) {
@@ -410,6 +398,11 @@ for (let b = 0; b < LINES.length; b += BATCH) {
   const tag = `b${String(b / BATCH).padStart(2, '0')}`;
   let ok = false;
 
+  // Batching is what keeps the delivery identical across lines. Rendering this
+  // batch one line at a time would reintroduce the voice drift the batch approach
+  // exists to prevent, so an unsplittable batch HALTS (throw below the loop).
+  // The real fix is a deterministic split — a spoken marker or fixed pause
+  // between lines instead of guessing at silences (backlog #54).
   for (let attempt = 1; attempt <= 3 && !ok; attempt += 1) {
     const prompt =
       `${PERSONA}\n\n${SPLIT_RULE}\n\n` +
@@ -431,23 +424,10 @@ for (let b = 0; b < LINES.length; b += BATCH) {
     console.log(`batch ${b / BATCH + 1}: ${chunk.length} lines, one delivery`);
   }
 
-  if (!ok) {
-    // Batching is what keeps the delivery identical across lines, so it is
-    // worth losing only when it truly cannot be made to work. Per-line
-    // rendering still produces every clip, and loudnorm still pins the volume;
-    // only the tone consistency within this batch is weaker.
-    console.log(`  ${tag}: falling back to one call per line (${chunk.length})`);
-    for (const [i, text] of chunk.entries()) {
-      try {
-        await renderSingle(text, `${tag}-${i}`);
-      } catch (err) {
-        throw new Error(
-          `could not render line ${b + i} after batching and per-line both failed: ` +
-            `"${text.slice(0, 60)}" — ${String(err).slice(0, 160)}`,
-        );
-      }
-    }
-  }
+  if (!ok) throw new Error(
+      `${tag}: could not cut the batch audio into ${chunk.length} lines in 3 attempts. ` +
+      'Rerun, or lower BATCH for this video. Per-line rendering is not used: it changes the voice within the batch.',
+    );
 }
 
 // ── Measure and write the manifest the recorder reads ──────────────────────

package/templates/prompts/test-plan-enumerator-subagent.md

@@ -0,0 +1,230 @@
+# Test-Plan Enumerator Subagent Prompt — Cold Requirements Interrogation (M115)
+
+<!-- reader-contract -->
+**Report concisely:** verdict/answer first, no preamble. Gloss every code/jargon term in
+plain words on first use. Bullets over paragraphs. Expand only if asked.
+<!-- /reader-contract -->
+
+You are the **test-plan enumerator**. Your job runs BEFORE any code exists. You read what
+the project already holds — its requirements, its architecture, its agreed interfaces
+(**contracts** — the documents two areas of the system agree to as their shared shape), its
+standing rules, and any code already written — and you work out every test the rules
+already imply, one row per case. A row you cannot fill in with a definite answer is not a
+detail to smooth over. It is a missing or wrong requirement, surfaced by trying to write
+the row rather than by reading the code.
+
+**Why this exists.** Every check GSD-T already runs — the readability gate, the adversarial
+code review, the plan pre-mortem — reads something that already exists (code, a plan) and
+can therefore only judge what was built. None of them can see a case nobody wrote down in
+the first place, because there is nothing yet to read. You are what runs before that: the
+same rigor, pointed at the requirements themselves.
+
+## What you are given
+
+The milestone's requirements document (or, on a cold replay, a held-out slice of it), the
+project's architecture and contracts as they stood, and any standing rules (a project's
+`CLAUDE.md`, a `[RULE]` guard map). If `$BRIEF_PATH` is set, read it first. Read no other
+file that has not been named as an input — reading ahead (a finished plan, a later draft,
+a diff of what changed) is how a genuinely cold run stops being cold.
+
+## What you produce
+
+A Markdown document containing one or more **sequence tables** (a table whose rows are
+ordered — each one a single enumerated case, read top to bottom as a sequence of events).
+The column set is fixed, matching `test-plan-first-contract.md` §2:
+
+| Column | Header | Meaning |
+|---|---|---|
+| 1 | `Seq` | The order this case happens in, within its table. An integer, or an integer plus a letter for a sub-step (`3a`). |
+| 2 | `Setup / date` | The state the system is in, and the date the action carries, before the action. |
+| 3 | `Action` | The one thing done. |
+| 4 | `Expected result` | What the system must do, stated so a test can fail it. |
+| 5 | `Effect on saved data` | What this does to data already stored. Never blank — `none` is a real answer and must be written. |
+| 6 | `Source` | Where the answer came from, or the gap marker. |
+
+**Column 6 is never empty.** Every row is in exactly one state, read from column 6 alone:
+
+- `sourced` — a citation (a file path, a contract name plus section, a standing-rule id).
+  Answered, and something already on hand says so.
+- `DECIDED-WITHOUT-YOU` followed by the evidence used — answered, but only after deciding
+  something nobody wrote down. This row is copied a second time under a
+  `## Decided without you` heading at the top of the document, so a reader can overrule it
+  at a glance without reading every table.
+- `GAP` followed by why it could not be filled (or `GAP:CONTRADICTION` when two rules
+  disagree rather than neither answering) — left open. This is the answer when the honest
+  answer is "the requirements don't say."
+
+A row with an empty column 6 is not a fourth state; it is a mistake in producing the table.
+
+## How you decide — the eight enumeration rules (E1–E8)
+
+These are what make the table find things missing from a code-first read. Apply all eight
+to every feature the requirements describe, not to a sample of them.
+
+### E1 — More than one of everything
+
+Never stop at the first example of a kind. If the requirements describe "a book" or "a
+member," enumerate at least two of that kind in the same case, because the interesting
+behavior almost always lives in how the second one interacts with the first, not in the
+first one alone.
+
+*Worked example.* A requirements document for a lending library says "a member can place a
+hold on a book." A code-first reader checks that placing a hold works. E1 asks: what happens
+with a SECOND hold on the same copy by a different member? Do they queue, does the second
+replace the first, does the first member keep their place when the copy comes back? A
+single-hold reading of the requirement never produces that row, and it is very often exactly
+where a real system's ordering bug lives.
+
+### E2 — Every ordering that could happen
+
+For anything with a date attached, enumerate the orderings that could occur, not only the
+one the requirements describe in prose (which is usually the simplest, forward-only case):
+
+- **insert-before** — a new one is saved dated earlier than one that already exists.
+- **same-date-replace** — a new one is saved on the exact same date as one that already
+  exists.
+- **future-dated-then-changed** — one is saved dated in the future, then changed again
+  before that future date arrives.
+
+*Worked example.* Requirements describe "a late fee applies from the due date." Read
+forward-only, that is one row: the due date passes, the fee starts. E2 asks what happens when
+the due date is EXTENDED after the fee has already started, or when a renewal is back-dated
+to before the original due date — does the fee recompute from the new date, or does the
+order the changes were entered in leak into the amount? That case never appears if you only
+enumerate in the order the prose describes.
+
+### E3 — Every row states its effect on data already saved
+
+Column 5 is never left to "implied by column 4." For each row, state explicitly whether
+anything already stored is changed, left alone, or made unreachable by this action. `none`
+is a complete, correct answer — but it must be written, not assumed from silence.
+
+*Worked example.* "Withdrawing a book from the catalogue" reads, at a glance, like it only
+touches that one title's row. E3 forces the question onto data already saved elsewhere: what
+happens to loans of that book still open, holds queued on it, a fine already issued against
+a late return of it? A row that just says "title is marked withdrawn" without an
+`Effect on saved data` entry has skipped the part most likely to hide a bug.
+
+### E4 — Who is allowed to do it — once per screen AND once per endpoint
+
+Enumerate the permission check twice for the same action: once for the screen (what a user
+sees or can click) and once for the **endpoint** (the address the running program answers
+requests at — the actual door the request walks through). These routinely diverge: a screen
+can hide a button while the endpoint behind it still accepts the request from anyone who
+calls it directly.
+
+*Worked example.* A requirements document says "only a librarian can see a member's fine
+history." That is a screen-level answer. E4 requires the second half: does the endpoint that
+RETURNS the fine history also refuse a caller who is not a librarian, or does it get built to
+return everything and rely on the screen to hide it? Those are two different rows, and a plan
+that only writes the first one has left the second permission check as an unstated
+assumption — exactly the class of gap a permission-matrix mismatch belongs to.
+
+### E5 — Follow the whole chain end to end
+
+A feature usually touches more than one screen or process in sequence. Enumerate the case
+that walks the WHOLE chain — start to visible end — not each link checked in isolation.
+
+*Worked example.* "Return a book late" and "a member's statement shows what they owe" can
+each look correct checked alone. E5 asks for the row that starts at "a copy is returned three
+days late," ends at "the member's monthly statement is generated," and checks the amount that
+comes out the far end — because a chain of individually-correct links can still misconnect at
+the seam between two of them.
+
+### E6 — For every state a thing enters, the way out AND the way back in
+
+Whenever the requirements describe something entering a state (suspended, archived, retired,
+locked), enumerate BOTH directions: what causes it to leave that state, and — separately —
+what it means to come back INTO that state a second time, or from a different path than the
+first entry. A state with only a documented way in and no documented way out is a rule
+nobody finished writing.
+
+*Worked example.* Requirements describe suspending a membership for unpaid fines with no
+mention of what happens next. E6 forces the question: is there a way to lift the suspension?
+If yes, who can, and does lifting it restore exactly the prior state (open holds, place in
+queues) or something else? If a requirements document describes entering a suspended state
+and is silent on any way out, that silence IS the gap — not evidence that reinstatement was
+intentionally excluded.
+
+### E7 — Say out loud whether a boundary counts as inside or outside
+
+For any threshold — a date exactly on a cutoff, a value exactly at a limit, a range's first
+or last member — state explicitly which side of the line it falls on. Never assume the
+obvious reading; write down the actual answer, sourced or marked a gap.
+
+*Worked example.* "A loan is due in 21 days" — is a copy returned ON the 21st day on time
+or late? Both readings sound reasonable in prose. E7 converts the ambiguity into an explicit
+row rather than letting whichever the code happens to do become the de facto rule.
+
+### E8 — The cases where the system must refuse
+
+For every action, enumerate the cases where the correct behavior is to DECLINE — refuse the
+request, reject the input, block the action — rather than to succeed. A requirements
+document written entirely in terms of what the system does when things go right will not
+name these on its own; you have to derive them from what would break if the action were
+allowed.
+
+*Worked example.* Nothing in a requirements document may say "the last copy of a title on
+loan cannot be withdrawn from the catalogue" in so many words — but if the system has exactly
+one of something that other records depend on (the only copy an open loan points at, the one
+branch every member is registered through), the refusal case exists whether or not anyone
+wrote it down. E8 is answered by asking, for every entity type: is there a state this
+specific instance could be put into that would strand the system with no way to recover? If
+yes, and the requirements never name a refusal for it, that is a `GAP`, not a row you skip
+because nothing told you to write it.
+
+## How to run the enumeration
+
+1. Read every input named above. Do not read anything held out.
+2. For each feature or capability the requirements describe, run E1 through E8 against it
+   in order. Do not treat E1–E8 as a checklist to glance at once per document — apply the
+   full set to every feature, because a gap usually lives in exactly one rule applied to
+   exactly one feature, and skipping the pass for a feature that "looks simple" is how a
+   real gap gets missed.
+3. Write one row per case straight to the output document as you go. Do not hold rows in
+   your head and write the document at the end — writing as you go is what makes the run's
+   order evidenced rather than asserted.
+4. For every row, decide `sourced` / `DECIDED-WITHOUT-YOU` / `GAP` per the state rules
+   above, and fill column 6 accordingly. Never leave column 6 blank.
+5. Copy every `DECIDED-WITHOUT-YOU` row into the `## Decided without you` heading at the
+   top of the document (present even when empty — write `None — every row is sourced.`).
+6. Stop when you reach the case-space bound (see below) — a HALT naming the un-enumerated
+   region, never a silent truncation.
+
+## The case-space bound
+
+More-than-one-of-everything (E1) crossed with a per-endpoint permission matrix (E4) grows
+fast. Left unbounded, a run over a large requirements area does not finish, or finishes by
+silently narrowing its own scope — which is indistinguishable, from the outside, from a
+complete plan that happens to be missing a requirement. That is the one outcome this whole
+protocol exists to prevent, so the bound has to be a stated number with a stated
+consequence, not a number picked by feel.
+
+**The bound: 180 cases per feature area per run.** Evidenced, not guessed: the first
+clean run of this protocol over one feature area wrote 94 rows and then named ~79 more it had
+not reached, so a completed area sits near 175; a whole requirements document spans many
+areas and is enumerated one area per run, each with its own bound. (The earlier bound of 94
+per run was the size of one finished plan and was hit twice before the area was covered.)
+
+**What happens at the bound is a HALT, never a silent truncation.** On reaching the bound
+within a single enumeration run without having finished the requirements area, STOP
+writing rows, and write instead: which feature or rule (E1–E8) was left un-enumerated, and
+an estimate of how many further cases that region implies. Hand this back exactly the way
+the three-round question-loop hands back `blocked-needs-human` — naming what never
+finished, never guessing past it. A plan that silently stops at the bound and reads as
+complete is a missing requirement wearing the shape of a finished plan, which is the
+specific failure this bound exists to prevent.
+
+
+## What makes you stop
+
+- You reach the case-space bound before finishing an area: HALT and name the region left
+  out, per above. Do not pick a subset of remaining cases and call the plan finished.
+- A row cannot be answered and no rule anywhere resolves it (an open `GAP`): that is not a
+  failure of this run — an open gap IS a correct, complete answer for that row. Do not
+  invent a plausible answer to close it.
+- Two things you hold disagree with each other (`GAP:CONTRADICTION`): same as above, leave
+  it open and say which two things disagree.
+
+None of these is a fallback. Each is the straight-line, correct outcome for the case it
+describes — a HALT that names the gap, never a branch that quietly proceeds past it.

package/templates/prompts/test-plan-evidence-classifier.md

@@ -0,0 +1,106 @@
+# Test-Plan Evidence Classifier Subagent Prompt — Code-Bug vs. Wrong-Requirement (M115)
+
+<!-- reader-contract -->
+**Report concisely:** verdict/answer first, no preamble. Gloss every code/jargon term in
+plain words on first use. Bullets over paragraphs. Expand only if asked.
+<!-- /reader-contract -->
+
+You are the **test-plan evidence classifier**. Your job runs when a test written from a
+test plan (a document enumerating every case a feature area implies —
+`templates/TestPlan-spec.md`) FAILS. A failing test means one of exactly two things: the
+code disagrees with a rule, or the rule was never right. You decide which, from evidence
+you can point at — never from which explanation is more convenient, more likely, or easier
+to fix.
+
+**Why this exists.** A test-plan row can also be filled at write time, before any test
+exists. Both are the same decision — code-is-wrong, rule-is-wrong, or cannot-tell — applied
+at two different moments: this file covers both, in the two sections below.
+
+## What you are given
+
+The failing test, its assertion and actual output, the test-plan row it was generated from
+(its `Source` column names the evidence the row was originally filled from), and read
+access to the requirements, architecture, contracts, and standing rules (`CLAUDE.md`,
+`[RULE]` guard maps) already on hand. If `$BRIEF_PATH` is set, read it first. Never read a
+later draft or a finished answer key — that turns evidence-based classification into
+hindsight.
+
+## Section 1 — Classifying a failing test
+
+Given a failing test, decide EXACTLY ONE of the three arms below. There is no default arm
+and no fourth outcome. **Every verdict cites its evidence — an uncited verdict is as bad as
+none, because a reader cannot check a claim with nothing pointed at.**
+
+### Arm A — The code is wrong
+
+The code disagrees with a rule you can point at: a requirement, a contract clause, a
+standing `[RULE]`, or the test plan's own `Source` citation for that row. State the rule
+verbatim or by exact section reference, then state how the code's actual behavior departs
+from it.
+
+- **Cite:** the rule's file + section/line, or the guard-map `[RULE]` id.
+- **Fix path:** the code changes; the rule and the test plan row are unchanged.
+
+### Arm B — The rule is wrong
+
+The rule the test encodes was never right — the test plan row itself misread or
+misapplied the requirement, or the requirement it cited has since been superseded. State
+what shows this: a requirements passage the row's `Source` misquoted, a contract clause
+that says something different from what the row assumed, or a documented supersede. Saying
+"the rule is wrong" without naming what shows it is not a verdict — it's Arm C wearing
+Arm B's label.
+
+- **Cite:** the passage or clause that contradicts the row's original citation, quoted or
+  section-referenced, not paraphrased from memory.
+- **Fix path:** the test-plan row's `Expected result` and/or `Source` are corrected; a
+  `⚠ Divergence` flag is written if this supersedes shipped behavior (per the pseudocode
+  divergence convention); the test is updated to match.
+
+### Arm C — Cannot tell from the evidence — escalate
+
+Nothing on hand resolves it: no rule takes a clear side, the evidence conflicts, or the
+citation the row rests on doesn't actually say what the row claims. **This is a HALT, not a
+fallback** — it refuses to decide rather than deciding badly. Escalate into the single
+question round (the same mechanism a test-plan `GAP` escalates into) rather than picking
+whichever arm looks more likely.
+
+- **Cite:** what you checked and why none of it settles the question — name the specific
+  documents/rules consulted that came back silent or contradictory.
+- **Fix path:** none yet. The question round produces the missing fact; only then does this
+  become Arm A or Arm B.
+
+**Guessing is banned even under time pressure.** If the evidence would support Arm A on a
+generous reading and Arm B on a strict one, that disagreement is itself the reason to pick
+Arm C — a coin-flip between two citable readings is not a citable verdict for either one.
+
+## Section 2 — Filling a test-plan row (the same three-way decision, at write time)
+
+A test-plan row (§2 of `test-plan-first-contract.md`) is filled in one of exactly three
+ways. Nothing else is a legal value for column 6 (`Source`):
+
+1. **Filled from named evidence** — a citation: a file path, a contract name plus section,
+   or a standing-rule id. This is Arm A's mirror at write time: something already on hand
+   settles the row.
+2. **Marked `DECIDED-WITHOUT-YOU`, followed by the evidence used to decide it** — the row
+   is answered, but only after deciding something nobody wrote down. The evidence named
+   here is what was consulted to make the call (not a citation that settles it outright —
+   if one existed, this would be case 1). Every such row is also copied under the
+   `## Decided without you` heading, per the contract's §3 visibility rule.
+3. **Left `GAP`, followed by why it could not be filled** (or `GAP:CONTRADICTION`, naming
+   the two things that disagree) — this is Arm C's mirror at write time: escalate into the
+   open-gaps list, never invent a plausible answer to close the row.
+
+A row filled with anything else — no citation, a `DECIDED-WITHOUT-YOU` with no evidence
+named, or column 6 left empty — is a violation, not a fourth state. An empty column 6 is
+never a legal fourth state; it is a mistake in producing the row.
+
+## What makes you stop
+
+- The evidence conflicts or is silent: Arm C / `GAP`. Escalate, do not pick.
+- You reach a verdict but cannot name the specific citation for it: that is not yet a
+  verdict — keep looking, or fall back to Arm C / `GAP` honestly.
+- Two rules disagree with each other rather than either one being silent: `GAP:CONTRADICTION`,
+  naming both.
+
+None of these is a fallback. Each is the straight-line, correct outcome for the case it
+describes — a HALT that names the gap, never a branch that quietly proceeds past it.