feat: governance improvements

[krancour]

Supersedes #6065

Summary

This PR is a significant overhaul of how contributions to Kargo are governed.

1. Contributor docs

Updated the Contributor Guide to more clearly describe the issue-first contribution model: contributors open an issue, maintainers review and unblock it, and only then is a pull request welcome. The guide spells out the conditions under which work on an issue may proceed.

2. Issue and PR templates

The old Markdown issue templates have been replaced with structured YAML forms for bug reports and feature requests. A new PR template sets expectations up front — linked issue, scope, quality bar.

3. Governance bot

Replaces the Birthday Research oss-governance-bot GitHub Action and adds a substantial crop of new capabilities.

This is also substantially more lightweight than alternatives like prow.

High-level features:

• PR policy enforcement: PRs without a linked issue — or linked to a blocked issue — are automatically closed with an explanatory comment. Maintainers and bots are exempt. (The old bot did not do this.)

• Label governance: new issues and PRs that lack required label prefixes (area/, kind/, priority/) get a needs/<prefix> label added automatically. (This is roughly the extent of what the old bot did.)

• Automatic PR assignment: new PRs are automatically assigned to their author. (The old bot did not do this.)

• Label inheritance: new PRs inherit kind/* and area/* labels from their linked issue so classification carries through. (The old bot did not do this.)

• Slash commands: maintainers can drive triage with commands like /discuss, /research, /maintainer, /duplicate #N, /enterprise, /unblock, /premature, /quality, /unsolicited, and a context-aware /help. Multiple commands per comment are supported.

Behavior is driven entirely by .github/governance.yaml straight from the repo's main branch. Adding a new slash command, changing a canned message, adjusting blocking labels, or tweaking PR policy is a config change that does not require the bot to be re-deployed.

4. Deployment

The bot is intended to run as an AWS Lambda behind a Function URL.

It must be deployed and wired into a new GitHub App before this PR is merged.

Labels to create

Two new labels need to exist on akuity/kargo before merge:

• policy/no-linked-issue
• policy/blocked-issue

All other labels referenced by the config already exist.

Testing

Extensively tested end-to-end on krancovia/kargo.

Demo

I'll provide a live demo later in the week.

[netlify]

✅ Deploy Preview for docs-kargo-io ready!

Name	Link
🔨 Latest commit	a2d88d3
🔍 Latest deploy log	https://app.netlify.com/projects/docs-kargo-io/deploys/69e41d7c8e8b4e0008fb1291
😎 Deploy Preview	https://deploy-preview-6077.docs.kargo.io
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[codecov]

Codecov Report

❌ Patch coverage is 68.92265% with 225 lines in your changes missing coverage. Please review.
✅ Project coverage is 57.64%. Comparing base (e5f5a4c) to head (a2d88d3).

Files with missing lines	Patch %	Lines
pkg/governance/handler.go	62.41%	39 Missing and 14 partials ⚠️
pkg/governance/actions.go	46.15%	39 Missing and 10 partials ⚠️
pkg/governance/github_client.go	68.80%	32 Missing and 7 partials ⚠️
cmd/governance-bot/main.go	0.00%	36 Missing ⚠️
pkg/governance/pr_handler.go	82.22%	19 Missing and 13 partials ⚠️
pkg/governance/comment_handler.go	90.09%	7 Missing and 3 partials ⚠️
pkg/governance/issue_handler.go	82.60%	2 Missing and 2 partials ⚠️
pkg/governance/common.go	92.59%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6077      +/-   ##
==========================================
+ Coverage   57.44%   57.64%   +0.20%     
==========================================
  Files         474      482       +8     
  Lines       40230    40954     +724     
==========================================
+ Hits        23110    23609     +499     
- Misses      15745    15920     +175     
- Partials     1375     1425      +50     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[krancour]

@hairyhum had a suggestion to add changing a PR to/from draft status would be another useful action. I will add that.

[krancour]

Added several improvements:

1. At @hairyhum's suggestions, I added "convert to draft" as a possible action and softened our own policy in governance.yaml to convert blocked PRs to drafts instead of closing them.

2. Added an action to re-evaluate a PR against policy. Wired it into the /policy command. This can be used for ad-hoc policy re-evaluation when any conditions that may affect its outcome have changed.

3. Policy is re-evaluated when a closed PR is re-opened or when a draft PR is marked ready for review.

4. It is now possible to specify the actions to execute when a PR passes policy. So, for instance, if certain labels were added in response to policy violations, this creates the opportunity to, remove them.

[krancour]

Reminder to self: Implement a way to optionally exempt PRs from policy based on miniscule size or being a docs-only change.