micronaut-quality-gates

name	micronaut-quality-gates
description	Shared definition of done for Micronaut planning, implementation, QA, security review, code review, and PR handoff.

Micronaut Quality Gates

This skill defines the minimum bar each role must protect before its execution-policy stage can resolve as approved.

Shared Stage Contract

Before any role resolves its stage:

• the role has read the current execution stage, current stage participant, latest linked GitHub context, and any linked approval
• the role has read executionState.returnAssignee when the issue is in active review
• the role has produced one durable stage artifact that explains the decision
• QA does not collapse intake and verification into one artifact; use separate durable issue documents such as qa-intake and qa-verification
• when the role is the active execution-stage participant, it resolves approved with status: done plus a decision comment and resolves changes_requested with a non-done status, preferably in_progress, so Paperclip routes automatically through currentParticipant and returnAssignee
• manual TODO assignment is reserved for non-policy owner changes outside the active review chain
• for synced GitHub delivery work, approved advances the issue to the next stage or PR follow-through; it is not permission to mark the Paperclip item DONE
• if a human governance decision is required, the role creates or updates a real Paperclip approval instead of treating a comment as approval
• if non-governance board or user input is required, the role uses an issue-thread interaction instead of a loose comment: suggest_tasks for selectable task lists, ask_user_questions for bounded questions, and request_confirmation for explicit plan or proposal confirmation
• the role advances or assigns the issue correctly and lets Paperclip routing wake the next participant; an agent-authenticated caller must not attempt to invoke another agent's heartbeat
• if Paperclip has opened a productivity review issue with issue_productivity_review for the source issue because of a no-comment streak, long-active duration, or high-churn loop, the manager or CEO records a queue-health manager decision on that review issue before the source work is forced to continue
• the role re-opens the issue and verifies the execution state matches the intended outcome before finishing

Intake Gate

Before an actionable issue moves out of QA intake:

• a human has moved the synced issue from BACKLOG to TODO
• deduplication has been performed against open and closed GitHub issues in the same synced repository, and closed GitHub issues were evaluated by why they were closed, including closure disposition, duplicate links, closure comments, and already-implemented evidence, before QA forms the triage opinion
• the issue has the correct type: label, unless it is on a documented immediate-closure path
• QA has identified the repository's actual current default branch, the latest stable non-pre-release release, the next release implied by that branch, the SemVer delta from latest stable to next release, and the target branch decision; GitHub prereleases such as milestones (-M<number>) and release candidates (-RC<number>) do not count as the default branch having already shipped
• QA has decided whether the issue's SemVer impact fits the default branch's major/minor/patch release target and recorded any mismatch instead of inventing a non-default target branch; the PR target branch is not automatically the default branch, and an alternative target requires a maintainer, Architect-approved plan, or linked human approval
• QA has chosen the best-fit Micronaut organization project set for the eventual PR, or recorded that no matching project exists yet or tooling cannot apply it; Micronaut organization projects represent Micronaut Platform BOM release boards, not repository module or project versions. When a GA target has both matching milestone or release candidate boards and a GA release board open, the set includes all matching projects, such as both 5.0.0-M3 and 5.0.0 Release
• any linked contributor PR has been evaluated for whether it should stay on the normal gates or be replaced by a separate maintainer-owned PR while staying open
• confident questions use the documented type: question plus closed: question direct-answer path
• clarification requests use the documented status: awaiting feedback path and may close after 30 days with closed: question
• bugs have a reproducer or a precise non-reproducer record
• direct QA triage closures that are not duplicates use GitHub's native Close as not planned reason instead of Close as completed
• unreproduced bugs that now point toward closure use the documented closed: cannot reproduce path instead of falling back to changes_requested
• duplicates use the documented closed: duplicate path with GitHub's native Close as duplicate reason and a link to the superseding GitHub issue
• already-implemented closures cite the exact version, PR, release, or documentation evidence and use QA's direct closure path
• closure comments contain detailed evidence, are not short generic close notes, and cite the exact facts that justify the closure
• the authoritative qa-intake booleans and ordered stageSequence encode the correct downstream route; issue type is only a surface label and does not select the route
• required all-of gates are modeled as separate sequential stages instead of one multi-participant stage
• if the issue needs a public answer or closure outside QA's direct GitHub authority, the board-approval path is explicit
• if intake needs bounded maintainer input rather than open-ended discussion, QA uses ask_user_questions with clear options and a continuation policy so the issue resumes when answered

Planning Gate

Before implementation starts, the plan artifact must state:

• target repository and branch
• target release or release line
• the QA-derived release-targeting facts still hold, or any revision is explicitly justified
• problem statement and expected outcome
• acceptance criteria
• compatibility and migration impact
• test strategy
• documentation impact
• whether the change must remain non-breaking
• the QA-selected Micronaut organization project set, or the recorded ambiguity or tooling gap that explains why the live PR may not carry it yet
• explicit human approval when the change needs one
• when the plan needs confirmation but not governance approval, a request_confirmation interaction targets the latest plan document revision with a stable idempotency key and a continuation policy

If any required items above are missing, planning does not resolve as approved. The QA-selected organization-project set or ambiguity note should be carried forward, but missing live linkage alone does not block planning approval.

Implementation Gate

Before code or docs leave implementation:

• the change is the smallest safe diff
• the change follows the approved plan or makes the QA reproducer pass
• tests cover the changed behavior, or the implementation artifact explains why that is impossible
• docs impact is addressed or explicitly ruled out
• branch and release-line choices are correct
• git work used the local git CLI
• hidden cleanup has not been bundled without approval
• the next QA stage can verify the work without reconstructing intent from scratch
• repository-changing work has one immutable full commit SHA and a publication-manifest containing the proposed base, title, body, linkage, labels, projects, reviewers, and PR-visible assets; no agent-owned PR is created before internal approval

QA Gate

The QA Engineer verifies:

• intake decisions are correct and the downstream stage sequence is correct
• release-targeting facts, SemVer delta, approved target branch, allowed change class, and organization-project selection from QA intake are correct, including any GA-plus-prerelease project set
• the implementation still matches the approved plan or the reproducer
• when a linked contributor PR exists, QA has correctly decided whether it remains the implementation vehicle or should be replaced
• the original issue or PR concern is actually resolved
• tests and documentation support the claimed change
• visual, browser-rendered, or file-based evidence has been captured locally and named in publication-manifest; the publication owner must upload and verify the same evidence after approval without changing the reviewed commit
• no important acceptance criteria were silently dropped
• public answers and closure paths use the correct GitHub labels when applicable, use GitHub's native Close as not planned or Close as duplicate reason as appropriate, include detailed evidence rather than short generic close notes, treat evidence-backed already-implemented issues as part of QA's direct closure authority, and only require Paperclip board approval when the path is outside QA's direct GitHub authority

Work that passes QA moves into the next configured review stage or completes through the allowed direct GitHub answer or closure path. Inside an active execution-policy stage, QA should let Paperclip move the issue into the next in_review participant automatically. When QA is changing owners outside the active review chain, it should use a normal TODO assignment plus a clear next-action comment. Work that needs a board-approved public answer or closure resolves as request_board_approval. Work that fails QA resolves as changes_requested.

Security Gates

Security participates only when the authoritative ordered qa-intake.stageSequence includes it. In either Security stage, the Security Engineer checks for:

• source-code exploit paths and attack-surface changes
• authentication, authorization, secret handling, serialization, filesystem, process, and network risk
• dependency, build, CI/CD, release, and supply-chain risk
• insecure defaults or examples that would steer users into unsafe deployment or configuration choices
• whether blocking findings are concrete enough to justify changes_requested

Approved pre-triage advances only to the next entry in the authoritative ordered qa-intake.stageSequence, which is Architect when planning is required and otherwise the implementation owner. Pre-triage does not skip Architect, implementation, QA verification, or final Security review. Approved final Security review advances to Code Reviewer. A rejected Security stage returns through the execution policy as changes_requested.

Code Review Gate

The Code Reviewer checks for:

• correctness beyond the happy path
• maintainability and readability
• performance and regression risk
• API, config, and developer-experience quality
• missing or weak tests
• for unpublished agent-owned work, exact-SHA diff quality and the complete publication-manifest; for an already-open surviving PR, live linkage, label, reviewers, and project associations
• if approved is chosen for unpublished work, every applicable upstream gate names the same immutable SHA and the implementation owner is recorded for publication-only follow-through
• if a human maintainer changed, rescheduled, or retargeted the PR organization project after PR creation, that maintainer project change is authoritative and must remain; code review must not restore, reapply, re-add, or reset the original QA-selected organization project set over the maintainer's choice
• once the approved target branch is identified, the work branch is fetched and updated from the target branch before starting work, editing, committing, opening, creating, or updating a PR; target branch rebase or merge conflicts are recorded as blockers instead of publishing conflicting PRs

If unpublished work is approved, Code Reviewer returns a publication-only handoff to the durable implementation owner; Reviewer never publishes. If an acceptable PR already existed before internal review, Reviewer verifies it without mutation. Otherwise it resolves changes_requested. Routine prose and executable docs omit Security; security-sensitive work follows the configured Security stages.

PR Gate

Before a PR is considered healthy:

• every applicable internal gate approved the same immutable SHA before the implementation owner created the PR; publication read-back proves the remote SHA and metadata match publication-manifest
• the synced Paperclip delivery item remains open until GitHub merge or an approved GitHub closure path syncs back
• the summary and rationale are coherent
• linked issue context is accurate and uses a closing keyword
• the PR carries exactly one type: label
• the PR should be linked to all selected Micronaut organization projects chosen during QA intake when GitHub tooling can apply them; those projects represent Micronaut Platform BOM release boards, not repository module or project versions. If that choice carried ambiguity, the PR description repeats it; prose alone is not a substitute for the live organization-project association; missing linkage due to no matching project or tooling gaps does not by itself block a healthy PR. For a GA release target with concurrent prerelease and release boards, link both the matching prerelease board and the GA release board, for example 5.0.0-M3 and 5.0.0 Release. If a human maintainer changes, reschedules, or retargets the PR organization project after PR creation, preserve that maintainer project choice and do not restore, reapply, re-add, or reset the original QA-selected organization project links unless a later maintainer or board decision explicitly asks for it.
• test evidence is ready to share
• visual evidence and generated review artifacts are embedded in the PR body when the change affects rendered output or produces files such as PDFs, using paperclip-github-plugin:upload_pull_request_asset; if upload fails, the PR explains the concrete permission, size, MIME, or runtime blocker instead of saying assets are unavailable
• documentation or migration notes are included when needed
• guide-related PRs created or updated by guide routines carry the type: docs label
• guide, docs, or documentation PRs whose CI is not needed because the changed docs are not exercised by the build use a skip-ci keyword in the commit message, such as [skip ci]
• guide, docs, or documentation PR branches are updated from the target branch before opening or updating the PR; rebase or merge conflicts are recorded as blockers instead of publishing conflicting PRs
• standalone micronaut-guides PRs created or updated by guide routines include the generated guide PDF as a PR-visible uploaded artifact or attachment link, and the PDF is not committed to the repository
• applicable security review comments are addressed; prose-only docs have no Security gate
• CI is green
• Sonar Quality Gate issues are addressed
• all review threads are replied to with a decision explanation before they are resolved
• the maintainers can understand the change without reconstructing hidden context
• the team remembers that only the board or other maintainers merge or release