ci: hygiene aggregate annotations name the failed gate but not why it failed

[kyle-sexton]

Problem

Each hygiene gate step in lint and lint-2 runs with continue-on-error: true, and scripts/aggregate-hygiene-results.sh fails the job at the end. For a failed gate it emits only:

::error title=<check> failed::Hygiene check finished with outcome: failure

The gate step's own annotation is the generic "Process completed with exit code 1." with no step name. The reason (which file, which rule, what command fixes it) is printed only in the gate step's log, so a reader has to open the full job log and search for it.

Evidence

Run 37094085450, job lint-2 (111120385079), on #5992:

gh api repos/melodic-software/claude-code-plugins/check-runs/111120385079/annotations returns six annotations: three "Process completed with exit code 1." and three "Hygiene check finished with outcome: failure" titled spoke-plugin-root failed, plugin-options-docs failed, shell-portability-lint failed. The reasons are only in the 3,976-line log:

• line 802: plugins/harness-config/skills/audit/reference/audit-checklist.md: has 2 occurrence(s) of ${CLAUDE_PLUGIN_ROOT}, scripts/spoke-plugin-root-baseline.txt allows ...
• line 1234: STALE options docs in 1 plugin(s): harness-ops / Run: python scripts/sync-plugin-options-docs.py
• line 3714: PORTABILITY: plugins/harness-ops/hooks/session-event-log.test.sh:345: \\b -> ...

Each of those lines would have been enough to fix the failure without opening the log.

Impact

Every hygiene failure costs a log download and search (gh run view --log plus grep, or scrolling the web log) before the fix can start. Agents pay this on every red run, and the PR checks page shows nothing actionable.

Proposed fix options

1. Capture each gate's output and put its tail in the aggregate annotation. Each gate step tees stdout and stderr to $RUNNER_TEMP/hygiene/<id>.log; on failure the aggregator adds the last N lines (say 10) to the ::error message and writes all failing tails to $GITHUB_STEP_SUMMARY. One change in the aggregator plus a tee in each step, or a small wrapper the steps call.
2. Have each gate script emit its own ::error file=...,line=...:: annotations. Best signal (inline on the diff), but it means editing about 35 scripts and the composite actions in ci-workflows.
3. Fold this into the single gate runner proposed in the companion draft ("ci: add one local entry point that runs the lint and lint-2 hygiene gates against the diff"): the runner already holds each gate's output and can emit the annotation itself.

Recommendation: option 1 now, which is small and self-contained, and option 3 if the gate runner lands. Basis: the annotation and log lines above.

Acceptance criteria

• For a failed hygiene gate, the check run's annotations include at least the gate's last non-empty output lines, so the three failures in run 37094085450 would each show their reason line above in the annotation.
• The job summary lists every failing gate with its output tail.
• scripts/aggregate-hygiene-results.sh --self-test covers the new behaviour.

[kyle-sexton]

This was generated by AI during triage.

Decision defaulted: option 1, so each failing hygiene gate's output tail goes into its aggregate annotation and the job summary, instead of waiting for the gate runner in #6008 (option 3) — veto before merge
Basis: verified, scripts/aggregate-hygiene-results.sh:23 (the only annotation is ::error title=<check> failed::Hygiene check finished with outcome: <result>); .github/workflows/ci.yml:978, :1230, :1611, :1936 (the aggregator runs at the end of four hygiene jobs); .github/workflows/ci.yml has 69 continue-on-error: true steps.

Verification: confirmed on main. The aggregator still emits only the gate name and outcome. Stale title and body: lint and lint-2 no longer exist. The hygiene gates now run in four jobs (lint-repo, lint-shell, check-plugins, check-skills), each ending in the aggregator. The brief below says "every hygiene job".

Overlap with #6008: #6008 (one local runner that CI also calls) is routed for a human decision. If it lands, its runner can emit these annotations itself (this issue's option 3). Both changes touch the same gate steps, so whichever lands second rebases onto the other's. Option 1 is small, can be undone, and helps every red run in the meantime, as the issue body recommends.

Priority: medium. Work class: scoped (C3), feature.

Agent Brief

Type: Feature
Summary: A failed hygiene gate's annotation and the job summary show why it failed, not only that it failed.

Current behavior:
Each hygiene gate step runs with continue-on-error: true. The hygiene aggregator then fails the job, emitting one ::error title=<gate> failed::Hygiene check finished with outcome: failure per failed gate. The reason (file, rule, fix command) appears only in that step's log.

Desired behavior:

• Every hygiene gate that runs as a run: step captures its combined stdout and stderr to a per-gate file under the runner's temp directory, and still prints it to the step log as today.
• On a failed gate, the aggregator's ::error message carries the last 10 non-empty lines of that gate's output (escaped for workflow-command syntax so newlines and % survive).
• The aggregator writes every failing gate, with its output tail, to the job summary.
• A gate that runs as a uses: composite action, whose output cannot be captured this way, gets a "see the step log" line in the annotation and summary instead of a tail. It is never left out silently.
• When no output file exists for a failed gate, the annotation falls back to today's text plus "no captured output".
• Gate pass/fail semantics and exit codes are unchanged.

Key interfaces:

• Hygiene aggregator input: today <gate>=<outcome> records; it also locates each gate's captured output by gate id.
• Aggregator --self-test: covers the new behavior.
• Gate steps in every hygiene job: one consistent capture pattern (a small wrapper or a tee), the same for each run: gate.

Acceptance criteria:

• --self-test covers: a failed gate with captured output yields an annotation containing its last non-empty lines; a failed gate with no output file yields the fallback; a composite gate yields the "see the step log" line; all-success yields no annotation.
• On a PR that deliberately breaks one run: gate, the check run's annotations include that gate's reason line, and the job summary lists it with its tail.
• Every run: hygiene gate in every hygiene job uses the capture pattern.

Out of scope:

• Editing each gate script to emit its own file=/line= annotations (option 2).
• Changes to the ci-workflows composite actions.
• The local gate runner (ci: add one local entry point that runs the lint and lint-2 hygiene gates against the diff #6008).

[kyle-sexton]

This was generated by AI during work-loop.

Approve this for autonomous dispatch (with its defaulted decision), or keep it for a human?

Triage marked this decision-defaulted as a feature-shaped C3 (work-class: scoped). The work-loop admission gate human-gates feature-shaped C3 work, so the lane removed agent-ready and applied needs-human. Flip it back through /work-items:attend-queue to dispatch.

Lane: work-loop, instance melo-worker-1, cycle 2.