source: .claude/rules/forge-et-iaac.md · generated — edit the markdown, not this file

forge-et-iaac — a developer’s change is a PR to dev

The detail behind git-conventions.md § forge-et-iaac. Read this file before branching, pushing or opening a PR in forge-et-iaac.

forge-et-iaac (the DevOps repository, AD #23) is not one of the four delivery repos and has its own conventions:

  • Its trunk is dev, not main. A developer (Tharinda, Dinil, and any other delivery-team member, and every Claude session working for one) branches from dev and opens the PR against it (gh pr create --base dev), and never pushes to dev directly. The DevOps team, Shyamin Ayesh and Senuthmi Thimansa, may push to dev directly (the lead’s rule, 2026-10-05), so a change on dev with no PR is expected and not a finding.
  • When dev changes, the harness documents that describe the estate are updated — .forge/design/environments-and-identity.md §4 (what is applied, the open PRs), the register’s “Start here” steps and A-5 (.forge/cloud-gated-validation.md), and the open-risks paragraph of .forge/active-context.md. Read git -C ../forge-et-iaac log origin/dev at the start of any F38 work and after the DevOps team reports a change; the standing reminder is in .forge/owed.md. The deploys live in the app repos — forge-et-be (.github/workflows/build.yaml and .aws/td.dev.json), forge-et-fe and forge-et-pwa (.github/workflows/build.yaml in each; the capture app’s came from the delivery team’s forge-et-pwa#91) — and the DevOps team may push changes to them straight to main (git-conventions.md § Branch Protection), so read git -C ../<app-repo> log origin/main -- .aws .github/workflows for each at the same time.
  • Terraform is written in a linked worktree, never in the checkout. protected-paths.sh allows the Edit and Write tools on .tf and .tfvars files only under $WS/worktrees/<ticket>/…/forge-et-iaac/ — a worktree made, from origin/dev, for a work item whose plan was approved — and still refuses them in $WS/forge-et-iaac itself and in every other repository. Never write Terraform through Bash to get past the hook.
  • Every Secrets Manager secret is declared in one shared base module, never in a module of its own per feature (Shyamin Ayesh’s request, 2026-10-25): base/secrets, where a new secret is a new key in its list (forge-et-iaac#9). Each secret is still created without a value (no aws_secretsmanager_secret_version), its value set by hand. A change that would move a secret’s address uses a moved block, so the plan shows a move, not a destroy: a destroyed secret loses its value and keeps its name reserved for the recovery window.
  • Check before review, and get the plan from the workflow. Before asking for review, run terraform fmt -check -recursive at the root, then terraform init -backend=false and terraform validate in overlays/dev and in overlays/uat (dev.yaml checks only overlays/dev, so a base/ change that breaks the other overlay passes CI), each on its own line with its exit status, with Terraform 1.12.1 (the version dev.yaml pins) or, when it is not installed, the hashicorp/terraform:1.12.1 Docker image (docker run --rm -v "$PWD":/w -w /w hashicorp/terraform:1.12.1 <command>). Never run terraform plan or apply locally: the delivery team cannot read the et-ops state. A plan of a branch comes from gh workflow run dev.yaml --repo altrium-io/forge-et-iaac --ref <branch>: a manual run uses the branch’s own dev.yaml, which plans and applies only when the branch is dev. It runs with svc-github’s administrator key, so ask the lead before starting it.
  • Every PR to dev gets a review before it merges, the DevOps team’s included (the lead’s rule, 2026-11-08): /forge-review-pr forge-et-iaac#<N>, which runs the checks, dispatches the iaac-reviewer agent and posts its verdict on the PR. That posted verdict is the record: the repository has no required checks, so the record is a comment whose first line is <!-- forge-review v=1 sha=<head> verdict=<approve|block> -->. A push after it gets a delta review. Whoever in the delivery team first sees an unreviewed PR runs it; the PR’s author never waits for a particular person.
    • A finding is fixed on the PR, or given a home before the merge — .forge/owed.md with an owner, .forge/bugs.md, or the register — so a PR merged without the fix leaves a row the team walks. A DevOps-team PR’s fixes are the author’s to make; the reviewer posts and does not push unless the author agrees on the PR.
    • A merged PR that was never reviewed gets the post-mortem review /forge-review-pr step 1 describes: posted on the PR, each finding marked fixed since, still open or no longer applying against origin/dev, and each still-open one given a home.
    • A DevOps-team push straight to dev is reviewed the same way after the fact, by whoever next reads git -C ../forge-et-iaac log origin/dev (at the start of any F38 work, as the bullet on the harness documents says): the commits since the last reviewed one, with the findings posted as a comment on the most recent open PR to dev or, when none is open, recorded only in their homes.
  • A PR merges only after Shyamin Ayesh has approved it; after his approval anyone with write access may merge it, with a merge commit (the lead’s rule, 2026-10-21). A commit pushed after his approval is named on the PR, as forge-et-iaac#3 did for a359b61. The review above comes first, so his approval is given with the verdict in front of him.
  • Request review from everyone else with write access there: Shyamin Ayesh (shyaminayesh), Senuthmi Thimansa (senuthmi07), Tharinda (tharinda-altrium), Dinil (dinil-gamage) and Nanndish (nanndish-altrium) — the four who did not open the PR, passed with --reviewer (the organisation’s administrators, who also appear in the collaborators list, are not requested). The repository has no CODEOWNERS file, so nothing requests them automatically. Biseni does not have write access yet (read only, as of 2026-11-19 — re-check with gh api --paginate repos/altrium-io/forge-et-iaac/collaborators --jq '.[]|.login+" "+.role_name'; without --paginate the first page leaves some people out); when someone is given write access, they join the reviewer list.
  • This is a team rule, not an enforced one: as of 2026-11-19 dev has no branch protection and no ruleset of its own — only the organisation’s repository-level rules (gh api repos/altrium-io/forge-et-iaac/rules/branches/dev) — so GitHub would accept a direct push.
  • The temporary uat instance is applied only by hand. uat.yaml (forge-et-iaac#11) plans, applies or destroys overlays/uat when someone starts it on dev; no push or PR runs it. One instance is kept, with its data, from Phase 1’s round through Phase 2’s, then destroyed when the lead decides (AD #23, revised 2026-11-18); a fresh instance comes up in three steps (F38-h spec Rev 7). Any run is a billed AWS write, so a delivery-team session asks the lead first (.claude/CLAUDE.md § ASK FIRST). Because the instance stays up, an apply from dev brings in every base/ change merged since the last one, so check that the running UAT backend handles each new scheduled job before applying (.forge/owed.md, the price-broadcast-send row).
  • Only dev applies on a push. dev.yaml runs on a push to dev (a merged PR or a DevOps push), which plans and then applies with terraform apply -auto-approve, and on a manual run, which plans on the chosen branch and applies only when that branch is dev. A branch pushed for review runs nothing, so its commits need no [skip ci]. So a merge to dev changes the dev estate within minutes: read the merge’s dev.yaml run (gh run list --repo altrium-io/forge-et-iaac --branch dev) and its terraform::apply step. GitHub runs the workflow file from the pushed commit, so this holds only while each branch’s dev.yaml keeps these rules; a branch cut from dev before forge-et-iaac#3 merged (d230b133, 2026-10-20) carries the older file, which runs on every push to any branch with its apply step commented out, so merge dev into it before pushing.
  • A change that a backend handler consumes waits as a draft PR until the handler runs on dev (.forge/lessons.md L-319). A schedule, a queue’s consumer wiring or a route that the backend must handle goes in its own wave with no gate and depends_on: [], run in a second session with /forge-deliver <TICKET> --wave <N> beside the code wave, and its PR is opened as a draft whose body says why. Mark it ready only after the backend wave PR that adds the handler has merged and dev’s running task definition uses an image built from a commit that contains that merge (aws ecs describe-services, then aws ecs describe-task-definition for the image tag, then git merge-base --is-ancestor <merge> <image commit>). The WI’s plan carries a subtask that checks this at each --wave <N> resume and marks the PR ready only when it holds (F37-a-WI-2.1 subtask 8), because Stage 14 does not. base/ is shared, so the next UAT or production apply from a dev that holds the change creates it there too: in the wave’s harness half, add an owed.md row for the owners of those applies to check that the backend released there already includes the handler. Why: a merge to dev applies at once, and a schedule that fires before its handler exists is refused every minute and dead-lettered; a per-wave gate holds back only the dispatch, not the merge (F20-g, F37-a).

Generated from .claude/rules/forge-et-iaac.md by .claude/lib/render-docs-html.js. Markdown is canonical.