@tekyzinc/gsd-t 3.18.13 → 3.19.0

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, maxWorkers: null, stagger: null };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--help" || a === "-h") out.help = true;
@@ -90,6 +90,12 @@ 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);
+    else if (a === "--max-workers") out.maxWorkers = parseInt(argv[++i], 10);
+    else if (a.startsWith("--max-workers=")) out.maxWorkers = parseInt(a.slice("--max-workers=".length), 10);
+    else if (a === "--stagger") out.stagger = parseInt(argv[++i], 10);
+    else if (a.startsWith("--stagger=")) out.stagger = parseInt(a.slice("--stagger=".length), 10);
   }
   return out;
 }
@@ -107,6 +113,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 +314,350 @@ 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);
+}
+
+/**
+ * _runCacheWarmProbe — fire a single short `claude -p` before fan-out so the
+ * Anthropic prompt cache (5-min TTL) is pre-populated with the files every
+ * worker will read. When workers spawn within the warm window, their initial
+ * Read(CLAUDE.md), Read(progress.md), Read(contracts/*.md) return cache-read
+ * tokens (free for ITPM budget, lower rate-limit pressure).
+ *
+ * Returns `{ok, filesRead, error}`. Best-effort; failures do not block fan-out.
+ *
+ * The probe reads the existing files (skips missing ones silently) and asks
+ * the child to print the literal string "warm" — cheap, deterministic, fast.
+ * Cache key matches exactly when `model` equals the workers' model and the
+ * workers use the same tool-call shape (Read on the same paths) within TTL.
+ */
+function _runCacheWarmProbe(opts) {
+  const projectDir = (opts && opts.projectDir) || process.cwd();
+  const model = opts && opts.model;
+  const timeoutMs = Number.isFinite(opts && opts.timeoutMs) ? opts.timeoutMs : 60000;
+
+  const candidates = [
+    "CLAUDE.md",
+    ".gsd-t/progress.md",
+    ".gsd-t/contracts/headless-default-contract.md",
+    ".gsd-t/contracts/wave-join-contract.md",
+  ];
+  const filesRead = candidates.filter((rel) => {
+    try {
+      return fs.statSync(path.join(projectDir, rel)).isFile();
+    } catch {
+      return false;
+    }
+  });
+  if (filesRead.length === 0) return { ok: false, filesRead: [], error: "no_warm_files" };
+
+  const { spawnSync } = require("node:child_process");
+  const prompt =
+    "Read the following files so they enter the prompt cache for subsequent workers, " +
+    "then reply with the single word `warm` and nothing else:\n" +
+    filesRead.map((f) => `- ${f}`).join("\n");
+
+  const env = Object.assign({}, process.env);
+  if (model) env.ANTHROPIC_MODEL = model;
+
+  try {
+    const r = spawnSync(
+      "claude",
+      ["-p", prompt, "--dangerously-skip-permissions"],
+      {
+        cwd: projectDir,
+        env,
+        encoding: "utf8",
+        timeout: timeoutMs,
+        stdio: ["ignore", "pipe", "pipe"],
+      },
+    );
+    if (r.error) return { ok: false, filesRead, error: r.error.message };
+    if (r.status !== 0) return { ok: false, filesRead, error: `exit_${r.status}` };
+    return { ok: true, filesRead };
+  } catch (e) {
+    return { ok: false, filesRead, error: (e && e.message) || "spawn_error" };
+  }
+}
+
+/**
+ * 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 plannerWorkerCount = Number(result.workerCount) || 0;
+  const parallelTasks = Array.isArray(result.parallelTasks) ? result.parallelTasks : [];
+
+  // Concurrency cap (v3.18.19) — caller may clamp the planner-selected worker
+  // count via `opts.maxWorkers`. Motivated by 2026-04-23 incident: the Max
+  // subscription concurrent-session throttle rate-limits `claude -p` bursts
+  // regardless of model choice (since all spawns inherit the parent's Max
+  // OAuth, not an API key — see feedback_anthropic_key_measurement_only). The
+  // planner has no knowledge of this throttle; callers who know they're near
+  // the ceiling need a direct cap.
+  const cap = Number.isFinite(opts && opts.maxWorkers) && opts.maxWorkers > 0
+    ? Math.floor(opts.maxWorkers)
+    : 2;
+  const workerCount = Math.min(plannerWorkerCount, cap);
+  if (workerCount < plannerWorkerCount) {
+    appendEvent(projectDir, {
+      type: "parallelism_reduced",
+      source: "dispatch_max_workers_cap",
+      original_count: plannerWorkerCount,
+      reduced_count: workerCount,
+      reason: `max_workers_cap:${cap}`,
+      ts: new Date().toISOString(),
+    });
+  }
+  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(),
+  });
+
+  // Worker model selection (v3.18.18) — mechanical fan-out defaults to Sonnet
+  // so the orchestrator's Opus bucket isn't the bottleneck. Caller may
+  // override via `opts.workerModel` ("opus" | "sonnet" | "haiku" | full ID).
+  // A task can opt back to Opus by declaring "[opus]" in its tasks.md line;
+  // the planner surfaces this via per-task metadata (future; today the per-
+  // subset opt-in is an all-or-nothing knob passed by the caller).
+  const DEFAULT_WORKER_MODEL = "claude-sonnet-4-6";
+  const modelAlias = {
+    opus: "claude-opus-4-7",
+    sonnet: "claude-sonnet-4-6",
+    haiku: "claude-haiku-4-5-20251001",
+  };
+  const callerModel = opts && opts.workerModel;
+  const workerModel = callerModel === false
+    ? null // explicit opt-out: inherit parent's ANTHROPIC_MODEL
+    : (modelAlias[callerModel] || callerModel || DEFAULT_WORKER_MODEL);
+
+  // Stagger between spawns — 10s default empirically-validated against the
+  // Max-subscription concurrent-session throttle (2026-04-23 M46 probe: two
+  // 10s-staggered 2-parallel rounds of real work, both exit 0, no 429; prior
+  // 3s default burst at >2 workers hit rate limits). Caller may override via
+  // `opts.spawnStaggerMs` (0 = no delay, previous burst behavior).
+  const staggerMs = Number.isFinite(opts && opts.spawnStaggerMs)
+    ? Math.max(0, opts.spawnStaggerMs)
+    : 10000;
+  const busyWait = (ms) => {
+    if (!ms) return;
+    // Synchronous sleep that releases the CPU (Atomics.wait on a dummy
+    // SharedArrayBuffer — pattern used in Node REPL/sync-sleep helpers).
+    // Keeps runDispatch's sync return contract without pegging a core.
+    // Total wall-clock added to startup: (subsets-1) * staggerMs.
+    try {
+      const sab = new SharedArrayBuffer(4);
+      const view = new Int32Array(sab);
+      Atomics.wait(view, 0, 0, ms);
+    } catch (_) {
+      // Atomics unavailable — fall back to a coarse spin.
+      const until = Date.now() + ms;
+      while (Date.now() < until) { /* spin */ }
+    }
+  };
+
+  // Cache-warming probe (v3.18.19) — opt-in via GSD_T_CACHE_WARM=1 or
+  // opts.cacheWarm. Anthropic's prompt cache has a 5-minute TTL keyed on the
+  // exact system-prompt + tool-call prefix. One leader probe that reads the
+  // same foundational files every worker will read (CLAUDE.md, progress.md,
+  // top-level contracts) populates the cache so the first N seconds of every
+  // subsequent worker hit cache-read tokens (free for ITPM budget, lower
+  // rate-limit pressure). Probe runs synchronously so workers land inside
+  // the warm window rather than racing it. Gated behind opt-in until
+  // backlog #23 (mitmproxy instrumentation) measures the actual delta.
+  const warmEnv = (opts && opts.env) || process.env;
+  const cacheWarmEnabled =
+    (opts && opts.cacheWarm === true) ||
+    (!(opts && opts.cacheWarm === false) && warmEnv.GSD_T_CACHE_WARM === "1");
+  if (cacheWarmEnabled) {
+    const warmStart = Date.now();
+    let warmResult = { ok: false, error: "not_run" };
+    try {
+      const probeImpl = (opts && opts.cacheWarmProbeImpl) || _runCacheWarmProbe;
+      warmResult = probeImpl({
+        projectDir,
+        model: workerModel, // same model as workers so cache key matches
+        timeoutMs: (opts && Number.isFinite(opts.cacheWarmTimeoutMs))
+          ? opts.cacheWarmTimeoutMs
+          : 60000,
+      });
+    } catch (e) {
+      warmResult = { ok: false, error: (e && e.message) || "unknown" };
+    }
+    appendEvent(projectDir, {
+      type: "cache_warm_probe",
+      source: "dispatch",
+      ok: !!warmResult.ok,
+      duration_ms: Date.now() - warmStart,
+      error: warmResult.error,
+      files_read: warmResult.filesRead,
+      ts: new Date().toISOString(),
+    });
+  }
+
+  const workerResults = [];
+  for (let i = 0; i < subsets.length; i++) {
+    if (i > 0) busyWait(staggerMs);
+    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",
+        workerModel,
+      });
+    } 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 +696,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 +717,57 @@ 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 dispatchOpts = {
+      projectDir: process.cwd(),
+      mode,
+      milestone: args.milestone,
+      domain: args.domain,
+      command: args.command,
+      env,
+    };
+    if (Number.isFinite(args.maxWorkers) && args.maxWorkers > 0) {
+      dispatchOpts.maxWorkers = args.maxWorkers;
+    }
+    if (Number.isFinite(args.stagger) && args.stagger >= 0) {
+      dispatchOpts.spawnStaggerMs = args.stagger * 1000;
+    }
+    const dispatch = runDispatch(dispatchOpts);
+    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 +776,7 @@ function runCli(argv, env) {
 
 module.exports = {
   runParallel,
+  runDispatch,
   runCli,
   formatPlanTable,
   PLAN_HEADER,
@@ -373,6 +784,8 @@ module.exports = {
   _parseArgv: parseArgv,
   _detectMode: detectMode,
   _appendEvent: appendEvent,
+  _partitionTaskIds,
+  _runCacheWarmProbe,
   _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`);