source: .claude/rules/git-conventions.md · generated — edit the markdown, not this file

Git Conventions

Branching — trunk-based, with one maintenance branch per shipped release

main is the trunk. All work branches from it and merges back to it. A release/vX.Y.Z branch exists only for a release that is live in production and carries nothing but fixes for that release.

main                                    # The trunk. Protected. Never commit directly (one DevOps exception: § Branch Protection). Dev deploys every merge (backend, CRM frontend).
feature/<TICKET>-<short-description>    # All new work — from main, PR back to main
fix/<TICKET>-<short-description>        # Bugfix work on the trunk — from main, PR back to main
release/vX.Y.Z                          # Maintenance branch for a live release — cut from its tag, protected, never deleted
hotfix/<TICKET>-<short-description>     # Fix for what is live — from release/vX.Y.Z, PR back to release/vX.Y.Z

Rules:

  • main is the trunk and always deployable. Every feature and every fix that is not for a live release goes here. The development environment deploys main on every merge: forge-et-be, forge-et-fe and forge-et-pwa each have a build workflow that does so (forge-et-pwa’s, to capture.dev.crm.empire.lk, skips a push that changes only workflows). A manual run may deploy another branch to dev (AD #24, F38 Rev 18); UAT and production deploy tags only.
  • feature/* and fix/* branch from main, merge back via PR, and are deleted on merge. Keep them short-lived — open a PR early.
  • A release/vX.Y.Z branch is created only when that release goes to production, cut from the tag that went live and named after it (production runs v0.1.1 → the branch is release/v0.1.1). Before a release is live there is no release branch — the tag alone is the deliverable. The branch name records the release the line started at and does not change as patches land on it: v0.1.2 and v0.1.3 are cut from release/v0.1.1.
  • release/* branches are never deleted. They stay as the record of what shipped.
  • hotfix/* branches from the release branch, not from main, and merges back into it by PR. Every merged hotfix is then merged back into main so the trunk never loses a fix. This merge-back is mandatory and is the one discipline the model requires.
  • At most one release branch is active at a time. When the next release ships, the older branch stops receiving fixes.
  • Tracked post-ship bugs use the bug id as the ticket: fix/BUG-NNN-<short-description> on the trunk, or hotfix/BUG-NNN-<short-description> when the defect is in a live release. See the bug-fix flow in .claude/rules/tracker.md → “Bug Tracking”.

Never rebase or force-push a shared branch (main, release/*). Branch protection blocks it.

Resolving a merge conflict is resolve, prove, then commit — three commands, never one chained line. After resolving, prove the tree is clean before anything is committed: git diff --check and grep -rnE '^(<<<<<<< |>>>>>>> )' --exclude-dir=.git . must both print nothing. Only then git commit, then git push, each on its own. A resolver script chained into … && git commit && git push on one line once stopped on a block it could not resolve while the rest of the chain committed and pushed the conflict markers — nothing in the chain had checked. A conflict in tracker.yaml is resolved by hand with the Edit tool (.claude/rules/tracker.md), never by checkout --ours/--theirs on the whole file, which silently drops the other branch’s row edits. A conflict in a built prototype page (.forge/design/prototypes/*-current/*-prototype.html) or in its screenshots is resolved by rebuilding, never by picking a side: once the page’s source/ files are merged, run its source/ build (npm run build), then its screenshots/capture.mjs. Keep the recaptured pictures the merge changed, put back any that changed only through the camera test feed, and check one merged picture shows both sides’ changes. Why: both sides’ pages are built from different sources, so either side alone drops the other’s screens (F36-d wave 2, harness#1525).

Merge main into an open PR’s branch only for a reason, never because the branch is behind. On main, branch protection does not require a branch to be up to date before merging, and every push to a ready app-repo PR re-runs CI and leaves the new head without the local record’s Test record check, so the suite runs again before merge (§ Pull Requests). A PR into release/* must be up to date with its base (protect-releases): when the release branch moves, merge it in, then run pnpm e2e:gate --full --push (frontends) and the record again on the new head. The reasons that justify merging main in:

  • GitHub reports a conflict.
  • The branch needs code that has landed on main, or main changed something the PR’s code or tests rely on (/forge-review-pr step 2).
  • A frontend PR’s selected browser run is older than a merge on main that changes a file under the same src/features/<feature> folder, the same e2e/ spec or the same page state: merge main in and run pnpm e2e:gate --selected again on the new head before merging (.forge/design/harness/fewer-nightly-reds.md R-2).

A PR that is green on its own head and mergeable merges as it is, however far main has moved. When main is merged in to resolve a conflict, the push is handled like any other push to a ready PR: after the last push, the local record runs again (forge-et-be: git push, then the build record; the frontends: git push, then pnpm test:record, then on a PR into main pnpm e2e:gate --selected, .forge/design/harness/fewer-nightly-reds.md R-1), because the resolved lines are code neither branch tested, and the delta review covers only the conflict resolutions (review-record.md). On a PR into main, when every path the merge left in conflict or changed itself is documentation that no test or build step reads, or the merge made no change of its own, the record script sets the check without running the tests, naming the recorded commit before the merge (test-run-cost.md W-5): without the resolutions the merged code is what GitHub’s own merge of the PR would make, which needs no new record. In forge-et-be a merge that brings a migration into a branch that adds or changes one of its own is built anyway, because two migrations can share a version. This carries only the test record: on a frontend PR, pnpm e2e:gate --selected still runs again on the new head (R-1) unless its earlier line still covers the head by the gate’s own rule, and R-2 above still applies.

Two branches can still merge cleanly and break each other’s tests; that is caught after the merge, by the nightly full run of the three app repos on main (§ Pull Requests) or the next PR’s own tests (its local record), and fixed before new work starts, as a failed nightly run is. Why: refreshing every PR before it merged cost a full local build and a delta review each time, and delayed merges more than the rare break it caught. The exception is a forge-et-be PR that turns a refusal into an acceptance: it is checked before it merges against the frontend tests that assert the refusal (/forge-review-pr step 2), because after the merge it fails the frontend’s browser suite on main (.forge/lessons.md L-200).

Harness-only PRs (specs, plans, the tracker) merge main in only on a conflict. “Update branch” on a PR that GitHub shows as mergeable spends a full CI run and changes nothing.

Push when CI or a reviewer needs the change, not after every commit. GitHub Actions minutes are one budget for the whole org, and running out stops every workflow, deployments included. Every push to a PR starts CI; a push while a run is in progress cancels it, but the minutes it already used are still billed; and each push to a harness PR bills at least a minute of Repo hygiene.

  • Commit as often as is useful, and push once a piece of work is ready. Push tracker and status commits together with the work they record, not one at a time.
  • Open an app-repo PR as a draft while it is still changing: on a draft the Fast lane stops after the compile (forge-et-be) or after the static checks (forge-et-fe, forge-et-pwa), and no local record is needed. Review it while it is a draft. Mark it ready once the work and its review are done and the local check is on the final head — forge-et-be: git push, then the build record (python3 scripts/local-build-evidence.py); forge-et-fe and forge-et-pwa: git push, then the test record (pnpm test:record), then on a PR into main the selected browser run (pnpm e2e:gate --selected, its line in the test evidence), with pnpm e2e:gate --full --push in place of the push on a PR into release/* (§ The test suites run locally); that runs the rest of CI once. In wave mode, /forge-pr-open opens every per-WI PR as a draft, because the wave PR is the one that ships.
  • Do not re-run a green or cancelled run to check again. Re-run a failed run only after fixing the cause, or with the flaky test recorded (.forge/bugs.md).
  • A required check whose run stays queued long after later runs have finished is lost on GitHub’s side: gh run cancel, the API’s force-cancel and gh run rerun all refuse it, and closing and reopening the PR starts a second run that passes but leaves the lost one holding the check, so the PR stays blocked. Only a new head clears it: push the PR’s next real change, or an empty commit when there is none. Why: forge-et-harness#1298 (2026-11-12).
  • A run that sits queued with no job started, or a job that runs far longer than its usual time, is first checked against GitHub’s status page (curl -s https://www.githubstatus.com/api/v2/incidents.json) before anything in the repository is changed: the runs lost on 2026-11-12 were created between 20:21 and 20:48 UTC, around an Actions outage GitHub reported from 20:48 to 21:21 UTC. A dev deploy lost that way (build on main) is started again by hand, gh workflow run build -R altrium-io/<repo> --ref main, since no push follows to replace it. Why: the lost runs looked like a slow Fast lane.

Deleting merged branches

A merged feature/*, fix/*, hotfix/* or wave branch is reclaimed — remote and local — as soon as its PR merges. release/* and main are never deleted.

  • Remote deletion is automatic (delete_branch_on_merge is enabled on all four delivery repos). When a PR merges, GitHub deletes its head branch. release/* is exempt by construction: the protect-releases ruleset’s deletion rule blocks auto-delete too (probe-verified — “Cannot delete this branch”), so the merge-back PR from a release branch never costs the branch.
  • Local branches and worktrees are cleaned separately. After a merge, run git fetch --prune, point the local branch’s upstream at the remote trunk (git branch -u origin/main <branch>, so -d checks the merge against it rather than a local main that may be behind — L-093), and delete it with git branch -d — -d, never -D, because it refuses an unmerged branch and that refusal is the safety net.
  • /forge-deliver offers this at Stage 14 when it detects the wave PR merged (and at Stage 0 when reconciliation finds a merge that happened outside the session). It lists the reclaimable branches and asks before deleting; with auto-delete handling the remote, what’s left is the local branch and worktree. It only ever offers branches already merged into main, and never one with an open PR.
  • Never delete a branch that is not merged into main, with two exceptions, both made by /et-cleanup: a local branch or worktree whose tip is exactly origin’s copy of the branch and unchanged for a day (nothing is lost while origin keeps the branch), and a stale remote branch that the user picks after /et-cleanup has looked into it and asked (its step 4). Any other unmerged branch left behind is a finding to report, not a cleanup candidate.
  • /et-cleanup does the whole workspace at once: it updates every checkout, removes the merged worktrees and branches in all the repos and the local copies of pushed work, and asks once about everything only the user can decide — stale unmerged remote branches, merged worktrees with old uncommitted changes, leftover folders and unclaimed Docker items — keeping anything another session may still be using (the rules are in .claude/lib/cleanup.sh).

Ticket IDs

Every branch, commit, and PR that belongs to a tracked item carries its id.

Id What Source
F<n> Feature .forge/features.md
FS-<n> Foundation slice architecture.md § Foundation Backlog
BUG-<nnn> Tracked post-ship defect tracker.yaml bugs: + .forge/bugs.md
UAT-<nnn> UAT-raised issue tracker.yaml uat_issues:

Work-item ids (WI-<wave>.<index>) identify a slice within a feature — they belong in the branch name for per-WI branches and in the PR body, not in the PR title, which carries the feature id.

Work with no tracked item omits the ticket segment entirely — harness housekeeping, dependency bumps, repo config. Do not invent an id to satisfy the format.

Commit Format

<type>(<TICKET>): <description> — or <type>: <description> when there is no ticket.

Types: feat, fix, refactor, test, docs, chore, ci

feat(F2): add drag-and-drop to the kanban board
fix(BUG-000): round quote totals to two decimal places
docs: correct the stale capture-repo notes
ci: bound the gitleaks download so a stall fails fast

ci versus chore — ci is the delivery pipeline itself: workflow files, runner configuration, required checks, the git hooks, commitlint.config.js, Dependabot config. Everything else non-product is chore. The boundary is worth holding because without it CI work drifts between the two and git log --grep '^ci' stops being able to answer what changed about the build — which is the first question asked when a pipeline starts behaving differently.

This list is enforced, not advisory. commitlint.config.js in each app repo holds the same enum, and both the commit-msg git hook and the Fast lane’s PR-title check run it — so a type that is not in the list fails the build. Change the list here and in all three commitlint.config.js files in the same change, or the doc and the gate disagree and the gate wins. The harness repo has no commitlint of its own; this document is its only statement of the convention.

Rules:

  • Imperative present tense (“add”, not “added”)
  • Header line (type, scope and subject together) at most 120 characters — commitlint’s header-max-length, the same in all three commitlint.config.js files. It is 120 because Dependabot writes its own PR titles, and a long package name or version takes them past a shorter limit (a Gradle title reached 105)
  • No period at the end of the subject line
  • One ticket in the scope. Additional tickets go in the body: Refs: F3, F7

Pull Requests

Review requests are automatic and mutual (team rule). Every PR requests review from the other three delivery-team members (Tharinda, Dinil, Biseni, Nanndish — whoever didn’t open it):

  • Primary mechanism: .github/CODEOWNERS in each repo (wired in all four delivery repos — harness, forge-et-be, forge-et-fe, forge-et-pwa; add it to any new delivery repo at creation — the read-only forge-et-pwa-poc reference repo carries none of these conventions, since nothing is ever pushed to it; forge-et-iaac has its own rule, § forge-et-iaac below) — * @tharinda-altrium @dinil-gamage @biseni-droid @nanndish-altrium — GitHub then auto-requests the owners other than the author on every PR, however it was opened.
  • When opening via CLI, also pass the reviewers explicitly for immediacy: gh pr create --reviewer <the three who aren't you> (usernames above; /forge-pr-open includes this).
  • No approval is required to merge into main for now — the author may merge their own PR once the required status checks are green. Review is still requested on every PR, and asking a teammate to look before merging stays good practice; /forge-review-pr stays mandatory on code PRs (.claude/CLAUDE.md § Quality Gates). release/* still requires one Code Owner approval (§ Branch Protection).
  • Merge by hand. Auto-merge is off in all four delivery repos (allow_auto_merge is false). Merging someone else’s PR is the developer’s decision, asked for each PR. When the developer says to merge, run gh pr merge <N> --merge once the required checks pass — Repo hygiene in the harness; in an app repo the required checks, Forge review and Test record included. Why: a PR set to merge itself would merge without anyone confirming the checks it was given.
  • On anyone’s PR, comments and title or description corrections need no asking. Add a comment, or correct a wrong or stale title or description, whenever the work calls for it — to tell the author their PR was reverted or merged, to point an app-repo PR at its harness half, to fix an id the diff no longer uses — and say in the session what was posted. Correct what is wrong; never rewrite the author’s account of their work. Why: the lead’s decision of 2026-11-10 — these change no one’s code, and holding them back left authors uninformed.
  • A commit to someone else’s PR needs the developer in the session to agree first (.claude/CLAUDE.md § Boundaries, ASK FIRST: a change to another developer’s in-progress work), and, when it is a review fix, the PR author’s agreement as well (.claude/CLAUDE.md § Quality Gates). This covers a change that needs matching edits in someone else’s open PR (a moved file its links point at, a renamed section). Keep the commit to the lines the change requires, never resolve the author’s own conflicts for them, check first that no worktree or session has the branch checked out, and leave a PR comment naming the commit, what it changed, and that the author should pull before pushing. Why: a merged change that leaves open PRs pointing at old paths leaves their authors to find the breakage alone (the link fix pushed to forge-et-harness#452, 2026-10-11).

Merge method: merge commit — the only enabled method. The branch’s original history is always preserved; squash and rebase merges are disabled at two independent layers — the repo merge-method toggles, and the rulesets’ PR rule (allowed_merge_methods: ["merge"]) on main and release/* — so there is no dropdown to get wrong, and flipping one layer alone cannot re-enable them. If a branch’s commit trail is genuinely noise, clean it up on the branch (before review) rather than at merge time. Re-enabling squash would be a team decision and a repo admin change.

Every PR must include:

  • PR title matches commit convention (<type>(<TICKET>): <description>)
  • Link to the spec file in .forge/specs/
  • Link to the plan file in .forge/plans/
  • Summary of what was built and any plan deviations
  • Test evidence — screenshots or test output for UI/critical paths

A .github/PULL_REQUEST_TEMPLATE.md in every repo makes those sections appear by default rather than depending on the author remembering them — GitHub pre-fills the description box from it, so the reviewer gets the same shape every time and an omission is a visible blank instead of a silent absence. This repo’s is .github/PULL_REQUEST_TEMPLATE.md, shaped for harness work: it swaps “test evidence — screenshots” for the gate commands and their output (nothing here has a UI), and reminds the author that the generated mirrors are gitignored and the generators must run clean. Each app repo has its own, shaped for code: the sections above, plus, in forge-et-fe and forge-et-pwa, a Browser gate section that a PR into release/* fills in.

Templates are prompts, not gates. CI enforces what must be true; the template only makes sure nobody has to hold the checklist in their head.

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

forge-et-iaac (the DevOps repository, AD #23) is not a delivery repo. Its trunk is dev: a developer branches from dev, never pushes to dev directly, opens the PR with --base dev, and requests review with --reviewer from the others who have write access there. The DevOps team (Shyamin Ayesh, Senuthmi Thimansa) may push to dev directly. Every push to dev runs terraform apply on the dev estate; a branch pushed for review runs nothing. Every PR there gets /forge-review-pr forge-et-iaac#<N> before it merges, the DevOps team’s included, and its posted verdict is the record (.claude/CLAUDE.md § Quality Gates). The reviewer list, how to re-check it, the state of its branch protection, and what to do with a branch cut before the workflow changed are in .claude/rules/forge-et-iaac.md — read it before working in that repository.

The test suites run locally, and the PR records them

The detail is in .claude/rules/test-record.md — read it before running a local record or the browser gate, marking an app-repo PR ready, or writing a wait loop for a heavy run. It holds what CI and the nightly full run cover, how the record chooses its tests, the load check, the heavy-run lock and wake lock, documentation-only changes and asking CI for the suite. The rules every session needs:

  • No app repo’s CI runs its test suite on a pull request, a Dependabot PR included, or on a push to release/*; it runs in each repo’s Slow lane only on demand, and the weekly scheduled run is the Fast lane only. A suite runs in one place, never in two. The nightly full run on main (02:00 Sri Lanka time, the lead’s Mac, .claude/lib/nightly/run-nightly.py) runs every suite of the three app repos, the browser gates included, and is the only run of the browser suites for a PR into main, and, since a PR’s record runs only the tests its change needs, the only run of every test; § Branching relies on it after a clean merge.
  • The developer records the tests once per PR, on its final commit, after the last push: the script runs the tests the change needs, comments the counts on the PR and sets the required Test record commit status. It refuses a dirty tree or a commit that is not the PR’s pushed head, and records nothing when a test fails.
  • Claude passes --ignore-load only when the developer says so in that session. The records and the browser gate refuse to start while other work keeps the CPU more than 0.65 busy. Why: an overloaded run fails with timeouts that are not in the code (BUG-194, BUG-195), and an agent that is refused would otherwise add the flag and repeat the problem.
  • One heavy run at a time on a machine. Every heavy run takes one lock: the browser gate, both records, the nightly run and a direct playwright test take it themselves, and any other heavy command (a Gradle build or test run, a multi-file vitest run, a timing measurement) runs through python3 <harness>/.claude/lib/heavy-run.py -- <command>, with a backend the run needs started inside the same call (test-record.md). Never a lock folder of your own. Start the second run rather than a wait loop of your own. A wait loop that is still needed brackets one character of each pgrep -f alternative ('[e]2e:gate|[l]ocal-build-evidence') and, when the same shell starts the command after the loop, anchors on the program that runs it (pgrep -f '[n]ode .*e2e:gate'); it never uses ps … | grep, which matches its own command line. A loop on the lock waits while the lock names a live process (kill -0 on its pid), not while the file merely exists. Check the loop once by hand while nothing runs (it must find nothing), and run it in the background (L-234, L-240).
Repo The local record The end of a PR
forge-et-be the build record: python3 scripts/local-build-evidence.py runs ./gradlew build with the tests the change needs commit → git push → python3 scripts/local-build-evidence.py → gh pr ready
forge-et-fe, forge-et-pwa the test record: pnpm test:record runs the Vitest tests the change needs commit → git push → pnpm test:record → pnpm e2e:gate --selected (its line in the PR’s test evidence as Selected browser run: …) → gh pr ready; into release/*: commit → pnpm e2e:gate --full --push → pnpm test:record → gh pr ready
  • Keep a PR a draft until it is done and reviewed. A draft needs no record, and its pushes are plain git push. Review it on the draft (/forge-review-pr) and fix until the review records approve; then run the end of the PR above once.
  • Scan the branch for secrets before marking it ready. The Fast lane’s gitleaks step scans every commit of the branch, and the first full run starts at gh pr ready. Run the same version locally first, or its container when the machine has no gitleaks: /forge-pre-pr-review Step 3, Secret scan. Run the scan in a command of its own, with echo "EXIT=$?". Run gh pr ready in a later command, after reading EXIT=0, never chained to the scan behind a pipe. Why: a finding after gh pr ready costs a new head, a new local record and a delta review (.forge/lessons.md L-203), and a scan chained behind | tail once let gh pr ready run on a failing scan (L-246).
  • A push after the record needs the record again before merge, not before the push. Every new commit starts without the check, so the merge stays blocked until the new head is recorded. When more pushes will follow (a CI fix, a conflict resolution), push them all and record once, after the last.
  • Keep the runs down: push fixes in batches, merge main in only for a reason (§ Branching), and while developing run only the tests the change needs or one file; none of them is the record. A change to documentation that no test or build step reads needs no new test run: the record script still runs, and sets the check without the suite when an earlier commit on the PR already has a delivery-team member’s record (never on a PR into release/*, whose record always runs every test); on a PR into main it does the same after a merge of main whose own changes (§ Branching) touch only such documentation; a documentation-only PR gets the check from CI. How to do both: test-record.md.
  • Review reports a missing Test record check as owed while it runs, and blocks an approve record on a ready PR whose head has none (/forge-review-pr steps 5 and 9). Merging main in makes a new head, so record again — the local record (which carries the earlier record when the merge’s own changes are documentation only, § Branching), then the review record (review-record.md).
  • Ask CI for the suite when local proof is not enough — a migration, security code, a large merge from main, or a machine that cannot run the suite: gh workflow run "PR validation" --ref <branch> in the app repo. That run reports the required checks on the branch’s head commit; it does not set Test record, so record anyway.
  • A failed nightly run on main is fixed before new work starts. The nightly full run opens a nightly-red issue in the red repo, assigned to the whole delivery team, and closes it on the next green night; every session start lists an open one, and a night the run did not happen (.claude/hooks/inject-gate-state.sh). A defect it finds gets a BUG-NNN through the bug flow, linked from the issue. Its nightly log is the harness issue labelled nightly-log.
  • Triage a red suite by re-running only the tests that failed or were flaky, never the whole suite. Run them alone, with retries off, at the commits the night tested (the nightly worktrees $WS/worktrees/nightly/<repo> stay at them until the next night resets them), against a backend started as the night starts it; compare each test’s time with earlier nights’ logs and the night’s recorded load, and post the result on the nightly-red issue. The commands and how to sort the result are in .forge/guides/test-runs-explained.md § The nightly full run. A whole-suite hand run (run-nightly.py --now --only <suite>) proves nothing more about one test; the next scheduled night re-runs the red suite and closes the issue when it passes. Why: on 2026-11-06 the two CRM gate failures re-ran alone in 20 seconds, against the gate’s 50 minutes, and showed the night’s timeouts came from machine load.
  • A hand run closes the nightly-red issue when the repo is green again. A run with --now, with or without --only, closes it when every suite it ran passed and every other suite of that repo last passed (run-nightly.py’s partial_covers_repo, read from ~/.et-nightly/state.json). That is the usual way to clear a suite the night did not run (the Mac slept, a port was held). A last pass may be on an older commit than main; the next scheduled night re-runs that suite and reopens the issue if it is red. A suite whose inputs have not moved is skipped as unchanged and closes nothing; add --force to run it. A hand run’s log heading still says “started by hand”, so it is never release evidence (release-and-branch-protection.md § Release Process). Why: an issue left open after the repo is green shows a red main at every session start and stops new work for nothing (the lead, 2026-11-13).
  • A missed or interrupted night is run again by hand the next morning (the lead, 2026-11-03). When the session start reports no run since the night before, or a nightly-red issue says a suite did not run (the Mac slept, the night’s deadline passed, a port was held), the lead runs python3 .claude/lib/nightly/run-nightly.py --now on the Mac that morning, after clearing the cause (mains power, the lid open, the gates’ ports 15173 and 15174 free), and before new work starts. It runs every suite that has not passed since its inputs last moved; --force runs them all. Why: CI runs no test suite on main (test-run-cost.md N-5), so a night that does not run leaves main unchecked until the next one. A hand run’s log says “started by hand”, so it does not stand in for a scheduled night where the release rule asks for one (release-and-branch-protection.md § Release Process). A suite that ran and failed is not a missed night: re-run its failing tests instead (above).

The review record

The rule — every app-repo PR into main or release/* carries a review record for its head, and every later push needs it written again — is stated in .claude/CLAUDE.md § Quality Gates › Mandatory. How the record is written, deltas, skips, a base change, Dependabot and Markdown-only PRs are in .claude/rules/review-record.md — read it before writing, skipping or re-writing a record.

Release Process

Releases are annotated tags vX.Y.Z, cut only from a commit CI has fully tested and, on main, the nightly full run passed in full, never from a branch. Development deploys main (and, by a manual run, another branch — § Branching); UAT and production deploy tags; at a tagged commit the manifest versions match the tag. The tag format, the phase handover sequence, the manifest-version rules and how the running system reports its version are in .claude/rules/release-and-branch-protection.md § Release Process — read it before cutting a tag, bumping a manifest version or cutting a release/* branch.

Branch Protection

main in all four delivery repos and release/* in the three app repos are protected by GitHub rulesets (protect-main, protect-releases). Every change is a PR (one exception, the DevOps team’s deploy files, below); force-push and deletion are blocked, so correcting a pushed commit means a new commit, never an amend. On main no approval is required and the author may merge once the required checks pass; on release/* a Code Owner other than the author must approve. The ruleset detail (the rules table, what creating and deleting a branch allow, restoring an approval on main, who holds the admin bypass) is in .claude/rules/release-and-branch-protection.md § Branch protection rulesets — read it before changing a ruleset.

Required status checks: the harness requires Repo hygiene; each app repo requires Fast lane and Slow lane (the §7.1 lanes in coding-standards.md), Test record, the local record’s commit status (§ Pull Requests), and Forge review, the review record’s commit status (.claude/rules/review-record.md). A person’s login sets the two statuses; a workflow sets both on a documentation-only PR and Forge review on a Dependabot PR, so their source is left as “any source”. The check names are the contract: workflow content is team-editable on write access, but adding or renaming a required check needs repo admin — so never rename a required job, and change the required-checks list (the protect-main and protect-releases rulesets) in the same change as the workflow it matches.

In each app repo the Slow lane (the test suite) is required and is skipped on every PR. A skipped required check counts as passing, so the PR’s Test record check stands in for it (§ Pull Requests).

Never bypass a required check to merge a delivery PR. A check that failed, was cancelled or is still running means the PR waits, or the run is re-run. For a delivery PR the repository-admin ruleset bypass is for a genuine emergency only (the DevOps exception below is not a PR), and a PR merged that way says so in its body, with the run link and the reason. Why: a PR merged over a red, pending or cancelled check leaves no record of whether its code was tested (.forge/engagement-gate-runs.md § Post-merge /forge-review-pr audit on 2026-09-28).

One exception: the DevOps team’s deploy configuration. Shyamin Ayesh, a GitHub organisation administrator, pushes deploy files (.github/workflows/build.yaml, .aws/) straight to an app repo’s main without a PR. The lead accepts this while a push breaks nothing and keeps to the team’s standards. Whoever next works on F38 checks each such push after the fact (git -C <app-repo> log origin/main -- .aws .github/workflows) and records what it finds in .forge/design/environments-and-identity.md §4; a fault is raised with Shyamin or fixed by a PR of our own. The same person runs the dev smoke run (pnpm e2e:smoke, F38-g) after the deploy such a push starts, since no delivery-team merge names anyone to run it (the lead, 2026-11-19). Everyone else’s changes still go through PRs.

Worktree Commands

$WS (the workspace parent, derived from git rev-parse), absolute worktree paths, installing dependencies in a fresh app-repo worktree before the first commit, and the single-plan and wave-mode worktree commands and their cleanup are in .claude/rules/worktrees-and-waves.md — read it before creating or removing a worktree by hand. forge-worktree-up does all of it for a ticket. Two of its rules in short: worktree paths are absolute ($WS/worktrees/<TICKET>/<repo>), and a fresh app-repo worktree runs corepack pnpm install --frozen-lockfile before its first commit.

Give git its path with git -C <path>; never cd <path>; git …. This workspace is shared by parallel sessions. Where a directory change is unavoidable, chain it with &&, never ;. A failed cd in a ; chain runs the next git command in whatever checkout the shell is in, which once detached HEAD in the shared harness checkout (.forge/lessons.md L-082).

Never switch branches in a shared checkout, and never remove, overwrite or stash an untracked file to make a switch possible — it may be another session’s work in progress. Do harness work in a worktree of its own cut from origin/main, or, for a ticket, in the worktree of the branch /forge-deliver Stage 0 Step 0a finds for it, and leave a merged branch or worktree that another session may still be using for that session to remove (/et-cleanup applies the rules).

Never use git stash in a worktree of a repository other sessions also use. All of a repository’s worktrees share one stash list, so a git stash pop can apply another session’s entry made in the gap since your push. To set changes aside, commit them on your branch, or write them to a patch file (git diff > <file>, then git apply <file>). Why: it happened in forge-et-fe on 2026-11-12 after the lesson that warned of it (.forge/lessons.md L-160) had been written.

Wave Branches (multi-plan specs)

A decomposed feature ships one wave at a time: each work item has its own branch, the wave’s work items integrate on feature/<ticket>-wave-<N>, and that branch’s PR to main is the unit that ships and gets /forge-review-pr. The branch names, the harness spec and plan branches, and keeping a wave branch current are in .claude/rules/worktrees-and-waves.md § Wave Branches.

Generated from .claude/rules/git-conventions.md by .claude/lib/render-docs-html.js. Markdown is canonical.