ci: hoist docs_only scope resolution into one job instead of 46 references

[claude]

Parent

Refs #2914

Context

The docs_only string contract fans out to 46 references in .github/workflows/ci.yml. Consumers gate on steps.scope.outputs.docs_only != 'true' — an inverse-polarity condition whose correctness is maintained by a prose comment rather than by anything executable. That is connascence of meaning at 46 sites: every consumer has to independently know that the flag is a string 'true', that the safe direction is to run the suite, and that the negation must be spelled this exact way.

Two failure modes follow from the shape. A consumer that writes == 'false' instead of != 'true' skips its lane whenever the detector emits anything unexpected — a fail-open, and the polarity comment is the only thing that prevents it. A consumer that forgets the gate entirely runs always, which is merely wasteful. The asymmetry is why the comment exists, and why 46 hand-maintained copies of it is the wrong mechanism.

Route-lane finding 5 of 7 from the first /coupling:reduce dogfood run (#2914). Reproduced against the tree at dff0942: exactly 46 docs_only references in ci.yml.

Proposed work

• Hoist scope resolution into a single job that runs the detector once and publishes the result as a job output.
• Have consumers read needs.scope.outputs.docs_only rather than each re-deriving or re-referencing the step output.
• Consider publishing the already-negated form (e.g. a run_full output) so consumers express the safe direction positively and the inverse-polarity comment stops being load-bearing.
• Preserve the existing never-skip discipline: the detector self-test runs unconditionally, and detection stays fail-closed toward running the full suite.

Acceptance criteria

• One job resolves scope; every consumer reads its output rather than re-referencing the detector step.
• Adding a new gated job requires referencing one documented output, with no polarity decision to get wrong.
• A detector failure still resolves to "run the full suite" — verified by a test, not by a comment.
• The intentional docs-only skip is still mapped to success in the aggregator feed, with the aggregator unchanged.
• check-lane-coverage.sh --check stays clean (every job still reachable from ci-status.needs).

References

• Parent umbrella: coupling: route-lane findings from /coupling:reduce dry-run over scripts/ #2914 (route-lane finding 5 of 7)
• .github/workflows/ci.yml — the 46 references and the polarity comment
• scripts/check-docs-only.sh — the detector, whose fail-safe contract must be preserved
• refactor(scripts): extract the shared changed-file and awk-operand seams #3144 — findings 1 and 2 of the same batch

Metadata

Field	Value
Category	unspecified
Area	unspecified
Ecosystem	unspecified

---

Generated by Claude Code

[kyle-sexton]

[kyle-sexton]

This was generated by AI during triage.

Triage outcome: briefed, decision-defaulted → agent-ready

Verification. Reproduced against current main (post-#3144/#3161 merges): the docs_only string contract now fans out to 48 references in .github/workflows/ci.yml (drift from the 46 counted at filing — expected as new gated jobs were added since). The id: scope step (running check-docs-only.sh) is independently duplicated in six jobs (hygiene, plugin-gate, miro-plugin, video-extraction, ai-briefing-build, course-digest-extraction), and downstream consumers gate on steps.scope.outputs.docs_only != 'true' per the inverse-polarity comment this issue describes. Not implemented; problem confirmed as filed.

Decision-defaulted. The "Proposed work" section leaves one open fork: whether to publish the raw docs_only flag as-is via needs.<job>.outputs.docs_only, or publish an already-negated form (e.g. run_full) so consumers express the safe direction positively. Acceptance criterion 2 ("no polarity decision to get wrong") is satisfiable either way, but the positive-polarity form better serves the issue's own stated goal (retiring the load-bearing prose comment), so:

Decision defaulted: publish the positive-polarity output (e.g. run_full) from the hoisted scope job, not a re-exposed docs_only flag — veto before merge.

This is a maintainer-vetoable implementation choice, not an open design/product/policy question — reversible in review.

Classification. work-class: scoped (C3): blast radius is bounded by the closed, enumerated acceptance criteria in the issue body, and mechanical verification already exists (check-lane-coverage.sh --check, the detector self-test) to confirm the refactor didn't drop a lane. Not structural (C4) — the change is a straightforward, git revert-able CI workflow edit, not a hard-to-reverse contract migration. Consistent with the sibling same-batch finding #3157 (also triaged scoped).

No redundant implementation found (searched .github/workflows/ci.yml and scripts/); no docs/out-of-scope/ ledger entry for this concept in this repo.

[kyle-sexton]

Lease takeover

This issue carried a work-item lease held by instance MELO-LAP-001-triage-202608230449, acquired at 2026-08-23T15:29:39Z with a one-hour TTL. That lease expired at 2026-08-23T16:29:39Z and was never renewed. As of this comment the issue has had no activity since 2026-08-23T15:36:55Z, and no newer lease from any other instance has been posted.

Instance melo-lap-001-worker-202608231812 is taking over the lease on this issue. The issue is being assigned to kyle-sexton, matching the account the prior lease recorded as its holder, and a fresh lease marker in the same machine-readable format follows this comment, stamped with the new instance and the same one-hour TTL.

This is an announced takeover of an expired lease, not a contested claim. If the prior instance is still live and intends to keep this item, it should say so on this issue and the takeover will be released.

[kyle-sexton]

[kyle-sexton]