Repository navigation
Description
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_onlyrather than each re-deriving or re-referencing the step output. - Consider publishing the already-negated form (e.g. a
run_fulloutput) 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
successin the aggregator feed, with the aggregator unchanged. -
check-lane-coverage.sh --checkstays clean (every job still reachable fromci-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 commentscripts/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
Activity
refactor(scripts): define the list-file format once, and close a thir…
kyle-sexton commentedon Aug 23, 2026
kyle-sexton commentedon Aug 23, 2026
This was generated by AI during triage.
Triage outcome: briefed, decision-defaulted →
agent-readyVerification. Reproduced against current
main(post-#3144/#3161 merges): thedocs_onlystring 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). Theid: scopestep (runningcheck-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 onsteps.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_onlyflag as-is vianeeds.<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: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. Notstructural(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 triagedscoped).No redundant implementation found (searched
.github/workflows/ci.ymlandscripts/); nodocs/out-of-scope/ledger entry for this concept in this repo.kyle-sexton commentedon Aug 23, 2026
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-202608231812is taking over the lease on this issue. The issue is being assigned tokyle-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 commentedon Aug 23, 2026
kyle-sexton commentedon Aug 23, 2026
kyle-sexton commentedon Aug 23, 2026
fix(ci): correct the pr-issue-linkage header's claims about the pinne…
kyle-sexton commentedon Aug 23, 2026
Implemented in #3237, which hoists the docs-only scope resolution into a single
scopejob publishing a positive-polarityrun_fulloutput, and addsscripts/check-docs-only-gate.shto hold the contract's fail-closed properties againstci.ymlin place of the prose comment that carried them.refactor(ci): resolve the docs-only scope once and gate the contract (#…
refactor(scripts): unify test-harness scaffolding in scripts/lib/test…