Skip to content

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

Closed

Description

@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

Metadata

Field Value
Category unspecified
Area unspecified
Ecosystem unspecified

Generated by Claude Code

Activity

  1. added
    needs-triageNot yet classified. Floor until a type and one priority tier are set.
    on Aug 23, 2026
  2. self-assigned this
    on Aug 23, 2026
  3. kyle-sexton commented on Aug 23, 2026

    @kyle-sexton
    Member
    No description provided.
  4. added
    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.
    status: readyTriaged, unblocked, and fully specified; eligible to pick up.
    and removed
    needs-triageNot yet classified. Floor until a type and one priority tier are set.
    on Aug 23, 2026
  5. kyle-sexton commented on Aug 23, 2026

    @kyle-sexton
    Member

    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.

  6. removed their assignment
    on Aug 23, 2026
  7. kyle-sexton commented on Aug 23, 2026

    @kyle-sexton
    Member

    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.

  8. self-assigned this
    on Aug 23, 2026
  9. kyle-sexton commented on Aug 23, 2026

    @kyle-sexton
    Member
    No description provided.
  10. kyle-sexton commented on Aug 23, 2026

    @kyle-sexton
    Member
    No description provided.
  11. kyle-sexton commented on Aug 23, 2026

    @kyle-sexton
    Member
    No description provided.
  12. kyle-sexton commented on Aug 23, 2026

    @kyle-sexton
    Member

    Implemented in #3237, which hoists the docs-only scope resolution into a single scope job publishing a positive-polarity run_full output, and adds scripts/check-docs-only-gate.sh to hold the contract's fail-closed properties against ci.yml in place of the prose comment that carried them.

  13. added a commit that references this issue on Aug 23, 2026
    8f2b45c
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.status: readyTriaged, unblocked, and fully specified; eligible to pick up.

Type

No type

Fields

No fields configured for issues without a type.

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions