@tekyzinc/gsd-t 5.17.13 → 5.18.10

package/bin/gsd-t-traceability-gate.cjs

@@ -51,6 +51,7 @@
  */
 
 const fs = require("node:fs");
+const { walkSections, parseRows, rowState, tableName, REQUIRED_COLUMN_COUNT } = require("./gsd-t-testplan-rows.cjs");
 const path = require("node:path");
 
 // ─── tasks.md parsing ────────────────────────────────────────────────────
@@ -179,6 +180,15 @@ function _acBulletText(lines) {
 // bold forms both match, exactly like the M83 field scan.
 const PSEUDOCODE_SECTION_FIELD_RE = /^\s*[-*]?\s*pseudocode-section\s*:/i;
 
+// ─── M115 A7: plan-row binding (test-plan-first-contract.md §2 + §7) ──────
+//
+// `**Plan-Row**: <TestPlan-doc-title>#<TableName>/Seq-<n>` — an ADDITIONAL way
+// an acceptance line may clear, alongside the existing Files+Test binding.
+// Recognized by the contract §2 row identity: the plan document, a table
+// name, and a Seq. Matched emphasis-agnostically on the BARED line, exactly
+// like every other field scan in this file — never a substring search.
+const PLAN_ROW_FIELD_RE = /^\s*[-*]?\s*plan-row\s*:/i;
+
 /**
  * Parse the `**PseudoCode-Section**: <Title>#<anchor>` citation from a task's
  * lines. Returns { title, anchor } structured segments, or null if absent.
@@ -255,19 +265,94 @@ function docTitleFromFilename(filename) {
   return m ? m[1] : null;
 }
 
+/**
+ * Parse a `**Plan-Row**: <doc>#<TableName>/Seq-<n>` citation (M115 A7,
+ * test-plan-first-contract.md §2 + §7 row identity: plan document + table
+ * name + Seq). Structured segments, never substring-matched — the value is
+ * split path-as-path on the FIRST `#`, then the anchor on the LAST `/`.
+ * Returns { doc, table, seq, raw } or null if the field is absent.
+ */
+function parsePlanRowCitation(lines) {
+  for (const ln of lines) {
+    const bare = _bare(ln);
+    if (!PLAN_ROW_FIELD_RE.test(bare)) continue;
+    const idx = bare.indexOf(":");
+    if (idx < 0) continue;
+    const val = bare.slice(idx + 1).trim();
+    const hash = val.indexOf("#");
+    if (hash < 0) return { doc: val, table: "", seq: "", raw: val, malformed: true };
+    const doc = val.slice(0, hash).trim();
+    const anchor = val.slice(hash + 1).trim();
+    const slash = anchor.lastIndexOf("/");
+    if (slash < 0) return { doc, table: anchor, seq: "", raw: val, malformed: true };
+    const table = anchor.slice(0, slash).trim();
+    const seqPart = anchor.slice(slash + 1).trim();
+    const seqMatch = seqPart.match(/^Seq-(.+)$/i);
+    if (!seqMatch) return { doc, table, seq: "", raw: val, malformed: true };
+    return { doc, table, seq: seqMatch[1].trim(), raw: val, malformed: false };
+  }
+  return null;
+}
+
+/**
+ * Load a single TestPlan doc's real row identities: every `## Table: <name>`
+ * section's `Seq` column values, read structurally (positional table-cell
+ * parsing, never a substring search) — the same discipline as
+ * enumerateSections. Returns Set<"table::seq"> or null if the doc is absent.
+ */
+function loadTestPlanRowIdentities(testPlanDir, docTitle) {
+  // TestPlan docs live in `.gsd-t/test-plans/` — the directory the front door
+  // (commands/gsd-t-test-plan.md) writes to and the verify gate globs
+  // (contract §7, ratified at M115 integrate).
+  //
+  // Red Team M115 (2026-09-03): a doc title is a single path SEGMENT. Anything
+  // else (`../`, a slash, an absolute path) could name a file outside the
+  // test-plans directory, so the resolved path must stay inside it.
+  if (typeof docTitle !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(docTitle)) return null;
+  const root = path.resolve(testPlanDir);
+  const candidate = path.resolve(root, `TestPlan-${docTitle}.md`);
+  if (!candidate.startsWith(root + path.sep)) return null;
+  let md;
+  try { md = fs.readFileSync(candidate, "utf8"); } catch { return null; }
+  // identity -> row state, read through the ONE shared plan reader (fence-aware
+  // for both fence styles, exact six-cell width). Red Team HIGH: a `GAP` row is
+  // an UNANSWERED requirement and must never clear an acceptance criterion;
+  // code-review run 4: a row with an EXTRA cell was read as sourced and cleared
+  // one anyway. A malformed row is its own state and never clears.
+  const identities = new Map();
+  for (const sec of walkSections(md)) {
+    const table = tableName(sec.heading);
+    if (!table) continue; // Open gaps, Sign-off, ... are not tables of identities
+    for (const row of parseRows(sec.lines, sec.startLine)) {
+      if (!row.cells[0]) continue;
+      const id = `${table}::${row.cells[0]}`;
+      // Two rows with one identity: nobody can say which one a citation means, so
+      // neither clears (code-review M115 run 6 — last-write-wins let a later
+      // sourced row overwrite an earlier GAP).
+      if (identities.has(id)) { identities.set(id, "duplicate"); continue; }
+      const state = row.width !== REQUIRED_COLUMN_COUNT ? "malformed" : rowState(row.cells[5]);
+      identities.set(id, state);
+    }
+  }
+  return identities;
+}
+
 /**
  * A task is "behavioral" (subject to the gate) if it declares acceptance
  * criteria — i.e. it promises an observable behavior. Pure-scaffolding tasks
  * with no ACs are out of scope (nothing to trace).
  */
-function assessTask(task) {
+function assessTask(task, opts = {}) {
   const lines = task.lines;
   // M87 D2: every task may carry a section citation, AC-bearing or not — capture
   // it regardless so non-behavioral coverage tasks still count toward citations.
   const sectionCitation = parseSectionCitation(lines);
+  // M115 A7: every task may ALSO carry a plan-row citation, AC-bearing or not,
+  // captured unconditionally for the same reason.
+  const planRowCitation = parsePlanRowCitation(lines);
   const hasAc = hasMultiField(lines, AC_FIELD_RE);
   if (!hasAc) {
-    return { title: task.title, behavioral: false, violations: [], sectionCitation };
+    return { title: task.title, behavioral: false, violations: [], sectionCitation, planRowCitation };
   }
 
   // Underscore-preserving values for path/runner scans (Red Team recheck HIGH).
@@ -297,17 +382,33 @@ function assessTask(task) {
 
   const isHeadline = lines.some((ln) => HEADLINE_FIELD_RE.test(_bare(ln)));
 
+  // M115 A7 — ADDITIVE ONLY: an acceptance line may ALSO clear via a plan-row
+  // binding. This arm fires ONLY when a citation is actually present AND it
+  // resolves to a real row in a real loaded plan — never as a fallback the
+  // old Files+Test path drops into when it comes up short. `opts.resolvePlanRow`
+  // is supplied by the caller (runGate) already knowing which plan docs are in
+  // scope; when no resolver is supplied (e.g. a bare assessTask() call, or a
+  // milestone with no test plan), planRowClears stays false and every existing
+  // violation kind fires exactly as it did before this change.
+  let planRowClears = false;
+  if (planRowCitation && !planRowCitation.malformed && typeof opts.resolvePlanRow === "function") {
+    planRowClears = !!opts.resolvePlanRow(planRowCitation);
+  }
+
   const violations = [];
-  if (!hasFiles) {
+  if (!hasFiles && !planRowClears) {
     violations.push({ kind: "ac-without-path", detail: "task declares acceptance criteria but no **Files** implementing path — an unbacked promise." });
   }
-  if (!hasTest) {
+  if (!hasTest && !planRowClears) {
     violations.push({ kind: "ac-without-test", detail: "task declares acceptance criteria but names no test (Test field, test path, or runner) — the dead-code class: it can pass vacuously / never be exercised." });
   }
   if (isHeadline && !hasImplPath) {
     violations.push({ kind: "headline-without-impl", detail: "HEADLINE task has no non-test implementing path — the milestone's reason to exist is not bound to real code (the M5 AC-6 dead-code failure)." });
   }
-  if (isHeadline && !hasTest) {
+  // A resolved plan row IS the headline's test (the suite is generated from the
+  // plan — contract §7.1); the impl-path rule above is untouched, a test row is
+  // not an implementation (Red Team M115 run 4, MEDIUM).
+  if (isHeadline && !hasTest && !planRowClears) {
     violations.push({ kind: "headline-without-test", detail: "HEADLINE task has no test proving the milestone's core capability is delivered (the missing >100MB-fixture failure)." });
   }
 
@@ -317,6 +418,8 @@ function assessTask(task) {
     isHeadline,
     hasFiles, hasTest, hasImplPath,
     sectionCitation,
+    planRowCitation,
+    planRowClears,
     violations,
   };
 }
@@ -518,6 +621,50 @@ function runGate({ projectDir = process.cwd(), milestone = null, tasksFile = nul
     return { ok: false, exitCode: 64, milestone, reason: "no-tasks-files", tasks: [], violations: [] };
   }
 
+  // M87 D2 dir resolution, hoisted ABOVE the task loop unchanged (M115 A7):
+  // this computation depends only on (projectDir, pseudocodeDir), never on
+  // taskResults, so moving it earlier changes nothing about what it resolves
+  // to — it only makes the resolved dir available to the plan-row resolver
+  // below. Containment: an explicit --pseudocode-dir must resolve INSIDE the
+  // project tree (the D2 test legitimately points it at test/fixtures/, also
+  // inside the project; an out-of-tree `../../evildocs` is refused). The
+  // default `.gsd-t/pseudocode/` is always in-tree. A refused dir → empty doc
+  // set (logged skip, never an out-of-tree read), same fail-closed shape as a
+  // missing dir.
+  let resolvedPcDir = pseudocodeDir || path.join(projectDir, ".gsd-t", "pseudocode");
+  if (pseudocodeDir) {
+    const resolvedProject = path.resolve(projectDir);
+    const candidate = path.resolve(resolvedProject, pseudocodeDir);
+    if (candidate !== resolvedProject && !candidate.startsWith(resolvedProject + path.sep)) {
+      resolvedPcDir = null; // out-of-tree → no docs loaded (fail-closed)
+    } else {
+      resolvedPcDir = candidate;
+    }
+  }
+
+  // M115 A7: resolve a plan-row citation against `.gsd-t/test-plans/` — the
+  // in-tree directory the front door writes plans to and the verify gate
+  // globs (contract §7). A milestone with no test plan (dir or doc simply
+  // absent) makes every citation resolve to false — planRowClears stays
+  // false and the task takes EXACTLY its pre-A7 path. Never a fallback: this
+  // only ever WIDENS what clears, it is not consulted unless a citation was
+  // actually written.
+  const testPlanDir = path.join(path.resolve(projectDir), ".gsd-t", "test-plans");
+  const planRowIdentityCache = new Map(); // docTitle -> Map<"table::seq", state>|null
+  function resolvePlanRow(citation) {
+    if (!citation.doc || !citation.table || !citation.seq) return false;
+    if (!planRowIdentityCache.has(citation.doc)) {
+      planRowIdentityCache.set(citation.doc, loadTestPlanRowIdentities(testPlanDir, citation.doc));
+    }
+    const identities = planRowIdentityCache.get(citation.doc);
+    if (!identities) return false;
+    const state = identities.get(`${citation.table}::${citation.seq}`);
+    // An open GAP row is the plan saying "nobody has answered this yet". Letting
+    // it clear an acceptance criterion would recreate the dead-deliverable shape
+    // this gate exists to catch (Red Team M115 HIGH).
+    return state === "sourced" || state === "decided";
+  }
+
   const taskResults = [];
   const violations = [];
   let behavioralCount = 0;
@@ -525,7 +672,7 @@ function runGate({ projectDir = process.cwd(), milestone = null, tasksFile = nul
     let md;
     try { md = fs.readFileSync(f.tasksPath, "utf8"); } catch { continue; }
     for (const t of parseTasks(md)) {
-      const r = assessTask(t);
+      const r = assessTask(t, { resolvePlanRow });
       r.domain = f.domain;
       taskResults.push(r);
       if (r.behavioral) behavioralCount++;
@@ -536,21 +683,6 @@ function runGate({ projectDir = process.cwd(), milestone = null, tasksFile = nul
   }
 
   // M87 D2: section-citation coverage over the in-scope PseudoCode docs.
-  // Containment: an explicit --pseudocode-dir must resolve INSIDE the project
-  // tree (the D2 test legitimately points it at test/fixtures/, also inside the
-  // project; an out-of-tree `../../evildocs` is refused). The default
-  // `.gsd-t/pseudocode/` is always in-tree. A refused dir → empty doc set
-  // (logged skip, never an out-of-tree read), same fail-closed shape as a missing dir.
-  let resolvedPcDir = pseudocodeDir || path.join(projectDir, ".gsd-t", "pseudocode");
-  if (pseudocodeDir) {
-    const resolvedProject = path.resolve(projectDir);
-    const candidate = path.resolve(resolvedProject, pseudocodeDir);
-    if (candidate !== resolvedProject && !candidate.startsWith(resolvedProject + path.sep)) {
-      resolvedPcDir = null; // out-of-tree → no docs loaded (fail-closed)
-    } else {
-      resolvedPcDir = candidate;
-    }
-  }
   const pseudocodeDocs = resolvedPcDir ? loadPseudocodeDocs(resolvedPcDir) : new Map();
   const coverage = assessSectionCoverage(taskResults, pseudocodeDocs);
   for (const v of coverage.violations) violations.push(v);
@@ -631,5 +763,6 @@ module.exports = {
   runGate, parseTasks, assessTask, listTasksFiles,
   parseSectionCitation, slugifyHeading, enumerateSections, docTitleFromFilename,
   loadPseudocodeDocs, assessSectionCoverage,
+  parsePlanRowCitation, loadTestPlanRowIdentities,
   _internal: { fieldValue, TEST_PATH_RE },
 };

package/bin/gsd-t.js

@@ -1812,6 +1812,13 @@ const GLOBAL_BIN_TOOLS = [
   // M109 — project-history reader + rule miner, used by /gsd-t-setup to write a
   // project CLAUDE.md from what actually happened rather than from a template.
   "gsd-t-project-history.cjs", "gsd-t-rule-mine.cjs",
+  // M115 (contract test-plan-first-contract.md §5) — the A2 shape gate and the A5
+  // non-convergence halt for the test-plan-first command. Both are dispatched by
+  // `bin/gsd-t.js` ("testplan-lint" / "testplan-halt" cases) AND by the verify
+  // workflow's gate wiring, so an omission here is the same propagation-gap class
+  // caught four times before ([[project_global_bin_propagation_gap]]). Also in
+  // PROJECT_BIN_TOOLS below — both lists, both tools.
+  "gsd-t-testplan-lint.cjs", "gsd-t-testplan-halt.cjs", "gsd-t-testplan-rows.cjs",
 ];
 
 // Directories under bin/ that must ship whole. A runner whose parts stay behind
@@ -3574,6 +3581,11 @@ const PROJECT_BIN_TOOLS = [
   // Plus the verify-gate lint (gsd-t-verify-gate.cjs invokes it via __dirname,
   // so it must sit alongside the gate in the project's bin/).
   "gsd-t-doc-marker.cjs", "gsd-t-env-registry.cjs", "gsd-t-env-registry-check.cjs",
+  // M115 (contract test-plan-first-contract.md §5) — the A2 shape gate and the A5
+  // non-convergence halt. The verify workflow's project-local runCli resolves these,
+  // and /gsd-t-test-plan calls them directly — same propagation-gap class as the
+  // graph tools above. Also in GLOBAL_BIN_TOOLS — both lists, both tools.
+  "gsd-t-testplan-lint.cjs", "gsd-t-testplan-halt.cjs", "gsd-t-testplan-rows.cjs",
 ];
 
 // Files that older versions of this installer copied into project bin/ but
@@ -5999,6 +6011,36 @@ if (require.main === module) {
       });
       process.exit(res.status == null ? 1 : res.status);
     }
+    case "testplan-lint": {
+      // M115 (contract §5) — `gsd-t testplan-lint (--doc <f> | --dir <d>)` thin dispatcher
+      // to the A2 test-plan shape gate (owner: deterministic-gates). Sibling of
+      // `pseudocode-style` — same proven shape (0 clean / 4 violations / 64 bad input).
+      const { spawnSync } = require("child_process");
+      const js = path.join(__dirname, "gsd-t-testplan-lint.cjs");
+      if (!require("node:fs").existsSync(js)) {
+        error(`gsd-t-testplan-lint.cjs not found at ${js} — reinstall GSD-T (contract test-plan-first-contract.md §5)`);
+        process.exit(1);
+      }
+      const res = spawnSync(process.execPath, [js, ...args.slice(1)], {
+        stdio: "inherit",
+      });
+      process.exit(res.status == null ? 1 : res.status);
+    }
+    case "testplan-halt": {
+      // M115 (contract §5) — `gsd-t testplan-halt check --doc <f> --round <n>` thin
+      // dispatcher to the A5 non-convergence halt (owner: halt-convergence). Reuses
+      // bin/gsd-t-loop-ledger.cjs read-only for the repeated-symptom cap.
+      const { spawnSync } = require("child_process");
+      const js = path.join(__dirname, "gsd-t-testplan-halt.cjs");
+      if (!require("node:fs").existsSync(js)) {
+        error(`gsd-t-testplan-halt.cjs not found at ${js} — reinstall GSD-T (contract test-plan-first-contract.md §5)`);
+        process.exit(1);
+      }
+      const res = spawnSync(process.execPath, [js, ...args.slice(1)], {
+        stdio: "inherit",
+      });
+      process.exit(res.status == null ? 1 : res.status);
+    }
     case "archive-domains": {
       // Backlog #40 — `gsd-t archive-domains --domains a,b --archive <dir>` deterministic
       // archive+sweep of a completed milestone's domain dirs (complete-milestone Step 7).

package/commands/cpua.md

@@ -115,11 +115,29 @@ Verify the output shows `+ @tekyzinc/gsd-t@{NEW_VERSION}`. If publish fails:
 ## Step 6: Update global install + propagate to projects
 
 ```bash
-npm install -g @tekyzinc/gsd-t@{NEW_VERSION}
+G="$(npm root -g)/@tekyzinc/gsd-t"
+# 1. Install by TARBALL URL, not by version spec. Right after `npm publish`, npm keeps
+#    the pre-publish package listing cached and `@tekyzinc/gsd-t@{NEW}` returns ETARGET
+#    for minutes while `npm view` already shows the version (v5.17.14, 2026-09-03).
+#    The tarball URL bypasses the cached listing and is deterministic.
+npm install -g "https://registry.npmjs.org/@tekyzinc/gsd-t/-/gsd-t-{NEW_VERSION}.tgz"
+# 2. VERIFY ON DISK — never trust npm's exit code for this step. On v5.17.13 `npm install -g`
+#    reported success and left the OLD version in place; `update-all` then ran from the
+#    stale global, told 32 projects they were "already current", and overwrote a
+#    hand-patched project file with the old build.
+ON_DISK=$(node -p "require('$G/package.json').version")
+if [ "$ON_DISK" != "{NEW_VERSION}" ]; then
+  echo "global install is $ON_DISK, expected {NEW_VERSION} — removing and reinstalling"
+  npm uninstall -g @tekyzinc/gsd-t; rm -rf "$G"; npm cache clean --force
+  npm install -g "https://registry.npmjs.org/@tekyzinc/gsd-t/-/gsd-t-{NEW_VERSION}.tgz"
+  ON_DISK=$(node -p "require('$G/package.json').version")
+  [ "$ON_DISK" = "{NEW_VERSION}" ] || { echo "HALT: global install still $ON_DISK"; exit 1; }
+fi
+# 3. Only now propagate.
 gsd-t update-all 2>&1 | tail -30
 ```
 
-Use `npm install -g @tekyzinc/gsd-t@{NEW_VERSION}` (NOT `npm update -g`) — npm rejects update for some legacy version strings (e.g., `3.19.00` is invalid semver because of the leading-zero patch). Pinning to the exact version sidesteps this.
+Never `npm update -g` (npm rejects it for legacy version strings like `3.19.00`). After `update-all`, prove propagation by `ls`/`grep` of one NEW or CHANGED file in a real registered project — the "copied N tool(s)" line is a report, not proof. Note: `update-all` also overwrites `~/.claude/commands/*.md` from the package, so THIS file's source of truth is `commands/cpua.md` in the GSD-T repo; an edit made only in `~/.claude/commands/` is lost on the next propagation.
 
 ## Step 7: Report
 

package/commands/gsd-t-help.md

@@ -31,6 +31,7 @@ MILESTONE WORKFLOW                                          [auto] = in wave
   milestone           Define a new milestone
   partition    [auto] Decompose milestone into domains + contracts
   plan         [auto] Create atomic task lists per domain
+  test-plan           Enumerate the case space from requirements, before any code/tests exist
   impact       [auto] Analyze downstream effects before execution
   execute      [auto] Run tasks (solo or team mode)
   test-sync    [auto] Sync tests with code changes
@@ -235,6 +236,14 @@ Use these when user asks for help on a specific command:
 - **Note (M26)**: Pre-mortem step now also reads rules.jsonl for historical failure patterns via getPreMortemRules
 - **Note (M38)**: Conversational use cases (formerly `/gsd-t-prompt`, `/gsd-t-brainstorm`, `/gsd-t-discuss`) are now handled by the Smart Router's conversational mode — just describe what you want via `/gsd` or plain text.
 
+### test-plan
+- **Summary**: Enumerate every test case a requirements document implies, BEFORE any code or tests exist — an unfillable row is surfaced as a missing or wrong requirement, not smoothed over.
+- **Auto-invoked**: No (standalone, on-demand; runs in-session like `architect`)
+- **Args**: `/gsd-t-test-plan [requirements path]` (before-mode, default) or `/gsd-t-test-plan --after` (re-enumerate against built code, classify failures by cited evidence)
+- **Creates**: `.gsd-t/test-plans/TestPlan-[FeatureArea].md`
+- **Use when**: A requirements document exists (or a milestone is about to be planned) and you want its case space interrogated for gaps before any test is written; or after a milestone is built, to classify test failures as code-bug vs. wrong-requirement from cited evidence only.
+- **Note (M115)**: Every open row is batched into ONE question round — never a drip. Three rounds without closure, or the same failure signature twice running, HALTs via `gsd-t testplan-halt` rather than filling an open row with anything plausible. `gsd-t testplan-lint` gates the plan's shape before it is presented, and again as a FAIL-blocking `verify` gate.
+
 ### impact
 - **Summary**: Analyze downstream effects of planned changes
 - **Auto-invoked**: Yes (in wave, between plan and execute)

package/commands/gsd-t-migrate-logging.md

@@ -4,6 +4,7 @@ Scaffolds the two framework-default logging streams — **trace** (transient deb
 
 ## What this does
 
+- **Declared streams are skipped.** If `.gsd-t/logging-manifest.json` names a stream's `module` (e.g. `{ "audit": { "module": "server/src/audit.ts", "store": { "kind": "postgres", "table": "tb_audit_log" }, "retention": "indefinite" } }`), that stream already exists and is NOT scaffolded — reported under `declared`. This is how a project with a real audit table at a path the checker does not guess adds only the missing trace stream, with no second audit module written beside the first. An unreadable manifest is an error, not "no manifest".
 - Copies the trace module template (`templates/logging/trace-module.template.ts`) to `src/logging/trace.ts` — **only if that file does not already exist**.
 - Copies the audit module template (`templates/logging/audit-module.template.ts`) to `src/logging/audit.ts` — **only if that file does not already exist**.
 - Distills the per-project trace category / audit action schema from the project's own plan (when `--plan` is given) into `.gsd-t/logging-schema.json` — never confabulated; an unstated category/action is a gap, not a guess.

package/commands/gsd-t-test-plan.md

@@ -0,0 +1,85 @@
+# GSD-T: Test-Plan-First — Enumerate the Case Space Before Tests Exist
+
+You run the M115 test-plan-first interrogation, in-session, as the lead agent — the same
+pattern as `/gsd-t-architect`. There is no separate Workflow phase script for this command:
+every deliverable it orchestrates is a deterministic gate (`bin/gsd-t-testplan-lint.cjs`,
+`bin/gsd-t-testplan-halt.cjs`) or a subagent protocol file you Read and follow directly, per
+`.gsd-t/contracts/test-plan-first-contract.md`.
+
+**Why this exists.** Every check GSD-T runs today reads something that already exists (code,
+a plan) and can only judge what was built. This runs BEFORE any code exists: it enumerates
+every case the requirements already imply, so a missing or wrong requirement is caught as a
+gap in a row, not as a bug found later.
+
+## Argument Parsing
+
+Parse `$ARGUMENTS`:
+- **No flag (before-mode, default)** — enumerate from what is already held (requirements,
+  architecture, contracts, standing rules, any code that exists), before tests are written.
+- **`--after`** — the same enumeration run against already-built code: run the plan's rows
+  as tests, classify each failure by cited evidence.
+- **First positional** (either mode) — the requirements document or feature-area slice to
+  enumerate. Defaults to `docs/requirements.md`.
+
+## Before-mode (default)
+
+0. **Where the plan lives.** Write the plan to `.gsd-t/test-plans/TestPlan-[FeatureArea].md`
+   — the sibling location of `.gsd-t/pseudocode/PseudoCode-[Title].md`, one stage earlier in
+   the pipeline. This is what the verify workflow's gate globs.
+1. **Read the enumeration protocol.** `Read templates/prompts/test-plan-enumerator-subagent.md`
+   in full — the E1-E8 rules that define the case space. Do not restate it here; follow it.
+2. **Read the mold.** `Read templates/TestPlan-spec.md` — the section set and six-column
+   row schema a plan must have (frozen shape: `.gsd-t/contracts/test-plan-first-contract.md`
+   §2-§3).
+3. **Enumerate.** Apply E1-E8 to the target requirements document. Fill each row from named
+   evidence (`sourced`), or mark it `DECIDED-WITHOUT-YOU` (self-answered — also grouped
+   under `## Decided without you`), or leave it `GAP`/`GAP:CONTRADICTION` (open). Never fill
+   an unanswerable row with something plausible — that is the one failure this command
+   exists to prevent.
+4. **Batch every open row into ONE question round (A4).** Collect every `GAP`/
+   `GAP:CONTRADICTION` row from every table, ask them together in a single round, fold the
+   answers in together, then re-enumerate to confirm closure. **Never ask one question at a
+   time as each answer arrives — a drip defeats the batching the reviewer's attention
+   depends on.**
+5. **Round cap: three rounds, never a fourth.** After folding each round's answers,
+   re-enumerate and run `gsd-t testplan-halt check --doc <plan path> --round <n>` (falls
+   back to `node bin/gsd-t-testplan-halt.cjs check ...` locally). If it reports
+   `halted: true` — either round three still has open rows, or the same failure signature
+   has recurred across two consecutive rounds — STOP: hand back `blocked-needs-human`
+   naming every row the tool lists as never settled, rather than continuing with anything
+   left open. A repeated symptom means the belief behind an earlier answer is wrong, not
+   that the row needs a third try.
+6. **Fold closed answers into `docs/requirements.md`.**
+7. **Gate for shape.** Run `gsd-t testplan-lint --doc <plan path> --json` (falls back to
+   `node bin/gsd-t-testplan-lint.cjs --doc <plan path> --json` locally). A non-zero exit
+   means the plan is malformed — fix it before presenting; never present a plan that fails
+   its own gate.
+8. **Present for sign-off.** Show the plan (or a summary with the file path) and stop for
+   the user's review. **Tests are generated from the rows only after sign-off** — this
+   command does not write tests itself.
+
+## `--after` mode
+
+1. Read the same enumerator protocol and re-enumerate against the requirements as they
+   stand today, against the built code.
+2. Run the resulting rows as tests against the code.
+3. For each failure, `Read templates/prompts/test-plan-evidence-classifier.md` and follow it
+   to classify the failure as code-bug or wrong-requirement, from cited evidence only —
+   never a default arm.
+4. Fix code-bugs directly (small, local). A wider refactor a classification surfaces is
+   spilled to `.gsd-t/techdebt.md` rather than done in this pass.
+5. Re-run `gsd-t testplan-lint --doc <plan path> --json` on the updated plan before
+   presenting the result.
+
+## Document Ripple
+
+Fold closed answers into `docs/requirements.md`. Log a Decision Log entry in
+`.gsd-t/progress.md` for the enumeration round(s) run and their outcome. A wider refactor
+found in `--after` mode goes to `.gsd-t/techdebt.md`, not into this pass's diff.
+
+## Next Up
+
+`/gsd-t-plan` — turn the signed-off plan's rows into tasks.
+
+**Also available:**
+- `/gsd-t-execute` — when run in `--after` mode against a milestone already mid-build.

package/commands/gsd.md

@@ -88,6 +88,7 @@ When the same request could fit multiple commands at different scales:
 - **Requires its own milestone with domains** → `milestone` or `project`
 - **Needs investigation before fixing** → `debug` (not `quick`)
 - **Spec/requirements to verify against code** → `gap-analysis` (not `scan`)
+- **Enumerate every test case a requirements doc implies, BEFORE any code or tests exist** → `test-plan` (not `plan` — `plan` writes task lists from an already-partitioned milestone; `test-plan` interrogates the requirements themselves for gaps)
 
 ### Design-to-code routing:
 
@@ -179,7 +180,7 @@ Where `{last-command}` is:
 
 **CRITICAL: `{command}` and `{last-command}` MUST be a real GSD-T command slug — never a free-form description.**
 
-Valid command slugs: `quick`, `debug`, `feature`, `execute`, `milestone`, `project`, `scan`, `gap-analysis`, `plan`, `partition`, `impact`, `integrate`, `verify`, `test-sync`, `complete-milestone`, `wave`, `status`, `populate`, `setup`, `init`, `health`, `log`, `pause`, `resume`, `prd`, `backlog-add`, `backlog-list`, `backlog-promote`, `promote-debt`, `triage-and-merge`, `version-update`, `version-update-all`, `design-decompose`, `design-build`, `design-audit`, `design-review`
+Valid command slugs: `quick`, `debug`, `feature`, `execute`, `milestone`, `project`, `scan`, `gap-analysis`, `plan`, `partition`, `impact`, `integrate`, `verify`, `test-sync`, `test-plan`, `complete-milestone`, `wave`, `status`, `populate`, `setup`, `init`, `health`, `log`, `pause`, `resume`, `prd`, `backlog-add`, `backlog-list`, `backlog-promote`, `promote-debt`, `triage-and-merge`, `version-update`, `version-update-all`, `design-decompose`, `design-build`, `design-audit`, `design-review`
 
 **WRONG ❌** — do not do this:
 ```

package/docs/requirements.md

@@ -1001,6 +1001,24 @@ Contract: `.gsd-t/contracts/unproven-assumption-doctrine-contract.md` v1.0.0 STA
 | REQ-M90-06 (SC-SELF-OBEDIENCE) | M90's own artifacts show the doctrine applied to itself: discuss produced a sourced approach, pseudocode signed off before code, premises re-verified on disk, and any ≥3-cycle same-signature non-convergence triggered a recorded premise re-examination (not a variant patch). Every §6 [RULE] traces to an enforcement point (orphan rule FAILS the guard-map test). | m90-d-contract-doctrine-integrate | D4-T1/T7 | complete (M90) |
 | REQ-M90-07 (SC-RESEARCH-GATE) | Plan is mechanically blocked until discuss emits a sourced approach with ≥1 external citation per detection mechanism. | m90-d-contract-doctrine-integrate (doctrine contract) | D4-T1 | satisfied (discuss `.gsd-t/discuss/M90-approach-sourced.md`) |
 
+## M115 Test-Plan-First Requirements Interrogation (complete - v5.18.10)
+
+Before any code exists, enumerate every test case a milestone's requirements imply into a reviewable sequence-table document; every row nobody can fill in is a requirements gap, surfaced by trying to write the row rather than by reading code. Origin: the TimeTracking v1.27 rate-ledger review (2026-09-01/02), whose test plan found three unwritten requirements.
+
+Contract: `.gsd-t/contracts/test-plan-first-contract.md` v1.1.0 STABLE · Pseudocode: `.gsd-t/pseudocode/PseudoCode-TestPlanFirst.md` · Command: `/gsd-t-test-plan`
+
+| ID | Requirement | Domain | Tests | Status |
+|----|-------------|--------|-------|--------|
+| REQ-M115-A1 (BLIND-REPLAY) | Cold enumeration from the pre-review requirements alone (generic protocol, no answer-key material, memory-free context) surfaces the three gaps the human review found; scored against pre-registered hit conditions held out from the enumerator. Condition 1 re-written to the gap's shape (rate changes silently alter issued invoices) with a recorded ⚠ Divergence, David-approved 2026-09-03. | enumerator-core | `test/m115-a1-blind-replay.test.js` (6) over `.gsd-t/scan/m115-cold-enumeration-blind-scoped.md` | **complete 2026-09-03** |
+| REQ-M115-A2 (SHAPE-LINT) | `gsd-t testplan-lint (--doc \| --dir)` exits 0 clean / 4 violations / 64 bad input over the six-column mold; unknown markers, blank Seq, blank source, wrong width, duplicate identities, fenced fakes are violations; mandatory negative tests | deterministic-gates | `test/m115-a2-testplan-lint.test.js` (14), `test/m115-verify-fixes.test.js` | **complete 2026-09-03** |
+| REQ-M115-A3 (SELF-ANSWER-VISIBLE) | Every DECIDED-WITHOUT-YOU row is grouped under one `## Decided without you` heading exactly matching the rows, fence-aware, so a reviewer can overrule any at a glance | plan-visibility | `test/m115-a3-self-answer-visibility.test.js` (6) | **complete 2026-09-03** |
+| REQ-M115-A4 (ONE-ROUND) | Open rows are asked in ONE batched question round per loop, never one at a time | plan-visibility / front-door-wiring | `commands/gsd-t-test-plan.md` protocol; `test/m115-a8-front-door-test-plan.test.js` | **complete 2026-09-03** |
+| REQ-M115-A5 (NON-CONVERGENCE-HALT) | Three question rounds with rows still open, or the same open-row set twice running, HALTS with `blocked-needs-human` naming every open row; rounds are counted per plan and per round (idempotent re-check), through `gsd-t-loop-ledger.cjs` read-only | halt-convergence | `test/m115-a5-non-convergence-halt.test.js` (13), `test/m115-verify-fixes.test.js` | **complete 2026-09-03** |
+| REQ-M115-A6 (EVIDENCE-OR-HALT) | In `--after` mode every failing case is classified code-bug / wrong-requirement / cannot-tell from cited evidence — three arms, no default branch; cannot-tell joins the question round | plan-visibility | `test/m115-a6-evidence-or-halt.test.js` (21) | **complete 2026-09-03** |
+| REQ-M115-A7 (PLAN-ROW-BINDING) | An acceptance criterion may bind to `**Plan-Row**: <Plan>#<Table>/Seq-<n>` in `.gsd-t/test-plans/`; only a sourced or decided row of exactly six cells with a unique identity clears; GAP, malformed, duplicate or escaped-path rows never do; M83/M87 behaviour byte-identical | deterministic-gates | `test/m115-a7-traceability-plan-row.test.js` (17), `test/m83-*.test.js`, `test/m87-*.test.js` unchanged | **complete 2026-09-03** |
+| REQ-M115-A8 (FRONT-DOOR) | `/gsd-t-test-plan` is reachable: command file, `/gsd` router case, both bin-tool registries, CLI dispatch, verify-gate wiring with a NAMED skip distinguishable from a clean run; the front-door test was RED before wiring and GREEN after | front-door-wiring | `test/m115-a8-front-door-test-plan.test.js` (15) | **complete 2026-09-03** |
+| REQ-M115-R1 (ONE-READER) | Every consumer of a test plan (lint, halt, traceability gate) reads sections and rows through `bin/gsd-t-testplan-rows.cjs` — both fence styles, exact six-cell width, one classifier, one heading pattern — so the three cannot drift apart again | verify (7 runs) | `test/m115-verify-fixes.test.js` (29), `test/verify-gate-tools-propagated.test.js` (sibling requires ship) | **complete 2026-09-03** |
+
 ## Updated Functional Requirements (scan findings - v4.0.27)
 
 The deep scan identified functional deficiencies not captured in previous requirements. These are recorded here for tracking:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "5.17.13",
+  "version": "5.18.10",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 54 slash commands with headless-by-default workflow spawning, unattended supervisor relay with event stream, graph-powered code analysis, real-time agent dashboard, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",

package/templates/CLAUDE-global.md

@@ -256,6 +256,7 @@ Every GSD-T project gets TWO logging streams scaffolded by default at `gsd-t-ini
 - **Storage is stack-adaptive and human-approval-gated** — `bin/gsd-t-logging-scaffolder.cjs` detects the stack, presents real alternatives, and STOPS for approval; it never silently picks a backend (the one sanctioned pause against the Level-3 full-auto default).
 - **Trace and audit NEVER collapse into one stream.** A trace envelope carrying audit markers (`before`/`after`/`actor`/`action`) or vice-versa is a contract violation and a `gsd-t-verify` FAIL — see each contract's §no-collapse boundary.
 - **Brownfield migration**: `gsd-t migrate-logging <projectDir>` scaffolds both streams into an EXISTING project additively — it never modifies or deletes a pre-existing file. See `commands/gsd-t-migrate-logging.md`.
+- **Streams that already exist somewhere the checker does not guess** (an audit table behind `server/src/audit.ts`, say) are DECLARED in `.gsd-t/logging-manifest.json` — `{ "audit": { "module": "server/src/audit.ts", "store": { "kind": "postgres", "table": "tb_audit_log" }, "retention": "indefinite" } }`. The declaration is checked (a path that does not exist FAILs), an external store's rows are not inspected offline (reported in `notes`, the module surface is the enforced evidence), and `migrate-logging` skips a declared stream so it never scaffolds a twin.
 
 ## Orthogonal Validation Triad (Mandatory)
 
@@ -607,6 +608,7 @@ Add `**Also available:**` with `- /gsd-t-{alt} — {desc}` lines if alternatives
 | `partition` | `plan` | `discuss` (if complex) |
 | `discuss` | `plan` | |
 | `plan` | `execute` | `impact` (if risky) |
+| `test-plan` | `plan` | `execute` (if `--after` mode against a milestone already mid-build) |
 | `impact` | `execute` | |
 | `execute` | `test-sync` | |
 | `test-sync` | `verify` | `integrate` (if multi-domain) |

package/templates/TestPlan-spec.md

@@ -0,0 +1,78 @@
+# TestPlan-{Title}
+
+**Project:** {Project Name} · **Date:** {Date}
+
+One sentence: what feature area this plan enumerates, and which requirements document it
+was enumerated from.
+
+---
+
+<!--
+  ─────────────────────────────────────────────────────────────────────────────
+  HOW TO WRITE THIS  (delete this comment block in the real instance)
+  ─────────────────────────────────────────────────────────────────────────────
+
+  This is the blank mold every test plan (a document that enumerates every
+  case a feature area implies, so a reviewer approves DIRECTION before
+  TESTS exist) is filled from. It is the sibling of `PseudoCode-spec.md` —
+  same job, one section earlier in the pipeline: PseudoCode maps intended
+  BEHAVIOR before code; this maps intended CASES before tests.
+
+  Full row schema, marker literals, and self-answered-visibility rule:
+  `.gsd-t/contracts/test-plan-first-contract.md` §2–§3 (frozen — do not
+  restate or diverge from it here; this file shows the shape in place).
+
+  Section order below is FIXED. A plan missing any of the five, or with
+  them out of order, does not satisfy the contract's row schema.
+
+  Name the real file `TestPlan-[FeatureArea].md` — never a milestone id —
+  the way a PseudoCode doc is named for its subject, not its milestone.
+  ─────────────────────────────────────────────────────────────────────────────
+-->
+
+## Decided without you
+
+Every row anywhere in this document whose `Source` column carries the marker
+`DECIDED-WITHOUT-YOU` is copied here a second time, so a reviewer can overrule any of them
+by reading this one group and nowhere else. Present always — even with nothing under it.
+
+- `{table name}` Seq `{n}` — {the decision made} — evidence: {what was used to decide it}
+
+When there are none:
+
+> None — every row is sourced.
+
+---
+
+## Table: {Feature or Capability Name}
+
+| Seq | Setup / date | Action | Expected result | Effect on saved data | Source |
+|---|---|---|---|---|---|
+| 1 | {system state and date before the action} | {the one thing done} | {what must happen, stated so a test can fail it} | {what changes in data already stored — `none` is a real, written answer} | `docs/requirements.md#{anchor}` |
+| 2 | {system state and date before the action} | {the one thing done} | {what must happen} | {effect, or `none`} | DECIDED-WITHOUT-YOU — {evidence used} |
+| 3 | {system state and date before the action} | {the one thing done} | {what must happen} | {effect, or `none`} | GAP — {why it could not be filled} |
+
+Add one `## Table:` section per coherent sub-area within this feature. Each keeps its own
+`Seq` numbering starting at 1.
+
+---
+
+## Open gaps
+
+Every `GAP` (and `GAP:CONTRADICTION`) row across every table, collected here in one list.
+This is what the single question round is built from — a reviewer answers this list, not
+the tables.
+
+- `{table name}` Seq `{n}` — {why it could not be filled}
+
+When there are none:
+
+> None — every row is answered.
+
+---
+
+## Sign-off
+
+| Signed by | Date |
+|---|---|
+| {name} | {Date} |

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

@@ -28,8 +28,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';