update bmad

Author: root

.github/ai-review-policy.md

@@ -0,0 +1,94 @@
+# AI PR Workflow Policy
+
+This document defines how AI should participate in PR creation, review, and merge decisions for this repository.
+
+## Goals
+
+- Speed up routine authoring and review work
+- Improve consistency of change summaries and review coverage
+- Keep merge authority and release authority under explicit repository controls
+
+## Allowed AI Roles
+
+### 1. PR Authoring Support
+
+AI may help with:
+
+- PR title and summary drafting
+- change categorization
+- release-note draft text
+- test-plan drafting
+- reviewer-facing risk summaries
+
+Human expectation:
+
+- The PR author remains responsible for accuracy.
+- Generated text must be edited if it is vague, inflated, or inconsistent with the actual diff.
+
+### 2. PR Review Support
+
+AI may help with:
+
+- first-pass diff review
+- identifying likely regressions
+- spotting missing tests
+- flagging API, workflow, or release-surface changes
+- summarizing CI results and risk areas
+
+Human expectation:
+
+- AI comments are advisory.
+- CODEOWNER-equivalent human review is still required for risky or cross-cutting changes.
+
+### 3. Merge Readiness Support
+
+AI may help by summarizing whether a PR appears merge-ready based on repository rules.
+
+AI may recommend merge only when all of the following are true:
+
+- required PR checks are green
+- requested human reviewers have approved
+- there are no unresolved review threads
+- no required follow-up item is hidden in comments
+
+## Disallowed AI Roles
+
+AI must not:
+
+- bypass required CI or branch protection
+- approve its own generated code without human review
+- be treated as the sole reviewer for workflow, release, auth, security, migration, or destructive runtime changes
+- directly merge to `main` without repository rules explicitly allowing auto-merge after human approval
+- treat advisory post-merge findings as if they were release-blocking by default
+
+## Repository-Specific Review Focus
+
+AI review should explicitly check whether a PR changed any of these surfaces:
+
+- GitHub Actions workflows under `.github/workflows/`
+- release behavior, tags, release assets, or image publication
+- OpenAPI or API route behavior
+- container startup, runtime env requirements, or e2e behavior
+- installation or bootstrap scripts
+
+If any of those surfaces changed, AI should call them out clearly in the PR summary.
+
+## Recommended Operating Model
+
+Use AI in this order:
+
+1. Draft PR summary and validation notes
+2. Produce a first-pass review summary
+3. Highlight risky files and missing checks
+4. Let humans decide approval and merge
+
+## Merge Authority
+
+Final merge authority stays with:
+
+- branch protection rules
+- required status checks
+- required human approvals
+- repository maintainers
+
+AI is a reviewer-assistant, not a branch-protection substitute.

.github/branch-protection-guide.md

@@ -0,0 +1,79 @@
+# Branch Protection And CI Roles
+
+This repository uses three CI layers with different responsibilities:
+
+- `PR Gate`: the pre-merge blocking gate for `main`
+- `Main Post-Merge`: post-merge validation for merge-result health and advisory supply-chain checks
+- `Release`: tag-based release preparation and draft release creation
+
+Related workflows:
+
+- `.github/workflows/pr-gate.yml`
+- `.github/workflows/main-post-merge.yml`
+- `.github/workflows/release.yml`
+- `.github/workflows/publish-images.yml`
+
+## What Should Block Merge
+
+Only the PR gate should be configured as the required branch-protection check for `main`.
+
+Recommended required check target:
+
+- workflow: `PR Gate`
+- job: `Quality Gate`
+
+Why:
+
+- It is the main admission gate for code entering `main`.
+- It runs lint, tests, security fast checks, and e2e smoke.
+- It avoids using post-merge or release-only checks as pre-merge blockers.
+
+## What Should Not Block Merge
+
+`Main Post-Merge` should validate the merged result, but it should not be the primary merge gate.
+
+In the current design:
+
+- `Build Production Image` is a blocking post-merge health signal for `main`
+- `Advisory Image Security` is informative and should not redefine main-branch health on its own
+
+If `Main Post-Merge` fails:
+
+- treat `Quality Gate` or image-build failures as urgent main-health issues
+- treat advisory scan failures as triage items unless policy says otherwise
+
+## Recommended GitHub Settings For `main`
+
+Enable:
+
+- Require a pull request before merging
+- Require status checks to pass before merging
+- Require branches to be up to date before merging
+- Require conversation resolution before merging
+- Restrict direct pushes to `main`
+- Allow auto-merge only after required checks and approvals pass
+
+Recommended manual settings outside the repository:
+
+- set `PR Gate / Quality Gate` as a required status check
+- require at least one human approval
+- add CODEOWNERS later for sensitive areas such as workflows, release logic, and runtime bootstrapping
+
+## How To Treat AI In Branch Protection
+
+AI review may help summarize and pre-screen PRs, but branch protection should still rely on:
+
+- required CI checks
+- human approvals
+- repository permissions
+
+Do not treat AI comments or AI merge suggestions as equivalent to a required approval.
+
+## Release Layer
+
+Release workflows are not part of the merge gate.
+
+- `Release` validates tags, generates release artifacts, and creates a draft release
+- `Publish Images` runs only after a release is published
+
+This separation avoids using release-specific work as a daily development bottleneck.

.github/pull_request_template.md

@@ -0,0 +1,62 @@
+# Summary
+
+Describe the change in 2-5 lines.
+
+# What Changed
+
+- 
+- 
+- 
+
+# Why
+
+Explain the problem, requirement, or risk this PR addresses.
+
+# Validation
+
+- [ ] `make lint`
+- [ ] `make test backend`
+- [ ] `make test web`
+- [ ] `make e2e`
+- [ ] Other validation noted below
+
+Additional validation notes:
+
+```text
+
+```
+
+# Risk Review
+
+- User-facing impact:
+- Data or migration impact:
+- CI/release impact:
+- Rollback plan:
+
+# Contract Review
+
+- [ ] No API or schema contract changed
+- [ ] OpenAPI or generated contract artifacts were updated
+- [ ] Release notes or changelog impact was reviewed
+- [ ] No release/distribution behavior changed
+
+# AI Assistance
+
+- [ ] No AI assistance was used
+- [ ] AI helped draft code or tests
+- [ ] AI helped draft PR text or review notes
+- [ ] AI output was manually reviewed and corrected where needed
+
+Notes on AI usage:
+
+```text
+
+```
+
+# Reviewer Checklist
+
+- [ ] Scope is small enough to review safely
+- [ ] Validation is appropriate for the changed surface
+- [ ] New behavior is covered by tests or explicitly justified
+- [ ] Docs/workflows/contracts were updated if behavior changed
+- [ ] Rollback or follow-up risk is acceptable