# AGENTS.md

## Sea Haven Governance

**Standards authority**: The engineering handbook is the single authority for coding standards, naming conventions, and workflow configuration. Do not justify changes by citing it in PR bodies.

**Work authority**: Jira is the source of truth for work status. Before creating a ticket, search Jira for duplicates. Route product work to DEV, infrastructure and platform work to PLAT, and security work to SEC.

**Branch names**: Use `feature/`, `fix/`, `hotfix/`, `chore/`, `docs/`, `refactor/`, or `release/` with a kebab-case description. Do not include Jira keys in branch names. Dependabot branches and emergency reverts are exempt.

**PR title format**: `type(scope): description (DEV-123)` — Jira key required on every non-exempt PR. Dependabot and permission-controlled emergency reverts are exempt.

**PR body headings** (exact, in this order):
1. Summary
2. Validation
3. Tests
4. Notes

**Prohibited**: AI-attribution footers in commits, PRs, comments, or generated artifacts.

**Security gates**:
- PRs touching payment flows, authentication logic, secret handling, AWS IAM, or untrusted user input require security review.
- IAM role, policy, or resource-permission changes require cross-family review.

**CI workflow refs**: All `uses:` refs must be pinned to a 40-char SHA with a `# vX.Y.Z` comment. No floating tags or branch refs.

## Repository Notes

This repo drives the SHOC PR review pipeline and is included in the org-wide policy rollout. SHOC product repos (`shoc-frontend-new`, `shoc-backend`) are excluded from automated review scope but are checked out read-only by this runner.

**Do not edit these workflows:**

- `.github/workflows/ci.yaml` — thin caller whose `ci / ci` check context satisfies the org branch-protection rule; structure must not change.
- `.github/workflows/ci-runner-checks.yaml` — bespoke reusable CI for shell/workflow tooling; no standard org template applies here.
- `.github/workflows/review-pr.yml` — manually dispatched two-job review pipeline with an intentional security boundary between the untrusted `gates` job and the secret-bearing `review` job. Do not merge these jobs; the isolation is a deliberate security control documented in the workflow header comment.