Codify the org security + merge baseline: auto-merge and auto-delete
head branch (no org default, set per-repo), and the secret-scanning /
CodeQL / code-security surface carried by the 'Sea Haven Standard' org
Code Security Configuration. Note docs-repo CodeQL exception and the
shoc-backend/shoc-frontend-new exclusion.
Capture the org conventions rolled out in the INFRA-47 hygiene pass:
- github-standards.md: static-only README badges (dynamic shields break on
private repos; CI badge is member-only) and a lowercase-hyphenated repo
topic vocabulary, both part of new-repo provisioning.
- cicd.md: the central inline-config reusable PR labeler — pull_request
trigger, the three required caller permissions, no per-repo labeler.yml.
Exact pins remain (reproducibility) but the pinned version is kept
current by Dependabot version updates gated by CI + dependency review,
not by a number frozen in the handbook. Blanket dependabot ignore
entries are banned; version-specific ignores only, commented and
temporary. Bundled-dep vulnerabilities are a prompt to advance the
pin, never to dismiss the alert.
2.253.1 bundles fast-uri 3.1.0 (two high-severity GHSAs, unfixable via
overrides since it ships in the tarball). 2.257.0 bundles patched
fast-uri 3.1.2 and passes npm ci (the 2.254.0 breakage that motivated
the old pin was release-specific).
Pinning every Dependabot PR to a single assignee created noise and a
bottleneck. Remove the assignee requirement and the per-ecosystem
assignees blocks from the example configs.
Both pages existed in working drafts but were not linked from the
README table of contents, so they were undiscoverable. Add them to the
index alongside the related SAM layout and code review pages.
Work is tracked in Jira while code lives in GitHub; the org-level GitHub
for Jira app is already installed but nothing told contributors how to
trigger the link. Document putting the Jira key in the branch name, PR
title, or Refs trailer so branches, commits, and PRs thread into the
issue's development panel. Use a generic PROJ-123 placeholder rather
than naming specific projects, which change over time.
Require PR authors to create a GitHub issue for any review
finding deferred past the current PR, and link it in the
review thread before merging. Prevents informal tracking
from dropping items.
Adds three handbook pages covering conventions that were previously
scattered across feedback memories or rederived from scratch each
time:
- bedrock.md captures the cross-region inference profile requirement
for Claude 4.x Bedrock Agents and the alias-version pinning gotcha,
plus the IAM resource pattern and the KB Docker requirement.
- dev-environment.md documents the workstation directory layout,
pyenv/Node conventions, the macOS launchd/TCC sandbox gotcha, and
cleanup cadence.
- lambda-template.md provides a minimal SAM scaffold that follows the
Lambda defaults already in aws-infrastructure.md (Python 3.12,
arm64, explicit 60-day log retention, scoped Secrets Manager
access, module-level secret cache).
Also extends two existing pages:
- sam-project-layout.md gains a Lambda Layers section with the
BuildMethod nesting pattern that caused a ~22-hour production
outage when violated.
- naming-conventions.md adds a Legacy Stacks note acknowledging that
pre-convention PascalCase stacks (SeaHavenDoorUnlockStack,
WorkorderIngestStack) stay as-is rather than risk stack
replacement.
* Update CDK version policy, Node 24 runtime, and GitHub Actions CI/CD
- Pin blessed aws-cdk-lib version (2.253.1) with upgrade procedure
- Update Lambda runtime default from Node 22 to Node 24
- Rewrite CI/CD page to reflect GitHub Actions reusable workflows
(was still referencing CodePipeline/CodeBuild)
* Add pre-push hook for npm ci validation
Catches lock file drift locally before it breaks CI. Includes
install instructions in git-workflow.md.
* Add repo provisioning script
Automates the new-repo checklist: GitHub repo creation, OIDC deploy
role, repo secret, security features, CI/CD workflow stubs, and
pre-push hook installation. Supports both SAM and CDK stack types.
* Add shared VpnEc2Instance CDK construct
Reference construct for the VPN-accessible EC2 pattern used by
file-share and forgejo. Includes VPC/subnet lookup, SG, IAM role,
encrypted EBS, and DLM snapshots. Copy into lib/constructs/.
* Add post-deploy health check template
Template script for project-specific health checks. Copy to
scripts/health-check.sh — CD workflows run it automatically.
Documents the org-wide policy for dependabot.yml files: ecosystem
selection, standard templates for single/multi-ecosystem repos and
SAM projects, auto-assignment, and merge guidance.
