fix(pm): make check-family discovery fail loud on undiscoverable workflow verification steps

[os-project-manager]

Fixes#9187

What

extractCheckInvocations in scripts/pm/dispatch-gates.mjs only recognized two shapes as a discoverable check family: pnpm [--filter PKG] [run] check:NAME and node scripts/**check-NAME.mjs. A workflow verification step using neither shape contributed zero discovered families and was invisible to both halves of the tool's output — not matched, not undetermined, not silent. docs-drift-check.yml's mapper self-test (node scripts/docs-audit/affected-docs.mjs --self-test) was exactly that case, and — after #9171/#9188 landed the CI-trigger match key — it became the one paths:-filtered workflow whose trigger bought the derivation nothing, because there was no discovered family to attach it to.

Per the route in the grading comment (option 3): rule the check-* naming convention normative and add a gate that fails a workflow verification step which is not discoverable, with a declared (not implicit hard-coded) opt-out for workflows that genuinely have no check family.

Blast-radius census (per the card's instruction, before making anything fail)

Of the 25 workflow files, only 6 declare a paths: filter (the scope this gate applies to — see the code comment for why it's scoped that way):

workflow	discovered families before this PR
docs-drift-check.yml	0 ← fixed here
scaffold-e2e.yml	0 ← exempted here
engine-split-metric.yml	1
prerelease-pin-watch.yml	1
spec-liveness-check.yml	4
validate-deps.yml	3

Exactly the 2 known cases from the issue — no larger blast radius, so proceeding with the failing gate is safe. (Unfiltered workflows run on every PR regardless of any family, so they're out of this gate's scope by design.) I also found two heavier, non-paths:-filtered scripts that are genuinely verification-with-a-verdict but not check--named — scripts/downstream-smoke.sh (pre-publish hotcrm compat gate) and scripts/publish-smoke.sh (publish-artifact smoke) — both already use an established, distinct, deliberately-different *-smoke.sh naming convention (network/registry-dependent, not a quick local pre-push gate the way check:* is), and neither lives in a paths:-filtered workflow, so they're unaffected by this gate and out of scope for this card.

Changes

• scripts/pm/dispatch-gates.mjs: adds declaredNoCheckFamiliesReason (reads a workflow's own opt-out comment, spelled # dispatch-gates: no-check-families -- followed by the reason text) and checkFamilyCoverageGaps (every paths:-filtered workflow must discover at least one check family, or carry that declared reason). Both are asserted in the tool's own --self-test, fixture-pinned and against the live workflow tree — mirroring the existing "census guard" ([finding] check:engine-double-contract is a PM judgement call in dispatch-gates.mjs, not a convention entry — and a mechanical trigger for it exists #8632) pairing. The opt-out is declared by the workflow, never a hardcoded filename list in this script (the exact mirror-one-level-down shape the card calls out).
• docs-drift-check.yml: the mapper self-test now runs through a new wrapper script, scripts/docs-audit/check-affected-docs.mjs, instead of a raw node scripts/docs-audit/affected-docs.mjs --self-test call, so it becomes discoverable (now 1 family, not 0).
• scripts/docs-audit/check-affected-docs.mjs (new): a thin spawn-and-relay wrapper, mirroring scripts/pm/check-dispatch-gates.mjs's own established shape — plain node, zero dependencies. Not a pnpm check:NAME package.json script: docs-drift-check.yml's job deliberately never runs pnpm install (the mapper it wraps has zero deps, kept that way so this job stays fast on every packages/** PR), so a pnpm invocation isn't just unwired, pnpm itself isn't on PATH there. First push of this PR tried the pnpm check:NAME route and broke this exact job (pnpm: command not found, exit 127) — fixed by switching to the direct-node-script discovery shape instead, which needs nothing this job doesn't already have.
• scaffold-e2e.yml: carries the declared opt-out — its steps are an install/build/boot/docker e2e pipeline, not a named local verification.

Reverse verification (both fix shapes): reverted the workflow/script changes back to origin/main and re-ran --self-test each time — it failed exactly as expected (gaps: docs-drift-check.yml, scaffold-e2e.yml for the full revert; gaps: docs-drift-check.yml for the final wrapper-only revert). Restored, green again both times.

Tests

At e624bcd09 (final commit):

node scripts/pm/dispatch-gates.mjs --self-test
✓ dispatch-gates self-test: 228 cases pass.
pnpm check:pm-dispatch-gates # ✓ (runs the self-test above)
pnpm check:nul-bytes # ✓
pnpm check:node-version # ✓
pnpm check:required-contexts # ✓
pnpm check:shard-attestation # ✓
pnpm check:workflow-status-functions # ✓
pnpm check:docs-audit-scope # ✓ (affected-docs.mjs is unchanged; sanity-checked anyway)
node scripts/docs-audit/check-affected-docs.mjs # ✓ affected-docs self-test: 56 cases pass. (run with plain `node`, matching what the workflow job actually has on PATH)
pnpm exec eslint scripts/pm/dispatch-gates.mjs scripts/docs-audit/check-affected-docs.mjs --no-inline-config # clean

Re-derived the gate union against the changed paths with the changed version of the script itself (I'm editing dispatch-gates.mjs, so its own derivation output is only trustworthy read from the edited copy):

node scripts/pm/dispatch-gates.mjs scripts/pm/dispatch-gates.mjs .github/workflows/docs-drift-check.yml .github/workflows/scaffold-e2e.yml scripts/docs-audit/check-affected-docs.mjs

names exactly: check:node-version, check:pm-dispatch-gates, check:required-contexts, check:shard-attestation, check:workflow-status-functions, node scripts/check-shard-attestation.mjs, node scripts/docs-audit/check-affected-docs.mjs (all run above, all green). It does name its own self-test — check:pm-dispatch-gates matches via scripts/pm/dispatch-gates.mjs, so a card editing this file always derives its own gate.

Live check run at this head: "Flag docs affected by code changes" (the job this PR's fix targets) — success.

Not in scope

• [finding] the metadata TYPE registry moves the same metadataForms bundles and is still invisible to dispatch-gates path derivation #9144 — same blind-spot family, registry-visibility half, graded separately. Not touched here.
• dispatch-gates.mjs's runCommandTexts does not recognize the compact - run: cmd single-line step form at all — zero commands discovered for that step #9203 (filed) — an unrelated, pre-existing gap found while writing this fixture's YAML: runCommandTexts doesn't recognize the compact single-line step form (- run: cmd, dash and run: on one line — vs. the usual separate - name: … / run: … lines) at all, so a check step written that way would be silently missed. Confirmed via grep this form exists today only for two non-check pnpm install/pnpm turbo build steps in showcase-smoke.yml, so it has zero live impact right now — different defect class (YAML step-shape parsing, not filename convention) from this card, so filed separately rather than folded in here.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

No hand-written docs reference the 0 changed package(s). ✅