Skip to content

feat(rhdh-jira-lint): remediate Jira hygiene instead of notifying - #172

Open
Fortune-Ndlovu wants to merge 2 commits into
mainfrom
feat/rhdh-jira-lint
Open

Fortune-Ndlovu wants to merge 2 commits into
mainfrom
feat/rhdh-jira-lint

Conversation

@Fortune-Ndlovu

Copy link
Copy Markdown
Member

What this replaces

The RHDH Jira lint job finds hygiene violations and sends them to assignees in Slack. The findings are often seen and not acted on, so the job's output is not the outcome the team wants: a compliant issue.

This skill removes the hop. It finds the violation, investigates the issue, applies the agreed procedure, writes the value, verifies it by read-back, and leaves one comment explaining what changed and why. The runner only has to invoke it.

What one invocation does

  1. Resolves the scope: a person, a team, a release, an explicit JQL, or the open backlog.
  2. Discovers release dates through /rhdh-release-schedule — no calendar file has to be prepared first.
  3. Runs the rule set with scripts/scan.py and reads findings, exemptions, calendar gaps, and warnings.
  4. Investigates each finding using the evidence ladder in references/investigation.md.
  5. Derives, estimates, classifies, drafts, or escalates. Every value carries its basis.
  6. Writes through scripts/apply.py, which checks the precondition, writes, reads back, and records before/after.
  7. Posts one receipt comment per changed issue, mentioning the assignee or the reporter.

Rule coverage

The scanner reproduces the deployed bot's rule set: missing Component, Priority, Story Points, T-shirt Size, duplicate Fix Versions, Feature/Code Freeze priorities, GA leftovers, and the three Release Note rules — with the Documentation-team and Release-component exemptions, and the Release Pending / subtask / Outcome / [test execution] exclusions.

Four deliberate differences, all turning silent failures into loud ones:

  • Custom field IDs are resolved by name at run time, never hard-coded.
  • The scanner no longer fetches on conditions the bot never reports (affectedVersion is EMPTY, staleness).
  • Release Note Status is enforced only when the field exists.
  • An empty ADF body counts as empty.

Dates

ga_push is the GA announce date, never Go/No Go. The scanner accepts the YAML calendar or the JSON /rhdh-release-schedule returns, in either shape. TBD or incomplete versions are reported in scope.calendar_problems, and versions in scope without a usable entry are listed in scope.calendar_missing_versions; their date-dependent rules are skipped, unrelated rules continue. The skill never estimates a milestone date.

Autonomy and safety

docs/adr/0013-unattended-jira-remediation.md records the decision. An unattended invocation authorizes only the skill's published procedures; there is no separate runner policy file. The executor enforces it mechanically:

  • the field must still be empty;
  • the issue must still be in scope;
  • the payload must use a supported field and value;
  • plans over 50 operations are refused;
  • every write is read back, and a mismatch is failed.

The skill never writes transitions, closures, assignments, or exemptions, and never derives Blocker or Critical. Interactive runs keep the existing mutation gate.

Comments

One comment per distinct batch, marked with [rhdh-jira-lint] plus a short batch hash. A retry of the same batch is unchanged; a new batch gets a new comment. No comment when nothing changed, and escalations go in the summary rather than on the issue.

Tests and evidence

  • Full suite: 986 passed, 1 skipped.
  • 40 focused tests for rule parity, exemptions, release phases, calendar shapes, mention fallback, comment-batch idempotency, and plan validation.
  • Fake-Jira end to end: JSON calendar → LINT-COMPONENT, LINT-POINTS, LINT-FF-PRIORITY; 2 writes verified; 1 comment created; a second run skipped both writes and left the comment unchanged; rescan showed only the escalation.
  • Ruff check and format clean; catalog valid; generated marketplace and /ask-rhdh routes current; pinned markdownlint clean.

Out of scope

references/inventory.md records the old job's remaining responsibilities and marks three gaps rather than claiming them: the docs-review queue, the Backstage version-bump announcement, and the SoS reminder. Freeze announcements already belong to /rhdh-release-announce.

Reviewer notes

The procedures that decide how much the skill may decide alone are in references/remediation.md — particularly the priority table (never infers Blocker/Critical) and the sizing evidence requirements. Those are the part worth arguing about before merge.

Find the lint findings, investigate the issue, apply the agreed procedure, write the value, verify it by read-back, and leave one receipt comment that mentions the assignee or the reporter.

The scanner carries the rule set from rhdh_jira_lint.py, with four deliberate differences that turn silent failures into warnings. Release dates are discovered through the release skills, so no calendar file or runner-side refresh job is required. Comments carry a batch hash, so a retry is a no-op and a new batch is a new comment.

ADR-0013 records the bounded unattended authorization for this skill only.
@Fortune-Ndlovu Fortune-Ndlovu self-assigned this Nov 18, 2026
Enforce schema 2 evidence, rule and field allowlists, issue grouping, Red Hat Employee comment visibility, fixed Jira host, durable receipts, and guarded rollback. Align story-point guidance with rhdh-jira-authoring and mark that dependency required.
@mattreid

Copy link
Copy Markdown
Contributor

Hey @Fortune-Ndlovu, thanks for getting this started. I did a pass to try and harden it, position it better to be used in a one-shot, non-interactive style (like chai-bot/fullsend) and clean up some boundaries across the rest of the skill pack, but there are more to work through still. I haven't run this live, so please put it through its paces and keep iterating on anything you think needs more work. Happy to chat more about this next week.

Hardening update

This tries to tighten the unattended remediation path after review feedback from GLM, Deepseek, and Muse.

Safety model

The executor now treats the remediation plan as untrusted input and mechanically enforces the published procedure:

  • schema 2 plans only;
  • rule-specific evidence;
  • rule, field, and value allowlists;
  • issue scope, status, type, summary, and expected updated timestamp;
  • empty-only preconditions;
  • a hard cap of 50 issues and 50 operations;
  • one grouped issue update per issue;
  • read-back verification for every written field;
  • a receipt comment only after every field on that issue verifies.

Priority policy

The executor now allows:

  • Normal, Major, and Minor from direct evidence;
  • Blocker and Critical only when inherited from a verified parent.

It rejects self-inferred Blocker or Critical.

Comment safety

Every lint receipt comment is:

  • derived from successful writes;
  • restricted to the Red Hat Employee Jira group;
  • read back after creation;
  • checked for exact body and visibility;
  • paginated and idempotent by run ID and canonical operation set.

If any write on an issue fails, that issue receives no receipt comment.

Credential and transport hardening

The bundled Jira client now:

  • fixes the Jira host to https://redhat.atlassian.net;
  • rejects arbitrary JIRA_BASE_URL values;
  • blocks redirects;
  • checks token-file permissions;
  • retries 429 once;
  • suppresses Jira notifications for writes and comments.

Audit and rollback

Confirmed runs now require both:

  • a durable receipt;
  • a guarded revert plan.

Receipts and revert plans are written atomically after every issue, so an interrupted run still records every write already applied.

Revert plans use equals preconditions against the value written by the original batch, so rollback cannot overwrite a newer human edit.

Boundary cleanup

I also deduplicated the obvious skill boundaries:

  • /rhdh-jira-refine now reports readiness gaps and no longer claims lint-owned Priority and Component remediation;
  • /rhdh-jira-lint owns only its automated receipt comments;
  • /rhdh-jira-update owns human-authored comments, transitions, links, and waivers;
  • Story-point and T-shirt sizing now defer to /rhdh-jira-authoring;
  • /rhdh-jira-lint now requires:
    • /rhdh-jira-authoring;
    • /rhdh-release-schedule;
    • /rhdh-feature-docs.

Verification

  • Focused lint/catalog tests: 103 passed
  • Catalog validation: passed
  • Generated /ask-rhdh routes: current
  • Ruff check and format on changed files: passed
  • Full suite on macOS: 996 passed, 1 skipped, 3 failed
    • The three failures are pre-existing BSD sed failures in the base-image tests and are unrelated to this change.

Boundaries left for follow-up

These are deliberately left as discussion items rather than hidden in this patch:

  1. Jira API adapter ownership

    /rhdh-jira-lint bundles a skill-local authenticated Jira adapter so it remains self-contained. This overlaps the authenticated REST boundary owned by /rhdh-jira-api. We should decide whether to keep that as a documented exception or move the adapter boundary into /rhdh-jira-api.

  2. Runtime field-ID discovery

    The lint scanner resolves custom fields by name at runtime. That avoids stale hard-coded IDs, but /rhdh-jira-api is the nominal owner of Jira field mechanics. We should decide whether to document this as a deliberate lint exception or move discovery into the API skill.

  3. Generated comments and /prose-editing

    Lint receipt comments are mechanically derived from structured evidence. We should decide whether those generated audit comments are exempt from the prose pass, while free-form Release Note Text remains subject to /prose-editing.

  4. Release-calendar cache provenance

    /rhdh-release-schedule owns milestone truth, but lint still accepts a local calendar as a cache. We should define freshness and provenance requirements for that cache.

  5. Mutation-gate exception documentation

    ADR-0013 defines a narrow unattended exception for /rhdh-jira-lint. /mutation-gate may need a short cross-reference so agents reading only that skill understand the exception.

  6. Setup documentation for the lint token-file requirement

    The lint compatibility now correctly requires the token file. A follow-up may update /setup-rhdh-skills to surface that requirement explicitly.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants