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:
mainis the trunk and always deployable. Every feature and every fix that is not for a live release goes here. The development environment deploysmainon every merge:forge-et-be,forge-et-feandforge-et-pwaeach have abuildworkflow that does so (forge-et-pwa’s, tocapture.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/*andfix/*branch frommain, merge back via PR, and are deleted on merge. Keep them short-lived — open a PR early.- A
release/vX.Y.Zbranch is created only when that release goes to production, cut from the tag that went live and named after it (production runsv0.1.1→ the branch isrelease/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.2andv0.1.3are cut fromrelease/v0.1.1. release/*branches are never deleted. They stay as the record of what shipped.hotfix/*branches from the release branch, not frommain, and merges back into it by PR. Every merged hotfix is then merged back intomainso 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, orhotfix/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, ormainchanged something the PR’s code or tests rely on (/forge-review-prstep 2). - A frontend PR’s selected browser run is older than a merge on
mainthat changes a file under the samesrc/features/<feature>folder, the samee2e/spec or the same page state: mergemainin and runpnpm e2e:gate --selectedagain on the new head before merging (.forge/design/harness/fewer-nightly-reds.mdR-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-feandforge-et-pwa:git push, then the test record (pnpm test:record), then on a PR intomainthe selected browser run (pnpm e2e:gate --selected, its line in the test evidence), withpnpm e2e:gate --full --pushin place of the push on a PR intorelease/*(§ The test suites run locally); that runs the rest of CI once. In wave mode,/forge-pr-openopens 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
queuedlong after later runs have finished is lost on GitHub’s side:gh run cancel, the API’sforce-cancelandgh run rerunall 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
queuedwith 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 (buildonmain) 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_mergeis enabled on all four delivery repos). When a PR merges, GitHub deletes its head branch.release/*is exempt by construction: theprotect-releasesruleset’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-dchecks the merge against it rather than a localmainthat may be behind — L-093), and delete it withgit branch -d—-d, never-D, because it refuses an unmerged branch and that refusal is the safety net. /forge-deliveroffers 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 intomain, 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-cleanuphas looked into it and asked (its step 4). Any other unmerged branch left behind is a finding to report, not a cleanup candidate. /et-cleanupdoes 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 threecommitlint.config.jsfiles. 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/CODEOWNERSin 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-onlyforge-et-pwa-pocreference repo carries none of these conventions, since nothing is ever pushed to it;forge-et-iaachas its own rule, §forge-et-iaacbelow) —* @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-openincludes this). - No approval is required to merge into
mainfor 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-prstays 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_mergeisfalse). Merging someone else’s PR is the developer’s decision, asked for each PR. When the developer says to merge, rungh pr merge <N> --mergeonce the required checks pass —Repo hygienein the harness; in an app repo the required checks,Forge reviewandTest recordincluded. 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’sSlow laneonly on demand, and the weekly scheduled run is theFast laneonly. A suite runs in one place, never in two. The nightly full run onmain(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 intomain, 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 recordcommit 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-loadonly 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 testtake it themselves, and any other heavy command (a Gradle build or test run, a multi-filevitest run, a timing measurement) runs throughpython3 <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 eachpgrep -falternative ('[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 usesps … | grep, which matches its own command line. A loop on the lock waits while the lock names a live process (kill -0on itspid), 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 recordsapprove; 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-reviewStep 3, Secret scan. Run the scan in a command of its own, withecho "EXIT=$?". Rungh pr readyin a later command, after readingEXIT=0, never chained to the scan behind a pipe. Why: a finding aftergh pr readycosts a new head, a new local record and a delta review (.forge/lessons.mdL-203), and a scan chained behind| tailonce letgh pr readyrun 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
mainin 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 intorelease/*, whose record always runs every test); on a PR intomainit does the same after a merge ofmainwhose 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 recordcheck as owed while it runs, and blocks anapproverecord on a ready PR whose head has none (/forge-review-prsteps 5 and 9). Mergingmainin 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 setTest record, so record anyway. - A failed nightly run on
mainis fixed before new work starts. The nightly full run opens anightly-redissue 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 aBUG-NNNthrough the bug flow, linked from the issue. Its nightly log is the harness issue labellednightly-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 thenightly-redissue. 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-redissue 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’spartial_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 thanmain; 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--forceto 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 redmainat 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-redissue says a suite did not run (the Mac slept, the night’s deadline passed, a port was held), the lead runspython3 .claude/lib/nightly/run-nightly.py --nowon 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;--forceruns them all. Why: CI runs no test suite onmain(test-run-cost.mdN-5), so a night that does not run leavesmainunchecked 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>; nevercd <path>; git …. This workspace is shared by parallel sessions. Where a directory change is unavoidable, chain it with&&, never;. A failedcdin 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.mdL-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-deliverStage 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-cleanupapplies the rules).
Never use
git stashin a worktree of a repository other sessions also use. All of a repository’s worktrees share one stash list, so agit stash popcan apply another session’s entry made in the gap since yourpush. To set changes aside, commit them on your branch, or write them to a patch file (git diff > <file>, thengit apply <file>). Why: it happened inforge-et-feon 2026-11-12 after the lesson that warned of it (.forge/lessons.mdL-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.