@tekyzinc/gsd-t 3.18.12 → 3.18.17

package/CHANGELOG.md

@@ -2,6 +2,57 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [3.18.17] - 2026-04-23
+
+### Fixed — `npm test` picks up `worker-sim.js` fixture
+
+- **`test/fixtures/m44-proof/worker-sim.js`** was being globbed by `node --test`'s default test-directory matcher (anything under `test/` with a `.js` extension), and failed because the fixture requires `OUT_DIR` to be set. The fixture now exits `0` when env vars are absent instead of `2` — it's a worker fixture, not a test. Full suite back to 2016/2016 green. Required to unblock the v3.18.16 publish.
+
+## [3.18.16] - 2026-04-23
+
+### Added — Proof measurement `--visualize` flag
+
+- **`bin/m44-proof-measure.cjs --visualize`** writes synthetic spawn-plan files into the project's `.gsd-t/spawns/` directory as each simulated worker launches and calls `markTaskDone` + `markSpawnEnded` when they finish, so the M44 D9 parallelism panel (`scripts/gsd-t-transcript.html`, endpoint `/api/parallelism`) renders the fan-out live. Off by default — the unflagged measurement still writes spawn-plans only under the temp fixture root. Enables end-to-end visualizer observation of the dispatcher without burning API tokens.
+- **Reproducibility**: three consecutive 20s-worker runs (13:08, 13:09, 13:27 local) produced identical `T_par / T_seq ≈ 0.251`, `speedup ≈ 3.98×`, `parallelism_factor ≈ 3.97`, `parallelism_factor_mode: "live"` with `activeWorkers: 4` for the full 20s parallel window. Panel transitions IDLE → live → IDLE confirmed by `/api/parallelism` polling.
+
+## [Unreleased] — v3.19.00 pending
+
+### Measured — Dispatcher T/2 criterion (backlog #15, leg 1 of 2)
+
+- **`bin/m44-proof-measure.cjs`** runs a falsifiable measurement of the v3.19.00 parallel dispatcher using a synthetic spawner (`test/fixtures/m44-proof/worker-sim.js`) injected into `runDispatch` via `opts.spawnHeadlessImpl`. Fixture (`test/fixtures/m44-proof/fixture.tasks.md`): 4 file-disjoint tasks with explicit `- touches:` sub-bullets (D5 disjointness requirement). Each worker sleeps `WORKER_DURATION_MS` (default 8000ms) then writes a JSON `.done` marker — zero LLM calls, zero network, zero side effects outside `OUT_DIR`. **Result**: T_par = **8111.1 ms**, T_seq = **32146.1 ms**, speedup **3.96×**, parallelism_factor **3.95** (ideal = 4), dispatch overhead **8.2 ms**. Criterion `T_par ≤ T_seq/2` → **MET ✓**. Report JSON at `.gsd-t/m44-proof-report.json`. This proves the dispatcher fans out concurrently; it does NOT prove N Claude workers produce correct code in T/N (a separate experiment, deferred to a follow-up backlog item).
+
+### Pending — Zero-compaction criterion (backlog #15, leg 2 of 2)
+
+- **NOT YET MEASURED.** Requires an unattended supervisor run over a workload that historically would have triggered mid-run `/compact`, producing zero `type:"compaction_post_spawn"` rows in `.gsd-t/metrics/compactions.jsonl` under the fully-wired v3.19.00 surface (`ca20477` supervisor→planner + `799a8af` single-instrument + `19eb3eb` D9 observability panel). Existing 81 rows in the compactions log contain 0 `compaction_post_spawn` entries, but the only post-19eb3eb unattended state predates the D9 landing and is therefore not a valid sample.
+- **`v3.19.00` tag deferred** until the zero-compaction leg completes. Per user standing directive `feedback_measure_dont_claim.md`: "milestones with measurable success criteria are not complete until measurement is run AND reported."
+
+## [3.18.15] - 2026-04-23
+
+### Fixed — Supervisor false-failed marker (M45 follow-up)
+
+- **`bin/headless-exit-codes.cjs::mapHeadlessExitCode` polarity discipline** — the pre-fix matcher did `lower.includes("tests failed")` / `"verification failed"` / `"context budget exceeded"`, which fired on free-form narration like `"0 tests failed"`, `"no tests failed"`, and quoted phrases inside worker output. During the M45 run the worker's clean output contained `"tests failed"` 6× in healthy prose, flipping its mapped exit code 0 → 1 and causing the supervisor to finalize `status=failed` despite the milestone having been completed and archived. The matchers now require either a non-zero numeric count (`/([1-9]\d*)\s+(?:tests?|specs?|assertions?|examples?|suites?)\s+failed\b/i`), a structured terminal marker (`/^FAIL[:\s]/m`, Jest-style `/^Tests:\s+\d+\s+failed/m`), or a line-boundary / sentence-start anchor for free-form verification/context-budget phrases. 27 new polarity regression tests in `test/m45-fix-headless-exit-polarity.test.js`; all existing `headless.test.js` assertions preserved.
+- **`commands/gsd-t-unattended-watch.md` Step 3 reconciliation** — when the supervisor PID file is absent AND `state.status=failed` AND a fresh milestone archive exists under `.gsd-t/milestones/` (mtime ≥ supervisor `startedAt`), the watch tick now renders a reconciled success report noting the archive as the source of truth instead of the contradictory ✅-cleanly-finalized + failed-status block the previous logic would emit. Raw final report preserved for genuinely failed runs with no archive.
+
+## [3.18.14] - 2026-04-23
+
+### Added — M45 Conversation-Stream Observability
+
+- **Orchestrator dialog visible in the transcript viewer** — new hook `scripts/hooks/gsd-t-conversation-capture.js` (SessionStart + UserPromptSubmit + Stop + opt-in PostToolUse via `GSD_T_CAPTURE_TOOL_USES=1`) writes typed NDJSON frames to `.gsd-t/transcripts/in-session-{sessionId}.ndjson` for every human↔Claude turn. The visualizer's left rail now lists those entries with a `💬 conversation` badge alongside the `▶ spawn` entries, so users can watch their own dialog in the same surface as spawned work.
+- **Compact marker fallback target-selection** — `scripts/gsd-t-compact-detector.js::findActiveTranscript` now prefers a fresh spawn NDJSON when one has been modified within 30s, and falls back to the most recent `in-session-*.ndjson` otherwise. Mid-conversation `/compact` events land in the correct transcript instead of a random stale spawn file.
+- **New contract** `.gsd-t/contracts/conversation-capture-contract.md` v1.0.0 — documents the frame schema (`session_start` / `user_turn` / `assistant_turn` / `tool_use`), file-naming (`in-session-` prefix as the viewer + compact-detector discriminator), hook entry points, session-id source + fallback, and 16 KB content cap.
+- **Settings.json hook wiring documented** — `templates/CLAUDE-global.md` gains an "In-Session Conversation Capture (M45 D2)" section so users who install/update pick up the hook alongside the existing in-session token-usage hook.
+
+### Fixed — M45 D1 Viewer Route
+
+- **`GET /transcripts` now serves the real transcript viewer** — reverts the standalone `renderTranscriptsHtml` index page shipped in v3.18.13. The route now reads `scripts/gsd-t-transcript.html` with `__SPAWN_ID__` → `""`, giving users the same left-rail + main + right-panel surface they get at `/transcript/:id`. JSON back-compat preserved: `Accept: application/json` and `*/*` continue to return `{spawns: [...]}`.
+- **Session-id path-separator sanitization (Red Team BUG-1)** — `_resolveSessionId` in the new conversation-capture hook now rejects session_ids containing `/`, `\`, `\0`, or `..` and falls through to the pid-hash fallback. Prior behavior let `session_id="a/../b"` lexically collapse via `path.join` to produce `transcripts/b.ndjson` without the `in-session-` prefix, breaking the filename-prefix discriminator contract with the viewer + compact-detector.
+
+## [3.18.13] - 2026-04-23
+
+### Fixed
+
+- **Dashboard `/transcripts` returned raw JSON to browsers** — after the v3.18.12 always-enabled Live Stream button fix, opening the dashboard with no spawn data and clicking Live Stream landed the user on `{"spawns":[]}` because `/transcripts` always served JSON. The route now does Accept-header content negotiation: browsers (`Accept: text/html`) get a proper dark-themed HTML index page with a sortable table of spawns (or a friendly empty state with a `/gsd-t-quick` CTA when no transcripts exist); programmatic clients (`fetch()` default `*/*`, or explicit `application/json`) keep getting the JSON shape the dashboard polling code already consumes — full back-compat.
+
 ## [3.18.12] - 2026-04-23
 
 ### Fixed

package/bin/gsd-t-parallel-probe.cjs

@@ -0,0 +1,132 @@
+"use strict";
+
+/**
+ * gsd-t-parallel-probe — M44 D9 Step 3
+ *
+ * Deterministic in-session probe that runs the parallel planner in dry-run mode
+ * and emits a single JSON line to stdout. Command files (execute / quick /
+ * debug / integrate) invoke this as a bash shim to get a mechanical answer —
+ * replacing LLM prose judgment with a JSON shape that branching logic can read.
+ *
+ * Per user memory `feedback_deterministic_orchestration.md`:
+ *   "prompt-based blocking doesn't work; use JS orchestrators for gates/waits"
+ *
+ * Contract: wave-join-contract.md v1.1.0; unattended-supervisor-contract.md v1.5.0
+ *
+ * Output shape (stdout, one line):
+ *   {"workerCount":N,"parallelTasks":["M44-D9-T1",...],"mode":"in-session",
+ *    "reducedCount":null|N,"warnings":[...],"ok":true}
+ *
+ * On unexpected error (planner throw, missing repo state, etc.), emits a safe
+ * fallback shape so shell callers never have to parse stderr:
+ *   {"workerCount":1,"parallelTasks":[],"mode":"in-session","ok":false,"error":"..."}
+ *
+ * Exit code 0 on both success and safe-fallback. This is intentional: the shim
+ * is a decision probe, not a command; non-zero would force command files to
+ * defensively wrap it and add LLM noise.
+ *
+ * Hard rules:
+ *   - Zero external runtime deps
+ *   - Never writes to stderr by default (shell shim relies on quiet)
+ *   - Never writes to `.gsd-t/events/*` — that's runParallel's job
+ */
+
+const path = require("node:path");
+
+function parseArgv(argv) {
+  const out = { milestone: null, domain: null, mode: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--milestone" && argv[i + 1]) {
+      out.milestone = argv[++i];
+    } else if (a === "--domain" && argv[i + 1]) {
+      out.domain = argv[++i];
+    } else if (a === "--mode" && argv[i + 1]) {
+      out.mode = argv[++i];
+    } else if (a === "--help" || a === "-h") {
+      out.help = true;
+    }
+  }
+  return out;
+}
+
+const HELP = `gsd-t-parallel-probe — deterministic planner probe (JSON out)
+
+Usage:
+  node bin/gsd-t-parallel-probe.cjs [--milestone Mxx] [--domain name] [--mode in-session|unattended]
+
+Output: one JSON line to stdout with keys workerCount, parallelTasks, mode,
+reducedCount, warnings, ok. Exit 0 always. Use with in-session command files
+(execute, quick, debug, integrate) to replace prose-based parallel dispatch
+decisions with a mechanical branch on workerCount.
+`;
+
+function probe(argv, env) {
+  const args = parseArgv(argv || []);
+  if (args.help) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+
+  let runParallel;
+  try {
+    ({ runParallel } = require(path.join(__dirname, "gsd-t-parallel.cjs")));
+  } catch (e) {
+    process.stdout.write(
+      JSON.stringify({
+        workerCount: 1,
+        parallelTasks: [],
+        mode: args.mode || "in-session",
+        reducedCount: null,
+        warnings: [],
+        ok: false,
+        error: `planner_load:${(e && e.message) || "unknown"}`,
+      }) + "\n",
+    );
+    return 0;
+  }
+
+  let result;
+  try {
+    result = runParallel({
+      projectDir: process.cwd(),
+      mode: args.mode || undefined,
+      milestone: args.milestone || undefined,
+      domain: args.domain || undefined,
+      dryRun: true,
+      env: env || process.env,
+    });
+  } catch (e) {
+    process.stdout.write(
+      JSON.stringify({
+        workerCount: 1,
+        parallelTasks: [],
+        mode: args.mode || "in-session",
+        reducedCount: null,
+        warnings: [],
+        ok: false,
+        error: `planner_error:${(e && e.message) || "unknown"}`,
+      }) + "\n",
+    );
+    return 0;
+  }
+
+  process.stdout.write(
+    JSON.stringify({
+      workerCount: Number(result.workerCount) || 0,
+      parallelTasks: Array.isArray(result.parallelTasks) ? result.parallelTasks : [],
+      mode: result.mode || args.mode || "in-session",
+      reducedCount: typeof result.reducedCount === "number" ? result.reducedCount : null,
+      warnings: Array.isArray(result.warnings) ? result.warnings : [],
+      ok: true,
+    }) + "\n",
+  );
+  return 0;
+}
+
+module.exports = { probe, _parseArgv: parseArgv, _HELP: HELP };
+
+if (require.main === module) {
+  const code = probe(process.argv.slice(2), process.env);
+  process.exit(code);
+}

package/bin/gsd-t-parallel.cjs

@@ -79,7 +79,7 @@ function detectMode(opts, env) {
 // ─── CLI arg parsing ──────────────────────────────────────────────────────
 
 function parseArgv(argv) {
-  const out = { help: false, dryRun: false, mode: null, milestone: null, domain: null };
+  const out = { help: false, dryRun: false, mode: null, milestone: null, domain: null, command: null };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--help" || a === "-h") out.help = true;
@@ -90,6 +90,8 @@ function parseArgv(argv) {
     else if (a.startsWith("--milestone=")) out.milestone = a.slice("--milestone=".length);
     else if (a === "--domain") out.domain = argv[++i] || null;
     else if (a.startsWith("--domain=")) out.domain = a.slice("--domain=".length);
+    else if (a === "--command") out.command = argv[++i] || null;
+    else if (a.startsWith("--command=")) out.command = a.slice("--command=".length);
   }
   return out;
 }
@@ -107,6 +109,13 @@ Options:
   --domain <name>                  Limit planning to a single domain.
   --dry-run                        Print the proposed worker plan table
                                    and exit without spawning any workers.
+  --command <slug>                 When fan-out is safe (N≥2), spawn N
+                                   detached headless children running the
+                                   named GSD-T command, each with disjoint
+                                   GSD_T_WORKER_TASK_IDS. When N<2, exits 0
+                                   with a "sequential" banner so the caller
+                                   falls through to the in-command flow.
+                                   Omit to get plan-only output.
   --help, -h                       Show this message and exit 0.
 
 Gates applied before any fan-out (in order):
@@ -301,6 +310,182 @@ function runParallel(opts) {
   };
 }
 
+// ─── runDispatch — the single instrument (M44 D9 Step 3) ──────────────────
+
+/**
+ * Round-robin partition of task ids into `workerCount` non-empty subsets.
+ * Kept tiny + pure so unit tests can exercise it without spinning up spawns.
+ */
+function _partitionTaskIds(taskIds, workerCount) {
+  const ids = Array.isArray(taskIds) ? taskIds.filter((x) => typeof x === "string" && x.length) : [];
+  const n = Math.max(0, Math.min(Number(workerCount) || 0, ids.length));
+  if (n === 0) return [];
+  const buckets = Array.from({ length: n }, () => []);
+  for (let i = 0; i < ids.length; i++) buckets[i % n].push(ids[i]);
+  return buckets.filter((b) => b.length > 0);
+}
+
+/**
+ * runDispatch — the single instrument every command delegates to.
+ *
+ * Probes the planner; if N≥2 with green gates, spawns N detached headless
+ * children via `autoSpawnHeadless()` (one per task subset) and returns
+ * `{decision:'fan_out', fanOutCount, workerResults, plan}`. If N<2, returns
+ * `{decision:'sequential', …}` so the caller falls through to its legacy
+ * single-worker path. If planning fails, returns `{decision:'sequential'}`
+ * with a warning — purely additive, never throws.
+ *
+ * Design intent (per user directive 2026-04-23):
+ *   "create 1 instrument that accomplishes this instead of implementing it
+ *    in all the commands."
+ *
+ * Command files invoke this via one bash line; they do not re-implement the
+ * probe-and-branch pattern. The unattended supervisor (v1.5.0 §15a) uses the
+ * same planner + dep-injected spawn but owns its own heartbeat/watchdog — it
+ * does not consume this function.
+ *
+ * Contract: wave-join-contract.md v1.1.0; headless-default-contract v2.0.0.
+ */
+function runDispatch(opts) {
+  const projectDir = (opts && opts.projectDir) || process.cwd();
+  const command = (opts && opts.command) || null;
+  if (!command) {
+    return {
+      decision: "invalid",
+      error: "missing_command",
+      fanOutCount: 0,
+      workerResults: [],
+      plan: [],
+      mode: detectMode(opts, opts && opts.env),
+    };
+  }
+
+  let result;
+  try {
+    result = runParallel({
+      projectDir,
+      mode: (opts && opts.mode) || undefined,
+      milestone: (opts && opts.milestone) || undefined,
+      domain: (opts && opts.domain) || undefined,
+      dryRun: true,
+      env: opts && opts.env,
+    });
+  } catch (e) {
+    appendEvent(projectDir, {
+      type: "parallelism_reduced",
+      source: "dispatch",
+      original_count: null,
+      reduced_count: 1,
+      reason: `planner_error:${(e && e.message) || "unknown"}`,
+      ts: new Date().toISOString(),
+    });
+    return {
+      decision: "sequential",
+      fanOutCount: 1,
+      workerResults: [],
+      plan: [],
+      mode: detectMode(opts, opts && opts.env),
+      error: `planner_error:${(e && e.message) || "unknown"}`,
+    };
+  }
+
+  const workerCount = Number(result.workerCount) || 0;
+  const parallelTasks = Array.isArray(result.parallelTasks) ? result.parallelTasks : [];
+  const subsets = workerCount >= 2 ? _partitionTaskIds(parallelTasks, workerCount) : [];
+
+  if (subsets.length < 2) {
+    return {
+      decision: "sequential",
+      fanOutCount: 1,
+      workerResults: [],
+      plan: result.plan || [],
+      mode: result.mode,
+      parallelTasks,
+    };
+  }
+
+  // Resolve the spawner — tests inject a stub; production uses the real
+  // `autoSpawnHeadless`. Required: `({command, args, projectDir, env}) => {id, pid, …}`.
+  let spawnImpl = opts && opts.spawnHeadlessImpl;
+  if (!spawnImpl) {
+    try {
+      spawnImpl = require(path.join(__dirname, "headless-auto-spawn.cjs")).autoSpawnHeadless;
+    } catch (e) {
+      return {
+        decision: "sequential",
+        fanOutCount: 1,
+        workerResults: [],
+        plan: result.plan || [],
+        mode: result.mode,
+        error: `spawn_load:${(e && e.message) || "unknown"}`,
+        parallelTasks,
+      };
+    }
+  }
+
+  appendEvent(projectDir, {
+    type: "fan_out",
+    source: "dispatch",
+    command,
+    fan_out_count: subsets.length,
+    task_ids: parallelTasks,
+    mode: result.mode,
+    ts: new Date().toISOString(),
+  });
+
+  const workerResults = [];
+  for (let i = 0; i < subsets.length; i++) {
+    const subset = subsets[i];
+    const workerEnv = {
+      GSD_T_WORKER_TASK_IDS: subset.join(","),
+      GSD_T_WORKER_INDEX: String(i),
+      GSD_T_WORKER_TOTAL: String(subsets.length),
+    };
+    let spawnResult = null;
+    let spawnError = null;
+    try {
+      spawnResult = spawnImpl({
+        command,
+        args: [],
+        projectDir,
+        env: workerEnv,
+        spawnType: "primary",
+      });
+    } catch (e) {
+      spawnError = (e && e.message) || "unknown";
+    }
+    appendEvent(projectDir, {
+      type: "task_start",
+      source: "dispatch",
+      worker_index: i,
+      worker_total: subsets.length,
+      task_ids: subset,
+      command,
+      spawn_id: spawnResult && spawnResult.id,
+      pid: spawnResult && spawnResult.pid,
+      error: spawnError,
+      ts: new Date().toISOString(),
+    });
+    workerResults.push({
+      idx: i,
+      taskIds: subset,
+      spawnId: spawnResult && spawnResult.id,
+      pid: spawnResult && spawnResult.pid,
+      logPath: spawnResult && spawnResult.logPath,
+      error: spawnError,
+    });
+  }
+
+  return {
+    decision: "fan_out",
+    fanOutCount: subsets.length,
+    workerResults,
+    plan: result.plan || [],
+    mode: result.mode,
+    parallelTasks,
+  };
+}
+
 // ─── CLI entry ────────────────────────────────────────────────────────────
 
 // ─── dry-run table formatter ──────────────────────────────────────────────
@@ -339,15 +524,17 @@ function runCli(argv, env) {
     return 0;
   }
   const mode = args.mode || detectMode({}, env);
-  const result = runParallel({
-    projectDir: process.cwd(),
-    mode,
-    milestone: args.milestone,
-    domain: args.domain,
-    dryRun: args.dryRun,
-    env,
-  });
+
+  // --dry-run: plan-only output, same as M44 D2 baseline.
   if (args.dryRun) {
+    const result = runParallel({
+      projectDir: process.cwd(),
+      mode,
+      milestone: args.milestone,
+      domain: args.domain,
+      dryRun: true,
+      env,
+    });
     process.stdout.write(formatPlanTable(result.plan));
     process.stdout.write(
       `\nTotal workers: ${result.workerCount}   Mode: ${result.mode}` +
@@ -358,6 +545,50 @@ function runCli(argv, env) {
     );
     return 0;
   }
+
+  // --command: live dispatch. The single instrument that command files
+  // delegate to instead of re-implementing probe-and-branch logic.
+  if (args.command) {
+    const dispatch = runDispatch({
+      projectDir: process.cwd(),
+      mode,
+      milestone: args.milestone,
+      domain: args.domain,
+      command: args.command,
+      env,
+    });
+    if (dispatch.decision === "fan_out") {
+      process.stdout.write(
+        `gsd-t parallel — fan_out command=${args.command} mode=${dispatch.mode} workers=${dispatch.fanOutCount}\n`,
+      );
+      for (const w of dispatch.workerResults) {
+        process.stdout.write(
+          `  worker[${w.idx}] tasks=${w.taskIds.join(",")} spawn=${w.spawnId || "-"} pid=${w.pid || "-"}${w.error ? " error=" + w.error : ""}\n`,
+        );
+      }
+      return 0;
+    }
+    if (dispatch.decision === "sequential") {
+      process.stdout.write(
+        `gsd-t parallel — sequential command=${args.command} mode=${dispatch.mode} (N<2, caller falls through)${dispatch.error ? " error=" + dispatch.error : ""}\n`,
+      );
+      return 2; // non-zero so shell `&&` short-circuits; caller branches on $?
+    }
+    process.stdout.write(
+      `gsd-t parallel — ${dispatch.decision} command=${args.command} mode=${dispatch.mode}\n`,
+    );
+    return 3;
+  }
+
+  // Legacy path: no --dry-run, no --command. Print plan summary only.
+  const result = runParallel({
+    projectDir: process.cwd(),
+    mode,
+    milestone: args.milestone,
+    domain: args.domain,
+    dryRun: false,
+    env,
+  });
   process.stdout.write(
     `gsd-t parallel — mode=${result.mode} workers=${result.workerCount}\n`,
   );
@@ -366,6 +597,7 @@ function runCli(argv, env) {
 
 module.exports = {
   runParallel,
+  runDispatch,
   runCli,
   formatPlanTable,
   PLAN_HEADER,
@@ -373,6 +605,7 @@ module.exports = {
   _parseArgv: parseArgv,
   _detectMode: detectMode,
   _appendEvent: appendEvent,
+  _partitionTaskIds,
   _HELP_TEXT: HELP_TEXT,
 };
 

package/bin/gsd-t-task-graph.cjs

@@ -79,7 +79,7 @@ function parseTasksMd(absPath, domainName) {
       continue;
     }
 
-    // Task heading: "### M44-D1-T1 — Title"  (em-dash, en-dash, hyphen all OK)
+    // Task heading (Shape D — parser-canonical): "### M44-D1-T1 — Title"
     const taskMatch = line.match(/^###\s+([A-Z]\d+-D\d+-T\d+)\s*[—–\-]?\s*(.*)$/);
     if (taskMatch) {
       flush();
@@ -92,33 +92,77 @@ function parseTasksMd(absPath, domainName) {
         deps: [],
         touches: null, // null = unset (will fall back to scope.md); [] = explicit empty
         statusWarning: null,
+        shape: "D",
+      };
+      continue;
+    }
+
+    // Task bullet (Shape C — bullet-with-bold-id, checkbox in heading):
+    //   "- [ ] **M44-D9-T1** — Title"
+    // Dependencies absent in Shape C source; touches come from an indented
+    // "  - touches: a, b" sub-bullet below the task.
+    const bulletMatch = line.match(/^-\s+\[(.)\]\s+\*\*([A-Z]\d+-D\d+-T\d+)\*\*\s*[—–\-]?\s*(.*)$/);
+    if (bulletMatch) {
+      flush();
+      const marker = bulletMatch[1];
+      let status = "pending";
+      let statusWarning = null;
+      if (STATUS_MAP[marker]) {
+        status = STATUS_MAP[marker];
+      } else {
+        statusWarning = `unknown status marker '[${marker}]' on ${bulletMatch[2]} — treating as pending`;
+      }
+      cur = {
+        id: bulletMatch[2],
+        domain: domainName,
+        wave: currentWave,
+        title: (bulletMatch[3] || "").trim(),
+        status,
+        deps: [],
+        touches: null,
+        statusWarning,
+        shape: "C",
       };
       continue;
     }
 
     if (!cur) continue;
 
-    // Field lines look like:  "- **Status**: [ ] pending"
+    // Shape D field line: "- **Status**: [ ] pending"
     const fieldMatch = line.match(/^\s*-\s+\*\*([A-Za-z][\w\s]*?)\*\*\s*:\s*(.*)$/);
-    if (!fieldMatch) continue;
-    const key = fieldMatch[1].trim().toLowerCase();
-    const val = fieldMatch[2].trim();
-
-    if (key === "status") {
-      const m = val.match(/\[(.)\]/);
-      if (m) {
-        const marker = m[1];
-        if (STATUS_MAP[marker]) {
-          cur.status = STATUS_MAP[marker];
-        } else {
-          cur.status = "pending";
-          cur.statusWarning = `unknown status marker '[${marker}]' on ${cur.id} — treating as pending`;
+    if (fieldMatch) {
+      const key = fieldMatch[1].trim().toLowerCase();
+      const val = fieldMatch[2].trim();
+
+      if (key === "status") {
+        const m = val.match(/\[(.)\]/);
+        if (m) {
+          const marker = m[1];
+          if (STATUS_MAP[marker]) {
+            cur.status = STATUS_MAP[marker];
+          } else {
+            cur.status = "pending";
+            cur.statusWarning = `unknown status marker '[${marker}]' on ${cur.id} — treating as pending`;
+          }
         }
+      } else if (key === "dependencies" || key === "deps") {
+        cur.deps = parseDepList(val);
+      } else if (key === "touches" || key === "files touched" || key === "touched") {
+        cur.touches = parseFileList(val);
+      }
+      continue;
+    }
+
+    // Shape C sub-bullet field: "  - touches: a, b" or "  - deps: X, Y"
+    const subFieldMatch = line.match(/^\s+-\s+([a-zA-Z][\w\s]*?)\s*:\s*(.*)$/);
+    if (subFieldMatch && cur.shape === "C") {
+      const key = subFieldMatch[1].trim().toLowerCase();
+      const val = subFieldMatch[2].trim();
+      if (key === "touches" || key === "files touched" || key === "touched") {
+        cur.touches = parseFileList(val);
+      } else if (key === "dependencies" || key === "deps") {
+        cur.deps = parseDepList(val);
       }
-    } else if (key === "dependencies" || key === "deps") {
-      cur.deps = parseDepList(val);
-    } else if (key === "touches" || key === "files touched" || key === "touched") {
-      cur.touches = parseFileList(val);
     }
   }
   flush();
@@ -126,6 +170,7 @@ function parseTasksMd(absPath, domainName) {
   for (const t of tasks) {
     if (t.statusWarning) warnings.push(t.statusWarning);
     delete t.statusWarning;
+    delete t.shape;
   }
   return { tasks, warnings };
 }
@@ -292,6 +337,22 @@ function buildTaskGraph(opts) {
     if (!fs.existsSync(tasksPath)) continue;
     const { tasks, warnings: ws } = parseTasksMd(tasksPath, domain);
     for (const w of ws) warnings.push(w);
+    if (tasks.length === 0) {
+      // tasks.md exists but no tasks matched any known shape. Heuristic check
+      // for an unsupported shape so the caller knows to author in Shape C or D.
+      let src = "";
+      try { src = fs.readFileSync(tasksPath, "utf8"); } catch {}
+      const hasLegacyNoMilestoneH3 = /^###\s+D\d+-T\d+\b/m.test(src);
+      const hasBareSection = /^##\s+T-\d+\b/m.test(src);
+      if (hasLegacyNoMilestoneH3) {
+        warnings.push(`${domain}/tasks.md uses '### D1-T1' (legacy, no milestone prefix) — parser requires '### Mxx-D1-T1' or '- [.] **Mxx-D1-T1**' form; 0 tasks read`);
+      } else if (hasBareSection) {
+        warnings.push(`${domain}/tasks.md uses '## T-1:' section headings — parser requires task-id shape 'Mxx-Dx-Tx' in '###' heading or '- [.] **...**' bullet; 0 tasks read`);
+      } else {
+        warnings.push(`${domain}/tasks.md parsed 0 tasks — no '### Mxx-Dx-Tx' heading nor '- [.] **Mxx-Dx-Tx**' bullet found`);
+      }
+      continue;
+    }
     for (const t of tasks) {
       if (byId[t.id]) {
         warnings.push(`duplicate task id ${t.id} (domain ${domain}) — first wins`);