seahaven-org-baseline/AGENTS.md

# Sea Haven Governance

**Standards authority:** engineering-handbook · **Status authority:** Jira

## Routing

- Product / feature work → DEV
- Infrastructure and platform → PLAT
- Security → SEC

## Branches

`feature/`, `fix/`, `hotfix/`, `chore/`, `docs/`, `refactor/`, `release/` + kebab-case description.
No Jira keys in branch names.

## Pull Requests

**Title:** `type(scope): description (DEV-123)` when a Jira ticket already exists. Minor, docs, hygiene, and dependency changes omit the suffix. Do not create a ticket only to fill a title.

**Body sections (in order):** Summary · Validation · Tests · Notes — use "None." when a section is empty.
State verifiable facts only. Do not cite the handbook to justify changes.

Allowed types: `feat` `fix` `docs` `style` `refactor` `perf` `test` `build` `ci` `chore` `revert` `release`.

## CI and SHA Pins

Pin every GitHub Actions ref to a full commit SHA with an inline version comment:

```yaml
uses: actions/checkout@abc123def456 # v4.1.0
```

The deterministic global pre-push security hook must not be bypassed (`--no-verify` requires
explicit approval). Linting stays in CI; do not gate on it locally.

## Repository Note

**High-blast AWS org/IAM substrate.** This repo synthesises and diffs the organisation-level CDK
stack. Always run `cdk synth` and review `cdk diff` output before raising a PR.

## Cursor Cloud specific instructions

CI pins Node 24. On this VM, `node` on `PATH` can resolve to an older binary under `/exec-daemon` ahead of nvm. Select Node 24 in the same shell before `npm` or `cdk`:

```bash
export NVM_DIR="$HOME/.nvm"
. "$NVM_DIR/nvm.sh"
nvm use 24
export PATH="$(dirname "$(nvm which 24)"):$PATH"
```

Canonical checks: `npm ci`, `npm run build`, `npx cdk synth`. Also run `cdk diff` for every stack this change touches and review the output before opening the PR, whenever this VM can read those accounts. If credentials cannot reach an account, say that in Validation and leave the diff for a human reviewer. Do not `cdk deploy` from this environment.
ci: add org PR policy caller (#74) Refs: PLAT-62 2026-08-04 11:56:30 -04:00			`# Sea Haven Governance`

			`Standards authority: engineering-handbook · Status authority: Jira`

			`## Routing`

			`- Product / feature work → DEV`
			`- Infrastructure and platform → PLAT`
			`- Security → SEC`

			`## Branches`

			`feature/`, `fix/`, `hotfix/`, `chore/`, `docs/`, `refactor/`, `release/` + kebab-case description.
			`No Jira keys in branch names.`

			`## Pull Requests`

docs(agents): keep cdk diff required and exempt docs titles Cloud agents still review cdk diff when the VM can read the accounts. Docs, hygiene, and dependency pull requests omit a Jira suffix instead of opening a ticket only to fill the title. Co-authored-by: Adam Moussa <amoussa1229@users.noreply.github.com> 2026-09-28 01:12:53 +00:00			Title: `type(scope): description (DEV-123)` when a Jira ticket already exists. Minor, docs, hygiene, and dependency changes omit the suffix. Do not create a ticket only to fill a title.
ci: add org PR policy caller (#74) Refs: PLAT-62 2026-08-04 11:56:30 -04:00
			`Body sections (in order): Summary · Validation · Tests · Notes — use "None." when a section is empty.`
			`State verifiable facts only. Do not cite the handbook to justify changes.`

			Allowed types: `feat` `fix` `docs` `style` `refactor` `perf` `test` `build` `ci` `chore` `revert` `release`.

			`## CI and SHA Pins`

			`Pin every GitHub Actions ref to a full commit SHA with an inline version comment:`

			```yaml
			`uses: actions/checkout@abc123def456 # v4.1.0`
			```

			The deterministic global pre-push security hook must not be bypassed (`--no-verify` requires
			`explicit approval). Linting stays in CI; do not gate on it locally.`

			`## Repository Note`

			`High-blast AWS org/IAM substrate. This repo synthesises and diffs the organisation-level CDK`
docs(agents): drop security review gates (#156) Agents no longer treat a security review or a cross-family review as a merge gate. 2026-09-26 17:18:04 -04:00			stack. Always run `cdk synth` and review `cdk diff` output before raising a PR.
docs(agents): document Node 24 for cloud agents Co-authored-by: Adam Moussa <amoussa1229@users.noreply.github.com> 2026-09-27 20:18:49 +00:00
			`## Cursor Cloud specific instructions`

			CI pins Node 24. On this VM, `node` on `PATH` can resolve to an older binary under `/exec-daemon` ahead of nvm. Select Node 24 in the same shell before `npm` or `cdk`:

			```bash
			`export NVM_DIR="$HOME/.nvm"`
			`. "$NVM_DIR/nvm.sh"`
			`nvm use 24`
			`export PATH="$(dirname "$(nvm which 24)"):$PATH"`
			```

docs(agents): keep cdk diff required and exempt docs titles Cloud agents still review cdk diff when the VM can read the accounts. Docs, hygiene, and dependency pull requests omit a Jira suffix instead of opening a ticket only to fill the title. Co-authored-by: Adam Moussa <amoussa1229@users.noreply.github.com> 2026-09-28 01:12:53 +00:00			Canonical checks: `npm ci`, `npm run build`, `npx cdk synth`. Also run `cdk diff` for every stack this change touches and review the output before opening the PR, whenever this VM can read those accounts. If credentials cannot reach an account, say that in Validation and leave the diff for a human reviewer. Do not `cdk deploy` from this environment.