source: .forge/lessons.md · generated — edit the markdown, not this file

Forge Lessons — Empire Teas CRM Engagement → upstream sync log

Lessons learned in this engagement that should flow back to forge-harness (template repo) so future engagements inherit them.

Two fields decide what happens to an entry:

  • Sync target: is exactly upstream (the lesson applies to any project on forge-harness) or project-only (it is specific to this project). No other value: when part of a lesson is general, choose upstream and port only the general part.
  • Synced: is _pending_ until the entry is ported, then the forge-harness commit. A lesson found to be wrong or no longer relevant is withdrawn: its entry stays as a record, a > **Withdrawn YYYY-MM-DD:** <reason> note goes under its heading, and Synced: reads not applicable — withdrawn YYYY-MM-DD. A withdrawn entry is never synced, and its Sync target: no longer matters.

How to use this file when syncing upstream:

  1. Read each entry top-to-bottom.
  2. For entries marked Sync target: upstream and Synced: _pending_, port the change into the matching template file in forge-harness/templates/project-harness/.
  3. Skip entries marked Sync target: project-only, and every withdrawn entry.
  4. After porting, mark the entry Synced: <forge-harness commit>.

Append new entries to the bottom. Newest at bottom, in chronological order. One entry per coherent change (not one per commit — group commits that share a single lesson).


L-001 — The issued proposal is a binding input to every gate, and internal docs drift from it silently

  • Date: 2026-08-06
  • Source commits in this repo: 977d8af, 7548a5b, 7b0b938, f90a2a2, 853bf76
  • Sync target: upstream
  • Synced: pending

Problem observed

During a Gate 2 re-run on the Empire Teas engagement, four separate facts were found to be already settled inside project-proposal.md — a document that had already been issued to the client — while internal artifacts recorded them as unknown, open, or different. In one session:

  1. Mailbox scope. The PRD implied a four-provider email build (Gmail / Outlook / Exchange / IMAP) in five places. The proposal named Microsoft 365 exclusively in six places, including a cost table specifying “synchronisation via Microsoft Graph.” Roughly three provider integrations of unfunded implied scope. Corrected in PRD Rev 7.
  2. The delivery window. Both architecture.md and the Gate 2 Run 1 audit recorded “no delivery window has been supplied.” The proposal § 7 carried a full phased timeline (~11–13 weeks feature-complete, ~3.5–4 months signed-off) plus a day-for-day slippage clause. It had been sent to the client and never read back into the harness.
  3. Three “open architectural decisions.” AD-O-1 (frontend hosting), AD-O-5 (backup RPO/RTO, retention, restore cadence) and AD-O-6 (data-retention policy and erasure path) were all fully specified in proposal § A.2 / A.5 / A.6.3 — in more detail than the architecture would have produced.
  4. A contradicted infrastructure claim. architecture.md stated “Multi-AZ prod.” The proposal’s costed baseline is single-AZ everywhere, with Multi-AZ as a priced add-on recommended later. The architecture was describing something the client had not bought.

Worse, the correction attempt itself went wrong twice before landing: the mailbox scope was revised three times (Rev 1 → 1a → 1b) because the first two passes reasoned from an internal open-question resolution instead of from the proposal. The OQ resolution’s own wording (“Gmail/Exchange/IMAP remain supported by the build”) was itself an unfunded claim, so using internal documents to check internal documents reproduced the error.

The root cause is structural, not human: project-proposal.md was not in /forge-arch-probe’s step-3 input list. The gate read the PRD, the signals, the architecture, the checklist and the constitution — every internal artifact — and never opened the one document with a client signature pending on it.

Change made

Generic — sync upstream:

  • .claude/commands/forge-arch-probe.md step 3 — added .forge/client/project-proposal.md to the input table, with the precedence rule stated explicitly: where the proposal and an internal document disagree about scope, timeline, providers, infrastructure or a target, the issued proposal wins. Also notes that the proposal frequently answers items internal docs record as unknown, and that divergences must be raised as step-4 contradictions.

Project-specific — do NOT sync:

  • PRD Rev 7 (email-provider narrowing across five locations), architecture.md Rev 1a/1b/2, the closure of AD-O-1/5/6, the Multi-AZ correction, the R-ARCH-001 restatement, and new signal OQ-48.

Lesson

A gate that reads only internal artifacts can only ever verify internal consistency. It will happily certify a coherent architecture that contradicts what the client bought — and the failure is silent, because every document it read agreed with every other one.

Two rules follow, and they generalise past Gate 2:

  1. Any artifact that has left the building is a binding input. Proposals, SOWs, contracts, signed change requests. They outrank internal documents on scope, price, timeline and named third parties — not because they are more correct, but because they are what someone is owed. An internal doc that promises less is a scope leak; one that promises more is unfunded work.
  2. Never check an internal document against another internal document alone. When reconciling a discrepancy, reach for the outermost artifact available. In this case an open-question resolution — an internal record — was itself wrong, so two correction passes inherited its error before anyone opened the proposal.

A useful smell test: if this document is wrong, who finds out and when? Answers of “the client, at UAT” mean the check belongs at a gate, against the client-facing artifact.

Verification

Re-run /forge-arch-probe dry-run on an engagement whose proposal disagrees with its PRD on any scoped item. Step 3 should read the proposal; step 4 should surface the divergence as a contradiction naming the proposal as authoritative. Before this change, the run completed cleanly and reported no contradiction.

L-002 — Comments state the rule, not the author; live counts point at their source

  • Date: 2026-08-18
  • Source commits in this repo: 275736b / eb35a0a introduced the pattern; fixed in the follow-up commit on the same branch
  • Sync target: upstream
  • Synced: pending

Problem observed

Two decay patterns accumulated in one day’s work. First, config and code comments were being signed — .gitattributes carried “Decision ('s ask)”, a hook carried “Unprotected by team decision ()”, a CI header carried “applied (team decision)” — attribution that adds nothing a reader can act on, goes stale when the decision evolves, and duplicates what git blame already records precisely. Second, counts derived from other files were copied into passing prose — “~16 OQs await the Pipedrive audit” (four locations), “20 locked ADs”, “7 open decisions”, “26 open/partial OQs as of ” — and a same-day fresh review found three of them already contradicting each other, because each copy must be found and hand-updated every time the source moves.

Change made

Stripped names/dates from all comment-level attribution (the rationale stays; the provenance lives in git history). Replaced every copied count in live prose with either a qualitative statement or a pointer at the single source of truth (“the audit-tagged OQs in project-prd-signals.md”, “locked ADs live in CLAUDE.md § Architecture Decisions”). Added both rules to CLAUDE.md § NEVER DO.

Lesson

Comments and prose should state the rule and the why — never who decided it or when; version control is the attribution system, and a signature in a comment is a stale-data liability the moment the decision is revisited. And a live-state count is a copy of someone else’s data: if a number can change without the sentence around it being edited, don’t write the number — write the pointer. The discriminator for both rules is the same as the upstream forge-harness lesson L-047’s current-state-vs-provenance test: governance artifacts whose schema requires attribution (AD dates, approvals, revision entries, accepted_by) and point-in-time records (audit registers, gate runs) keep names, dates, and numbers verbatim — rewriting those falsifies history. Everything else derives.

Verification

grep -rn "team decision 20\|(Tharinda)\|(Dinil" .claude/ .github/ .gitattributes returns nothing; grep -rn "~1[0-9] OQs\|locked ADs in" .claude/CLAUDE.md .forge/tracker.yaml .forge/features.md returns only source-pointer phrasings.

L-003 — An in-place YAML writer rewrites the whole file, so a one-field update lands as an unreviewable diff

  • Date: 2026-08-19
  • Source commits in this repo: the tracker restore + Edit-tool redo on docs/pwa-repo-exists
  • Sync target: upstream
  • Synced: pending

Problem observed

Setting a single tracker field with yq -i '.last_updated = "…"' .forge/tracker.yaml produced a 177-line diff for a one-value change. The command exits 0 and reports nothing, so the damage is only visible in git diff — and only if someone looks before staging.

yq (v4.53.2) does not edit a YAML file in place; it parses the document and re-serialises the whole thing. Comments survive, but the formatting that carries meaning to a human reader does not:

  • Trailing-comment alignment is collapsed — a column of aligned # … annotations becomes one space after each value, so a hand-tuned block reads as ragged text.
  • Folded block scalars are flattened — every notes: > field, the ones deliberately wrapped so a paragraph of engagement context is readable in a diff, collapses into a single very long line. This is the worst of it: those fields are the tracker’s prose, and prose on one line is prose nobody reviews.
  • Blank-line structure and flow-map spacing are normalised away, so section boundaries the file used for grouping disappear.

The recovery was git show HEAD:.forge/tracker.yaml > .forge/tracker.yaml, then redoing both intended changes with the Edit tool — final diff exactly 2 lines, which is what the change actually was.

This is not a one-off operator slip, and that is the point. The harness’s own automated flows write the tracker this way by design: .claude/skills/forge-pr-open/SKILL.md flips impl_status and stamps last_updated with yq -i, and .claude/skills/forge-worktree-up/SKILL.md writes branch / base_branch the same way. Neither has run yet — wave delivery has not started — so the hazard is dormant, and detonates on the first /forge-deliver wave, at exactly the moment several parallel sessions are each rewriting the file.

Change made

  • Added the writer rule to .claude/rules/tracker.md § Update Rules: hand-edits go through the Edit tool, which fails loudly on a non-match and touches only the matched line; yq is for reading.
  • The lesson is recorded here rather than silently patching the two skills, because changing how the automated flows write is a design decision (it interacts with the flock serialisation convention in the same section) and belongs to a deliberate pass, not to a docs commit. Open upstream fix: convert the yq -i mutations in forge-pr-open and forge-worktree-up to surgical single-line edits, and keep the lock around whatever replaces them. Done 2026-09-27: both skills now write tracker fields with the Edit tool between .claude/lib/tracker-write.sh begin and finish <n>, which holds a directory lock across the edits (flock cannot span separate tool calls, and macOS has none) and restores its snapshot if more lines changed than declared. It was not done sooner, and the failure recurred on F11-a (F-001) and F5-i (F-001) because the skills still showed yq -i as the way to write.

Lesson

A tool that round-trips a file through a parser is a whole-file writer, whatever the flag is called. -i means “write the result back here”, not “modify this line” — the same trap applies to jq on JSON, to formatters run with a wide glob, and to any config-editing helper that pretty-prints on save. The failure is quiet by construction: the command succeeds, the data is correct, and only the reviewability of the file is destroyed.

Two rules follow:

  1. Match the writer to the edit. A one-field change should produce a one-line diff. If the diff is larger than the change, the tool is wrong for the job — stop and pick a surgical one, don’t hand-repair the reflow.
  2. Check the diff of a generated write before staging it, especially when the command succeeded. Exit 0 is not evidence for a file whose value is its readability. This is the same class as the existing rule that a scripted find-and-replace must assert its anchor matched — an unmatched replacement and a whole-file reflow both exit 0 and both look like success.

The discriminator for which files this matters on: does a human read this file in a diff? tracker.yaml, specs, plans, and CLAUDE.md are read by people in review, so formatting is content. Generated mirrors (docs-html/, the dashboard *.js) are not, which is why a regenerator is allowed to rewrite those wholesale.

Verification

On a scratch copy of the tracker, yq -i '.last_updated = "…"' yqtest.yaml then diffing against HEAD reports 177 changed lines, with notes: > blocks collapsed to single lines and trailing-comment columns stripped. The same edit applied with the Edit tool reports 1.


L-004 — A sibling engagement’s shipped-defect history is a Foundation input, not trivia

  • Date: 2026-08-20
  • Source commits in this repo: the coding-standards.md §0.1/§3.1–3.3/§5/§7 additions and the FS-1 spec ACs that enforce them
  • Sync target: upstream
  • Synced: pending

Problem observed

While specifying Foundation slice 1, the developer raised a class of bug an earlier Altrium engagement on the same hosting model (static bundle behind a CDN, separate API) had shipped, been diagnosed across three tickets, and permanently fixed. Reading those tickets and their fix commits turned one remembered symptom — “the page showed data from build time” — into four distinct failure modes, three of which were live risks on this project and none of which the architecture or coding standards addressed:

  1. Build-time snapshot rendered as live data. The static build ran the data fetch at build time and froze the result into shipped HTML; fresh data never appeared without a redeploy.
  2. Seed-then-refetch flash. The baked snapshot painted first, the client refetch resolved to empty, so content flashed and vanished. A sibling page didn’t flash — because it held a loading state instead of painting the seed.
  3. A fabricated fallback dataset reaching production. A hardcoded list existed as a dev convenience for API-unreachable runs. A refactor changed a fetch from swallowing errors to propagating them, which turned two previously-dead catch blocks live; a build against an unreachable API then baked invented records into the public HTML for every visitor until the next deploy. Nothing in that refactor’s diff hinted at it.
  4. A temporal-predicate disagreement. Two tickets defined the same “upcoming” rule against different timestamps, and a redundant client-side status filter duplicated a server-side one.

Two of these were not discoverable from first principles. The aria-live container must be rendered unconditionally — a live region has to exist before its content changes for the change to be announced, so conditionally rendering the wrapper alongside the content silently defeats it. And the fetch effect needed a cancellation guard, because a double-invoked effect lets the losing run clobber the newer result.

Failure 3 is the one that matters most, and it is a different kind of bug from the other three. Those were correctness failures — the screen was out of date. That one is an integrity failure: unable to reach the truth, the system invented a plausible substitute and presented it as fact. Nobody reports it, because nothing looks broken.

Change made

  • coding-standards.md gained §0.1 as a second prime directive — never show a user something that isn’t true — with the four failure shapes tabulated against the good intention that produces each, because every one of them is something a competent developer does for a defensible reason.
  • Mechanics written up where implementers read them: §3.1 (config is baked at build time, data never is; no build-time data path may be added), §3.2 (the six loading/empty/error states, with copy rules — empty-because-filtered is distinct from empty, and a failed refresh keeps its data with an as-of label), §3.3 (the server owns every number that matters — including that a server-enforced gate is never decided client-side, which on this project is an approval-bypass risk, not a display bug), §2 (one authoritative predicate per visibility or temporal rule, boundary written into the spec’s ACs), §5 (fixtures structurally unreachable outside local/test).
  • Enforced mechanically rather than remembered, at three levels: ArchUnit forbids a production class reaching a fixture package (§7.2), dependency-cruiser forbids the transitive frontend equivalent (§7.3), and a CI script greps built artifacts for the mandated FIXTURE_ prefix (§7.6). §6.10 requires the guarantee demonstrated red-green before the first feature WI.
  • The FS-1 spec carries the ACs that prove it, and the capture app’s service worker is scoped to shell assets by allow-list — a worker serving stale API responses survives redeploys, which is the one version of the staleness failure the usual fix cannot clear.

Lesson

Before Foundation locks a project’s coding standards, mine the shipped-defect history of the most architecturally similar prior engagement — and mine the tickets and fix commits, not people’s memories of them. The recollection was one bug; the record was four, plus two non-obvious implementation details and a reproduction technique.

Three things make this cheap and high-yield, and they generalise past this instance:

  1. Architectural similarity predicts defect similarity better than domain similarity does. The prior project was a public marketing site and this is an internal B2B CRM — nothing in common at the domain level. They share a deployment shape, and that is what determined which bugs were reachable. Pick the comparison by architecture.
  2. A fixed bug’s value is in its fix commits. The ticket says what was wrong; the commit messages say what was tried, what turned out to be a different bug wearing the same symptom, and how it was verified. Failure 3 above was discovered only because a commit message explained that making a function propagate had activated dead catch blocks.
  3. Convert findings into a machine check, not a paragraph. A standard that says “don’t ship fabricated data” is advice. An ArchUnit rule making the fixture unreachable is a guarantee. Where a rule survives only by being remembered, assume it will be forgotten at the exact moment the deadline makes it inconvenient.

Also worth carrying: this failure class self-conceals under normal verification. A build made in the current data state bakes the correct answer, so the bug vanishes on redeploy and reads as fixed. Reproducing it needs a build from one data state served against another, or a build against an unreachable API with the output artifact grepped for what it baked. Any bug whose repro depends on state a fix destroys must have its reproduction captured before the fix lands.

Verification

The four failure modes were read from the sibling engagement’s ticket records and confirmed against its fix commits and diffs, including a commit message documenting that an API-unreachable build had been reproduced and the fabricated records found in the shipped output. Each resulting rule is anchored to an FS-1 acceptance criterion or a named §7 tool, so none of them rests on recall.


L-005 — A harness sentence describing a repo outside the harness is a dated observation, not a fact

  • Date: 2026-08-20
  • Source commits in this repo: the .claude/CLAUDE.md + .forge/team-guide.md POC-description corrections and OQ-55 (landed alongside the FS-1 change)
  • Sync target: upstream
  • Synced: pending

Problem observed

Three harness documents described the read-only capture-app POC (forge-et-pwa-poc) in the same words: “actual app, hardcoded data, no backend.” Running it took about ten minutes and showed something else entirely — its own docs/plans/README.md records 12 of 15 epics Done (verified): a deployed Python/FastAPI backend on Supabase Postgres + pgmq with SES mail and Supabase auth, an API-integrated frontend (the mock src/data/leads.js deleted), and four post-MVP features nobody had catalogued.

The description was true when written (2026-08-18/19) and went stale within two days, because the POC is a live repo that nobody in this harness watches. Nothing announced the drift.

It was load-bearing in two places:

  • The estimate. AD #20 and R-ARCH-001 size the capture stream as a “prototype-adjusted ~2.5–3.5 wk parallel stream” — a basis computed against the mock-shell description. The real POC makes the frontend port cheaper and reveals its backend as unportable (its ADRs 3/4/5/8/9 all yield to AD #19–#23), so the number was built on a picture that was wrong in both directions.
  • The scope. F36 diverges from what the POC actually ships in both directions: five capabilities already built that F36 never mentions, and two that F36 requires but the POC lacks (badge QR scanning, offline-tolerant queued upload — both verified absent). This went unnoticed for weeks because reading the harness’s description felt like reading the repo.

The sharpest detail: all three documents agreed with each other, so no amount of internal cross-checking could have caught it. They agreed because they were copies of one sentence.

Change made

  • Corrected the description in all three places, and split it along the line that actually matters for the port: the frontend is the portable half, the backend is a proven reference, not reusable code.
  • Added a two-command run recipe to team-guide.md § Repos on This Project, so the next person forms their picture by running the thing rather than by reading a paragraph about it — including the non-obvious AUTH_ENABLED=false, without which every data route 401s.
  • Recorded the F36 delta as OQ-55 (Blocks: F36) rather than editing scope internally, since it needs the client’s answer.
  • Made the doctrine a rule: .claude/rules/source-trust.md gains ## When describing something outside this repo — describe external state qualitatively or stamp it, open/run it before sizing it, and treat agreement between internal docs as no corroboration at all.

Lesson

Any sentence in an internal document that describes something outside that document’s repo is an observation with a shelf life. It is the same class as a copied count (L-002) and the same failure mode as L-001 — internal docs drifting from a binding external input — but pointed at a sibling repo rather than at the proposal. Three rules follow:

  1. Describe external state qualitatively, or stamp it. “A working prototype exists” ages badly; either point at the source of truth the reader can check (its docs/plans/README.md records the epic status) or carry an explicit as-of marker so a reader knows to re-verify. This engagement already applies the principle to CI — a job-name comment was dropped precisely because it asserted external state.
  2. Before you plan against an external artifact, open it or run it. Not before you mention it — before you size it, scope it, or put a number on it. Verifying cost ten minutes here; not verifying cost an estimate basis and an unnoticed scope gap on a P1 feature.
  3. Agreement between internal documents is not corroboration. They are usually descendants of one sentence. Reach for the outermost artifact (.claude/rules/source-trust.md) — and when the outermost artifact is a repo, the repo is runnable, which makes it the cheapest source to check, not the most expensive.

The discriminator for when this matters: if this sentence is wrong, who finds out and when? “The team, at week 8, when they open the repo they were told was a mock” is a good enough answer to justify verifying now.

Verification

Reproduced end to end. docs/plans/README.md in the POC reports 12 of 15 epics Done (verified); both servers were installed and run (USE_MOCKS=true AUTH_ENABLED=false for the API, npm run dev:web for the PWA) and the full loop exercised through the real API — a campaign created, three captures posted, enrichment returning tier hot / score 95, duplicate detection firing on captures 2 and 3, the exhibitor CSV imported and ranked, and the lead-detail research view rendered. The two F36 gaps were confirmed by grep: no QR/barcode library or BarcodeDetector, and no IndexedDB or background sync — the install banner’s “works offline” refers only to the Workbox app-shell precache, so a capture taken with no signal is lost. The POC repo was left untouched (git status --porcelain empty); the production build used for verification was written to a scratch directory via --outDir.


L-006 — An mtime freshness check cannot see a deletion, so the regen it guards silently goes stale

  • Date: 2026-08-20
  • Source commits in this repo: the regen-reference-graph.sh rewrite that dropped its find -newer guard, and the harness-graph.py / CI additions landing with it
  • Sync target: upstream
  • Synced: pending

Problem observed

The reference-graph regen hook guarded its work with a cheap freshness test: skip unless find -newer reports some source newer than the generated artifact. Sound-looking, and wrong — deleting a file changes no surviving file’s mtime. Delete a doc and the guard sees nothing newer, skips, and leaves an artifact that still lists a file which no longer exists. Proven with a probe: adding a doc updated the graph; deleting it did not, and the stale entry survived until the generator was run by hand.

The failure mode is the nasty kind — the hook exits 0, reports nothing, and the artifact looks current. It is only wrong about the one class of change nobody thinks to test.

The obvious patch is worse than it looks. Directory mtimes do change on create and delete, so widening the check to directories fixes deletions — but .forge/dashboard/ gets its mtime bumped every turn anyway, because a sibling regen hook replaces a dashboard blob via temp-file-and-rename. The widened check therefore fires on every single turn: all of the cost of regenerating, plus the complexity of a guard that no longer guards anything.

The same guard shape ships in a sibling engagement’s harness, so it is carrying this bug too.

Change made

  • Deleted the optimisation instead of patching it. The hook now regenerates unconditionally. It costs ~0.4s, and because the generator is deterministic an unchanged turn rewrites byte-identical files and produces no diff — so the “saving” was buying nothing but the bug.
  • The hook comment records why there is no freshness check, so the next person does not helpfully add one back. It also names the replacement to reach for if the analyzer ever grows slow enough to need one: key the check on the repo’s file list, not on mtimes, because a file list can represent an absence.
  • Verified in both directions afterwards — additions and deletions both flow through, and the artifact round-trips byte-exactly to its pre-probe state.

Lesson

A freshness check must be able to represent an absence. Timestamps describe things that exist; deletion is the removal of the thing that would have carried the evidence. Any “is it stale?” test built only on mtimes is therefore blind to deletion and rename by construction — no amount of widening the watch set fixes the category error, it only moves it.

Three rules follow:

  1. Test a cache/guard against deletion explicitly, not just modification. Add, modify, remove — the third is the one that gets skipped, and it is the one that fails.
  2. When a guard is cheaper to delete than to make correct, delete it. The threshold is the generator’s actual runtime against the budget it runs in, measured — not assumed. An idempotent generator with deterministic output is safe to run unconditionally, and that property is worth more than the milliseconds a guard saves.
  3. A skipped run and a clean run are indistinguishable from the outside. Both exit 0 with no output. If a guard can skip, something must be able to prove the skip was correct — which is why the CI staleness gate diffs the regenerated artifact rather than trusting the hook to have fired.

Sibling of the vacuous-pass trap in the same subsystem: a CI staleness gate that calls a self-skipping hook in a fresh clone (where every mtime is checkout time) regenerates nothing and passes green. Same root cause — an mtime is not a fact about content.

Verification

Probe test, run against the hook rather than the generator. A new doc citing an existing one appeared in the artifact after the hook ran (edges 739 → 740). Deleting that doc and re-running the hook left the stale entry in place — the failure. After the guard was removed, the same sequence added and then removed the entry, and the artifact’s sha256 returned exactly to its pre-probe value. Fail-open behaviour re-confirmed after the change: with python3 absent from PATH the hook exits 0 and leaves the artifact untouched, and it exits 0 with the generator script missing.

L-007 — A dependency bot’s rejected major-version PR is a support-lifecycle signal, not noise

  • Date: 2026-08-21
  • Source commits in this repo: the AD #25 / ## Stack change, coding-standards.md §8.7’s rewrite, FS-1 spec Rev 5 and the plan’s superseding note; in forge-et-be, the Spring Boot 4.1.1 commit on forge-et-be#8
  • Sync target: upstream
  • Synced: pending

Problem observed

Dependabot opened a PR bumping Spring Boot 3.5.16 → 4.1.0. It read as exactly the kind of PR you close: a bot proposing a major-version jump across a locked architecture decision, with both CI lanes red and no awareness of what it would break.

Closing it would have been wrong, and not for a subtle reason. Spring Boot 3.5 had left open-source support seven weeks earlier — OSS support ended 30 Jun 2026 and 3.5.16 is the last free release. Nothing in this harness knew that. ## Stack, the README, team-guide.md, the FS-1 spec and the plan’s own pin record all said “Spring Boot 3.x” and all of them agreed, because they are descendants of one sentence written when 3.5 was current. No document was wrong when written and no document announced when it stopped being true.

The bot was the only thing in the system pointed at upstream. Its PR was not an upgrade proposal — it was the notification that the line we were on had ended, arriving in the only form the toolchain had available.

Two further failures fell out of the same session:

  • A coding standard asserted a mechanism that upstream had deleted. coding-standards.md §8.7 said “Spring Boot’s spring-jcl supplies the Commons Logging API”, with a matching comment in et.java-conventions.gradle. Spring Framework 7 removed spring-jcl. The rule’s intent (one JCL provider) survived; its named mechanism did not, and the standard read as current because nothing links a house rule to the upstream artifact it depends on.

  • A config key whose justification was a framework default outlived the default. The plan’s Decision 17 set management.endpoint.health.probes.enabled: true because on Boot 3.5 it was off by default and auto-enabled only on Kubernetes. On 4.1.1 it defaults to true — the key is now a restatement, and Decision 17’s stated reason is false for this line. Nothing failed; the rationale just quietly stopped being true, which is the harder failure to notice.

    Worth recording how this was nearly got wrong in both directions. The metadata lists two similarly-named keys — management.health.probes.enabled (false) and management.endpoint.health.probes.enabled (true) — and reading the metadata alone produced a confident, wrong conclusion that the migration guide’s “probes enabled by default” line referred to the other property. Commenting the block out and watching the liveness assertion still pass settled it in one run. Two plausible readings of a config table are a signal to run the thing, not to pick the more convincing one.

Change made

  • AD #25 records the 4.1 line and that the pin is a moving one: Boot minors now carry ~13 months of OSS support each, so the decision is a cadence, not a resting place. Recorded at the pin in buildSrc/build.gradle as well as in the AD table, with the dates.
  • Dependabot is deliberately left unrestricted — no ignore on major updates. Two reasons: the major PR is the sensor, and ignore in dependabot.yml also suppresses Dependabot security updates for the matched dependency, so muting majors would mute the CVE path for them too. The gate is review, not configuration.
  • The harness repo gained the dependabot.yml it never had, which is why its workflow pins had already drifted a major behind the three app repos with nothing reporting it.
  • §8.7 rewritten around the bridge that actually exists, with the condition under which it moves from testRuntimeOnly to runtimeOnly.

Lesson

A bot PR you would never merge as written can still be the most current information in the repository. Triage it for what it reports, not for what it proposes — and specifically ask “what does upstream know that we don’t?” before closing it. The right response here was neither merge nor close: it was to take over the branch.

Three rules follow:

  1. A dependency’s support window is a fact the harness does not hold, and cannot infer. Version numbers do not carry EOL dates. If a stack decision names a framework line, record when that line loses free support next to it, or accept that a bot is your only alarm.
  2. A house rule that names an upstream artifact inherits that artifact’s lifecycle. Prefer stating the invariant (“exactly one JCL provider”) over the mechanism (“spring-jcl supplies it”); where the mechanism must be named, it is a dated claim in the sense of [[L-005]] — and internal agreement between docs is not corroboration, because they drift together.
  3. Take the migration cost while the code that would pay it does not exist yet. This migration was ~40 lines because the backend was still a shell; the same move after the data layer, security and controllers land is a project. “Not yet needed” and “cheapest now” point in opposite directions, and the support calendar decides which one wins.
  4. A config key justified by a framework default needs a test, because the default is the framework’s to change. A version bump does not announce which of your explicit settings just became redundant, or which of your comments just became false. Where the behaviour matters, assert the behaviour — then the key can be re-justified or removed on evidence rather than defended from memory.

Verification

./gradlew clean build green on 4.1.1 — 46 tests, 0 failures, counted from the JUnit XML rather than a green log line. Three blockers found only by running it: Spock’s Groovy suffix is a compile gate (IncompatibleGroovyVersionException on Groovy 5), TestRestTemplate is absent from every 4.1.1 jar, and the missing JCL bridge kills every test task at test-discovery. Actuator defaults re-read from 4.1.1’s own configuration metadata and then tested, which is what caught a wrong reading of that metadata — see the third bullet above. Support dates taken from the published release calendar, not from memory.

L-008 — A generated mirror’s freshness guard treats its own broken output as up to date

  • Date: 2026-08-21
  • Source commits in this repo: the regen-tracker-dashboard.sh publish() change; diagnosis originally surfaced in forge-et-harness#21
  • Sync target: upstream
  • Synced: pending

Problem observed

regen-tracker-dashboard.sh wrote both its mirrors by redirecting straight at the destination — { ...; yq_json "$tracker"; ... } > tracker.js and "$py" - <<PY > signals.js. A shell redirect truncates its target before the producer runs, so any failure of yq or python leaves a 0-byte or partial mirror behind.

On its own that would be a visible, one-time annoyance. What made it self-perpetuating was the staleness guard in the same script:

[ ! -e signals.js ] || [ lessons.md -nt signals.js ]

A truncated file exists, and because the failed write just touched it, its mtime is newer than its source. So the guard reports “fresh”, skips the regen, and the broken mirror survives every subsequent run. The dashboard signal it feeds renders as no-data, and nothing anywhere says why.

A second, sharper case turned up while testing the fix: checking the temp file’s size is not enough either. In { printf header; yq_json; printf footer; } > tmp, a failing yq still lets both printfs write, so the result is a small but non-empty stub that passes [ -s ] and gets published over a good mirror. The first attempt at this fix shipped exactly that hole and the probe caught it.

Change made

A publish() helper takes the producer’s exit status as well as its output, and moves the temp file into place only if the producer succeeded and wrote something. A failed regen now leaves the previous good mirror untouched and says so on stderr. yq runs into a variable first, so its failure is a status rather than a half-written file. Both staleness guards changed from ! -e to ! -s, so a 0-byte mirror counts as missing however new its mtime is.

Output is byte-for-byte unchanged — $(...) strips yq’s trailing newline, which would have turned every future regen into a cosmetic diff on a committed mirror, so the newline is restored explicitly.

Lesson

Direct sibling of [[L-006]], in the same subsystem and the same category: a guard built on file metadata is blind to a class of content state. L-006 was blind to deletion; this one is blind to its own failure. The generalisation covering both: an mtime is not a fact about content, and “the file is there” is not a fact about the file being right.

  1. Never redirect straight at a generated artifact. Build into a temp file and move it into place only on success. The redirect destroys the previous good output before knowing whether there is a replacement.
  2. A guard must be tested against the failure it is supposed to survive, not only the success path. Truncate the output, make the producer exit non-zero, delete the output — then run the hook. Two of the three passed here and the third was the bug.
  3. Size is a weaker check than status. Any pipeline where a wrapper writes around a failing producer yields non-empty garbage. Check what the producer returned, not just what landed.
  4. This repo’s CLAUDE.md already notes the dashboard mirrors have no CI staleness gate, so a broken one “just lies quietly” — which is precisely why the write path has to fail safe on its own rather than relying on a diff in CI to catch it.

Verification

Four probes against the hook. A 0-byte signals.js with an mtime newer than lessons.md: skipped before the change, rebuilt to 487 bytes after. yq replaced with a stub that exits 1: truncated tracker.js from 17137 bytes to a 106-byte stub before the status check was added, left it byte-identical after. No .tmp files left behind on either path. And a normal run regenerates tracker.js byte-identical to the committed mirror, confirming the change is robustness-only. bash -n and shellcheck both clean.

L-009 — Fixing a Blocker writes new design, and that design is the only part nobody reviews

  • Date: 2026-08-22
  • Source commits in this repo: the forge-plan-review step-3c change; FS-2 spec Rev 4 and its plan; BUG-001 in .forge/bugs.md
  • Sync target: upstream
  • Synced: pending

Problem observed

forge-plan-review ran a single audit pass by design: the sub-agent audits, the main session applies Blocker and Important fixes, the human approves. The stated trade-off was that applied fixes are not machine-verified, so the human gate carries more weight.

Both foundation slices on this engagement were approved that way with Blockers in the findings — FS-1 with 4, FS-2 with 5. Two checks then showed what that costs.

FS-2, re-reviewed before approval. Pass 2 returned a Blocker inside a pass-1 fix. Spec Rev 3 had been written to close a Blocker about which Flyway location creates which schema; the repair overshot and made both schemas migration-owned, which is not implementable for the default schema — Flyway creates the history table there before the first migration runs, so the build is red on the first run either way the property is set. The fix for a Blocker was itself a Blocker, and nothing between them would have caught it.

FS-1, audited cold at its approval commit as a calibration check — reconstructed from git so the reviewer could not read the implementation outcome. It returned three real defects in the approved plan. Implementation later caught two, at much higher cost: a claimed build-graph guarantee that had no mechanism (invented mid-implementation), and a config fail-fast whose stated mechanism was simply wrong about the framework — the shipped application.yml now carries the correction and the words “Measured, not assumed — that is exactly what it did.” The third shipped green and was still open two weeks later.

Change made

forge-plan-review step 3c: a verification pass is required whenever the audit pass returns one or more Blockers. The trigger is the count, not a judgment about whether the fixes felt risky — the judgment would be made by whoever just wrote them. Automatic passes stop at two; if pass 2 also returns Blockers, that fact goes to the human at the gate.

Importants are deliberately excluded. An Important sharpens a decision the plan already made; a Blocker usually means the plan had not decided something, so closing it writes new design — and that design is then the only content in the plan nobody has reviewed.

Lesson

The asymmetry between review and execution is not about which is the stronger detector. Execution is stronger: it finds defects with certainty and finds ones no reader could predict. What execution cannot do is see a defect with no runtime signature.

The FS-1 finding that survived is the clean example. public/sw.js duplicated a predicate its unit tests cover, and its comment said the build asserted the two stayed in step. No such assertion existed. Tests green, build green, guard absent, comment claiming otherwise — and a future edit to the tested copy would ship untested. No amount of running the code detects that; only reading it does. It is now BUG-001, fixed with the guard the comment promised, and the replacement comment states what the guard does not prove.

So the value of review is not detection power. It is (a) price — the same defect costs an edit at review, a re-plan at implementation, and a migration at feature time — and (b) exclusive coverage of the vacuous-gate class, which is this engagement’s most frequent failure mode and the one execution reports as success.

Verification

The rule was derived from two measured runs, not from principle: FS-2’s pass 2 (a Blocker inside a pass-1 fix) and FS-1’s cold calibration (three real defects, one still open at the time of writing). The FS-1 run is reproducible — reconstruct the plan and spec from the approval commit into a scratch directory and dispatch plan-reviewer at those paths, with the implementation-outcome files explicitly excluded from what it may read.

L-010 — A git hook that has never received the input it filters on is untested, and its zero exit means nothing

  • Date: 2026-08-23
  • Source commits in this repo: FS-1 finding F-006 (.forge/specs/foundation/001-app-shell-findings.md); the lint-staged.config.js fix in forge-et-be
  • Sync target: upstream
  • Synced: pending

Problem observed

The backend pre-commit hook mapped *.java/*.groovy to a Gradle command, but lint-staged appends the staged filenames, so Gradle read them as task names and failed. Yet every commit between the hook landing and the first .java commit staged only non-matching files, so lint-staged printed “no matching files” and exited 0. The hook reported success on every commit while being incapable of succeeding on the one input it existed for — and the AC-22 demonstration did not catch it, because that proof exercises the commit-msg hook, not pre-commit.

Change made

Fixed with a lint-staged.config.js function that ignores the file list so Spotless runs as a normal Gradle invocation. The general check: stage one file of each configured type once, at the moment the hook is written.

Lesson

This is the vacuous-gate family (cf. [[L-006]], [[L-008]]) applied to git hooks: a hook given no matching input is untested, and exit 0 is not evidence it works. A gate is only proven once it has been shown to fail on the input it exists to catch.

L-011 — The Maven Central search index lags the repository; check a version against the repo or the plugin portal

  • Date: 2026-08-23
  • Source commits in this repo: FS-1 finding F-003 (.forge/specs/foundation/001-app-shell-findings.md)
  • Sync target: upstream
  • Synced: pending

Problem observed

Two version lookups from search.maven.org in one subtask were both wrong. It reported Spotless’s newest release as 7.0.4 (the Gradle Plugin Portal had 8.10.0, and 7.0.4 cannot provision a formatter on Gradle 9 at all); and it listed only 2.4-M1–M6 milestones for Spock against Groovy 4, implying no stable 2.4 existed, while 2.4-groovy-4.0 is real and returns HTTP 200 from repo1.maven.org.

Change made

Check a version against the artifact path (repo1.maven.org/maven2/...) or the Gradle Plugin Portal, not the search API. When a “latest” version behaves as though it predates your toolchain, suspect the lookup before the tool.

Lesson

The search index is incomplete and lags; the repository and the portal are authoritative. Tactical, but it cost real time twice in one sitting.

L-012 — A tracker note that grows into a history log breeds stale copied counts

  • Date: 2026-08-23
  • Source commits in this repo: this branch’s tracker.yaml FS-1/FS-2 note trim; the FS-1 note’s stale “Findings F-001 to F-005” enumeration
  • Sync target: project-only
  • Synced: pending

Problem observed

The FS-1 and FS-2 tracker.yaml notes had grown into multi-paragraph history logs (FS-2 ~600 words on one line), against .claude/rules/tracker.md’s “notes: one line, current state only.” The FS-1 note enumerated “Findings F-001 to F-005 … F-005 informational” — which went stale silently the same day, when F-005 was closed and F-006/F-007 were added, so the note contradicted the findings file. The giant folded blocks are also exactly what a stray yq -i flattens ([[L-003]]).

Change made

Trimmed both notes to a one-line current state, pushing the narrative into the spec/plan (where it already lives), via a line-anchored, asserted, verified edit — never yq -i.

Lesson

Keep tracker notes to a status line. A note that records history will copy counts from other files, and a copied count goes stale silently ([[L-002]]). The detail belongs in the spec/plan; the tracker holds current state only.

L-013 — A non-blocking build nudge can steer code style against the written standard, silently

  • Date: 2026-08-29
  • Source commits in this repo: this branch’s coding-standards §2.1/§7.2/§9.1 revision; forge-et-be b487f51 (the Lombok backfill and the -Xdoclint:all,-missing change)
  • Sync target: upstream
  • Synced: pending

Problem observed

Coding-standards §2.1 sanctioned Lombok as the required form for boilerplate (field-level @Getter/@Setter, @RequiredArgsConstructor as the DI pattern), FS-1 wired it and committed lombok.config — and FS-2’s substrate still shipped with every accessor and assignment-only constructor hand-written, each carrying filler Javadoc (“Returns the name. @return the name”) that §9.1’s own rule says to delete in review. The driver was the doclint missing nudge: a hand-written public member draws a missing-comment warning, a Lombok-generated one draws a default-constructor warning that only disappears if someone hand-writes and documents the member. The gate never blocked anything — it just made the standard-violating form the quiet path of least resistance, and no reviewer or document recorded the divergence.

Change made

The operative rule is now written where implementers read: §2.1 — if a member’s body would match what a sanctioned annotation generates, the annotation is the required form; hand-write only where behaviour is customized; contract prose moves to the field when the accessor is generated. §9.1 — generated members carry no Javadoc and none is owed; a member is never hand-written to give a comment somewhere to live. The gate was fixed to stop punishing the sanctioned pattern: doclint runs all,-missing (§7.2), keeping broken-{@link}/malformed-tag failures while dropping the missing-comment nudge. The shipped FS-2 classes were backfilled (forge-et-be b487f51, net −77 lines, check green before and after).

Lesson

When a written standard and a build gate disagree, the gate wins in practice even when it only warns — a standing warning is a nudge the next implementer resolves in whatever direction makes it go away, and nothing records the drift. When adopting a generate-don’t-hand-write policy (Lombok or any code generator), audit every lint that keys on source-visible members in the same change: a “missing documentation” check can only ever fire on the hand-written form, so left on, it penalizes exactly the pattern the policy mandates. Comments follow code; a gate must never make code follow comments.

L-014 — A partitioned migration version space needs out-of-order application, and fresh-DB CI is blind to the failure that proves it

  • Date: 2026-08-30
  • Source commits in this repo: FS-2 finding F-001 (.forge/specs/foundation/002-data-layer-findings.md); forge-et-be 3369e3f (the out-of-order: true fix + reasoning beside the Flyway config) and 373369f (the composition test that pins the key)
  • Sync target: upstream
  • Synced: pending
  • FS-14 note (2026-09-10): on this project the condition is moot — AD #31/FS-14 collapsed the partitioned version space into one sequential line (V1, V2, …, one location), so out-of-order is no longer needed here and the shipped migrations were squashed. The lesson stands for any project that partitions a Flyway version space and is still queued for upstream sync; it is why FS-14 chose one sequence over version bands.

Problem observed

FS-2 partitions the Flyway version space by module layer — generic core takes V1–V999, the tea domain takes V1000+ — and the tea location’s V1000 (CREATE SCHEMA tea) is applied by the very first migrate(). Flyway’s default outOfOrder=false treats a resolved-but-unapplied migration whose version sits below the highest already-applied version as a validation failure, not a pending migration. So once any environment has applied V1000, the next core-band migration added later (V2, V200, …) fails startup validation and the application crash-loops. The development environment auto-deploys main on every merge, so the first post-FS-2 core migration would take dev down; UAT and prod hit the same wall on their second deploy. FS-2’s own CI never saw it — every CI database is fresh, and migrating from empty applies V1, V2, V200, V1000 in numeric order and validates clean. The failure needs an already-partially-migrated database, which is exactly what every long-lived environment is and no CI database ever is.

Change made

spring.flyway.out-of-order: true — the designed-in posture for a partitioned/multi-band version space, not a workaround: out-of-order application is precisely what a scheme where tea occupies high versions from day one asks for, and the band map + duplicate-version check + tea-reference check already police what outOfOrder gives up (accidental renumbering, collisions). The reasoning was written beside the Flyway config where the next reader meets the trap, with a both-halves regression test that builds the exact failure shape (a tea-only head at V1000, then a later lower version applying under it). The pre-PR review then caught that the regression test supplied its own true and FlywayProperties ignores an absent key silently — so a composition test was added that loads the real application.yml and asserts the key is present and true, closing the silent-loss path.

Lesson

Two generalizable points. (1) A partitioned or multi-band migration version space (any scheme that reserves high version ranges for a module or domain applied early) requires out-of-order application as designed-in behaviour — treat outOfOrder=true as part of the scheme, not an exception, and let the band/duplicate/reference checks police the safety it trades away. (2) The deeper trap is the CI blind spot: a suite that only ever migrates from an empty database cannot see any failure that needs an already-partially-migrated one — out-of-order validation, order-sensitive interacting DDL, destructive migrations. Those surface only in long-lived environments (dev/UAT/prod), the most expensive place to find them. When a configuration default is exercised only by fresh databases it is effectively untested and can be dropped silently — pin it with a composition test that reads the shipped config, so the key that averts the production-only failure cannot vanish in a merge or a cleanup. (Same shape as L-010: a gate that has never received the input it filters on is untested, and its passing means nothing.)

Verification

Red-green proven: with spring.flyway.out-of-order: true commented out of application.yml, only the new composition test fails (the exact silent-loss scenario, now loud); restored, the suite is green. The regression test’s red half asserts FlywayValidateException (“not applied to database”) against a tea-only-head database; its green half asserts the late lower version applies under V1000. ./gradlew check green at 373369f (113 tests / 41 suites / 0 failures from the JUnit XML).

L-015 — A spec that names a tool option as the cause of an effect is a hypothesis until a toggle proves it

  • Date: 2026-09-01
  • Source commits in this repo: FS-4 finding F-001 (.forge/specs/foundation/004-build-ci-findings.md); the et.quality-conventions.gradle NullAway-config comment rewrite (forge-et-be, FS-4 subtask 1)
  • Sync target: upstream
  • Synced: pending

Problem observed

FS-4’s spec (FR-N4) and plan (Decision 5) both asserted that NullAway’s TreatGeneratedAsUnannotated=true is the switch that excludes Lombok’s generated accessors, and predicted that without it the bring-to-green sweep would “drown in spurious nullness findings on Lombok builders/equals/accessors.” A toggle matrix (transient probes, compileJava --rerun-tasks) showed neither half held: the exclusion is class-level — Error Prone inherently skips a fully-@Generated class, independent of TreatGeneratedAsUnannotated and disableWarningsInGeneratedCode — while generated members inside a hand-written class are analysed (harmlessly). What the option actually buys is call-site leniency toward a generated class’s APIs, not the exclusion. Turning the analyzer on produced exactly one finding, not a flood.

Change made

No functional change — the gate was correct. The convention-plugin comment was rewritten to state the measured mechanism, and finding F-001 records the toggle matrix so the next reader does not inherit the “the option excludes accessors” mental model. This lesson generalizes the pattern.

Lesson

When a spec or plan names a specific tool option (a compiler flag, an analyzer setting, a framework property) as the cause of an observed effect, treat the attribution as a hypothesis, not a fact — verify it with a toggle (turn it off; does the effect persist?) before relying on it or writing it into a contract. A plausible attribution that survives into a spec becomes load-bearing folklore: it shapes later decisions (here, the predicted suppression burden) and is expensive to unwind once code and sibling specs cite it. The check is cheap — one transient probe run both ways — and it is exactly the red-green discipline (§6.9) applied to a claim instead of a gate.

L-016 — Verify a tool can enumerate your ecosystem’s real lockfile/store before an architecture decision names it

  • Date: 2026-09-01
  • Source commits in this repo: FS-4 findings F-002 (with F-004/F-005 for the surrounding measurements); spec Rev 2 + AD #27 (the OWASP Dependency-Check → Trivy swap); .forge/specs/foundation/004-scanner-tool-analysis.md
  • Sync target: upstream
  • Synced: pending

Problem observed

AD #9 named OWASP Dependency-Check as the dependency-vulnerability scanner “uniform across Java and Node” — decided at project inception, before any lockfile existed. When FS-4 wired it, DC proved structurally unable to enumerate the pnpm frontends: --scan node_modules catalogued 0 npm coordinates (it wants package-lock.json and cannot traverse pnpm’s symlinked store), the experimental pnpm-lock parser read 1 dependency of 273, and a package-lock export timed out. The named tool could not satisfy the property the AD was written to guarantee. Its operational tail (an NVD key + cached DB, a JRE on the frontend runners, a wrapper whose own transitive was the only HIGH finding in either frontend) compounded the cost. Resolution took a mid-slice ASK-FIRST pause, a fresh empirical evaluation on the real lockfiles, and a replacement AD (#27, Trivy).

Change made

DC fully reverted (backend included), Trivy adopted uniformly, the NVD_API_KEY secrets deleted, AD #27 recorded with the evaluation in 004-scanner-tool-analysis.md. Enforcement phasing (spec Rev 1) unchanged.

Lesson

An architecture decision that names a specific tool is a hypothesis about that tool’s fit until it is run against the project’s actual artifacts. A tool’s headline capability (“scans Node”) is not the same as “enumerates this project’s dependency graph from this lockfile/store format” — package-manager choice (pnpm vs npm), monorepo layout and lockfile format all break that assumption silently, and the failure looks like a clean scan (zero findings), not an error. Validate the load-bearing capability as early as possible — a five-minute scan on the real lockfile at decision time, not at wiring time — and treat a named-tool AD as provisional until it passes. Corollary for the harness: prefer ADs that name the property required (uniform lockfile-level enumeration + severity gate + governed expiry) over ones that hard-name the tool, so a tool that fails the property is swapped without reversing the decision — which is how AD #27 was framed.

L-017 — A security tool’s own dependency tree and distribution are part of the attack surface it adds

  • Date: 2026-09-01
  • Source commits in this repo: FS-4 finding F-006; the OWASP Dependency-Check → Trivy swap (spec Rev 2, AD #27)
  • Sync target: upstream
  • Synced: pending

Problem observed

The only HIGH finding in either frontend’s locked set was extract-zip@2.0.1 (CVE-2026-56876, CVSS 8.1) — pulled in solely as a transitive of the owasp-dependency-check npm wrapper that had just been added to run the scan. Grype additionally flagged vulnerable jars inside DC’s own downloaded CLI distribution (jackson-databind, httpclient5, jsoup, …), executed on every scan. Removing the scanner removed every frontend finding: post-swap both frontends scan clean.

Change made

The scanner that carried the vulnerability was dropped in favour of a CI-installed pinned binary (Trivy) that appears in no manifest and no lockfile — so the gate adds no npm/Maven supply-chain surface of its own. Recorded as finding F-006 and folded into the AD #27 rationale.

Lesson

When you add a security or scanning tool, its own dependency tree and its downloaded distribution become part of the supply-chain surface you are now exposed to. A self-scan flagging the tool’s own transitive is a real signal, not noise, and “the scanner is the only thing with a finding” is a smell worth weighing against the tool alongside its capability. Prefer a scanner delivered as a pinned standalone binary — no package-manager transitives, absent from your lockfiles — over one that installs into the project’s dependency graph, all else equal.

L-018 — Anchor a lazy-loaded route’s e2e/accessibility waits on content the route renders, never on layout chrome

  • Date: 2026-09-01
  • Source commits in this repo: FS-4 finding F-007; the app-shell a11y specs in forge-et-fe/forge-et-pwa (FS-4 subtask 9, plus the pre-PR-review fix to wait on the route heading by name)
  • Sync target: upstream
  • Synced: pending

Problem observed

The first a11y spec waited for getByRole('main') to be visible before running axe, and axe reported page-has-heading-one on two routes that both do carry an <h1>. The layout’s <main> renders (and is “visible”) while the lazy route chunk inside it is still a RouteSkeleton, so the scan ran against the skeleton, not the page — a document-level violation that reads like a content defect but is a wait-condition bug. Moving the wait to the route’s own heading (getByRole('heading', { level: 1 })) turned the scan green under axe’s full default ruleset. A review follow-up tightened it to wait for the heading by name, because the error and not-found surfaces also render an <h1> and an anonymous wait let a broken route false-green the F-004 closure vehicle.

Change made

Both shipped specs wait for the route’s own heading before scanning, with a comment recording why; per-feature verify-WIs inherit the pattern by copying it. (Kept as a per-app test-authoring rule at finding time; promoted here because it applies to any code-split SPA.)

Lesson

On any SPA that code-splits routes (the common case), a browser/axe assertion must anchor its wait on content the route itself renders, never on layout chrome (<main>, header, nav) that exists before the route chunk arrives — the layout being visible says nothing about the route being loaded, and a scan that races the chunk reports the skeleton. Two corollaries: (1) prefer waiting on route content by name/text, not by role alone, because error/empty/not-found surfaces render the same structural landmarks and an anonymous wait can pass against the wrong screen; (2) treat an accessibility violation whose flagged node is <html> or other document-level chrome, on a page that plainly has the required content, as the signature of scanning too early rather than a real defect.

L-019 — A type-use-only nullability annotation (JSpecify @Nullable) is invisible to the OpenAPI generator, so a nullable field ships as non-nullable

  • Date: 2026-09-03
  • Source commits in this repo: FS-10 finding F-001; the API-conventions slice (forge-et-be#14, DTO exposing listPrice); confirmed by probing /v3/api-docs during the FS-10 pre-PR review; BUG-105 (forge-et-be#206) — the converter written for this lesson never changed the served document, because corollary (1)'s assertion was never written
  • Sync target: upstream
  • Synced: pending

Problem observed

The backend annotates nullability with JSpecify @Nullable, whose @Target is TYPE_USE only — it annotates the type use, not the member/getter. NullAway reads it (as a type-use) and is satisfied, so the build is green. But swagger-core / springdoc build the OpenAPI schema by reflective member introspection, which never sees a type-use annotation — so a nullable listPrice rendered in /v3/api-docs as a required, non-nullable number. No gate caught it: the compiler and NullAway are happy, and the OpenAPI document is not asserted field-by-field. It was found only by a runtime probe of the generated document during the adversarial review, and the wrong schema would otherwise have reached the first frontend code generator run and produced a client type that forbids the null the server actually returns.

Change made

Recorded as a deferred follow-up with a written fix path (add an explicit schema-level nullability annotation on the OpenAPI-visible member — swagger’s own @Schema(nullable = true) or a field-targeted annotation the generator reads — rather than relying on the type-use @Nullable), owed before the first FE generator run. No in-slice code change; the finding is the durable artifact.

Lesson

Nullability that a static-analysis tool enforces is not automatically nullability that a schema/OpenAPI generator sees — the two read different annotation targets. On any Boot 4 + springdoc (or generally any reflect-the-member schema generator) codebase using JSpecify or another TYPE_USE-only @Nullable, an API field’s nullability must be declared with an annotation the generator reads (member-targeted), separately from the one the null-checker reads. Corollaries: (1) the green build is not evidence the OpenAPI contract is right — assert the generated document’s nullability/required set for at least a representative DTO, because nothing else does; (2) treat “the null-checker passes” and “the API schema is correct” as independent claims that each need their own check, especially before a generated client consumes the schema.

Second instance — BUG-105 (2026-10-06). The fix for this lesson, NullableRecordComponentConverter, shipped with no test on the served document and never changed it: for a named model the swagger chain answers only a $ref, so the converter found no properties, and its nullable: true would have been dropped anyway, because the served document is OpenAPI 3.1, which has no nullable keyword. Corollary (1) is the rule that would have caught both: any code that shapes the OpenAPI document is done only when a test reads the served /v3/api-docs and asserts the shape it was written to produce (OpenApiIT’s BUG-105 feature is the pattern). In 3.1, a nullable property is the type set [type, "null"], and a nullable reference is anyOf: [{$ref}, {type: "null"}].

L-020 — A gate that reports what it found but not what it examined cannot tell “clean” from “blind”; assert the examined set is non-empty

  • Date: 2026-09-08
  • Source commits in this repo: FS-3 findings F-009, F-029 and F-008; the design-primitives slice (forge-et-fe#12, forge-et-pwa#13) — the check:boundaries and neutralRender gates and the check-testid-coverage.mjs red-green
  • Sync target: upstream
  • Synced: pending

Problem observed

Three gates in two slices could pass by seeing nothing. dependency-cruiser lost its TypeScript parser (F-009) and reported ✔ no dependency violations found (0 modules cruised) with exit 0 — the advisory about the missing transpiler printed below the pass line, and a single explicitly named file still parsed, so a spot check “confirmed” the tool worked. A static assertion that every var(--et-*) resolves read green because Vitest’s css: false stubs every stylesheet import to an empty string, so the loop over declarations was vacuous (F-029); only a guard added on suspicion — expect(declared.size).toBeGreaterThan(0) — exposed it. And the testid gate’s 28 embedded fixtures all passed an aria-hidden icon button that the gate exists to catch, because the fixtures were written from the same mental model as the code (F-008); the on-tree red-green found it, the self-test never would have. Same family as L-010 (an untested hook’s zero exit means nothing) and L-016 (verify the tool enumerates the ecosystem), arriving a third and fourth time.

Change made

Both dependency-cruiser configs carry the canary in their header — a healthy run reports tens of modules, and 0 modules cruised means the compiler is missing again. The neutral-render check asserts its declaration set is non-empty before iterating. The token-resolution check is carried forward as a file-reading scripts/ gate rather than a stubbed-out test. The red-green proofs for the two new gates were staged by injecting into a real route, not by re-running a fixture.

Lesson

  1. Every gate and static check asserts a lower bound on what it examined and fails on zero. A checkmark over an empty set is the failure mode most likely to be believed, because the output looks identical to a clean run. “No violations found” without a count is not evidence — print the count, and make zero a failure.
  2. Stage the red-green with a case the fixture set does not already cover. Inject into a real tree; self-authored fixtures share the author’s blind spots, so a green self-test proves the fixtures agree with the code, not that the gate sees what it should.
  3. When a gate’s parser, transpiler or stylesheet pipeline is optional or version-gated, the “tool absent” path is the one to probe first — it is where a pass costs nothing.

L-021 — Under an isolated workspace layout an undeclared dependency is not an error: it passes proofs by hoisting or evades path-based boundary rules

  • Date: 2026-09-08
  • Source commits in this repo: FS-3 findings F-004 and F-010; forge-et-fe 9f77ba8 (the test toolchain declared on @et/core-ui) and the .dependency-cruiser.cjs rule shapes in forge-et-fe#12
  • Sync target: upstream
  • Synced: pending

Problem observed

Two directions of the same trap. @et/core-ui gained a Vitest + Testing Library + jsdom toolchain and declared none of it; every test passed because pnpm’s layout still lets Node walk up to the workspace-root node_modules, so the package’s isolation proof (“builds and tests with no app in the graph”) was passing on hoisting rather than on its manifest — true by accident, false the moment the package is installed alone (F-004). In the other direction, the boundary rule matched to.path against ^packages/domain-tea-ui/, assuming a workspace import resolves to the package’s real path. It does when the importing package declares the dependency; otherwise the edge arrives as the bare specifier @et/domain-tea-ui with dependencyTypes: ['unknown'] and matches no path pattern (F-010). The rule covered the tidy violation and missed the careless one — the likelier one, and the one a reviewer is less likely to catch by eye.

Change made

The four test dependencies were declared at the specifiers already in the lockfile. The cruiser rules match both shapes — the resolved workspace path and the bare @et/<pkg> specifier — and the AC-8 red-green was re-run with the undeclared import, which is what exposed the gap.

Lesson

Isolation and boundary claims must be checked against the manifest, never against a green run:

  1. When a subtask adds a toolchain to a package, the toolchain is a dependency of that package. Look at packages/<x>/node_modules — if the runner is not there, the suite is passing on hoisting.
  2. Write import-boundary rules against both the resolved path and the bare specifier. Resolution fails exactly for the undeclared import, and under an isolated layout that is the default, not an edge case.
  3. Red-green each boundary rule with the undeclared import, not only the declared one. A config reviewed on its own reads correct; only the careless case shows the hole.

L-022 — Assert the served app’s identity before recording browser evidence; bind preview ports strictly

  • Date: 2026-09-08
  • Source commits in this repo: FS-3 findings F-015 and F-016; the AC-2/AC-4 browser evidence in the FS-3 plan’s ## Progress (subtasks 4 and 5)
  • Sync target: upstream
  • Synced: pending

Problem observed

Both frontends default vite preview to port 4173. A preview server from the fe evidence run was still listening — stopping the background task killed the pnpm wrapper and returned success while the vite child kept its socket, three orphans by the end of the session — so the pwa’s pnpm preview silently fell back to 4174 (Vite prints the fallback and exits 0). Navigating to 4173 out of habit measured the wrong repo, and every AC-shaped assertion came back green, because the two repos hold byte-identical token, base and font files by design: when two apps are supposed to produce the same numbers, matching numbers prove nothing about which app you measured. What caught it was identity — the page title and a route-chunk name in the request log — not values. Cost if missed: the pwa’s token layer signed off without ever being rendered.

Change made

The evidence steps now assert identity before recording values — byte-comparing the served index.html against the worktree’s own dist/index.html, which content-hashed asset names make specific to one build — and bind the port explicitly with --strictPort so a collision fails the run instead of moving it (note the pnpm trap: pnpm --filter <pkg> preview -- --port N passes the -- through and Vite ignores every flag). Orphans were killed and the values re-measured; nothing recorded had to change, but that was luck about which stale server it was.

Lesson

  1. Identity before values. Any browser-evidence step in a multi-app workspace records what it asserted about the served app (title, a route chunk, served-vs-built index.html) beside the measurements. Copy-identity between apps destroys the cross-check that would otherwise catch the mix-up.
  2. Bind explicitly and make a collision fatal (--port <n> --strictPort); a port that quietly moves is a measurement that quietly lies.
  3. “I stopped the server” is not evidence the port is free — check the listener. The cheap structural fix is a distinct default preview port per frontend repo (a two-repo config change; team call).

L-023 — An acceptance criterion that names a measurement must name the tier that can take it

  • Date: 2026-09-08
  • Source commits in this repo: FS-3 finding F-020 (F-021 is the measurement that followed); the FS-3 plan’s AC-16 row; the plan-reviewer TC-3 check extended in this Reflect
  • Sync target: upstream
  • Synced: pending

Problem observed

The FS-3 plan’s ## Test Approach stated that neither Vitest config applies stylesheets and jsdom performs no layout — and then its Field row asked a jsdom test for “height equal with and without error”, a layout measurement. Both halves were approved. Written literally the test is 0 === 0: every offsetHeight in jsdom is zero, so it passes against the exact regression it exists to catch (a conditionally rendered message node). A green tick with no assertion behind it is worse than an absent test, because it stops anyone looking again. It survived five review passes: TC-2 checks the plan’s tier against the assignment and TC-3 checks every AC has a test row — neither asks whether the row’s assertion is makeable at that tier.

Change made

The AC was split into the two things each provable where they sit: jsdom proves the mechanism (the message node is present in both states, so an error fills a node that already exists), the browser proves the quantity as recorded evidence in the plan’s ## Progress. plan-reviewer TC-3 gains an evidence-reachability sub-check (landed with this Reflect).

Lesson

Coverage is not evidence. For each AC-to-test row ask “can this tier make this assertion?” — an AC naming a pixel value, a duration, a visibility, a network request or a layout relationship needs a tier that performs layout, applies stylesheets or drives a browser. Otherwise the AC silently degrades into whichever assertion the tier can express. Spec and plan authors name the tier in the AC, or split it into a mechanism the unit tier proves and a quantity recorded as browser evidence; reviewers treat an unreachable row as a finding, not a coverage tick.

L-024 — A DOM-only test tier cannot see UA-stylesheet visibility, top-layer inertness, or a headless adapter’s pointer half; every overlay primitive gets one browser pass

  • Date: 2026-09-08
  • Source commits in this repo: FS-3 findings F-022, F-023 and F-025 (F-026 is the same family); design-system Rev 9 (§4 corrected); Tooltip, DropdownMenu, Toast, Modal and Combobox in forge-et-fe#12; BUG-089 (the Combobox’s open list hid the page aria-hidden but focusable, first checked in a browser by F26-b’s size matrix); BUG-121 (a disabled Tooltip still had Focusable check a trigger under the sidebar’s inert rail — jsdom has no inert property, so the warning appeared only in a browser run)
  • Sync target: upstream
  • Synced: pending

Problem observed

Three defects in one component wave, each behind a fully green jsdom suite. Both popover components set display: flex on their own class, which removes the user-agent rule [popover]:not(:popover-open) { display: none } — any author rule beats a UA rule — so both were visible from first paint (F-022); no stylesheet is applied in the test tier, so nothing could see it. A toast raised over an open <dialog> painted above it and was completely inert — showModal() makes everything outside the dialog’s subtree inert regardless of top-layer order — while design-system §4 asserted the opposite mechanism (F-023). A tooltip built on the headless library’s Focusable opened on focus and never on hover, because Focusable composes useFocusable and nothing else; eight jsdom tests passed, and jsdom cannot distinguish “hover doesn’t work” from an environment limit (F-025). The design-system rule was broken in the direction nobody checks — the hard half (keyboard) was handled, so review stopped there.

Change made

display moved behind :popover-open in both components. Design-system §4 was corrected (Rev 9) to state subtree membership, not mount order, as what governs interaction over a modal; the toast-viewport fix waits for its first caller and the limit is documented on Toast. The tooltip’s hover half is hand-wired (controlled isOpen, pointer enter/leave with delays, touch ignored, focus outranking pointer). All three were found, and re-verified, in Chromium.

Lesson

  1. A component whose visibility or interaction is decided by a UA stylesheet or by top-layer/inert semantics is unverifiable in jsdom. Either express its open state as something the DOM tier can see, or budget a browser pass — and do so for <dialog>, [popover], toasts, tooltips and comboboxes as a class, not one at a time when they bite.
  2. Evaluate the adapter you build around a headless library against the rule, not the library’s accessibility reputation. What ships is the component plus the adapter; the coverage gap lived in the adapter.
  3. The browser pass is a tier, not a courtesy. It found three defects after every unit suite was green; a UI foundation slice that skips it has not verified its overlays.

L-025 — TypeScript 7’s npm package exposes no Node compiler API; AST tooling needs an aliased 5.x, not the pin

  • Date: 2026-09-08
  • Source commits in this repo: FS-3 findings F-007 and F-009; typescript-classic@npm:typescript@5.9.3 and the pnpm packageExtensions entry in both frontends (forge-et-fe#12, forge-et-pwa#13)
  • Sync target: project-only
  • Synced: pending

Problem observed

Both frontends pin typescript: ^7.0.2 (the native port). Its exports map sends the main entry to ./lib/version.cjs, which exports version and versionMajorMinor and nothing else — createSourceFile and forEachChild are undefined via default, named and namespace import alike, and the compiler API exists only behind ./unstable/* subpaths, none of which offers a text-to-SourceFile entry point. The testid gate’s planned parser (Decision 9, flagged unverified) therefore did not exist, and one subtask later dependency-cruiser — which version-gates typescript at <7.0.0 — silently dropped every .ts/.tsx from its scan (see L-020).

Change made

typescript-classic@npm:typescript@5.9.3 as a devDependency in both repos, imported by name in the AST script; a pnpm packageExtensions entry hands dependency-cruiser the same 5.9.3 inside its own store. The ^7.0.2 pin is untouched — bare typescript still resolves to 7.0.2, so pnpm typecheck and the Fast lane are unchanged. Both repos carry the byte-identical script, so a fix lands in fe and is re-copied.

Lesson

Any tooling in these repos that needs the TypeScript compiler API — a permission-catalog check, a token-usage scan, a testid gate — imports typescript-classic, never the pin; anything that require('typescript')s internally needs the packageExtensions treatment and a canary that it parsed something. The alias is a bridge with an expiry: when TypeScript 7 stabilises a parse entry point, move the scripts onto it and remove the alias. And a plan-time toolchain assumption flagged “unverified” is probed before the subtask that depends on it starts, not discovered inside it.

L-026 — A PR that conflicts with main runs no pull_request CI; “no checks reported” means check the merge state first

  • Date: 2026-09-08
  • Source commits in this repo: the FS-3 plan’s ## Progress subtask-15 record (the corrected diagnosis); forge-et-fe#12 (merge commit 47507a6) and forge-et-harness#51; the forge-pr-open post-open check landed with this Reflect
  • Sync target: upstream
  • Synced: pending

Problem observed

Two of the three FS-3 PRs showed zero workflow runs after opening. The first diagnosis reached for the platform — an Actions delay, or an org-level minutes limit needing admin:org — and was wrong. Both PRs conflicted with main (fe on pnpm-lock.yaml from a Dependabot group bump; the harness 43 commits behind), and a pull_request workflow runs against GitHub’s merge ref, which a conflicting PR does not have — so no run is creatable, which is why opened, edited, synchronize and reopened all failed identically and why the one mergeable sibling PR ran normally. The root cause was upstream of CI: git-conventions.md already says to bring the branch current before opening the final PR, and the pre-PR run verified the code was green but never checked that the branch was.

Change made

origin/main was merged into the fe branch — merged rather than rebased, because a pushed branch with an open PR must not be rewritten — with the lockfile regenerated rather than hand-merged; the harness PR the same way. forge-pr-open step 6 now reads mergeable/mergeStateStatus immediately after gh pr create.

Lesson

  1. Before opening, bring the branch current with main and say so in the PR body; the pre-PR review’s “green” is about the code, not its base.
  2. After opening, read gh pr view <n> --json mergeable,mergeStateStatus before reading CI silence. CONFLICTING means no CI is possible, not that CI is slow.
  3. Resolve by merging main in, never by rewriting a pushed branch with an open PR, and regenerate lockfiles rather than hand-merge them.
  4. When one of several sibling PRs runs and the others do not, the difference between them is the diagnosis — look there before looking at the platform.

L-027 — The rule of two applies to architecture, not just helpers: speculative structure for a hypothetical consumer is a tax paid until someone removes it

  • Date: 2026-09-10
  • Source commits in this repo: FS-14 finding F-006 (.forge/specs/foundation/014-single-module-findings.md); the FS-14 code PRs (forge-et-be#16, forge-et-fe#14, forge-et-pwa#15) and the harness cascade; AD #17 (adopt) → AD #29 (stop) → AD #31 (collapse) in .claude/CLAUDE.md
  • Sync target: upstream
  • Synced: pending

Problem observed

Over FS-1/FS-2 the engagement built a genuinely separable generic-CRM layer — a two-tree module split (16 backend modules, 3 frontend packages), ten named extension points, two Postgres schemas with a partitioned Flyway version space, and four enforcement guards — so that the generic half could be reused on a future project. That reuse was never confirmed: it rested on OQ-50, a §Constraints / commercial open question marked “assumed yes” on advice, with no client answer. When the reuse stopped being expected (AD #29) and then the structure was removed outright (AD #31 / FS-14), the bill came due: 13 of 16 backend modules and 2 of 3 frontend packages were near-empty shells, the real code (~11k lines a side) simply moved between trees rather than depending on the split, and the collapse cost ~4 working days plus a full harness cascade. In the meantime every feature had paid a per-change tax — a Layer Classification per spec, a module and a version band per change, 16 lockfiles, out-of-order Flyway (L-014), and guards with no live purpose.

Change made

FS-14 collapsed the split to one Gradle module with feature-first packages, one public schema, one squashed migration sequence, and one frontend package — keeping every hygiene guard (layering, @NullMarked, fixture reachability) and adding a feature-cycle rule, while retiring every guard whose only job was to police the speculative boundary. The ## Layer Classification spec-template section was removed; coding-standards.md §1 now says put code in the package of the capability it serves; a shared abstraction waits for a second real consumer.

Lesson

The rule of two is an architecture rule, not just a helper-extraction rule. A module boundary, an extra schema, an extension point or a published-artifact seam built for a second consumer that does not yet exist is speculative structure, and it taxes every feature that crosses it until someone pays to remove it. The tell is cheap to spot early: a load-bearing “assumed yes” on a premise nobody outside the team has confirmed (here, a commercial reuse right). When the justification for structure is a hypothetical rather than a present, second, real consumer, build the tidy monolith and keep the option to extract later — AI-assisted extraction handles a clean feature-first tree well — rather than paying up front for a reuse that may never arrive. Record the premise as an open question with a named owner and a settle-by point, and revisit the structure the moment the premise weakens.

Verification

FS-14’s Appendix C gave all 111 FS-1/2/3/4/10 acceptance criteria a disposition (9 retired as split-only, the rest preserved), so nothing the split had established was lost by accident; the code PRs proved the substance moved rather than rewrote (byte-for-byte git mv commits separated from edits), and the test suites stayed green on both sides of the collapse.

L-028 — On Spring Boot 4 a third-party integration wires nothing without its spring-boot-<tech> module, and the gap is silent — prove auto-config on a real boot, not from the dependency’s name

  • Date: 2026-09-12
  • Source commits in this repo: FS-5 plan ## Progress → Failed Approaches finding 1 (.forge/plans/foundation/005-observability-stubs-plan.md); FS-5 harness PR #73 (spec Rev 2 + coding-standards §8.2 correction) and this Reflect PR (coding-standards §2.4 cross-reference; this entry); forge-et-be#17 (the two-artifact build.gradle)
  • Sync target: upstream
  • Synced: pending

Problem observed

FS-5 wired request-thread tracing by adding io.micrometer:micrometer-tracing-bridge-brave — the artifact named by the slice’s spec (FR-T1), its plan (Decision 1), and coding-standards §8.2, all of which described the binding as “the whole job: it auto-configures the span filter and populates the MDC.” On Spring Boot 4.1.1 the binding alone auto-configures nothing: a real request to an unmapped route served an error envelope with no traceId and the console carried no correlation bracket — the app booted and traced nothing. Boot 4 is modular (§2.4): the tracing auto-configuration (the Tracer bean, the observation→tracing handler, the brave→slf4j MDC correlation) lives in Boot’s own module org.springframework.boot:spring-boot-micrometer-tracing-brave, which spring-boot-starter-actuator does not pull and whose POM does not pull the binding. The assumption had been carried forward from Boot 3, where the binding self-wired, and it survived a spec, a plan, and a two-pass plan review unchallenged — because every one of those reasoned from the dependency’s name rather than from a running JVM. This is the same silent boots-but-does-nothing failure the build already hit with spring-boot-flyway beside flyway-core (the app booted but never migrated) and spring-boot-data-jpa-test.

Change made

Declared both artifacts runtimeOnly — the Brave binding plus Boot’s auto-config module — locked in gradle.lockfile. With both present, request threads are auto-instrumented, the MDC carries traceId/spanId, and the FS-10 error envelope carries a real trace id equal to the ERROR log line’s (AC-3 end-to-end). The engagement’s coding-standards §8.2 was corrected to name the modular pair (no longer “the dependency is the whole job”), the FS-5 spec’s FR-T1 took Rev 2, and §2.4 — which already carried the general “add Boot’s per-technology module, not a bare library” rule with two prior cases — gains the micrometer-tracing case as a third instance pointing at this lesson.

Lesson

On Spring Boot 4 / Framework 7, adding a third-party integration library (or a Micrometer binding) does not wire it: the umbrella spring-boot-autoconfigure / -test-autoconfigure no longer carry per-technology auto-config, so each technology needs its Boot module spring-boot-<tech> (and -<tech>-test for the test slice) alongside the raw library. The failure mode is the worst kind — the app boots green and the feature is silently absent (no bean, no error, no log), so a name-level check (“the dependency is on the classpath”) passes while the behaviour is missing. Two rules follow: (1) when adding any integration on Boot 4, add Boot’s module for it, not just the library — treat the raw library on its own as insufficient by default; and (2) prove the wiring on a real boot (a bootRun or a booted integration test asserting the observable effect — here, a traceId on a real response and its log line), never from the dependency’s name or from Boot-3 memory. A spec, a plan, and even a multi-pass review can repeat a Boot-3 assumption in lockstep, because none of them runs the JVM; only a real boot disproves it.

Verification

Measured on Boot 4.1.1: with the binding alone, a real request to an unmapped route returned an RFC-9457 envelope with no traceId member and a console line with no [traceId-spanId] correlation bracket; with both artifacts present, TracePropagationIT (AC-2/AC-3) is green — two lines in one request share one non-empty traceId, and a 500 envelope’s traceId equals the ERROR line’s MDC value — and the full ./gradlew check is green (326 tests, 0 failures). forge-et-be#17 ships the two-artifact build.gradle.

L-029 — An AWS SDK v2 / Spring Cloud AWS starter builds its client eagerly at context load and fails without a configured region, taking down every test context

  • Date: 2026-09-12
  • Source commits in this repo: FS-7 finding F-001 (.forge/specs/foundation/007-background-jobs-findings.md) + FS-7 plan ## Progress (subtask 1 record); forge-et-be 9634183 (the region pin, folded into the SQS-dependency commit); this Reflect PR
  • Sync target: upstream
  • Synced: pending

Problem observed

FS-7 added io.awspring.cloud:spring-cloud-aws-starter-sqs to put SQS on the classpath. Spring Cloud AWS eagerly constructs its SqsAsyncClient at context refresh, and an AWS SDK v2 client resolves its region at build time from the default provider chain (env var → profile → instance metadata). On a dev laptop and on CI there is no AWS_REGION, no profile, and no instance metadata, so the resolution throws — and because the client bean is built during context load, the failure is IllegalStateException: Unable to load region from any of the providers and it takes down every @SpringBootTest, not just the ones exercising SQS. The slice’s own messaging integration tests set spring.cloud.aws.* via @DynamicPropertySource, so they were fine; it was the unrelated existing context specs (data layer, API conventions) that went red the moment the starter landed, which is what made the cause non-obvious — the failing tests had nothing to do with the change.

Fixed by pinning spring.cloud.aws.region.static=us-east-1 (AD-O-9) in the always-loaded application.yml base, so the eager client build resolves a region in every profile and context. The real region in cloud is supplied the same way per environment; LocalStack test contexts override the endpoint but inherit the static region.

Change made

spring.cloud.aws.region.static=us-east-1 added to the base application.yml, committed alongside the dependency add (forge-et-be 9634183) so the starter never lands without its region. Recorded as FS-7 finding F-001 and promoted here.

Lesson

Treat “configure a static region” as an inseparable part of adding the first AWS SDK v2 / Spring Cloud AWS starter — put it in the always-loaded base config in the same change as the dependency, not when the first client is actually used. Two properties of this trap make it worth a lesson rather than a one-off fix:

  1. The client is built eagerly at context load, so region resolution failure is a startup failure, not a call-time failure. The blast radius is every Spring context in the suite — including tests that never touch the new service — so the symptom (a pile of unrelated @SpringBootTest failures) points away from the change that caused it.
  2. The provider chain resolves against the environment, which on a laptop/CI is empty by design. “It works when I deploy” is not evidence — an EC2/ECS task has instance metadata that a build agent does not.

Same family as [[L-028]] — a dependency does more, or other, than its name suggests, and the gap is silent until a real boot — but the failure mode is the mirror image: L-028 is a library that wires nothing without Boot’s module (boots green, feature absent); this is a starter that wires a client eagerly and fails the whole context without a region. Both are caught only by booting the JVM, never by checking that the coordinate is on the classpath.

Verification

Measured on forge-et-be: with the SQS starter added and no static region, the existing context specs fail at load with “Unable to load region from any of the providers”; with spring.cloud.aws.region.static=us-east-1 in the base application.yml, ./gradlew check is green (all pre-existing specs plus the five FS-7 LocalStack integration tests), and the AC-8 bootRun smoke on the local profile starts with no AWS account present.

L-030 — An integration-test suite’s context cache × per-context connection pool crosses the database’s connection ceiling as it grows, failing unrelated tests

  • Date: 2026-09-12
  • Source commits in this repo: FS-9 finding F-001 (.forge/specs/foundation/009-scheduler-substrate-findings.md) + FS-9 plan ## Progress → ### Failed Approaches; forge-et-be SharedPostgresSpec max_connections=300 (in forge-et-be#19); this Reflect PR; BUG-088 (F38-j finding F-001, forge-et-be#181)
  • Sync target: upstream
  • Synced: pending

Problem observed

FS-9 added three LocalStack integration tests. ./gradlew check went red — but not in the new tests. Unrelated data-layer specs, which FS-9 never touched, failed with FATAL: sorry, too many clients already. The cause is a global resource exhausted by a sum: each integration test whose @DynamicPropertySource (or @TestPropertySource / @MockBean / any context-differentiating config) produces a distinct context is a separate entry in Spring’s ContextCache, and each cached context holds its own connection pool (Hikari default 10) open for the JVM’s lifetime. The pools are never returned while the cache holds the contexts, so the suite’s peak connection demand is number of distinct contexts × pool size, not the demand of any one test. The suite was already near Postgres’s default max_connections=100; three more contexts pushed the total over, and the failure landed on whichever specs refreshed last — which is why the red tests had nothing to do with the change that caused it.

First tried collapsing the three new ITs onto one shared context (one queue triple) — that reclaimed two contexts but still tipped a razor-thin margin, flaking even a pre-existing IT. The fix that held was to stop fighting the margin: raise the shared test container to max_connections=300 (SharedPostgresSpec.withCommand('postgres', '-c', 'max_connections=300')). Production runs one context and one pool and is untouched.

Change made

forge-et-be’s shared Testcontainers Postgres base spec was given max_connections=300 headroom, committed with the FS-9 ITs. Recorded as FS-9 finding F-001 and promoted here.

Lesson

Budget for the whole suite’s context cache, not for one test. Two properties make this worth a lesson rather than a one-off:

  1. The blast radius is every context, so the symptom points away from the cause. A suite that adds contexts fails tests that add none — the last ones to refresh — so the red output names the victim, not the culprit. When a data-layer/connection error appears in specs a change didn’t touch, count contexts × pool size against the DB ceiling before hunting a leak in the failing spec.
  2. Two fixes, and they scale differently. Raising the container’s max_connections is the pragmatic one — it buys a fixed headroom that the next few contexts eat again, so the ceiling is re-approached slice by slice. The durable one caps the demand instead of the supply: set the test-profile pool small (Hikari maximum-pool-size: 2–5 — an IT rarely needs 10 concurrent connections) so headroom scales per context, and/or bound spring.test.context.cache.maxSize so old contexts (and their pools) are evicted. Prefer capping the pool for a suite expected to keep growing; the max_connections bump is the right pragmatic move when the headroom is genuinely one-off, as long as it is confirmed to be headroom and not a leak being masked.

Same family as [[L-028]] and [[L-029]] — a per-context resource behaves differently in aggregate than its name suggests, and the failure only appears once the whole JVM suite boots, never from reading one test.

Verification

Measured on forge-et-be: with the three FS-9 ITs added and the container at the default max_connections=100, ./gradlew check failed unrelated context specs with FATAL: sorry, too many clients already; isolated single-IT runs passed (one or few contexts, under the ceiling). With SharedPostgresSpec at max_connections=300, the full ./gradlew check is green. The per-context arithmetic (distinct @DynamicPropertySource ⇒ distinct cached context ⇒ +1 pool) was confirmed by the collapse experiment: merging three ITs to one shared triple reclaimed contexts and moved the margin, proving the count — not any single test — was the variable.

Recurrence — 2026-10-04 (F38-j finding F-001)

The ceiling was re-approached as point 2 predicted: the full suite peaked at about 293 of the 300 connections (sampled from pg_stat_activity during ./gradlew build on forge-et-be 3621c8c), and one more cached context failed ten unrelated pricing, tag and timeline specs with FATAL: sorry, too many clients already. F38-j worked around it with @DirtiesContext on its own new IT, and BUG-088 (forge-et-be#181) then made the durable fix point 2 recommends: every pool in the test JVM is capped at 5 through a test-only Hikari properties file, so a full 32-context cache holds at most 160 connections, and TestPoolBudgetIT fails the build if the pool size, the cache size or the container’s limit changes so that the budget no longer fits.

L-031 — A regex/annotation code guard must match every spelling the compiler accepts, or it is silently bypassable

  • Date: 2026-09-12
  • Source commits in this repo: FS-9 finding F-002 (.forge/specs/foundation/009-scheduler-substrate-findings.md); forge-et-be 6d2ba0d (regex broadened + bypass fixtures added); this Reflect PR
  • Sync target: upstream
  • Synced: pending

Problem observed

FS-9 shipped scripts/check-no-scheduled.py, the standing Fast-lane guard that is the teeth behind AC-6 / AD #12 (no in-process @Scheduled). Its first regex anchored only the bare @Scheduled token. The Java compiler, however, accepts several spellings of the same annotation identically:

  • fully qualified — @org.springframework.scheduling.annotation.Scheduled
  • whitespaced — @ Scheduled (and @\tScheduled)

All of these compile to the exact annotation the guard exists to forbid, and all of them slipped the first regex. The pre-PR review caught it as an Important (I-1). A guard that misses forms the compiler honours is not a guard — it is a comment asserting a guard exists, the precise failure mode of [[L-010]] (an untested guard’s green means nothing) and of FS-1’s phantom guard (a check behind a comment claiming it ran).

Fixed by broadening the pattern to @\s*(?:\w+\.)*Scheduled\b — matching an optional whitespace run, an optional dotted qualifier chain, and a word boundary so @ScheduledFuture and @EnableScheduling are still correctly not matched — and, crucially, by adding the FQN and whitespace forms as bypass fixtures to --self-test, so a future edit that re-narrows the pattern fails its own self-test instead of shipping a hole.

Change made

check-no-scheduled.py’s scan regex broadened to catch the FQN and whitespaced spellings; its --self-test fixture set extended with a positive FQN case and a positive whitespace case (alongside the negative @EnableScheduling/@ScheduledFuture cases). Recorded as FS-9 finding F-002 and promoted here.

Lesson

When a guard scans source text for a language construct, enumerate the construct’s legal spellings and make each a self-test fixture — the bypass forms, not just the happy path. An annotation can be bare or fully qualified or nested-qualified, with arbitrary whitespace after the @; an import can be direct, wildcard, or fully-qualified-at-use; a call can be static-imported or qualified. A regex guard that pins one spelling gives false assurance — worse than no guard, because the reviewer sees a green check and stops looking. The self-test is where this is made durable: a fixture for each bypass form converts “someone might narrow the regex later” from a silent risk into a failing test. This is the teeth-with-teeth companion to [[L-010]]: L-010 says exercise the guard with the input it filters on; this says that input set must include every spelling the compiler will accept.

Verification

Measured on forge-et-be: against the first regex, a fixture containing @org.springframework.scheduling.annotation.Scheduled and one containing @ Scheduled both passed the guard (not flagged) — the bypass. Against the broadened regex, python3 scripts/check-no-scheduled.py --self-test flags both while still leaving @EnableScheduling and @ScheduledFuture unflagged, and the live scan of src/main/java/com/empireteas/** is clean. The self-test now fails if the FQN or whitespace form is ever un-caught again.

L-032 — An authorization predicate evaluated only at login means “revoke access” silently means “and then wait”

  • Date: 2026-09-15
  • Source commits in this repo: FS-6 finding F-002 (.forge/specs/foundation/006-auth-scaffolding-findings.md); forge-et-be b1c87a1 (predicate moved into the resolver + SecurityChainIT revocation row); this Reflect PR
  • Sync target: upstream
  • Synced: pending

Problem observed

FS-6 checks is_active on both login paths — the stub’s findActiveByEmail and IdentityResolver’s .filter(AppUser::isActive) — and nowhere else. Sessions run eight hours. So an account deactivated at 09:00 kept every permission its role confers until 17:00, and the Administrator who had just deactivated it had no way to know.

The sharp part is that the codebase had already reasoned its way to the right principle and then missed the one line that implements it. AuthenticatedUser’s javadoc argues against caching resolved permissions on the principal, in as many words, so that revoking access does not mean “and then wait for their session to expire” — and the resolver it points at re-read the grants on every check, faithfully, while never asking whether the user was still active.

548 tests passed. Every one of them asked “can this user do X?” at a single instant. None asked what happens to a signed-in user after a state change — which is a different question, and the only one that could have caught this.

Change made

The active predicate moved into EffectivePermissionResolver.resolve, which every check runs through, so the answer is recomputed per check rather than trusted from the door. SecurityChainIT gained a row that signs in, deactivates the user out of band, and asserts the next request is refused.

Lesson

A property that gates entry must be re-evaluated on every use, not just at entry — or the gate describes the past. Login, token issue and session creation are all instants; authorization is a duration. Any predicate consulted only at the instant (is the account active, is the subscription current, is the device still trusted) silently acquires the session’s TTL as its revocation latency, and no point-in-time test will show it.

Two practical consequences:

  • Test the transition, not only the state. For anything with a session, at least one test should change the underlying state while signed in and assert the next request. “User A can’t do X” and “user A could do X and now can’t” are different assertions, and suites accumulate only the first.
  • Suspect the claim, not the intent, when a design argues against caching. A comment explaining why permissions are resolved fresh is evidence the author understood the requirement — and is not evidence the requirement is met. Related: [[L-010]] — an untested guard’s green means nothing.

L-033 — Proxy-aware URL generation fails only in deployment, and Spring Framework 6 removed the silent fallback

  • Date: 2026-09-15
  • Source commits in this repo: FS-6 finding F-003 (.forge/specs/foundation/006-auth-scaffolding-findings.md); forge-et-be b1c87a1 (server.forward-headers-strategy: framework); this Reflect PR
  • Sync target: upstream
  • Synced: pending

Problem observed

FS-6 built the Entra login leg with the conventional redirect-uri template, {baseUrl}/login/oauth2/code/{registrationId}. server.forward-headers-strategy was set nowhere.

Behind the ALB, TLS terminates at the load balancer and the ECS task receives plain HTTP on a private IP. Spring Framework 6 removed forwarded-header handling from UriComponentsBuilder, leaving ForwardedHeaderFilter — i.e. that one property — as the only mechanism. So {baseUrl} would have expanded to http://10.x.y.z:8080, the redirect_uri sent to Entra would not have matched the registered reply URL, and every cloud sign-in would have failed with AADSTS50011. The same unset property also made CookieCsrfTokenRepository fall back to request.isSecure() — false behind the proxy — so the CSRF cookie would have shipped without Secure.

No test in the slice could have caught either. @SpringBootTest(RANDOM_PORT) is a direct connection on which {baseUrl} is already correct: the test environment is missing the very component that breaks it. It was found by an adversarial review reasoning about the deployment topology, not by running anything.

Change made

server.forward-headers-strategy: framework added to the base application.yml as a universal-safe value — with no proxy in front the X-Forwarded-* headers are absent and the filter is a no-op — with the reasoning written at the line.

Lesson

Anything the application generates from “where am I?” — absolute URLs, redirect URIs, cookie Secure, links in outbound mail — is untestable in any environment that lacks the proxy, and is therefore review’s job rather than the suite’s. Add it to the standing list of fails-only-in-deployment classes (AD-O-11): a green suite is not evidence about it, in either direction.

Two specifics worth carrying:

  • Set server.forward-headers-strategy in the base configuration of any app that will sit behind a load balancer, not per-environment. It is a no-op without a proxy, so there is no reason to defer it to the environment that needs it — which is exactly the environment where discovering it is expensive.
  • A framework that removes a convenience leaves no compile error behind. Framework 6’s dropping of forwarded-header support from UriComponentsBuilder is invisible to the compiler and to every local run; it surfaces as a runtime mismatch in one environment. Treat “this used to be handled for us” as a migration checklist item, not an assumption.

L-034 — A test HTTP client that follows redirects leaves the application under test

  • Date: 2026-09-15
  • Source commits in this repo: FS-6 finding F-004 (.forge/specs/foundation/006-auth-scaffolding-findings.md); forge-et-be 7864ec7 (EntraLoginIT driven by a non-following client); this Reflect PR
  • Sync target: upstream
  • Synced: pending

Problem observed

EntraLoginIT drives the OAuth2 round-trip with RestTestClient, the repo’s standard integration client. The authorize leg answers 302 to login.microsoftonline.com, and RestTestClient follows redirects — so the test client left the application entirely and made a real network call to Microsoft with a fake tenant id. It also discarded the Location header, which carries the state the callback leg needs.

The symptom was six rows failing on a missing session cookie, which points nowhere near the cause and reads like a session-configuration bug. The suite was also silently dependent on outbound internet access, in a repo whose test strategy is explicitly offline (NFR-1).

Change made

The two redirect legs moved to a JDK HttpClient built with Redirect.NEVER, with the reasoning at the method. The rest of the spec still uses RestTestClient.

Lesson

When the redirect is the behaviour under test, the client must not follow it. Any flow defined by its 3xx hops — OAuth2/OIDC, SAML, form-login success and failure handlers, logout, post-redirect-get — needs a client configured not to follow, or the assertions are made against whatever the last hop returned, possibly from a different origin.

Two things make this worth a lesson rather than a one-line fix:

  • The failure is off-target. A following client turns “my redirect was wrong” into “my cookie is missing”, so the debugging starts in the wrong subsystem.
  • It can quietly reach the internet. A redirect to a real external host in a test that was supposed to be hermetic is a dependency nobody declared, and it will pass on a developer’s machine and fail on an offline runner — or worse, pass on both while measuring nothing.

Check the redirect policy of any test client before asserting on a flow that redirects; it is rarely the default you want.

L-035 — A shared test profile accumulates meanings, so activating it broadly wakes every subsystem scoped to it

  • Date: 2026-09-15
  • Source commits in this repo: FS-6 finding F-006 (.forge/specs/foundation/006-auth-scaffolding-findings.md); forge-et-be 28d0e0a (demo messaging made presence-activated; stub beans made servlet-only); this Reflect PR
  • Sync target: upstream
  • Synced: pending

Problem observed

Coding-standards §5 scopes development stand-ins to the local/test profile pair. Two slices did so independently and correctly:

  • FS-7 scoped its demo SQS listener and queue provisioner to local/test, and supplied LocalStack plus the queue names alongside them in MessagingContextSpec.
  • FS-6 scoped its stub login to the same pair, per the same rule.

Each is right on its own. Together, “the test profile is active” had quietly come to mean two things — and nothing anywhere recorded that. The moment FS-6 activated test on the shared base spec (which LoginSupport requires, because the stub is profile-scoped), FS-7’s beans woke up in every context and each failed to start on an unresolved ${et.messaging.demo-queue} placeholder. A second instance of the same shape followed immediately: profile-scoped beans that inject filter-chain beans also need @ConditionalOnWebApplication(SERVLET), because a WebEnvironment.NONE context activates the profile too and has no chain.

The plan had asserted “no spec activated a profile before this slice”, which was true when written and false by implementation time — so the collision was discovered by a failing suite rather than at planning.

Change made

FS-7’s demo pair became presence-activated — @ConditionalOnProperty on the listener, a skip-with-INFO in the provisioner — which is the rule FS-7 had already chosen for its own scheduler queue. The profile now means “dev affordances are available”; each subsystem additionally requires its own configuration to actually stand up.

Lesson

A profile is a namespace that every slice writes into, so treat “activate the profile” as a cross-slice change, not a local one. By the third or fourth slice, a test or local profile means the union of everything ever scoped to it, and the union is written down nowhere.

The durable fix is to make profile membership necessary but not sufficient:

  • Gate a subsystem on its own configuration, not on the profile alone. @Profile says may run here; @ConditionalOnProperty on the config it needs says is wanted here. A bean requiring both cannot be woken by an unrelated slice.
  • A bean that injects an infrastructure bean needs that infrastructure’s condition too, not just the profile — a non-web context activates profiles exactly as a web one does.
  • Before activating a profile on a shared base spec, grep for everything already scoped to it. The blast radius is every context in the suite, and the failure arrives as unrelated contexts refusing to start.

L-036 — In an enforcement primitive, abstaining fails open, so “I don’t know” must mean “no”

  • Date: 2026-09-15
  • Source commits in this repo: FS-6 finding F-009 (.forge/specs/foundation/006-auth-scaffolding-findings.md); forge-et-be b1c87a1 (RequiresPermissionAuthorizationManager denies and logs); this Reflect PR
  • Sync target: upstream
  • Synced: pending

Problem observed

RequiresPermissionAuthorizationManager returned null — Spring Security’s abstain — when it could not find the @RequiresPermission annotation the pointcut had matched. The interceptor treats abstain as “no opinion”, and with no other authorization manager configured that means the method runs.

The reasoning written at the line was sound for the tree as it stood: the pointcut and the lookup read the same annotation, so the branch is unreachable. But this is the one class where unreachable today and safe are different properties. Any later divergence — an annotation on an interface method, a JDK proxy in the chain, a change in AnnotatedElementUtils find-semantics — turns that branch into a silent grant on a method somebody annotated precisely because it needed a gate, with no log line, no exception and no test that would notice.

Change made

Changed to new AuthorizationDecision(false) plus a log.error naming the method. The branch remains unreachable in normal operation — which is exactly what makes a denial there costless.

Lesson

Where a component’s job is to permit or refuse, its “cannot determine” branch must refuse. The generalisation beyond Spring Security: any three-valued gate (allow / deny / abstain, or true / false / null) placed in an enforcement path collapses to allow-by-default unless something else is guaranteed to decide — and “something else decides” is a property of the configuration, not of the class, so it is not a property the class can rely on.

Two tests to apply:

  • Ask what happens if this returns its neutral value. If the answer is “the operation proceeds”, the neutral value is a grant wearing a neutral name.
  • Prefer a denial that is provably unreachable to an abstention that is merely currently harmless. A deny branch guarded by an invariant costs nothing while the invariant holds, and holds the line when it stops. Log loudly there: reaching it is a wiring fault, not a permission decision, and it should be diagnosable as one.

L-037 — A test fixture that is itself a detection signature must be encoded at rest, or the developer’s machine deletes it before the build reads it

  • Date: 2026-09-15
  • Source commits in this repo: FS-11 finding F-001 (.forge/specs/foundation/011-file-pipeline-findings.md); forge-et-be 7df9566 (LocalFileScanProvider.EICAR_BASE64); this Reflect PR
  • Sync target: upstream
  • Synced: pending

Problem observed

The local scan stand-in needed one input it would call infected, and the spec named the industry’s answer: the EICAR anti-malware test file. Spelled out as a string literal, that 68-character string would have sat in a .java source, a compiled .class, a Groovy spec and the shell transcript — and the contiguous string is the signature every desktop anti-malware engine matches. On a Windows developer machine Defender quarantines the source before Gradle compiles it, and the symptom is a file that vanished, not a test that failed. Two of the three developers are on Windows.

Change made

The signature is carried base64-encoded in one public constant with the reason at the line, and decoded at runtime; the bytes exist only in memory and inside the LocalStack container the tests upload to. The base64 form was computed from two halves on the command line so the contiguous string never touched the shell transcript either. The classifier is a substring search, so the decoded bytes are still recognised inside a larger file — which is also what lets a spec bury them after a PDF header and reach the INFECTED path.

Lesson

Any fixture that is the thing a detector detects — an anti-malware test string, a canary credential pattern, a known-bad hash, a leaked-key sample — is encoded at rest and decoded at the point of use, with the reason written at the constant. The failure mode is not a red test; it is a source file that is silently gone on one developer’s machine and present on another’s, which reads as “works on mine”. Corollary for the transcript: build such a string from parts on a command line rather than pasting it whole, because the session log is a file too.

L-038 — A startup guard placed before bean creation pre-empts every later startup failure, so the specs that assert those failures must satisfy the guard explicitly

  • Date: 2026-09-15
  • Source commits in this repo: FS-11 finding F-004 (.forge/specs/foundation/011-file-pipeline-findings.md); forge-et-be 7df9566 (SeamGuard), df78d37 (CloudSeamFakes); this Reflect PR
  • Sync target: upstream
  • Synced: pending

Problem observed

The file pipeline’s fail-closed guard is a BeanFactoryPostProcessor: it inspects bean definitions and refuses a cloud-shape context with no real scanner or visibility resolution behind the seams, before Flyway migrates, before Hikari dials, before any AWS client is built. That is the right order for a deploy — the operator sees the missing seam, not a datasource error that happened to fire first. It is the wrong order for every existing spec whose subject is a later startup failure: eight EtPropertiesSpec rows, both CloudShapeIT halves and GrantConsistencyStartupIT boot the no-profile shape to assert that a missing key, an absent Entra block or a stale grant is what fails. The moment the guard existed, every one of them failed naming the guard instead.

Change made

A test-only CloudSeamFakes — a plain class with two @Bean methods and no stereotype annotation, so the component scan never picks it up and it cannot collide with the test profile’s real stand-ins — registered explicitly by exactly the specs whose subject is a later failure. The spec that proves the guard registers nothing. The operational corollary is written at the guard: until the cloud half lands, a cloud deploy with any other misconfiguration reports the missing seam first.

Lesson

Fail-fast guards stack in startup order, and the earliest one wins every failure. Adding a guard that runs before bean creation changes what every later-failing spec observes, in a different package, with a message that looks like the new guard is broken. When adding one: (1) enumerate the specs that assert a startup failure in the same shape (grep for the marker of a complete argument set — here login-redirect-uri), (2) give them a way to satisfy the new guard that the production scan cannot see, and (3) write down which failure a real operator will now see first. The same pattern applies to any early hook — a BeanFactoryPostProcessor, an ApplicationContextInitializer, an environment post-processor — and to any framework, not only Spring.

L-039 — LocalStack accepts any S3 signature by default, so a presigned-URL narrowness test is vacuous until validation is switched on

  • Date: 2026-09-15
  • Source commits in this repo: FS-11 finding F-005 (.forge/specs/foundation/011-file-pipeline-findings.md); forge-et-be e399bd0 (SharedLocalStack, S3_SKIP_SIGNATURE_VALIDATION=0); this Reflect PR
  • Sync target: upstream
  • Synced: pending

Problem observed

AC-7 required the issued download URL to be read-only and scoped to one object. The wire rows were written as a PUT carrying the GET signature and a GET on a sibling key, both expected 403. On the first run the PUT answered 200 and overwrote the object: LocalStack’s S3_SKIP_SIGNATURE_VALIDATION defaults to 1, so any signature — or none — is accepted. Had the rows been written as “the URL contains X-Amz-Signature” they would have passed and proved nothing; written as behaviour, they caught the emulator. The plan had already named the account-level public-access block as the one S3 property LocalStack cannot enforce; signature validation was a second, and unlike the first it is switchable.

Change made

The shared container runs with S3_SKIP_SIGNATURE_VALIDATION=0. LocalStack then checks SigV4 the way S3 does: the GET-signed PUT and the sibling key both answer 403, and the application’s own properly signed requests are unaffected. The public-access half of AC-7 stays with the cloud half, stated in the spec’s Cannot prove block rather than silently skipped.

Lesson

An emulator’s defaults are tuned for convenience, not fidelity; before a test asserts a security property against one, find the flag that makes the emulator enforce it — and if there is none, the property is unprovable offline and the AC must say so. The tell is a security assertion that passes on the first run: prove it can fail by breaking the input (the wrong verb, the wrong key) before trusting it. Known LocalStack gaps as of this slice: S3 signature validation (switchable), account-level S3 public-access block (not emulated), and — from FS-9 — IAM policy evaluation on the EventBridge Scheduler leg (not emulated, deliberately left to the cloud half).

L-040 — On a CSRF-protected chain an anonymous write is refused as 403 before it can be 401, so “unauthenticated → 401” on a write endpoint needs a primed token

  • Date: 2026-09-15
  • Source commits in this repo: FS-11 finding F-009 (.forge/specs/foundation/011-file-pipeline-findings.md); forge-et-be e399bd0 (AttachmentPipelineIT, csrfPrimedAnonymous); this Reflect PR
  • Sync target: upstream
  • Synced: pending

Problem observed

The plan’s always-test row for every new endpoint reads “unauthenticated upload → 401”. On FS-6’s security chain the CSRF filter runs before authentication, so an anonymous multipart POST with no token answers 403 FORBIDDEN — correct behaviour, and a wrong expectation. The row failed, and the naive fix (change 401 to 403) would have replaced an authentication assertion with a CSRF one and left the authentication half of the endpoint unproven.

Change made

The row was split in two: an anonymous POST with no token is 403, and an anonymous POST carrying a live XSRF-TOKEN — primed from /actuator/health, the same dance LoginSupport performs before the stub login — is 401 UNAUTHENTICATED. The primed anonymous client is a four-line helper in the IT.

Lesson

On a chain with CSRF ahead of authentication, the 401 row for a state-changing endpoint is only reachable through a client that already holds a valid token; without one the test measures CSRF, not auth. Read endpoints are unaffected — a GET needs no token — which is why the FS-6 fixture never surfaced this and the first write endpoint did. The LoginSupport trait is the natural home for a csrfPrimedAnonymous() helper so the next write endpoint’s 401 row is one line, not a rediscovery.

L-041 — A slice counter that keeps dropped slices in the denominator but never the numerator can never reach the gate it reports on

  • Date: 2026-09-15
  • Source commits in this repo: a124ae2 (harness PR #92 — the three counters); this entry’s PR
  • Sync target: upstream
  • Synced: pending

Problem observed

Foundation on this engagement has fourteen slices: eleven done, two dropped before start (FS-12 and FS-13, by AD #29), one not started. Three surfaces render the slice figure — the tracker dashboard (.forge/dashboard/index.html), the forge-recap.sh Stop hook and the status-line segment (.claude/lib/forge-statusline-segment.sh) — and all three rendered it as done/total, keeping a dropped slice in the denominator and never in the numerator. That was deliberate (“every surface agrees on N/M”), and it produced a number that could not do its job: the lead read 11/14 as three slices outstanding when one was, and the status line’s own self-test pinned 2/3 slices · ready to seal as correct output — a figure that is simultaneously “not finished” and “sealable”. The seal condition already counted exit states (done + dropped = total), so the counter and the gate it was meant to track disagreed by construction.

Change made

All three counters now put every slice in an exit state — done or dropped — in the numerator over all slices, so N/M reads “N closed, M−N to go” and reaches M/M exactly when the phase is sealable; the dashboard’s foundation progress score uses the same basis. The dropped count is shown alongside (· 2 dropped) so a dropped slice is never read as built. The two dropped-slice self-test cases were re-pinned to the new output. On this project the surfaces now read 13/14 foundation slices closed · 2 dropped, foundation · 13/14 slices · 2 dropped · next gate: Gate 3 and 13/14 slices · 2 dropped · active: FS-8 not-started.

Lesson

Define a progress figure against the gate it reports on, and decide where every terminal state sits — in both halves of the fraction, or in neither — never in the denominator alone. If the seal fires when every slice has reached an exit state, the numerator is exit states; excluding one exit state from the numerator while keeping it in the denominator yields a number that can never reach the gate, and readers correct for it by hand or misread it. Show the excluded category as its own term rather than folding it into the arithmetic. The dashboard’s feature counts already do this the other way — paused and dropped features leave both halves — which is the same rule; the slice counters were the one place it had not been applied. Port to forge-harness/templates/project-harness/: the three files above and the segment’s self-test expectations.

Verification

bash .claude/lib/forge-statusline-segment.sh --self-test → 20 passed, 0 failed; the segment run against this tracker → 13/14 slices · 2 dropped · active: FS-8 not-started; the recap hook with a Stop payload → foundation · 13/14 slices · 2 dropped · next gate: Gate 3; the dashboard served over HTTP and rendered in the browser → 13/14 foundation slices closed · 2 dropped.

L-042 — A sub-agent’s report that a capability is missing is a dated observation about the machine, not a fact

  • Date: 2026-09-16
  • Source commits in this repo: FS-15’s plan ## Notes and findings F-002; this entry’s PR
  • Sync target: upstream
  • Synced: pending

Problem observed

Three consecutive implementer dispatches on FS-15 reported Docker unavailable and deferred every Testcontainers test, three inherited acceptance proofs and the pricing assertion script to CI. Each dispatch inherited the claim from the last without re-testing it. It reached the commit messages, the plan’s ## Notes, the tracker note and the PR body as “unverified locally — CI’s Slow lane is the first real run”, and the slice was minutes from review with its most expensive verification unrun. The reviewer, handed the same worktree, found the daemon up and ran all of it green in its first minutes.

The original check was not a lie: docker info genuinely failed at that moment. But nothing re-tested it across four hours, and a negative capability result is the easiest kind to carry forward, because it costs nothing to honour and every downstream step quietly adapts to it.

Change made

Treat a capability check exactly as source-trust.md treats a claim about an external artifact: it was true when it ran, and nothing announces when it stops being true. Before recording an absence in a durable artifact — a commit message, a plan note, a PR body’s evidence table — re-run the one-line check. When a sub-agent reports a capability missing, that is a lead to verify, not a finding to relay.

Lesson

The cost is asymmetric and the asymmetry is invisible. A false positive capability claim fails loudly at the first command. A false negative never fails at all — it silently downgrades verification, and the artifact that records it makes the downgrade look considered. Re-test before you write it down.


L-043 — A gate command that ends in a pipe reports the pipe’s exit status, not the gate’s

  • Date: 2026-09-16
  • Source commits in this repo: FS-15 findings F-001; this entry’s PR
  • Sync target: upstream
  • Synced: pending

Problem observed

timeout 590 ./gradlew check 2>&1 | tail -25, then echo "GATE EXIT: ${PIPESTATUS[0]}", printed GATE EXIT: 0 for a build the timeout had killed part-way through its test task. Two mechanisms combined: the echo followed a subshell, so PIPESTATUS had already been reset and [0] was tail’s status; and tail exits 0 whatever it is fed. The visible output was indistinguishable from success — ordinary task names, no BUILD FAILED, because a killed Gradle prints no verdict either. The only tell was elsewhere: the test-results directory held one suite where the branch has ninety.

This is the “show the receipts” rule defeated by its own receipt. The command was run, its output was pasted, and the exit code was printed — and all three were true about the wrong process.

Change made

A command whose exit status is the evidence gets its own invocation and its own $?: ./gradlew check > run.log 2>&1; echo "EXIT=$?". Read the log afterwards. Never pipe it to a pager or a filter in the same statement, and never wrap it in a timeout shorter than the thing it measures. Where the gate emits structured results (JUnit XML, a coverage report), assert on those too — a count that collapsed is the signal a truncated run leaves behind.

Lesson

“I ran the gate and it exited 0” is only evidence if the 0 belongs to the gate. Shell plumbing can relabel a failure as a success without anyone lying, which makes it worse than a missing check: a missing check is visibly missing.


L-044 — An exemption added to a consistency check can permit the exact case the check existed to catch

  • Date: 2026-09-16
  • Source commits in this repo: FS-15 findings F-003; this entry’s PR
  • Sync target: upstream
  • Synced: pending

Problem observed

A schema drift check compares shipped migrations to the data-model document one way: every CREATE TABLE a migration ships must appear in the document. Dropping a table breaks that rule permanently, because migrations are append-only and the original CREATE never leaves history. FS-15 added the obvious exemption — skip a table that a later migration drops — and shipped it with half the rule missing. It skipped the table on the migration side and said nothing about the document side, so a retired CREATE left in the document after the drop would be skipped by the migration loop and contradict nothing in the doc-to-script comparison. That is precisely the scenario the slice’s own plan had named as the thing to get right, and the check would have passed through it in silence. The missing half is four lines: a dropped table still defined in the document is drift.

Change made

When a check gains an exemption, write down what the exemption now permits, and assert on it in the same commit. Red-green the new rule the way the original was: make the bad state, watch it fail, remove it, watch it pass.

Lesson

An exemption is a hole with a justification attached. The justification covers one direction; the hole is usually symmetric. “This table may be absent from the document” and “this table must not be present in the document” are different statements, and shipping only the first turns a guard into a rubber stamp for its own worst case.


L-045 — A plan that names a CI lane is making a claim about an external artifact

  • Date: 2026-09-16
  • Source commits in this repo: FS-15 findings F-004; this entry’s PR
  • Sync target: upstream
  • Synced: pending

Problem observed

FS-15’s plan stated in its ## Test Approach that the pricing proof script — eighteen assertions against a real PostgreSQL — runs in the backend’s Slow lane, and the Success Criteria repeated it. It does not. The lane runs the drift check alone; the proof script is wired into no workflow at all. So the document whose job was to say how the slice would be verified named a gate that had never existed, for the one artifact in the slice whose entire purpose is executable proof. The claim survived a two-pass plan review and a spec revision, because every reader treated it as a statement about the plan rather than a statement about a file in another repo.

Change made

source-trust.md’s rule for external artifacts applies inside a plan’s own test table. A row naming a CI lane either cites the workflow file and job that runs it, or is written as an intention with the wiring listed as owed work. The same applies to any plan sentence asserting what a pipeline, a deployed environment or another repo’s tooling currently does.

Lesson

Plans are read as intentions, so a factual claim smuggled into one is not read as a claim at all. The sentences most likely to be wrong are the ones describing something the author cannot see from the file they are editing — and a test-strategy table is full of them.

L-046 — An onramp README tested by its author on the author’s platform measures the path, not the document; the test is a peer on the team’s majority platform

  • Date: 2026-09-16
  • Source commits in this repo: FS-8 finding F-001 (.forge/specs/foundation/008-developer-onramp-findings.md, the five-run record); spec Rev 1; forge-et-fe 3a83861, 50c43d8, 38ebdd9, 28f1639, 4b3de1f; forge-et-be 99e8279, fe3d4be; forge-et-pwa 29f9fc2, fb1f4af; harness PRs #98 and #106; this entry’s PR; BUG-073 (scripts/local-build-evidence.py, run only on its author’s platform, failed on Windows under Claude Code — forge-et-be#134)
  • Sync target: upstream
  • Synced: pending

Problem observed

The slice’s acceptance test is “a developer reaches a running app from the README in 30 minutes”. The author ran it first, on the author’s Mac: 147 seconds, every step did what it said, no defect and no question. The same READMEs then went to a teammate on Windows, the platform two of the three developers use. Run 2 reached the backend and stopped dead at step 2 of both frontends: the laptop’s Node 26 ships no Corepack and no version manager was installed, so the pin refused correctly and the README offered no route to the right Node. Runs 3, 4 and 5 found eleven more, three of them only visible under fnm on Windows — Corepack’s own lookup fails against fnm’s per-shell shim directory, --corepack-enabled acts at install time only so a machine that already holds Node 24 gets no pnpm, the shell has to be reopened after winget install and the hook added or fnm use changes nothing. Thirteen defects in all, every one a README or protocol defect, none of them findable on the machine that wrote the text, because that machine already held every prerequisite warm and so never exercised steps 1 and 2.

Change made

The spec’s FR-T1 took a Rev 1 naming the peer and the platform. fnm was named as the team’s Node manager (lead, 2026-09-16), step 1 installs it and reads .nvmrc, and step 2 creates the pnpm shim against the real installation directory fnm exports as FNM_DIR — the wording, the three Corepack error modes and their fixes, and the Windows section live in each repo’s README.md § Run it from a fresh clone (steps 1–2) and § On Windows, which are the checkable source; this entry does not restate them. The protocol counts every question the tester has to ask a person as a defect.

Lesson

An onramp document is tested by someone who did not write it, on the platform most of the team uses, with the project’s caches and images cleared — never by its author, whose machine has already absorbed every step the document is supposed to teach. The author’s run is still worth doing first, as a measurement of the path (it proved the 2.5 GB pull and the seed probe), but it is not the acceptance test and must not be recorded as one. Where the team is split across operating systems, the platform the author does not use is the one to test on. For any later repository that onboards Node developers: version managers change how Corepack finds itself, and a pin at >=24 <25 is also what keeps a Node with no Corepack from reaching step 2.

Verification

Run 2’s backend path plus run 3’s frontend path, both by the peer on Windows over office wifi, sum to 23 min 13 s to all three end states — inside the 30-minute target. Runs 4 and 5 re-proved step 2 with the global pnpm removed, so the route no longer depends on a leftover install.

L-047 — A documented sample call is a claim about the running system; run it before writing it, and re-run every recorded sample after a cross-cutting slice lands

  • Date: 2026-09-16
  • Source commits in this repo: FS-8 finding F-002; plan Important I1 (/forge-plan-review, 2026-09-16); forge-et-be#28 (docs/api/README.md § Running the worked example); this entry’s PR
  • Sync target: upstream
  • Synced: pending

Problem observed

The backend’s API guide showed a worked example — one curl against the catalog listing — with no session. It was correct when FS-10 wrote it. FS-6 then put every /api/v1 route behind a session, and the example started answering 401 UNAUTHENTICATED. Nobody noticed, because nobody ran it: a new developer following the guide as written would have read a refusal that looks exactly like a broken setup. It surfaced only because the plan required the README probe to be run against the running app on main before it went into the README, and the run’s negative control hit the stale example.

Change made

The example now carries the cookie jar the README probe fills and points at the probe for the sign-in dance. The same rule was applied to every command the slice wrote down: each was run on the tree first, and the pre-PR review lists the two negative controls that proved the probe’s shape.

Lesson

Every sample command in a document is a claim about the running system, so it is run against the tree before it is written and run again by any slice that adds a cross-cutting requirement. The second half is the one that decays silently: auth, CSRF, a URL prefix or a required header changes the answer of every recorded sample at once, and the slice that adds it owns the sweep — grep -rn 'curl' README.md docs/ in the repo it touched, each hit re-run. A sample that cannot be run (a deployed URL, a credential) states so beside itself so the reader does not spend a clock on it.

L-048 — A fail-closed consistency check over seeded data turns every key rename into a migration for every existing environment, so the rename owes its remedy line

  • Date: 2026-09-16
  • Source commits in this repo: FS-8 finding F-006; forge-et-be#28 merge a96d538 (README.md § If bootRun refuses to start after a git pull: the orphan-grant check); FS-15 forge-et-be#29 (the rename); AD #30’s “update roles is a required release step”; this entry’s PR
  • Sync target: upstream
  • Synced: pending

Problem observed

FS-15 renamed the product.* permission keys to buying_standard.* and re-keyed the local seed. The seed is insert-only (ON CONFLICT DO NOTHING), so on every laptop that had run the backend before the merge the old grant rows survived in ./.local/postgres, and the startup orphan-grant check refused to boot: Stored permission grants do not match the declared catalog, so the application will not start. The check did exactly what FS-6 built it for. A fresh clone never sees it; every existing developer does, on the first pull after any key rename — and the message reads like a broken install.

Change made

The backend README gained a section headed by the error text itself, so the string a developer sees is the string they search for, with the remedy (wipe the throwaway local data directory) beneath it.

Lesson

A feature that renames a key guarded by a fail-closed check — a permission key today, any catalog key a startup check compares against stored rows — adds a line, in the README section headed by the error text and in its release note, naming the environments it strands and the remedy. AD #30 already makes “update roles” a required release step for every feature that adds a key; this extends it to renames and to the local database. The structural cause is the insert-only seed: a seed that reconciled instead of inserting would make the rename invisible locally, and that is the ASK FIRST to raise if a third rename lands.

L-049 — Whole-file regenerations do not belong in git: two branches that both ran the generators conflict on every merge while never disagreeing about anything real

  • Date: 2026-09-16
  • Source commits in this repo: 835cf0d, ec2629b, 825bc3d (harness PR #106); the rule they replaced in .claude/CLAUDE.md § Boundaries (“regenerate the mirrors before staging”); this entry’s PR
  • Sync target: upstream
  • Synced: pending

Problem observed

The rendered doc site (docs-html/, ninety files), the dashboard data files (.forge/dashboard/{tracker,signals,metrics}.js) and the reference graph were committed, and a rule required regenerating them before every commit — so every branch carried a fresh copy of every mirror. Any two branches that had both run the generators then conflicted on every one of those files at every merge, without ever disagreeing about a source. FS-8’s harness branch merged main six times in one day and every conflict was a mirror. CI made it worse by diffing the committed mirror against a fresh render: a stale mirror bounced the PR, so the regenerate-before-staging rule was load-bearing and the conflicts were the price of obeying it.

Change made

The mirrors are gitignored and untracked. The Stop hooks rebuild them at the end of every turn, .githooks/pre-commit for commits made outside a session, ./forge-start.sh for a fresh clone; the generators read the whole tree, so the first regeneration after a pull includes everyone’s files. CI’s gate became “the generators run clean” — graph first, renderer second, both must produce their output. The hosted dashboard builds on deploy from the same script instead of serving committed files.

Lesson

A derived artifact that is a whole-file regeneration of the tree is built per machine and per deploy, never committed; the CI gate is “the generator runs clean”, never “the committed copy is fresh”. Committing it converts every generator run into a merge conflict and every rule about freshness into a reason to commit more of them. One always-conflicting line remains after this change: the tracker’s global last_updated, a timestamp two branches will always both bump — it is the same shape (a whole-file property on a shared file) and belongs to the upstream tracker schema, to be dropped or derived from git rather than fixed per project. Port to forge-harness/templates/project-harness/: the .gitignore entries, the pre-commit hook, the starter-script build step, and the CI gate’s shape.

L-050 — An mtime freshness check on a generated file is unsound; always regenerate, or key the check on content

  • Date: 2026-09-16
  • Source commits in this repo: .claude/hooks/regen-reference-graph.sh header (“WHY THERE IS NO MTIME FRESHNESS CHECK” — the deletion case, already fixed there); .claude/hooks/regen-tracker-dashboard.sh (the -nt tests in its dispatch section, still present as of this entry); harness PR #106’s merge day; this entry’s PR
  • Sync target: upstream
  • Synced: pending

Problem observed

Two regeneration hooks skip the rebuild when the output looks newer than its source. Three ways that check has now lied on this repo: deleting a source changes no surviving file’s mtime, so the graph kept listing a file that no longer existed (recorded in the graph hook’s header); a broken or partial output exists with a fresh mtime, so it read as up to date and was never rebuilt (recorded in the dashboard hook’s publish comment); and, on the FS-8 merge day, resolving a mirror conflict with git checkout --ours rewrote the output, gave it an mtime newer than tracker.yaml, and the hook skipped — the stale mirror went into the commit. The graph hook already concluded “always regenerate” and says why; the dashboard hook kept its two -nt tests at the same time.

Change made

This entry records the third failure beside the first two. The dashboard hook’s -nt skip is removed in the follow-up PR to this Reflect, so both hooks regenerate unconditionally; the graph hook measured its own cost at ~0.4 s and the write is deterministic, so a no-change turn rewrites byte-identical files.

Lesson

A freshness check keyed on modification time answers “was this file written recently”, not “does this file reflect its sources” — and merges, checkouts, partial writes and deletions all make those two questions disagree. For a generator that runs in well under a second, regenerate every time; if one ever grows past that, key the check on content — a hash of the file list and sources — never on mtimes. Apply the same answer to every regen hook in the harness at once: the second hook kept the check the first had already removed, which is how the same lesson got learned twice.

L-051 — Governance guards that hang off the Edit/Write tool matcher are bypassed by any Bash write; the Bash matcher must refuse the write shapes it can recognise on guarded paths

  • Date: 2026-09-16
  • Source commits in this repo: .claude/hooks/block-dangerous-bash.sh (the guarded-path section), .claude/hooks/README.md, .claude/CLAUDE.md § ALWAYS DO (the Edit/Write-only rule), .claude/rules/prd.md § Hook Contract, the two review skills’ “apply fixes” steps; this entry’s PR
  • Sync target: upstream
  • Synced: pending

Problem observed

Every governance guard in the harness — protected-paths, guard-spec-leapfrog, guard-spec-approval, guard-plan-approval, guard-prd-shape — is a PreToolUse hook on Edit|Write|MultiEdit. The enforcement triangle (skill writes the right shape, hook enforces it, annotation is the evidence) rests on the assumption that a file change arrives through one of those tools. Newer Claude Code clients carry a mode that tells the model to prefer Bash — sed -i, heredocs, redirects — for file changes. A Status: approved flipped with sed -i on a spec fires nothing; a ### Rev N block appended to project-prd.md with >> fires nothing. The guard did not fail; it was never consulted. Found while auditing the harness for assumptions inherited from the model era it was written in.

Change made

block-dangerous-bash.sh — already on the Bash matcher — gains a guarded-path section: when a command names a guarded path (.forge/specs/**, .forge/plans/**, the PRD files, tracker.yaml, .claude/ config) and uses a write shape the hook can recognise (sed -i, perl -i, tee, a >/>> whose target is the guarded path), it exits 2 and points at the Edit/Write tools. Deliberately narrow: the skills’ yq -i on the tracker stays allowed, reads are untouched, mv/cp are not inspected. A CLAUDE.md rule covers the shapes the hook cannot see (a Python script opening the file). The review skills’ “apply fixes” steps say Edit, never a Bash substitute.

Lesson

A hook is only as complete as the set of tool matchers it is wired to, and that set is a property of the client, not of the rule. When the client’s preferred write path changes, every guard on the old path is silently bypassed — no error, no warning, the guard simply stops being on the route. Audit the matchers whenever the client generation changes, and for a guard that protects a file, put a refusal on every tool that can write a file, not only on the one the author reached for.

L-052 — Instruction files calibrated to one model generation carry that generation’s numbers, tool names and verbosity; re-audit them when the client or model moves

  • Date: 2026-09-16
  • Source commits in this repo: .claude/CLAUDE.md (Active Context reduced to current state, history moved to .forge/engagement-log.md; AD #29–#32 Why columns compressed with the full text archived; context-size wording; Agent for Task), .forge/forge-harness-framework.md § Context Management During Implementation, .claude/agents/README.md, .claude/commands/forge-review-pr.md, the two review skills, .claude/hooks/README.md (the MultiEdit matcher note); this entry’s PR
  • Sync target: upstream
  • Synced: pending

Problem observed

The parent harness was written against an earlier model generation and client. An audit of every instruction file found no model pins (good — every run inherits the session’s model) and no shouting prompt idioms, but three kinds of drift: numbers that were true then (“after ~60% of the context window”, “burned ~150K context on turn 1”, “2–4 subtasks per session”) stated as thresholds; tool names that no longer exist or were renamed (Task → Agent; MultiEdit gone, still cited in five docs and the hook matchers); and volume — the root CLAUDE.md had grown to about 14,000 words loaded every session, a third of it a running narrative of how the engagement got here and a third the Architecture Decision table whose newest rows had become essays. None of this breaks a run. All of it lowers the share of load-bearing instruction in what the model reads, which matters more, not less, as models get better at following the rules they are given.

Change made

Numbers restated as judgement (“end a session when the working context is dominated by output the next subtask does not need”), keeping the reason each rule exists; tool names corrected, with a matcher note explaining why MultiEdit stays in settings.json; ## Active Context cut to current state with the narrative moved verbatim to a new .forge/engagement-log.md, and the four essay-length AD Why cells compressed to a one-line why plus a pointer to the archived original. A Compounding Engineering rule added: a rule carries its why in one sentence, the long rationale lives once and is pointed at.

Lesson

Instruction prose has a model-era watermark. Thresholds, tool names and the assumed cost of context all encode the client the author was using, and none of them announce when they stop being true. Keep the why (it survives generations) and drop the number (it does not); keep the rule short and the rationale elsewhere; and re-run this audit — model pins, prompting idioms, tool names, context figures, root-file size — whenever the team moves to a new model or client generation.

L-053 — A hook-enforced harness is robust to a model’s prompting quirks; pick the model and effort by task fit and quota, and route around a model rather than refactoring prompts for it

  • Date: 2026-09-17
  • Source commits in this repo: .forge/team-guide.md (new ## Choosing a Claude model and effort for /forge-deliver section); this entry’s PR
  • Sync target: upstream
  • Synced: pending

Problem observed

The team runs /forge-deliver on Claude Code under a Team seat where the premium (Fable) share is about half a weekly cap that does not roll over and depletes roughly twice as fast as Opus. Two questions followed: which model and effort to run for the driver versus the dispatched sub-agents, and whether the intensely prescriptive harness (dense CLAUDE.md rules, gates, turn-1 discipline) degrades output from Fable 5.1 — whose own prompting guide warns that instructions written to suppress older-model habits can misfire, and that it leans toward whole-file rewrites and scope/test sprawl. The initial instinct was that a harness “tuned for Opus” would need its prompts loosened for Fable.

Change made

Added a ## Choosing a Claude model and effort for /forge-deliver section to team-guide.md: a routing rule (baseline the driver on Opus 4.8 + xhigh; promote to Fable 5.1 + high only for open-ended reasoning bursts; put implementer sub-agents on Sonnet 5; never max on structured harness artifacts) and a Fable watch-list mapping each observable symptom to its documented fix. Deliberately made no change to CLAUDE.md prompts or the hooks.

Lesson

  • A hook-enforced harness is model-robust by construction. The load-bearing gates — spec/plan approval, protected paths, shape guards, turn-1 discipline — are deterministic hooks on Edit/Write (L-051), not natural-language rules the model must choose to obey. A model cannot “dislike” a hook into failing, so a stronger-but-differently-tuned model is a routing and observation question, not a prompt-rewrite project. The instinct to loosen the prompts for Fable was wrong.
  • Pick by task fit and quota, not by the clock. A use-it-or-lose-it premium bucket spent first-come is wasted on easy work. Baseline the driver on the predictable, tight-scope model at its recommended coding effort; promote to the most-capable model only for the open-ended reasoning where its edge shows; push bulk implementation to a cheaper sub-agent model; keep the top effort level off structured artifacts, which it overthinks.
  • Handle a model’s quirks by observation, not preemption. Vendor model-prompting guides are symptom-indexed (“start with the section that matches what you observe”) — the Compounding-Engineering loop restated. Add a targeted rule when a mistake recurs, in the specific skill/agent prompt where it bites, phrased for all models, never a global edit that also taxes every other model. The two Fable coding habits that matter here (whole-file rewrites, scope/test sprawl) were already countered by existing rules (L-003, the small-vertical-WI instruction).
  • One model tendency can fight the harness rather than the code. Fable’s “operate autonomously, don’t ask permission” nudge is the opposite of the harness’s deliberate stop-and-ask gates; do not import it. The hook-enforced gates hold regardless; the exposure is the soft ASK-FIRST items when a high-autonomy model is driving.
  • Complements L-052 (re-audit instruction files when the model moves) with the decision that usually follows the audit: for a hook-enforced harness, the answer is route-and-observe, not rewrite. For current model facts consult the claude-api skill; the specific figures here are 2026-09-17 point-in-time.

Verification

Grounded in Anthropic’s platform docs — Effort, Choosing the right model, and Prompting Claude Fable 5.1 — cross-checked against the claude-api skill’s model reference.

L-054 — Restructuring heavily-referenced docs: measure the citation blast radius, keep anchors at stable paths, and make canonical-layout changes upstream

  • Date: 2026-09-18
  • Source commits in this repo: the docs/restructure PR (.forge/design + .forge/discovery subfoldering); the .forge/guides/ PR
  • Sync target: upstream
  • Synced: pending

Problem observed

A request to “restructure the doc folders properly” grew, over one session, from grouping .forge/design and .forge/discovery into subfolders to also foldering architecture.md and regrouping the top-level .forge/ files (the PRD trio, tracker.yaml, features.md, …). Each expansion looked equally cheap from the outside. Measured, they were not: architecture.md is cited by 78 files (56 of them governance files that must be hand-edited through the Edit tool, not scripted), while tracker.yaml is hardcoded in 44 machinery files including 10 hooks that fire on every session, and project-prd.md in 127 files, with path-scoped rule globs and guard hooks keyed on those exact names — and every one of those files is defined by the parent forge-harness template this project syncs from.

Change made

Executed the safe tier only: grouped design/ (ai/, data/, archive/, prototypes/) and discovery/ (inventories/, source-schemas/, kickoff-deck into meeting-notes/), moved the misplaced top-level PRD×prototype cross-reference into design/prototypes/feature-detail.md, and updated every reference. Kept architecture.md and the top-level .forge/ files where they are. Verified with the reference graph before shipping.

Lesson

  • Measure a doc’s citation blast radius before moving it. grep -rlF <basename> across the repo, split into governance files (specs / plans / PRD / tracker / .claude — Edit-tool only, per the dangerous-bash guard) versus scriptable docs, is a two-minute check that turns a “cheap tidy-up” into a real cost estimate. A ~15-reference move is a doc-folder change; a 78-reference move rewrites in-flight feature specs.
  • Keep heavily-cited anchors at a stable, predictable path. The single most-referenced design doc earns its place at a known location; subfoldering it to match its neighbours trades a path everyone links to for cosmetic symmetry, and leaves a stale-link landmine in every in-flight branch that authored a new spec against the old path.
  • Machinery paths are not document payload. tracker.yaml, project-prd*, and the files hooks/skills/generators hardcode are the harness’s structural contract, not docs to rearrange. Moving them risks breaking the live harness for the team, and — because the parent template defines the layout — permanently forks the project from upstream, so every future sync becomes manual path surgery. A canonical-.forge/-layout change belongs upstream in forge-harness, done once and synced down, never as a one-project fork.
  • The reference graph is the gate for a doc move. Diff its dangling-reference list before and after: a net-zero delta (only path-shifted pre-existing danglers) proves nothing that resolved before is broken now. It does not catch rendered-markdown-link correctness for files that moved deeper, so also fix ../ and relative links by hand for any file whose depth changed.

Verification

python3 .claude/lib/harness-graph.py --convention reported 281/281 machinery files reachable; the dangling-reference diff against the pre-restructure baseline was net-zero (186 table rows before and after, the only changes being path-shifted pre-existing relative-prose refs); node .claude/lib/render-docs-html.js exited 0 with every moved page rendered.

L-055 — A cross-cutting request concern like the CSRF token belongs in the shared HTTP client, guaranteed on demand — not in each screen that renders a write surface

  • Date: 2026-09-19
  • Source commits in this repo: promoted from F-001 in .forge/specs/F5-a-findings.md (the F5-a Wave-1 apiClient CSRF-priming fix — forge-et-fe#19, shipped in wave PR forge-et-fe#21)
  • Sync target: project-only
  • Synced: pending

Problem observed

F5-a’s stub sign-in failed on the first click with a 403 CSRF rejection and succeeded on the second. Root cause: the /login route renders outside the AuthenticatedGate, and its interactive form became clickable during the session loading state — before the bootstrap GET /api/v1/me had resolved. That GET /me is also what plants the XSRF-TOKEN cookie (Spring emits it eagerly, on the 401 too), so a click inside the cold-load window sent the state-changing POST with no X-XSRF-TOKEN header and Spring refused it; the rejected response itself planted the cookie, which is exactly why the retry worked.

The first fix was UI-level — hold the LoginRoute form behind session.status === 'loading' so it only becomes interactive once the cold-load /me has planted the cookie. It was insufficient: POST /logout deletes the XSRF-TOKEN cookie and signOut() sets the store straight to unauthenticated (never back through loading), so the log-in → log-out → sign-in-again path re-rendered a live form with no cookie and 403’d again.

Change made

Moved the guarantee into the shared apiClient: before any state-changing request, if the XSRF-TOKEN cookie is absent it does a priming GET /api/v1/me (the backend emits the cookie on every response) and then echoes the freshly-planted token. This covers every path a write can reach with no cookie — cold start, post-logout, expiry — not just the login page. Unit tests in apiClient.test.ts (primes then echoes when absent; no prime when present); the cold-load loading gate stays as UX with its own LoginRoute.test.tsx coverage.

Lesson

  • Put cross-cutting request preconditions in the one place every request flows through — the HTTP client — not in the screens. A token/header/precondition that every state-changing request needs is the client’s job to guarantee, on demand, at the moment of the request. Pushing it to each screen (“don’t render a write surface before the bootstrap resolves”) only covers the paths you enumerate, and misses the ones where the precondition is invalidated after render (here: logout deleting the cookie while the form is already live).
  • Enumerate the ways a precondition can be invalidated, not just the ways it can be absent. The cold-load case (never-yet-present) was obvious; the post-logout case (present, then deleted, form still mounted) is the one a render-time gate structurally cannot catch. When a fix is a guard at render time, ask “what deletes this precondition without re-rendering?” before calling it done.
  • A defect that self-heals on retry is a precondition-ordering smell. “Fails first, works second” almost always means the failing action is also what establishes the precondition the action needed — look for the establish-vs-use ordering rather than treating it as flakiness.

L-056 — An FR with a matching AC can still ship a dropped clause — coverage checked per-FR-id is blind to an uncovered sub-clause

  • Date: 2026-09-21
  • Source commits in this repo: docs/BUG-007-followups (this PR); the instance is BUG-007 (fix forge-et-fe#33, F5-a spec Rev 2)
  • Sync target: upstream
  • Synced: pending

Problem observed

BUG-007 shipped a silent session expiry: the login page could not tell an expired session from a first visit. The requirement was not missing — FR-6 carried two testable promises (“preserve and restore the originally-attempted route” and “signal the expiry by routing to the login page with a ‘your session expired’ notice”). AC-8 encoded only the first. Every gate passed: spec-reviewer dimension §5 checks “every FR has at least one AC referencing it”, and AC-8 did reference FR-6, so FR-6 read as covered while one of its two clauses had no acceptance criterion at all. Implementation, peer review and the browser suite all checked against AC-8, all passed, and the notice was never built — nothing downstream could see the gap, because the coverage check is at FR-id granularity, not clause granularity. A whole FR clause was invisible to every gate.

Change made

Refined spec-reviewer dimension §5 (Acceptance Criteria — coverage) to check clause-level coverage: when an FR bundles more than one testable promise, each clause must map to some AC — not merely one AC referencing the FR id — and an FR whose ACs cover only a subset is an Important finding. The dimension now also prefers splitting a multi-clause FR into atomic FRs. Closed the specific instance in F5-a (AC-8 gained the notice clause, spec Rev 2) and shipped the code fix + regression tests (forge-et-fe#33, verified live).

Lesson

  • “Every FR has an AC” is not “every FR clause has an AC.” An FR that bundles clauses with “and” / “; also” can be marked covered by an AC that verifies one clause and silently drops the rest. The coverage gate must map clause-to-AC, or the requirement must be split so one FR carries one testable promise.
  • Prefer atomic FRs — one testable promise each. A multi-clause FR is a coverage hazard by construction: it lets a partial AC satisfy the gate. Splitting at authoring time is cheaper than the review-time clause audit and removes the blind spot entirely.
  • A clause with no AC is invisible to every downstream gate, not just the spec review. Plan AC-coverage (TC-3), the test tables and the browser suite all key off the ACs — so a clause that never became an AC cannot be caught later by any of them. The spec is the only place the gap is catchable; miss it there and it ships.

Verification

spec-reviewer.md §5 updated in this PR. The instance is closed and proven: F5-a AC-8 Rev 2 + forge-et-fe#33, the expiry notice verified end-to-end against a running backend (the forced-expiry e2e asserts the notice, and a first visit / voluntary sign-out stay silent).

L-057 — A hand-allocated global-monotonic id (BUG-NNN, AD #, Rev N) is not reserved between reading the next number and merging — expect a parallel-session collision and renumber the younger claim

  • Date: 2026-09-21
  • Source commits in this repo: the F5-b Reflect PR (chore/F5-b-reflect); the instance is BUG-008/BUG-009 (renumbered from an in-flight BUG-007)
  • Sync target: upstream
  • Synced: pending

Problem observed

This session opened BUG-007 for the current-user-menu polish. A parallel session independently opened its own BUG-007 for the silent-session-expiry defect and merged it to main first. Both sessions had read the then-highest BUG-NNN off their local main and taken “the next one” — but a bug id has no allocation guard (no hook reserves it, unlike spec/plan approval), so between reading the number and merging, nothing stopped a second writer from picking the same one. The collision did not surface as a tool error; it surfaced as two merged/​in-flight entries claiming the same id, discovered by eye.

Change made

Renumbered the younger (still-unmerged) claim — this session’s menu-polish bug BUG-007 → BUG-008, and its sibling role-display bug to BUG-009 — rebased onto the merged main, closed the stale forge-et-fe#32 PR and reopened it as forge-et-fe#34. The merged session-expiry BUG-007 kept its number. Added a one-line parallel-session caveat to .claude/rules/tracker.md § Bug Tracking’s id-scheme so the next allocator expects the race.

Lesson

  • “Global monotonic” is only monotonic within one writer’s view of the tree. In a workspace running several parallel sessions (this one does — see [[parallel-sessions-git-caution]]), “the next BUG-NNN” read from your local main is a guess about what no one else has taken, not a reservation.
  • Allocate against current origin/main at the moment you write the entry, and treat a merge-time collision as expected, not exceptional. On a clash, renumber the younger (unmerged) claim, rebase, and reopen its PR — never renumber a merged id, which others already reference.
  • The same shape applies to every hand-allocated monotonic id without an allocation guard — AD #, Rev N, L-NNN, FS-N. The remedy is identical: re-read the highest from the base you are merging into, right before writing, and be ready to bump. ([[tracker-yq-parallel-writes]]-style flock serialization protects a single file’s concurrent writes; it does not reserve a number across sessions — that is this separate hazard.)

Verification

.claude/rules/tracker.md § Bug Tracking updated in this PR. The instance is closed: BUG-007 (session-expiry, merged) and BUG-008/BUG-009 (this session, merged as forge-et-fe#34, forge-et-be#34, forge-et-fe#35) are now distinct, non-colliding ids.

Update — 2026-10-12

Bug ids are no longer “the highest plus one”: a new bug takes the lowest number not yet taken, so no number is left unused, and .claude/lib/next-bug-id.sh reads both origin/main and the open harness PRs, because a bug filed on a branch holds its number before it merges. The collision hazard above is unchanged, and so is the remedy, except that a clash is resolved by merging main in, not by rebasing (.claude/rules/git-conventions.md § Branching). The other ids stay highest plus one, also read from the open PRs, and no id of any kind is skipped, reused or deleted; .claude/rules/id-numbering.md is the current rule.

L-058 — git worktree add checks out tracked files only, so a fresh worktree is silently missing gitignored local-run config (e.g. application-local.yml)

  • Date: 2026-09-21
  • Source commits in this repo: the F5-b Reflect + dashboard-fixes PR (chore/F5-b-reflect, harness #158) — carries this lesson and the forge-worktree-up skill note; the paired forge-et-be/CLAUDE.md note ships in forge-et-be #36
  • Sync target: upstream
  • Synced: pending

Problem observed

Verifying BUG-009 in a fresh worktree, ./gradlew bootRun failed with et.datasource: null. Cause: application-local.yml (the local profile’s datasource/config) is gitignored, and git worktree add checks out only tracked files — so the new worktree never received it. The primary checkout booted fine and the worktree looked byte-identical in git status, because the missing file is exactly the one git is told to ignore. The symptom (a null-config crash at runtime) pointed at the datasource wiring, far from the actual cause (a file that was never checked out).

Change made

Copied application-local.yml from the primary checkout into the worktree; bootRun then started. (A symlink also works, but a copy survives a later git clean -x.)

Lesson

  • A worktree carries tracked files only. Anything gitignored — .env, application-local.yml, local secrets, .envrc, IDE run-configs — lives only in the checkout where you created it. A fresh worktree is missing precisely the files nothing in git will remind you about.
  • The failure lands far from the cause. You run the app, you don’t open the file, so a missing local-run config shows up as a runtime null/crash, not a “file not found”. Recognise the class: an app that boots in the primary checkout but not in a worktree is almost always a gitignored-config gap, not a code difference.
  • Copy or symlink the repo’s gitignored local-run config right after provisioning any worktree you intend to run (not just build or test in CI shape). This belongs in the worktree-provisioning step, so it is done once rather than rediscovered per developer. Landed: a Notes bullet in the forge-worktree-up skill (harness #158) and a note in forge-et-be/CLAUDE.md § Common commands (forge-et-be #36).

Verification

bootRun started in the worktree after the copy; BUG-009 was then verified live (the current-user chip rendered the role display name from /me). The two doc follow-ups landed: the forge-worktree-up skill Notes (harness #158) and forge-et-be/CLAUDE.md § Common commands (forge-et-be #36).

L-059 — A gate attached to an artifact silently disappears when that artifact is never created

  • Date: 2026-09-23
  • Source commits in this repo: F20-a findings F-006; this entry’s PR; BUG-052, BUG-053 and BUG-054 in .forge/bugs.md (forge-et-fe#21, a wave PR merged with no review, found by the 2026-09-30 post-merge backfill)
  • Sync target: upstream
  • Synced: pending

Problem observed

/forge-review-pr is mandatory on every shipped code PR, and in wave mode it is specified to run on the wave PR. On F20-a Wave 1, both sub-WI PRs merged straight to main before Pass-1 integration ran, so no wave branch and no wave PR were ever created. The gate did not fail — it had nothing to attach to, so it never ran. 86 files reached main looking entirely normal: branch protection was satisfied (a teammate approval, green CI), and the only outward signal was a PR list that looked slightly unusual to anyone who knew what to expect.

The cost was measured, not hypothesised. Running the pass retroactively produced five tracked bugs — a screen with no entry point anywhere in the app, a re-consent serving the previous grant’s cached token for up to an hour, a token-bearing record printing both tokens, a re-consent orphaning a Graph subscription nothing could later delete, and a WCAG AA contrast failure on a shipped screen. None was reachable by the tiers that did run.

Change made

Recorded as F20-a F-006, with two concrete follow-ups for /forge-deliver: notice when a wave reaches merged with no wave PR, and give impl_status a way to say “this WI shipped as its own surface” — today it has no merged value, so those rows were recorded wave-closed, which means superseded by a wave PR that did not exist.

Lesson

A process gate is only as reliable as the artifact it hangs off. “Run X on every Y” has a silent failure mode whenever Y can legitimately not exist, and that mode is worse than a gate that errors: an erroring gate is fixed the same day, while an unattached one leaves no trace at all. When writing a gate, ask what happens if its trigger artifact is never created — and if the answer is “nothing happens”, put the check on the state transition instead of on the artifact. Here the durable version is not “review the wave PR” but “a wave may not reach merged unreviewed.”

L-060 — Heal by ASK when “no work to lose” and “has not started pushing” look identical

  • Date: 2026-09-23
  • Source commits in this repo: F20-a findings F-007; this entry’s PR
  • Sync target: upstream
  • Synced: pending

Problem observed

/forge-deliver Stage 0 reconciles the tracker against GitHub and git before any stage acts. One healing rule auto-resets a WI at impl_status: dispatched with no pushed branch and no PR back to pending, on the stated reasoning that the agent “died before pushing anything, so there is no work to clobber.”

At F20-a’s Wave-2 entry, F20-a-WI-1.3 presented exactly that signature and its agent was alive — working in a local worktree, simply not having pushed yet. The auto-reset would have dispatched a second implementer onto a worktree already being written. The only thing that distinguished the two cases was out-of-band knowledge that the session was running.

Change made

Recorded as F20-a F-007. The proposed fix is a local-state check before healing: a worktree on that branch carrying commits or a dirty tree means an agent may hold it, so the divergence becomes an ASK rather than an auto-write.

Lesson

Before auto-healing on absence, ask whether absence is also the normal early state of success. Stage 0’s own reasoning — a dead agent is indistinguishable from a live one, so decide on what reached the remote — is right for two of its three cases and wrong for this one, because “has not pushed yet” is what every agent looks like in its first minutes. The general test for an auto-recovery rule: enumerate the states that produce the same observation, and if one of them is a healthy in-progress state, downgrade the rule from heal to ask. Reconciliation that can destroy work needs a higher bar than reconciliation that only corrects bookkeeping.

L-061 — A write guard that recognises shapes is silent on the shapes it does not

  • Date: 2026-09-23
  • Source commits in this repo: F20-a findings F-005; this entry’s PR
  • Sync target: upstream
  • Synced: pending

Problem observed

The harness rule is that specs, plans, the PRD and tracker.yaml are edited only through the Edit and Write tools, because every governance guard is a PreToolUse hook on those tools. block-dangerous-bash.sh enforces it for the write shapes it can recognise — sed -i, a redirect, tee.

It was breached three times on one feature, each time by a different actor reasoning the same way. An implementing agent used a script for a repetitive edit and disclosed it. Closing the feature, the orchestrator flipped four tracker fields with a Python script — same justification (“targeted replaces, no reflow”), same outcome: no hook fired. Minutes later the same orchestrator reached for a Bash heredoc to append to a findings file and was blocked.

So the guard works on the shapes it enumerates and is invisible on the ones it does not, and the actor most likely to find the gap is one doing bulk bookkeeping at the end of a long session — precisely when the Edit tool feels most tedious.

Change made

Recorded as F20-a F-005 with the two later instances appended. The argument it supports is widening the hook’s recognised shapes (a script interpreter invoked with a guarded path as an argument, at minimum) rather than only restating the rule in more places.

Lesson

An enforcement mechanism that covers a subset of a rule teaches the rule’s boundary, not the rule. Three actors independently concluded “my write is surgical, so the rule’s why does not apply to me” — which is a reasonable inference when the guard stays quiet. Two consequences worth generalising: state the mechanism alongside the rule, because “use Edit” without “hooks fire on Edit” reads as style preference; and when a guard is shape-based, treat every unrecognised shape as a live gap rather than an edge case, since the population that hits it is self-selecting for bulk edits.

L-062 — The one artifact with no local gate is the one that keeps failing CI

  • Date: 2026-09-23
  • Source commits in this repo: F20-a findings F-008; this entry’s PR
  • Sync target: upstream
  • Synced: pending

Problem observed

commitlint enforces a 72-character header on the PR title. That check exists only in CI, because the title exists only once the PR does. Every other lint in the repo has a local equivalent that runs before push.

It failed twice in one session — once for an implementing agent, once for the orchestrator — each costing a CI round trip for a character count. /forge-pr-open, which composes the title, currently advises “under 70 chars”: advice rather than a gate, and not even the enforced number.

Change made

Recorded as F20-a F-008, proposing a ${#TITLE} check in /forge-pr-open immediately before gh pr create, using 72 to match commitlint.

Lesson

Find the artifacts your local gates structurally cannot see, and gate them at the moment of creation instead. The PR title, the PR body’s required sections, the branch name and the tag message share this property: they are born outside the working tree, so no pre-commit hook will ever reach them. For each, the only cheap check point is the command that composes it. A rule of thumb: if a CI check has no local counterpart, that is usually not an oversight but a structural gap, and the fix belongs in the tool that creates the artifact rather than in a lint.

L-063 — A revision that moves ownership must be applied in both directions, and an unchanged total is not evidence it was

  • Date: 2026-09-23
  • Source commits in this repo: F20-b Decomposition Plan Rev 2 and Rev 3; the F20-b cross-plan consistency audit; this entry’s PR
  • Sync target: upstream
  • Synced: pending

Problem observed

F20-b’s Decomposition Plan Rev 2 moved two acceptance criteria — the axe scan and the tablet reflow — from one owner to two, because the work item that held them runs in wave 1 and the surfaces they cover do not exist until wave 2. The revision was applied forward: the gaining work item got three new test rows, a decision and a note. It was never applied backward to the work item that lost half its claim, which still asserted both criteria outright and would have ticked them as fully satisfied at wave-1 close — while a full-width danger banner nobody had scanned shipped in wave 2.

The same revision also created a sixth split acceptance criterion in everything but name, and left three pieces of the split machinery behind: the clause table that makes each owner restate its half verbatim, the coverage arithmetic, and the checkbox listing which ids cannot be ticked early. forge-test-verify maps criteria to test rows by id, so an id split across two owners without a clause row ticks green on half its evidence.

The revision entry’s own words are why nothing else was checked: “Coverage is unaffected in count.” That was true. The count was the check that got run, and the count passing ended the search.

None of it was caught by the plan reviews — six review passes ran across the affected plans after Rev 2 landed, each checking a plan against its siblings as they stood. It took a dedicated cross-plan audit before implementation to find it.

Change made

Rev 3 completes the split: clause rows for both criteria under both owners, the arithmetic restated, both ids added to the untickable list and the progress checkbox. A dated post-approval note on the plan that lost scope records what it never absorbed. The root cause is written into Rev 3’s own entry so the next reader of that revision chain sees it.

Lesson

A revision that reassigns ownership has two halves, and the forward half is the one you will remember. Gaining work is visible — someone gets new rows, a new decision, a new obligation. Losing work is invisible: the plan that quietly still claims something is indistinguishable from one that correctly claims it. So after any ownership move, go back to the artifact that lost scope and check it says so.

And distrust an unchanged total as evidence. Reassignment conserves counts by construction, so a coverage total is precisely the check that cannot detect one. When a revision’s own justification is “the count is unaffected”, treat that sentence as the signal to look harder at everything the count does not measure — which clause table, which checkbox, which sibling still asserts the old ownership.

Structural note for parallel planning. Pairwise review is not transitive. Every plan here was checked against its siblings at the moment it was reviewed, and every pair was consistent then; the defect lived in the joins, which nothing owned. Where plans are authored and reviewed in parallel, a cross-plan consistency pass before implementation is a distinct gate from the per-plan reviews, not a repetition of them.

L-064 — A harness statement about how Claude Code behaves is a claim to check against Claude Code

  • Date: 2026-09-23
  • Source commits in this repo: .claude/rules/*.md frontmatter; .claude/agents/*.md (model: inherit); .claude/CLAUDE.md § Role Delegation; .forge/team-guide.md § Choosing a Claude model and effort; the model sections of the three .forge/guides/ files; the price tables in .forge/dashboard/usage.html and index.html; this entry’s PR
  • Sync target: upstream
  • Synced: pending

Problem observed

Two harness statements about Claude Code’s behaviour were false, and nothing had checked either.

  • Every .claude/rules/*.md file scoped itself with a globs: key, and CLAUDE.md’s Reference Map described the rules as path-scoped. Claude Code reads only paths: from a rule’s frontmatter and ignores any other field without an error, so all six rules loaded at the start of every session — about 11,600 of the roughly 24,100 words loaded before any work began. It showed only by looking at what a fresh session actually received.
  • The team guide routed implementer sub-agents to Sonnet 5, but no agent definition set model: and /forge-deliver passed none, so implementers ran on whatever model the driver ran.

Both came to light while re-evaluating the model choice after Claude Opus 5.5 was released (2026-09-22).

Change made

  • Rules: globs: replaced by paths: lists. The two rules meant to load always (git-conventions.md, source-trust.md) lose the key, which never had an effect, and say in their description that they always load. One consequence to know: Claude Code loads a path-scoped rule when Claude reads a matching file, not on every tool use, so a session that touches tracker.yaml only through yq in Bash may never load tracker.md. Any Edit-tool change still loads it, because Edit requires a Read first.
  • Usage dashboard: its price table (.forge/dashboard/usage.html and the copy in index.html) stopped at Opus 4.7, so every model the team had run since — Opus 4.8, Opus 5, Fable 5, Fable 5.1, Opus 5.5, Sonnet 5, and the dated Haiku id Claude Code uses for background calls — was priced at the Opus 4.7 fallback. Recomputed over the local usage log, Fable had been shown at about half its API-rate cost. All are now listed at the rates on Anthropic’s pricing page (verified 2026-09-23).
  • Model: the team adopted Claude Opus 5.5 for all work — the driver, authoring, every sub-agent and background task — at high effort, xhigh for a hard problem, with no Sonnet and no Fable (team decision, Tharinda, 2026-09-23). Every agent definition now declares model: inherit and no effort:, so sub-agents follow the driver’s model and effort, and CLAUDE.md § Role Delegation rules out a per-dispatch model. The model names now live only in team-guide.md; the three guides point there. This replaces L-053’s routing (Opus 4.8 driver, Fable 5.1 for hard reasoning, Sonnet 5 implementers); L-053’s method — pick by task fit, don’t rewrite prompts for a model — stands.

Lesson

A harness sentence about how the tool behaves is a claim about an external artifact and needs the same check as any other (.claude/rules/source-trust.md). Frontmatter keys, model routing and load conditions look settled because they sit in configuration files, but a key the tool does not read fails silently, and routing that nobody wrote into configuration is only advice. Check each against the tool’s own reference when writing it, and after a tool upgrade observe the behaviour directly: what a fresh session loads, and which model a dispatched agent runs on. Keep model names in one document — they change with every release, and each extra copy is one more place to go stale.

Verification

  • Claude Code memory documentation, rule frontmatter reference: paths is the only field Claude Code reads from a rule.
  • A session started on 2026-09-23 received all six rule files before any file they apply to was opened.
  • Claude Code sub-agent documentation: a per-dispatch model wins over the definition’s model (inherit selects the main conversation’s model), which wins over CLAUDE_CODE_SUBAGENT_MODEL, which wins over the main conversation’s model; an omitted effort inherits the session’s.

L-065 — A race fixed at one caller is a class: list every caller with the same read-then-save shape before closing it

  • Date: 2026-09-25
  • Source commits in this repo: .claude/commands/forge-deliver.md Stage 7 Step 5d; .forge/specs/F20-b-inbound-sync-inbox-findings.md F-001; .forge/plans/F20-b/F20-b-WI-2.1-plan.md ## Progress (in-wave repairs 2 and 3) and ## Notes (“In-wave repair 2 — the same race on two user actions”); forge-et-be 081e271, 77d9387; .forge/bugs.md BUG-023 (the instance on Disconnect and re-consent, fixed in forge-et-be#60); BUG-051 (the role all-key race — every writer of the role now locks its row, fixed in forge-et-be#149); BUG-186 (F26-g’s date edit took the published-price lock and the later-price check, but F26-c’s sale create, the other writer of a sale’s start, did not — fixed in forge-et-be#251)
  • Sync target: upstream
  • Synced: pending

Problem observed

In F20-b, the connect’s back-fill job refreshes the mailbox access token under a row lock and saves the connection, which bumps its version. Any request that read the row before that and then saved it with a version check answered 409 STALE_VERSION. The orchestrator’s browser runs found it twice, in two different stub endpoints, one day apart, and each was a separate D11 repair cycle (be 081e271, then be 77d9387). The first repair’s own notes already named two more callers with the same shape on product paths, Disconnect and re-consent (F20-a’s MailboxConnectionService). They were left unfixed because the dispatch was scoped to the stub, and they ship as a user-visible, retryable error.

Change made

Both stub endpoints now lock before they read. The two product callers are recorded as a proposed follow-up bug (tracker F20-b notes) rather than fixed here. /forge-deliver Stage 7 Step 5d now says that a D11 repair of a race lists every other caller with the same pattern, and that each one it does not fix is raised as a BUG candidate before the wave PR opens.

Lesson

A concurrency defect is a pattern, not a line. When a repair fixes one caller that reads a row without the lock and saves it with a version check, search for every other caller doing the same thing in the same pass. Either fix each one, or record each as a tracked bug with its own id. Scoping the repair to the caller that happened to fail leaves the rest to be found one red run at a time, and the ones on product paths may never be found by a stub-based suite at all.

L-066 — A browser assertion passes vacuously when it can hold before the screen has settled

  • Date: 2026-09-25
  • Source commits in this repo: .claude/agents/frontend-reviewer.md dimension 12; .forge/specs/F20-b-inbound-sync-inbox-findings.md F-003; .forge/plans/F20-b/F20-b-WI-2.2-plan.md ## Notes (“Wave PR review (fe#55) — disposition”, items 3, 5, 6); forge-et-fe 3b20730, f0a6ef8, 8ce8cef
  • Sync target: upstream
  • Synced: pending

Problem observed

The review of forge-et-fe#55 found three assertions that were green in every orchestrator run and would have stayed green with the feature broken:

  • an absence check (the lapse notice is gone after Reconnect), which is also true during the loading render that refetch produces;
  • .poll(...).not.toBeNull() on lastSyncedAt, which passes when the member is missing, because undefined is not null;
  • a count-only row that counted mailbox-sync elements and asserted no state.

Change made

Each now requires a positive, settled state:

  • the absence check first waits for the second connection read, no loading element and the list present;
  • the poll matches the value against an ISO-8601 instant pattern;
  • the count row asserts the accessible name Waiting for mail.

frontend-reviewer now checks for the three shapes (review dimension 12).

Lesson

An assertion is only evidence if it can fail when the feature is wrong. Three shapes fail that test without looking wrong:

  • “X is absent” checked before the screen has settled;
  • a not-null check on a value that can be undefined;
  • a count with no statement about what was counted.

Anchor an absence on something that proves the screen reached its final state. Match the value you expect, not “not null”. Assert the state, not only the number. This is the test-code form of L-020, where a gate cannot tell “clean” from “blind”.

L-067 — A substrate’s first real consumer is the first time its cloud activation runs; read the activation conditions at spec time

  • Date: 2026-09-25
  • Source commits in this repo: .forge/specs/F20-b-inbound-sync-inbox-findings.md F-005; .forge/specs/F20-b-inbound-sync-inbox-spec.md FR-6b; .forge/specs/foundation/009-scheduler-substrate-spec.md Rev 1; forge-et-be ScheduledJobListener.java, SchedulerConfigGuard.java; .forge/bugs.md BUG-070 (forge-et-be#193) and BUG-097 (the guard checked the key, not the listener switch)
  • Sync target: upstream
  • Synced: pending

Problem observed

FS-9 shipped the scheduler substrate with a demo job. Its ScheduledJobListener was @Profile({"local","test"}) and conditional on et.messaging.scheduler-queue, a key application.yml deliberately leaves unset in cloud. So F20-b’s subscription renewal could never have fired in production, by two separate routes, while every local and CI test passed. The spec review found it only by opening the listener and reading when it activates. F20-b is FS-9’s first real consumer, so it was the first time anyone needed the cloud path to work.

Change made

F20-b FR-6b (built by WI-2.1):

  • removed the listener’s profile scope (only the demo handler keeps it);
  • made the queue key required configuration through SchedulerConfigGuard, which refuses a cloud shape without it;
  • made the registry reject unregistered job kinds, so FS-9’s demo job cannot run in cloud.

FS-9 spec Rev 1 records the change.

Lesson

A substrate proven only by a local demo consumer has never run in cloud shape. When a spec is the first real consumer of a Foundation substrate, read the substrate’s activation conditions (profiles, @Conditional* properties, keys left unset in application.yml) and state in the spec how each is satisfied in a deployed environment. A local green suite cannot show this. The profile and the property that made the demo safe are exactly what switch off the real consumer. L-035 is the reverse case: broad profile activation wakes too much.

A guard that requires the consumer must cover every activation condition, not only the first one found (BUG-070, BUG-097). SchedulerConfigGuard and ScanResultQueueGuard required their queue key but accepted spring.cloud.aws.sqs.listener.auto-startup=false, which the cloud-shape test contexts set on purpose and which stops every listener. A deployment activates no Spring profile, so the guard cannot use a profile to tell a deployment from those test contexts; it uses et.environment, where only test may switch a listener off. backend-reviewer checks new and changed consumer guards for this.

L-068 — A test tier that no PR lane runs stays red on main, and its red set hides new regressions

  • Date: 2026-09-25
  • Source commits in this repo: .forge/specs/F20-b-inbound-sync-inbox-findings.md F-008; .forge/plans/F20-b/F20-b-test-report.md; .forge/plans/F20-b/F20-b-WI-2.3-test-verify.md; .forge/plans/F20-b/F20-b-wave1-overnight-debrief.md §6; F20-a tracker notes (the eight-spec migration); .forge/bugs.md BUG-032 (the auth and shell specs left expecting the old landing page)
  • Sync target: upstream
  • Synced: pending

Problem observed

Every whole-tier playwright --project=chromium run across both F20-b waves ended with the same 12 failures, all outside the feature’s folder (e2e/browser/auth ×7, e2e/browser/shell ×5). They have failed on main since F1-a granted account.view and so changed the post-login landing page. F20-a had hit the same pattern (eight specs broken by a landing change, repaired inside its verify WI). No PR lane runs pnpm e2e, so main never went red and no one owned the fix. The orchestrator worked round it by diffing each run’s failures against the known list. That proves “no new failure”, but a real regression inside one of those 12 specs would be invisible.

Change made

Nothing in code. The red set and the diff method are recorded in the F20-b test report. A tracked bug for the 12 specs is proposed as a follow-up. Its owner is undecided (overnight debrief §6 item 2). The standing CI E2E tiers remain FS-1 cloud-half work.

Lesson

A tier with no lane has no owner. A change that breaks tests only that tier runs merges green, and the breakage then belongs to whoever runs the tier next. Until the tier runs in CI, record every failure found on main in it as a tracked bug when it is found, owned by the change that caused it. Diff each later run against that list. Treat a known-red test as a gap in coverage, not a pass.

L-069 — A green run is evidence only for the tree it ran on; re-run the gate on the commit that ships

  • Date: 2026-09-25
  • Source commits in this repo: .forge/specs/F1-a-account-contact-substrate-findings.md F-002; .forge/plans/F1-a/F1-a-WI-3.1-plan.md ## Notes (“AC-21 escalation”, “Review — forge-et-be#59”); .forge/plans/F1-a/F1-a-test-report.md
  • Sync target: upstream
  • Synced: pending

Problem observed

F1-a wave 3 had two cases of evidence that described a different tree from the one that shipped.

  • A different config. The AC-21 log sweep passed after capping a whole Spring package at INFO, set through an environment variable for the run, and the plan recorded that pass. The commit that followed capped one class inside the package. The committed tree was never run under a test able to see the difference, so a partial contact email still reached the log at DEBUG. The review pass found it by reading the framework’s bytecode, not by running anything.
  • A stale test count. The work item’s /forge-test-verify audit recorded its stats at one SHA. Three later commits went green (a migration renumber, the review fixes, a bug fix) without the guard being re-run. The feature ledger therefore reports an older, smaller run as the shipped one.

Change made

  • The package-wide cap was committed.
  • The strengthened test was run on the old config (EXIT=1, the leak reported) and then on the fix (EXIT=0), and both receipts are recorded.
  • The feature test report states which later runs were not harvested.

No framework file changed in this Reflect.

Lesson

A receipt belongs to a SHA. A passing run, whether the gate, a manual check or a test-verify stats block, is evidence for the exact tree and settings it ran on. Three rules follow:

  • The shipped settings are the ones on the branch. When a fix is proved by running with temporary settings (an environment variable, a flag, a local edit), the proof counts only after the committed change is run again on its own, with the temporary setting removed.
  • A late commit needs a fresh receipt. A commit made after the recorded run, such as a review fix, a renumber or a merge of main, needs its own run. When the guard writes stats, re-run it so the ledger does not keep the older numbers.
  • Pin every receipt. Every receipt names the SHA it ran on. A reviewer comparing that SHA to the PR’s head can tell at a glance whether the evidence is current.

L-070 — Two same-wave work items that each add a migration are coupled; decide the order at decomposition

  • Date: 2026-09-26
  • Source commits in this repo: .forge/specs/F39-audit-trail-findings.md F-001; .forge/plans/F39/F39-decomposition-plan.md ## Notes › “Revision 1”; .forge/plans/F39/F39-WI-1.1-plan.md ## Notes (OI-2)
  • Sync target: upstream
  • Synced: pending

Problem observed

F39’s Decomposition Plan ran WI-1.1 (V24) and WI-1.2 (V25) in parallel, both branched from main. GrantSchemaSpec requires the applied migration versions to be a contiguous run from 1, and out-of-order migrations are off, so a branch holding V25 without V24 could never pass ./gradlew check on its own. Nobody saw this at decomposition; the WI-1.1 plan author found it while checking version numbers, and WI-1.2 had to be restacked on WI-1.1’s branch after its plan was already drafted.

Change made

Decomposition Plan Revision 1 made WI-1.2 depend on WI-1.1 and stack on its branch. WI-1.2 then started after WI-1.1’s PR opened, with the other stacked work items.

Lesson

  • Migration order is a compile coupling. When more than one work item in the same wave adds a Flyway migration, the later versions need the earlier ones on the same branch. Either stack every later work item on the first, or put the migrations in one work item.
  • Decide it at decomposition. Count the migrations per wave in /forge-wave-decompose, next to the other compile couplings. Finding it at plan drafting means re-planning a draft and a revision to an approved Decomposition Plan.
  • Upstream: the rule applies to any harness whose migration tool refuses gaps or out-of-order versions; the GrantSchemaSpec check is this engagement’s own.

L-071 — The Postgres driver puts the failing row into exception messages; prove “no content in logs” with a realistic database error

  • Date: 2026-09-26
  • Source commits in this repo: .forge/specs/F39-audit-trail-findings.md F-002; .forge/plans/F39/F39-decomposition-plan.md ## Notes › “Wave 1 review”; forge-et-be#68 (689b4b0)
  • Sync target: upstream
  • Synced: pending

Problem observed

When a CHECK, NOT NULL or unique constraint fails, PostgreSQL puts the whole failing row (or the duplicate key) in the error’s DETAIL. pgjdbc copies DETAIL into PSQLException.getMessage() by default (logServerErrorDetail=true). F39’s audit rows carry changes JSON and actor labels, and that message reached three log outlets — Hibernate’s SqlExceptionHelper, the 500 handler and the SQS listener error path — before any application code ran. So the “log the exception class only” rules written into the audit service were already bypassed. The leak was not specific to audit_event: any table’s failing row, including a user’s email or message content, could reach the logs the same way. The test meant to prove no payload reached the logs forced a plain RAISE EXCEPTION, which carries no DETAIL, and captured only one class’s logger, so it passed.

Change made

DatasourceConfig sets logServerErrorDetail=false, the same in every environment. The failure probe now raises check_violation with a Failing row contains … DETAIL, and the test captures the root logger. It fails without the setting and passes with it; both runs are recorded.

Lesson

  • Fix the leak at the driver. Redacting in application code cannot catch a message the framework has already logged. Turn off server error detail in the JDBC driver, and check first that nothing parses DETAIL (SQLState and constraint names are in the primary message).
  • Prove it with the real error shape. A “no content in logs” test (AD-O-6) forces a realistic database error — the SQLState and DETAIL a real constraint produces — and captures the root logger, not the class under test.
  • Upstream: the pgjdbc setting and the testing rule apply to any Postgres-backed harness with a no-content logging rule.

L-072 — An ArchUnit “who calls X” rule must also walk method references and name the framework’s inherited writes

  • Date: 2026-09-26
  • Source commits in this repo: .forge/specs/F39-audit-trail-findings.md F-003; .forge/plans/F39/F39-WI-2.1-plan.md ## Notes › “Wave 2 review”; forge-et-be#70 (19d6f6f)
  • Sync target: upstream
  • Synced: pending

Problem observed

F39’s Wave 2 guard rules read only methodCallsFromSelf. ArchUnit reports a method reference (ids.forEach(connections::resetBackfill)) as a separate JavaMethodReference, so an ordinary Java idiom passed every rule. Separately, every repository inherits Spring Data’s deleteAllInBatch, deleteAllByIdInBatch and JpaSpecificationExecutor#delete / update. These run bulk JPQL or Criteria inside SimpleJpaRepository, with no @Modifying and no Hibernate entity event, so both the static rule and the runtime commit check missed them. Every probe was green, because none of the probes used either shape.

Change made

The rules walk calls and method references through one helper. *InBatch on a JpaRepository and the specification delete / update count as writes, with a parameter-type check so CrudRepository#delete(T) does not match. Each new shape has a probe that must fail. Raw java.sql.Statement writes and SimpleJdbcInsert were added in the same pass; a raw … RETURNING write run through a query method stays a named accepted gap, because ArchUnit cannot read SQL text.

Lesson

  • Walk references, not just calls. A rule about who calls a method reads codeUnitAccessesFromSelf, or joins methodReferencesFromSelf, so obj::method cannot slip past.
  • List the framework’s own writes. A write guard names the inherited bulk methods of the persistence framework explicitly. They carry none of the markers the guard looks for.
  • A probe per shape. Each shape a rule claims to catch gets a probe that must fail. A rule whose probes cover only the obvious call shape looks complete and is not.
  • State what the rule cannot see. A limit that cannot be closed, such as SQL text, is written down as an accepted gap where the next author will read it.

L-073 — A decimal request field carries the bounds of its column, or an overflow answers 500 and rounding splits the audit from the row

  • Date: 2026-09-26
  • Source commits in this repo: .forge/specs/F11-a-lead-substrate-findings.md F-003; .forge/plans/F11-a/F11-a-WI-1.2-plan.md ## Notes › “Wave PR review fixes (be#74)”; forge-et-be#74 (77f7305); BUG-256 (.forge/bugs.md)
  • Sync target: upstream
  • Synced: pending

Problem observed

F11-a’s estimatedValue was a plain BigDecimal on the create and edit request records, over a NUMERIC(14,2) column. A value of 10^12 or more reached Postgres, which raised 22003; the service translated only the duplicate-key code, so the error fell through to the generic handler as a 500. A value with three decimals was rounded by the column while the audit event recorded the value as sent, so the trail and the row disagreed, and an edit bumped the version for what was, after rounding, no change. Every test passed, because no test sent a value the column could not hold. The account’s estimatedLtv has the same gap.

Change made

@Digits(integer = 12, fraction = 2) on both request records (the precision minus the scale, and the scale), plus @PositiveOrZero once the developer decided a negative estimate has no meaning. The existing handler already maps both constraints to 400 VALIDATION_FAILED naming the field. LeadControllerIT sends each boundary as raw JSON text so no client conversion changes it: 13 integer digits, 3 decimals and -1 refused, the largest value and 0 accepted.

Lesson

  • Mirror the column on the request. Every BigDecimal request field gets @Digits(integer = p - s, fraction = s) for its NUMERIC(p, s) column, and a sign rule or an explicit decision that negatives are allowed. The database is not the validator: its refusal arrives as an unmapped exception, and its rounding arrives silently.
  • Test the edges the column enforces. A boundary test sends one value past each limit and the largest value that fits, as raw JSON so the client does not reformat it.
  • Check the other entry points. A bound on the REST record does not cover an in-process caller of the same service (F11-a’s intake, F-009); put the rule where every path passes, or list the gap.
  • Audit the stored value. Where a column can normalise a value (rounding, precision), record the value after normalising, not the value as sent.

Update — 2026-10-27

BUG-256 is a second instance of “Check the other entry points”, for a text bound rather than a decimal one: F1-e’s 1–50 character tag-name rule was checked only in TagController, and F4-d’s Pipedrive write run called TagService.findOrCreate in-process, so a label of 40 characters or more became a tag over the limit. The bound now lives in the service (TagService.MAX_NAME_LENGTH, checked by findOrCreate), and the migration leaves such a label out before the call. The bullet applies to any bound a route checks, not only a column’s.

L-074 — An approval passed on through the orchestrator does not authorise a sub-agent; changes to an approved PR branch happen in the main session

  • Date: 2026-09-26
  • Source commits in this repo: .forge/specs/F11-a-lead-substrate-findings.md F-004; .forge/plans/F11-a/F11-a-WI-1.2-plan.md ## Notes › “Wave PR review fixes (be#74)”
  • Sync target: upstream
  • Synced: pending

Problem observed

After /forge-review-pr on F11-a’s wave PR, the orchestrator dispatched a backend-implementer to apply the fixes on feature/F11-a-wave-1, the branch behind a PR two teammates had already approved. The permission check refused the agent’s edits and Gradle runs partway through (“Modify Shared Resources”). The developer then approved the work in chat; the orchestrator passed the approval to the agent, and the agent was refused again, correctly: text that reaches a sub-agent through another agent’s message carries no user authority. The run lost about half an hour, and the half-applied edits stayed uncommitted in the worktree.

Change made

The orchestrator made the remaining edits itself, in the main session where the developer’s approval was given directly, and they went through; it then ran the formatter, the targeted and full gates, committed and pushed.

Lesson

  • Fixes to an approved PR’s branch run in the main session. Review fixes after a PR has approvals, and any change that pushes to a shared or approved branch, are applied by the orchestrator, not a dispatched agent. A dispatched implementer is right for an unshared per-WI branch before review.
  • Ask the developer before the work, in the main session. When a change needs the developer’s say-so, get it in chat before starting, and do the work where the approval was given. Passing it on in a dispatch prompt or a follow-up message does not carry it.
  • Treat a sub-agent’s refusal as final. When a dispatched agent reports a permission refusal, do not re-send the same work to it with a note that the developer agreed; surface the refusal and either do the work in the main session with the developer’s direct approval, or hand it to the developer.

L-075 — On Windows, worktree removal needs long-path support and git branch -d needs a current local main

  • Date: 2026-09-26
  • Source commits in this repo: .forge/specs/F11-a-lead-substrate-findings.md F-005
  • Sync target: upstream
  • Synced: pending

Problem observed

Removing F11-a’s backend worktrees with git worktree remove failed with “Filename too long”: Gradle’s build/ output exceeds the 260-character path limit. Git had already unregistered the worktree, so a retry reported “is not a working tree” while the folder stayed on disk. Later, git branch -d refused every merged F11-a branch as “not fully merged”, although git branch --merged origin/main listed them all: -d compares with local main, and the main checkouts’ main was 74 and 86 commits behind origin/main.

Change made

The leftover folders were deleted with a \\?\-prefixed path in PowerShell (Remove-Item -LiteralPath "\\?\C:\…" -Recurse -Force), and later removals used git -c core.longpaths=true worktree remove, which succeeded. Both local main branches were fast-forwarded (git merge --ff-only origin/main, after confirming no local commits and no overlap with an uncommitted file in the checkout), and git branch -d then deleted every branch without -D.

Lesson

  • Remove a built worktree with long paths on. On Windows, run git -c core.longpaths=true worktree remove <path> for any worktree that has run a build. If a removal fails part way, check git worktree list; a folder git no longer lists is deleted with a \\?\-prefixed path.
  • Bring local main current before branch -d. Fast-forward local main to origin/main first; never switch to -D because -d refused. -d answering “not fully merged” against a stale main is not evidence that a branch is unmerged — git branch --merged origin/main is the check.

L-076 — A feature’s live tracker state is on its own branch; the checkout you happen to be in can show it as not started

  • Date: 2026-09-27
  • Source commits in this repo: .forge/specs/F5-j-cross-site-csrf-cookie-findings.md F-002
  • Sync target: upstream
  • Synced: pending

Problem observed

/forge-deliver F5-j was run from the main harness checkout, which was on another feature’s branch (feature/F38-c-spec). Its tracker.yaml showed F5-j at phase: backlog with a stub spec. F5-j was in fact at phase: review on feature/F5-j-plan, with its spec PR and both code PRs already merged. A feature’s tracker updates are committed to its spec and plan branches and reach main only when the plan PR merges, so every other branch keeps the older row. /forge-deliver Stage 0 skips reconciliation for a backlog ticket, and Stage 1 picks the entry stage from whichever tracker it reads; followed literally, it would have re-authored an approved spec.

Change made

Before acting, git worktree list showed a worktrees/F5-j/forge-et-harness worktree on feature/F5-j-plan, and gh pr list --repo altrium-io/forge-et-harness --search F5-j --state all showed spec PR #225 merged and plan PR #226 open. The session read the tracker from that worktree and continued there (Stage 15), leaving the main checkout and its uncommitted changes alone.

Lesson

  • Find the ticket’s own branch before trusting a tracker row. Before deriving a ticket’s stage, run git ls-remote --heads origin 'feature/<ticket>-*' and gh pr list --search <ticket> --state all. If a -spec or -plan branch exists, read the row from it (git show origin/feature/<ticket>-plan:.forge/tracker.yaml, or its worktree) and work in that branch’s worktree.
  • A backlog row is not evidence that nothing exists. It is the one state Stage 0 does not check, and the state every checkout off the feature’s branch will show until the plan PR merges.
  • Do not switch branches in a checkout another session is using. Work in the feature’s worktree, or create one, so uncommitted changes in the shared checkout are left alone.

L-077 — The template’s feature lookups use a sequence form that matches nothing on its own map-keyed features:

  • Date: 2026-09-27
  • Source commits in this repo: pending (the chore: map-keyed tracker feature lookups PR)
  • Sync target: upstream
  • Synced: pending

Problem observed

While reviewing a harness design, a reviewer found that the commands and skills look a feature up with yq '.features[] | select(.id == "<ID>") | …', but .forge/tracker.yaml stores features: as a map keyed by feature id, with no id field on any feature. On a map that expression matches nothing and exits 0. Verified with yq v4.53.2: yq '.features[] | select(.id=="F5-k") | .phase' printed nothing, while yq '.features["F5-k"].phase' printed backlog. The upstream template has the same form at 25 sites, and its own tracker.yaml declares features: {} — a map — so the defect is the template’s, not this project’s.

What it broke, silently:

  • Guards failed open. Every FEAT_SHIP_UNIT read (/forge-deliver Stage 1, /forge-wave-decompose step 1, forge-plan-author, forge-contract-author) returned empty, so a per-feature ship_unit override was never read.
  • Checks passed vacuously. /forge-deliver Stage 15’s all-waves-merged count read 0 for F5-c, whose three waves are not merged; it now reads 3.
  • Writes did nothing. forge-worktree-up’s yq -i writes of branch/base_branch changed nothing.
  • A fallback read the wrong level. forge-test-verify piped into the feature before its // .delivery.ship_unit fallback, so the engagement default was looked for inside the feature.

Change made

Every .features[] | select(.id == …) site was switched to .features["<ID>"]… (for a wave, .features["<ID>"].waves[] | select(.wave == <N>)). Each old/new pair was run against the real tracker and the results recorded in the PR. The rule is stated once, in .claude/rules/tracker.md § “Feature lookups in yq”, and the changed files point at it. forge-pr-open’s six --wave sites (steps 2 and 5) were fixed by altrium-io/forge-et-harness#230, which rewrote those steps with the map form.

Lesson

  • Match the lookup to the shape the template itself declares. A select(.id == …) over .features[] is only right if features are a list of objects with id; on a map, index by key.
  • A silent empty result needs a test against real data. yq exits 0 on a lookup that matches nothing, so run each tracker expression against the real tracker.yaml once before relying on it — a guard, a count or a write that “works” on no data looks exactly like one that works.
  • Upstream: port the map form to the template’s 25 sites and add the rule to its rules/tracker.md.

L-078 — A work item only a person can carry out needs its own type, and a wave’s outside dependency needs a structured gate

  • Date: 2026-09-27
  • Source commits in this repo: pending (this PR)
  • Sync target: upstream
  • Synced: pending

Problem observed

/forge-deliver assumed every work item is carried out by an agent. F5-i’s Wave 2 is an evidence-only check — signing in to the real Microsoft tenant as a test account — that no agent can do. Stage 7 would have dispatched it to an implementer or general-purpose agent, which might then have written evidence of a run that never happened. The F5-i Decomposition Plan worked around this by running Wave 2 by hand and forbidding /forge-deliver F5-i in between. Separately, a dependency that mattered to one wave only (F5-i Wave 2 on F5-k; F11-a Wave 1 on F39’s audit service) had nowhere to live except the feature-wide blocked_by, so both plans ran their checks by hand. Building the fix also surfaced two existing faults on every wave: Stage 14 read wave PR state with gh pr view --head, which is not a valid flag, so every state read empty; and the tracker lookups in forge-pr-open --wave used .features[] | select(.id == …), which matches nothing on the map-keyed tracker and exits 0.

Change made

Designed in .forge/design/harness/person-run-work-items.md and implemented across /forge-deliver, /forge-wave-decompose, forge-pr-open, forge-plan-author, plan-reviewer, the plan and Decomposition Plan templates, the tracker schema and rules, the metrics README and the dashboard:

  • a type: manual WI (tier: none, impl_status: with-person, run_by, handoff_sha) that lives only in an all-manual wave and is never dispatched; its plan is a run sheet, and the person’s results go in a record file of their own on a harness wave branch;
  • a manual-wave path in Stage 7 (M1 hand-off, M2 check and confirm, M3 harness-only wave PR), with every tracker write kept in the orchestrator’s checkout on the plan branch;
  • an optional waves[].gate list of structured checks (feature phase, wave merged, PR merged, text on main), each evaluated by a fixed read-only command on validated values — there is no free-form command form;
  • Stage 14 and forge-pr-open --wave fixed to read PR state with gh pr list --head and a single reduction, to use the map-keyed tracker lookup, and to refuse a wave with an empty touched_repos union.

Lesson

  • Model person-run work as its own type, not a flag on an agent type. Every dispatch site keys on type, so a new value that no site selects is never dispatched — a missed site fails safe. An executor: field on an existing type would have failed open at every site that forgot to read it.
  • No agent writes or completes evidence of a run it did not do. The person’s record is a separate file on its own branch; the orchestrator only checks that it exists and is complete, and asks the person to confirm.
  • Never evaluate a command taken from data. A word-based rule for “read-only commands” both refused a legitimate check and admitted a destructive one. A fixed set of named kinds, each with one fixed read-only command and validated values passed as quoted variables, covers the real cases.
  • Check a lookup against the real data shape before trusting its exit status. A yq or gh call that matches nothing or errors into /dev/null exits as if it succeeded; run it once on a scratch copy of the real file.

L-079 — Behaviour that depends on IAM needs the AWS reference read at plan time, because the local stack does not enforce IAM

  • Date: 2026-09-28
  • Source commits in this repo: .forge/specs/F38-c-guardduty-scan-adapter-findings.md F-001
  • Sync target: upstream
  • Synced: pending

Problem observed

F38-c’s scan-result consumer drops a result when neither the attachment row nor the stored object exists, and it checks the object with S3 HeadObject. The spec granted the task role only s3:GetObject. The AWS HeadObject reference says that without s3:ListBucket a missing key answers 403, not 404. In the cloud, every drop would have failed, been redelivered, reached the dead-letter queue and raised the alarm. LocalStack does not enforce IAM, so every local test passed. The gap was found only because the WI-1.1 plan review read the AWS reference.

Change made

Spec Rev 2 added s3:ListBucket to the task-role grant (F38-c FR-10), and F38-b’s spec carries it as an input. ObjectStore.exists maps only 404 to “absent” and lets a 403 propagate, so a role with the wrong grants fails loudly instead of dropping results.

Lesson

  • When a code path depends on what an AWS call returns under a given IAM grant, read that call’s AWS reference during plan review and name the grant the code needs. The local stack stands in for exactly the part that differs (IAM), so no local test can find this.
  • Map only the documented “absent” answer to absent. Treat any other error, 403 included, as a failure, so a mis-granted role cannot silently turn into a data decision.

L-080 — Cloud SDK error messages carry resource names that LocalStack’s error messages do not; strip the cause before a listener logs it

  • Date: 2026-09-28
  • Source commits in this repo: .forge/specs/F38-c-guardduty-scan-adapter-findings.md F-002
  • Sync target: upstream
  • Synced: pending

Problem observed

Spring Cloud AWS logs a failing SQS listener’s exception, cause chain included, at ERROR on every redelivery. Two causes in F38-c’s consumer could put an object key or bucket name in those lines. A Jackson parse error quotes the token it failed on, which may be part of a key. An AWS SDK network or timeout error names the virtual-hosted host <bucket>.s3.<region>.amazonaws.com. LocalStack uses path-style localhost, so the integration test’s leak check could not see the second one. This is the same shape as L-071 (the Postgres driver puts the failing row in its messages), on a different library.

Change made

MalformedScanEventException replaces the Jackson exception rather than wrapping it, and S3ObjectStore.exists throws ObjectStoreCallFailedException with no cause (forge-et-be a9b45e1).

Lesson

  • On any code path whose exceptions a framework logs with their cause chain (an SQS listener, a scheduled job, an error handler), throw a new exception with a fixed message and no cause when the underlying library’s message can contain record or resource identifiers.
  • A leak check run against LocalStack does not prove the cloud message is clean. LocalStack’s hosts and error texts differ from AWS’s; read the SDK’s real message format, or register the check as cloud-gated.

L-081 — Reproduce a CI tool’s finding locally, with the same tool and version, before changing code to satisfy it

  • Date: 2026-09-28
  • Source commits in this repo: .forge/specs/F38-c-guardduty-scan-adapter-findings.md F-004; rule added to .claude/CLAUDE.md § Boundaries by forge-et-harness#262; BUG-179 (forge-et-fe#239 — the frontend’s scan was never scoped, and one branch’s false positive failed every forge-et-fe PR; BUG-180 is the same step in forge-et-pwa, fixed by forge-et-pwa#73)
  • Sync target: upstream
  • Synced: pending

Problem observed

The forge-et-be Fast lane reported “leaks found: 1” from gitleaks, with no detail because the step runs with --redact and without -v. The orchestrator guessed the finding was AWS’s sample eTag in a test helper, changed the helper and a contract document, and added fingerprints to .gitleaksignore. Running the same gitleaks version locally showed the eTag was never a finding. The real finding was another feature’s false positive on its own unmerged branch: the CI step scanned every fetched branch, so one branch’s finding failed every other PR.

Change made

The eTag change was reverted (forge-et-be eb9739c). forge-et-be#83 scoped the scan to --log-opts=HEAD, with a self-test.

Lesson

  • Before changing code to satisfy a CI finding, run the same tool at the same version locally and see the finding yourself. A redacted or summarised CI log does not identify the finding, and a guessed fix can both change correct code and leave the real cause in place.
  • Scope a repository scanner to the commits the PR brings. A scan over every fetched branch reports other branches’ findings as this PR’s.

L-082 — In a workspace shared by parallel sessions, give git the path with git -C; never cd <path>; git …

  • Date: 2026-09-28
  • Source commits in this repo: .forge/specs/F38-c-guardduty-scan-adapter-findings.md F-007; rule added to .claude/rules/git-conventions.md § Worktree Commands by forge-et-harness#262
  • Sync target: upstream
  • Synced: pending

Problem observed

The orchestrator ran cd <worktree>; git fetch …; git checkout --detach origin/main, with ; between the commands. The worktree had already been removed, so the cd failed and the checkout ran in the shared harness checkout that other sessions use, detaching its HEAD. Nothing was lost only because HEAD, local main and origin/main were the same commit and the tree was clean.

Change made

git checkout main restored the shared checkout. forge-et-harness#262 added the rule to .claude/rules/git-conventions.md § Worktree Commands.

Lesson

  • Pass the path to git with git -C <path> so a missing directory makes git fail instead of running somewhere else. Where a directory change is unavoidable, chain it with &&, never ;.
  • A command that changes state (checkout, reset, commit) is the one to protect. A read in the wrong directory gives a wrong answer; a write in the wrong directory changes another session’s work.

L-083 — A migration that adds the first foreign key into a table breaks every TRUNCATE of that table in the tests

  • Date: 2026-09-29
  • Source commits in this repo: .forge/specs/F26-a-standards-price-substrate-findings.md F-001; F26-a-WI-1.1 plan revision 1
  • Sync target: upstream
  • Synced: pending

Problem observed

F26-a’s V29 migration added the first foreign keys into buying_standard. The full gate then failed 84 of 2,741 tests with one cause: two integration specs outside the work item’s file list cleaned up with TRUNCATE buying_standard, which PostgreSQL refuses once another table references it. The fix needed a plan revision because neither file was in scope.

Change made

Both cleanups became DELETE FROM buying_standard, with a comment saying why, under F26-a-WI-1.1 plan revision 1.

Lesson

  • When a plan adds a foreign key into an existing table, grep the tests for TRUNCATE <table> at planning time (grep -rn "TRUNCATE <table>" src/test) and list every hit in ## Files to Modify. TRUNCATE … CASCADE would also clear the referencing rows, so DELETE is the safe replacement.
  • The same applies to any statement the new constraint makes illegal — a raw INSERT of a now-orphan row, a DELETE of a referenced row — in specs the plan did not expect to touch.

L-084 — A response-time limit measured on a developer laptop measures mostly the laptop; state where the binding measurement is taken, and measure a baseline beside it

  • Date: 2026-09-29
  • Source commits in this repo: .forge/specs/F26-a-standards-price-substrate-findings.md F-003; F26-a spec Rev 3; .forge/cloud-gated-validation.md §B “F26-a”; rule added to .forge/test-strategy.md § Performance Baselines by the F26-a reflect-framework PR
  • Sync target: upstream
  • Synced: pending

Problem observed

F26-a’s NFR-2 set response-time limits (100 ms and 150 ms) measured on the local stack. Two readings on the developer’s laptop each breached one shape by about 10 ms, a different shape each time, and every median doubled between them. Only a third, diagnostic run showed why: endpoints the feature does not touch already took 43–50 ms on that laptop, while the database part of the new reads was 0.2 ms. Settling it took a spec revision.

Change made

Spec Rev 3 kept the limits and moved the binding measurement to the dev environment, registered as a cloud-gated row owned by F38; the local readings stay recorded as evidence.

Lesson

  • A spec that sets a latency limit says where the binding measurement is taken — a deployed environment, not a shared laptop — and treats a laptop reading as evidence only.
  • Every latency measurement records a baseline in the same session: an endpoint the feature does not touch, called the same way, interleaved with the new ones. The difference is the feature’s cost; without it a breach cannot be attributed.
  • Warm every shape before measuring any, and use 127.0.0.1 rather than localhost on Windows, which can add 7–18 ms per call.

L-085 — Parallel agents on one machine share a lock for their full-suite runs and timing sessions

  • Date: 2026-09-29
  • Source commits in this repo: .forge/specs/F26-a-standards-price-substrate-findings.md F-004 (F26-a Wave 2 dispatch); rule added to .claude/lib/forge-deliver/agent-prompt-template.md and .claude/commands/forge-deliver.md Stage 7 Step 3 by the F26-a reflect-framework PR
  • Sync target: upstream
  • Synced: pending

Problem observed

/forge-deliver dispatched three backend work items at once on a laptop with 16 GB of RAM and 8 GB for Docker. Each would end with a 25–40 minute ./gradlew check using Testcontainers, and one also had to take response-time readings that a concurrent build would slow down.

Change made

The dispatch prompt gave every agent one directory lock: mkdir <worktrees>/<ticket>/.heavy-run.lock, write an owner file (work item and UTC time), wait with a sleep while it is held, treat it as abandoned after 90 minutes, and remove it when the run ends. Targeted --tests runs did not need it. The three full checks and the timing session ran one at a time while the code work overlapped; after a power loss, the owner file identified the stale lock.

Lesson

  • When a wave dispatches more than one agent on the same machine, the dispatch prompt names one shared lock for every full-suite run and every timing measurement. mkdir is atomic on every platform the team uses, and the owner file makes a stale lock safe to clear.
  • Tell agents that a Gradle command longer than the tool’s 10-minute limit runs detached, with its exit status written to a file and polled, never through a pipe (L-043).

L-086 — When the plan branch has already merged, the orchestrator’s tracker writes go on the harness wave branch, cut at dispatch

  • Date: 2026-09-29
  • Source commits in this repo: .forge/specs/F26-a-standards-price-substrate-findings.md F-005 (F26-a Wave 2); rule added to .claude/commands/forge-deliver.md Stage 0 Step 0a by the F26-a reflect-framework PR
  • Sync target: upstream
  • Synced: pending

Problem observed

/forge-deliver writes its Stage 0 heals and Stage 7 dispatch fields on feature/<ticket>-plan. F26-a’s Wave 2 plans shipped in their own plan PR, which had merged and been deleted before dispatch, so no plan branch existed, and the shared main checkout must not take the writes.

Change made

The orchestrator cut the harness wave branch feature/F26-a-wave-2 from origin/main at dispatch, in its own worktree, committed the heal and dispatch writes there, pushed it, and cut each work item’s harness branch from it rather than from main. Each work item’s /forge-pr-open then found impl_status: dispatched to flip. Stage 11 merged the work items’ harness branches back into it, and it became the harness wave PR. The price was hand-resolved conflicts on the global last_updated and the feature notes line at each merge.

Lesson

  • If no open plan branch exists at dispatch, cut the harness wave branch at dispatch, not at Stage 11, and base the work items’ harness branches on it, so every branch starts from the dispatch state.
  • Expect last_updated and feature-notes conflicts at Stage 11 and resolve them by keeping the later timestamp and every notes entry. A work item that writes its notes on its own work-item entry, not the feature line, avoids the second.

L-087 — Bound every LocalDate request value to PostgreSQL’s range before it reaches a query

  • Date: 2026-09-29
  • Source commits in this repo: .forge/specs/F26-a-standards-price-substrate-findings.md F-007; forge-et-be#110 (1859fb3); rule added to .forge/design/coding-standards.md §2 (“Validate at the edge”) by the F26-a reflect-framework PR; BUG-074 (the shared FieldType.DATE / INSTANT filter parsing, forge-et-be#135) and BUG-075 (LeadCreateRequest.receivedAt, forge-et-be#137 — the value this rule missed)
  • Sync target: upstream
  • Synced: pending

Problem observed

Spring’s @DateTimeFormat(iso = DATE) parses with SignStyle.EXCEEDS_PAD, so it accepts signed years of five or more digits (+9999999-01-01, -10000-01-01). PostgreSQL’s date type refuses them, so F26-a’s ?asOf= answered 500 INTERNAL_ERROR instead of 400. The backend review found it; two new test rows reproduced it before the fix.

Change made

BuyingStandardPriceController refuses a year outside 1…9999 as 400 VALIDATION_FAILED with an OUT_OF_RANGE entry on asOf. The shared FieldType.DATE filter parsing has the same gap and is offered as a separate BUG task.

Lesson

  • Any request parameter or filter value bound to LocalDate (or Instant) is range-checked before it reaches SQL — years 1…9999 is the simple bound — and the endpoint’s integration spec has a row with an out-of-range year.
  • Send such a value as a URI variable in the test (?asOf={asOf}): a literal + in a query string arrives as a space and turns the case into an ordinary type mismatch, hiding the bug.

L-088 — An app-wide multipart setting reaches code that runs before sign-in

  • Date: 2026-09-29
  • Source commits in this repo: .forge/specs/F4-a-pipedrive-import-engine-findings.md F-001; forge-et-be#112 (1cd964f, reverted by ca39d62); F4-a spec Rev 2; BUG-042 and BUG-076 (.forge/bugs.md, the header-only CSRF fix, which found three more places; its second review found two more, fixed in forge-et-be d4e9230)
  • Sync target: upstream
  • Synced: pending

Problem observed

F4-a had to keep its uploads off disk, so option A set spring.servlet.multipart.file-size-threshold to 26 MB for the whole app. The PR review found that a multipart POST without the X-XSRF-TOKEN header makes Spring Security’s CSRF handler call request.getParameter("_csrf"), which makes Tomcat parse every part inside CsrfFilter, before authorization. Each anonymous request to any path could then hold about 27 MB of heap until its 403.

Change made

The developer chose option C: the spec now allows the container’s temporary part file, which lasts only the request, and the threshold stays at its default. A header-only CSRF request handler is raised with the lead as separate hardening.

Lesson

  • Before changing a servlet-container or multipart setting for one feature, ask what else parses the request before your controller — security filters run first, for every path, and for anonymous callers.
  • Prefer spending disk over heap for data an unauthenticated caller can send: the disk is far larger, and a temporary file is deleted per request.
  • Any parameter read before authorization parses a multipart body, not only the CSRF one (BUG-042). Fixing _csrf alone left two more: the refusal’s own error dispatch (DispatcherServlet resolves multipart eagerly unless spring.servlet.multipart.resolve-lazily is set) and Spring’s OAuth2 filters, which read code, state or action to recognise their traffic — and a caller passes the double-submit CSRF check by sending the same made-up value as cookie and header. Boot’s FormContentFilter, ahead of the security chain, read a PUT/PATCH/DELETE form body whole into the heap (BUG-076); it is off now. Find the readers with a thread dump taken during a slow upload (jcmd <pid> Thread.print, look for Request.parseParts), not by reading code.
  • Run such a check in the shape that is deployed. Plain local has no OAuth2 legs, so the live check there missed the OAuth2 filters; the test profile, laptop mode and cloud have them. And prove “the body was not read” against a real Tomcat with a partly sent body (the answer must arrive before the rest is sent) — MockMvc never parses a multipart body, so it cannot fail.
  • On a path open to signed-out callers, the handler itself runs before sign-in. Checking only the filters ahead of authorization missed POST /api/v1/mailbox/notifications (permitAll and exempt from CSRF): its @RequestParam validationToken made Spring parse a multipart body for anyone. So list every permitAll and CSRF-exempt path and read each handler’s bindings (@RequestParam, @RequestPart, @ModelAttribute); where the real caller never sends multipart, refuse it in the path’s authorization rule. Check every method, GET included: Spring and Tomcat parse a multipart body on any method, a GET needs no CSRF token, and the actuator reads the whole parameter map on every call, so a signed-out multipart GET to /actuator/health stored an upload until the third review of forge-et-be#139.
  • A read with a size limit is still a finding when a signed-out caller can trigger it. Tomcat read a form POST with a matching made-up CSRF pair up to max-http-form-post-size (2 MB by default) on every connection; the first review accepted that as a Nit, the second raised it to Important. Set such a limit to what the API needs (64 KB here), and not to 0, because Tomcat counts a multipart request’s text fields against it.

L-089 — Editing a PR’s body cancels the CI run its push started

  • Date: 2026-09-29
  • Source commits in this repo: .forge/specs/F4-a-pipedrive-import-engine-findings.md F-003; forge-et-be#112
  • Sync target: upstream
  • Synced: pending

Problem observed

gh pr edit starts a new pull_request run and cancels the one the push started, so the checks list briefly shows CANCELLED. A poll that stops on any finished state stops on the cancelled run.

Lesson

  • Edit a PR’s body before pushing, or wait on the newest run by its ID: gh run list --branch <b> --limit 1, then gh run watch <id> --exit-status.

L-090 — A real backend gate turns the build cache off, and the Groovy compiler needs 1 GB

  • Date: 2026-09-29
  • Source commits in this repo: .forge/specs/F4-a-pipedrive-import-engine-findings.md F-004; forge-et-be ea5d4e8
  • Sync target: project-only
  • Synced: pending

Problem observed

./gradlew clean check finished in 34 seconds from the build cache, which proves nothing about the code. Separately, the test tree (about 63,000 lines of Groovy) stopped compiling in Gradle’s 512 MB default Groovy compiler heap once F4-a’s tests landed (512m fails, 640m passes).

Change made

build.gradle sets groovyOptions.forkOptions.memoryMaximumSize = '1g' on every GroovyCompile task.

Lesson

  • The gate whose result is evidence is ./gradlew check --no-build-cache, run on its own line with echo "EXIT=$?", with the counts read from the JUnit XML.
  • When :compileTestGroovy fails with Java heap space, it is the size of the whole tree, not one test: raise the compiler heap in build.gradle, and check the CI runners’ memory.

L-091 — Parallel work items must not all edit the feature’s shared tracker notes line

  • Date: 2026-09-29
  • Source commits in this repo: .forge/specs/F4-a-pipedrive-import-engine-findings.md F-007; harness#276, harness#280
  • Sync target: upstream
  • Synced: pending

Problem observed

Each F4-a work item’s harness branch appended to the same features["F4-a"].notes string and bumped the same feature last_updated, so every wave integration conflicted on those two lines.

Lesson

  • A work item records its facts in its own workitems[] row and its own plan; the shared feature notes line and last_updated are written only by the orchestrator, at wave boundaries. (A rule change to .claude/rules/tracker.md and the implementation-agent prompt template is proposed as a follow-up.)

L-092 — Read the clock before writing any timestamp

  • Date: 2026-09-29
  • Source commits in this repo: .forge/specs/F4-a-pipedrive-import-engine-findings.md F-008
  • Sync target: upstream
  • Synced: pending

Problem observed

During a long overnight run the orchestrator wrote tracker and metrics timestamps dated the next day, and times ahead of the real clock, estimated from the conversation, and had to correct them.

Lesson

  • Run date -Iseconds before every tracker last_updated, metrics ts or dated note, and copy the value; never estimate the time from the conversation.

L-093 — git branch -d compares against a stale local main; point the branch at origin/main

  • Date: 2026-09-29
  • Source commits in this repo: .forge/specs/F4-a-pipedrive-import-engine-findings.md F-010
  • Sync target: upstream
  • Synced: pending

Problem observed

git branch -d checks a branch against its upstream if it has one, otherwise against the current HEAD. The shared checkouts’ main was 150+ commits behind origin/main and could not be updated (another session’s uncommitted work was in it), so -d refused every merged F4-a branch. On Windows, git worktree remove also unregistered seven worktrees but left their folders on disk.

Lesson

  • To delete merged branches without touching a shared checkout: confirm each with git merge-base --is-ancestor <b> origin/main, then git branch --set-upstream-to=origin/main <b> and git branch -d <b> — this keeps -d’s safety check against the real trunk. Never fall back to -D.
  • After git worktree remove on Windows, check the folder is gone; if it is unregistered but still there, confirm it holds no work before removing it by hand.

L-094 — A bug id taken on a feature branch is not reserved; check main and every branch, or file on main

  • Date: 2026-09-29
  • Source commits in this repo: .forge/specs/F40-accessibility-responsive-gate-findings.md F-001
  • Sync target: upstream
  • Synced: pending

Problem observed

F40 filed its bugs in tracker.yaml and bugs.md on feature/F40-plan. Other features filed bugs on main in the meantime. Two merges of main into the plan branch each found F40’s ids already taken, so one bug was renumbered twice (BUG-035 → BUG-037 → BUG-043) and every F40 document citing it was edited. L-057 already warns that ids can collide with a parallel session; the checks used here read only origin/main, and once a de-duplicated listing hid the clash.

Lesson

  • Before taking a BUG-NNN, take the highest id across origin/main and every remote branch’s tracker.yaml (git show <ref>:.forge/tracker.yaml | grep -oE 'id: BUG-[0-9]+' per ref), plus any id an open harness PR claims — never a sort that collapses the listing by branch.
  • Better, for a bug found mid-feature: file it on main in its own small harness PR and cite the merged id, so the id is final before anything references it.

L-095 — A guard that parses shell commands needs an adversarial review, and an accepted-gaps list

  • Date: 2026-09-29
  • Source commits in this repo: .forge/specs/F40-accessibility-responsive-gate-findings.md F-002; .forge/bugs.md BUG-059 (a redirection after a group, found by the BUG-044 probe pass); BUG-061 (a $(…) inside ${…} not read, found by the adversarial review of the BUG-044 change); BUG-062 (a shell or cd behind a prefix command); BUG-064 (standard-input shells named by -, a stdin device path, source, a flag taking an argument, or a shell outside the list, found by the second adversarial review of the BUG-044 change); BUG-098 (a | or & after an if, while, until, for or select statement, or before a ! or time prefix, recorded on the wrong item, found by the review of the BUG-059 fix and by probing the BUG-098 fix)
  • Sync target: upstream
  • Synced: pending

Problem observed

The browser-gate hook (about 2,000 lines of bash and PowerShell parsing) passed its own 162 unit tests. A fresh reviewer told to find ways around it found eight bypasses in one pass; a verification pass found three more, narrower ones; the live run found a false refusal (a case statement). Each round cost less to find and mattered less, and the CI check was the real enforcement throughout.

Lesson

  • Review a command-parsing guard adversarially (“find a command that gets past it”, “find a legitimate command it refuses”) before merge, not only against its design cases — its own tests cover what its author thought of.
  • Stop at a stated point. Fix what a plausible command hits; list the contrived forms (function bodies, env -S, argument reordering through another program) as accepted gaps in the guard’s README, and rely on the server-side check for the rest. A shell parser is never complete.

L-096 — A headless claude -p session is a real Claude session for testing hooks and skills

  • Date: 2026-09-29
  • Source commits in this repo: .forge/specs/F40-accessibility-responsive-gate-findings.md F-003
  • Sync target: upstream
  • Synced: pending

Problem observed

F40’s live proof (WI-2.2) was planned as person-run because the orchestrator’s session had loaded its hooks and skills before the feature merged, and a check of “the hook from a real Claude session” seemed to need a person opening one.

Lesson

  • From the orchestrator’s Bash tool, claude -p "<prompt>" --allowedTools Bash (or PowerShell; add --add-dir <path> for a second repo) starts a fresh session that loads the current .claude/ hooks and skills from disk, runs what it is told and reports what happened — including a hook’s refusal text. Run it from the checkout whose .claude/ is under test.
  • Tell it to run only the given command and stop after a refusal, so it does not work around the thing being tested.
  • With that, a “manual” live-proof work item can often be an owner-accepted agent run: the record names the runner and quotes the owner’s acceptance.

L-097 — Run every CI-only check locally before a PR is ready

  • Date: 2026-09-29
  • Source commits in this repo: .forge/specs/F40-accessibility-responsive-gate-findings.md F-004
  • Sync target: upstream
  • Synced: pending

Problem observed

scripts/check-anonymous-todos.mjs runs only in the app repos’ Fast lane. A test fixture holding the string 'TODO' passed pnpm check, pnpm test and the full browser gate, then failed both F40 wave PRs’ first CI run; fixing one word cost two more gate runs to re-stamp the PRs.

Lesson

  • Before marking a PR ready, run each Fast-lane step that no local script covers — read the workflow’s run: lines once and list them — or fold them into pnpm check, so a cheap check does not fail after an expensive one has passed.

L-098 — A button that starts a full-page redirect stays busy until the page is gone

  • Date: 2026-09-30
  • Source commits in this repo: .forge/bugs.md BUG-024 (fixed in forge-et-fe#56), BUG-027 (forge-et-fe#57); the sync-lapse notice’s “Reconnect” (forge-et-fe#55)
  • Sync target: upstream
  • Synced: pending

Problem observed

Five buttons in forge-et-fe had the same defect, fixed in three separate PRs: the sync-lapse notice’s Reconnect (forge-et-fe#55); the mailbox Connect and Reconnect buttons and the ?connect=failed banner’s “Try connecting again” (forge-et-fe#56, BUG-024); and “Sign in with Microsoft” (forge-et-fe#57, BUG-027). Each called location.assign(...) to start a Microsoft sign-in or consent. The first four cleared their busy state in a finally block; the sign-in button had no busy state at all. location.assign returns before the browser leaves the page, so each button was usable again at once, and a second press sent a second authorization request to Entra. Each was found and fixed on its own; nothing told the author of the next button.

Change made

frontend-reviewer dimension 13 checks for it. The fixes use one rule: the button is busy from the press until the page is gone; it becomes usable again only if starting the redirect throws, or on pageshow with persisted: true (the page restored from the back/forward cache after Back).

Lesson

  • Any control whose action navigates away from the SPA (location.assign, location.href =, a form post to another origin) keeps its busy state until the page unloads. Never clear it in finally.
  • Restore it only on failure or on a back/forward-cache restore, and test both with the dev-only in-place path switched off, because a stub that re-renders in place hides the defect.

L-099 — Every cache names the event that clears it, and in-memory state is per ECS task

  • Date: 2026-09-30
  • Source commits in this repo: .forge/bugs.md BUG-016 (fixed in forge-et-be#39), BUG-050 (fixed in forge-et-be#138), BUG-067 (fixed in forge-et-be#154); BUG-025 (forge-et-be#60) for the per-task reach; BUG-083 and BUG-085 (fixed in forge-et-fe#132) for the browser’s query cache
  • Sync target: upstream
  • Synced: pending

Problem observed

Two backend caches were missing the step that clears them. BUG-016: after a user re-consented, MailboxTokenService kept serving the access token cached under the previous consent for up to an hour, because connectOrUpdate never invalidated it. BUG-050: MailboxIngestService.folderCache is never evicted, so after a replaced mailbox is reconnected, its Drafts, Junk and Deleted Items can be ingested until the process restarts. The second also shows a gap in the obvious fix: the backend runs as more than one ECS task, and clearing an in-memory map reaches only the task that does the clearing. BUG-050’s first recorded fix cleared the cache in connectOrUpdate, on the task that served the reconnect request, while the back-fill it enqueues can run on any task; review caught it. The second recorded fix cleared it where the back-fill starts from a reset cursor, and a second review caught that too: a back-fill is several queued runs of up to 20 pages, and each continuation can land on another task. BUG-016’s and BUG-025’s tokens.invalidate calls have the same one-task reach, and are acceptable only because a cached access token lives no longer than the token itself (its expiresIn less a two-minute margin — about 60 to 90 minutes for an Entra token), which is the time limit the lesson asks for.

The frontend had the same gap. BUG-083: F5-d installed one TanStack QueryClient for the app and nothing cleared it, so after a stub sign-out and a sign-in as another user in the same tab, the second user’s screens rendered the first user’s cached reads. BUG-085: clearing the cache is not enough on its own. When the session’s /me re-read returns a different user while the screens stay mounted, QueryCache.remove does not notify a query’s observers, so a mounted useQuery keeps showing the value it already holds.

Change made

backend-reviewer checks for both: the cache row under § Concurrency & immutability, and the per-task row under § STACK-SPECIFIC CHECKS. BUG-050’s fix clears the entries at the start of every back-fill run, on whichever task runs it, and gives them a one-hour time limit.

In forge-et-fe, SessionProvider clears the query cache before it publishes a sign-out, an expiry or a different user, and AuthenticatedGate keys the authenticated screens by the user id so a change of user remounts them (forge-et-fe#132). frontend-reviewer § STACK-SPECIFIC CHECKS flags per-user browser data that is not cleared on those events.

Lesson

  • When adding a cache, write down the events that make an entry wrong (a re-consent, a reconnect, a role change) and clear the entry on each of them, with a test that counts the calls behind the cache, not the values it returns.
  • An in-memory cache is per ECS task. Clearing it on one task does not reach the others, so either give the entries a time limit that bounds how long they can be wrong, keep the state in the database, or store in each entry what it was built from and check that on every hit, so any task can tell it is stale (BUG-067: a cached token keeps its issued scopes and the connected_at of its consent). When the work that reads the cache is queued, clear it where each job runs — every run, when the work is split into continuations — not where the request that queued it ran.
  • Clearing a cache does not change a value a reader already holds. In the browser, per-user data is wrong once the session ends or the user changes; clear it before the new session renders, and make the readers that are already on screen read again (in forge-et-fe, by remounting them).

L-100 — The local stub hid bugs that only the real Microsoft path shows; walk the real path early

  • Date: 2026-09-30
  • Source commits in this repo: .forge/bugs.md BUG-022 (forge-et-be#122), BUG-037 (forge-et-be#116), BUG-040 (forge-et-be#117), BUG-047 (forge-et-be#119), BUG-048 (forge-et-be#120), BUG-049 (forge-et-be#121)
  • Sync target: upstream
  • Synced: pending

Problem observed

Sign-in, the shell and the mailbox were done locally for about a week, on the local profile’s stub login and stub mailbox, with every test green. On 2026-09-29, the first day of real Entra sign-ins on laptops (F5-i), five bugs appeared in one day: a refused sign-in showed no message (BUG-037); test accounts could not be switched (BUG-040); every user’s first mailbox connect landed on the API’s raw JSON (BUG-047, high); a mailbox Microsoft cannot read showed as connected and failed silently (BUG-048); and the consent showed Microsoft’s account picker (BUG-049). BUG-022 (the real consent path checks no permission while the stub path does) is the same shape, found by reading the code. BUG-047’s record says the test harness itself hid the bug: the round-trip test called the completion step directly and skipped the saved-request redirect a browser goes through.

Change made

test-strategy.md § Microsoft Graph now asks for the live walk as soon as the credentials exist and after any change to a sign-in or consent path, not only once per phase. backend-reviewer § Auth coverage on new endpoints flags a stub path and a real path that enforce different rules.

Lesson

  • Walk the real provider path as soon as credentials exist, before calling the work done, and again after any change to it. The stub proves the rules; only the real path proves the redirects, the provider’s refusals and its error codes.
  • A test that reaches a step by a shortcut must say which production step it skips. A test that calls a handler directly, rather than going through the filter chain a browser meets, cannot see a bug in the steps it skipped.
  • The stub and the real path enforce the same rules. A check that exists only on one of them is a finding.

L-101 — A browser test waits for the page to settle, not for an element to appear

  • Date: 2026-09-30
  • Source commits in this repo: .forge/bugs.md BUG-033 and BUG-034 (fixed in forge-et-fe#63), BUG-039 (forge-et-fe#81); BUG-045 (open) may be the same; BUG-084 (forge-et-fe#132, a Vitest case that read sessionStorage before the effect that clears it); BUG-115 (forge-et-fe#178, a request wait after an action that joined a shared query’s in-flight read); BUG-127 (forge-et-fe#206, an axe scan of the lead view’s match dialog while it faded in — BUG-033’s cause again); BUG-150 and BUG-151 (forge-et-fe#224: a click that scrolls fires its scroll event after the click, and a lazily loaded panel shifts the controls below it); BUG-135 (forge-et-fe#255: a Vitest case clicked again before Tiptap’s requestAnimationFrame focus landed, which then took focus back); BUG-134 (forge-et-fe#256: BUG-034’s gap again, after Escape on the compose dialog, this time fixed in the product); BUG-138 (forge-et-fe#260, forge-et-pwa#76: the shared page check listed the running animations once, and a transition that started while it waited was scanned part-way — the wait now lists the page again until nothing is running); BUG-230 (forge-et-fe#308: size-matrix states clicked in a lead panel before the lazy panels above it — F11-d’s AI summary among them — had mounted and grown, BUG-151’s cause again); BUG-233 (forge-et-fe#313: size-matrix states on /pricing left the page’s warnings read, added later by F26-g, to the shared backend, and warning cards that landed after a row menu opened moved it off-screen); BUG-239 (forge-et-fe#332: the Weekly prices state tests left the same warnings read to the backend, and a card that landed after the hover moved Published out from under the pointer, so its tooltip never opened); BUG-260 (forge-et-fe#344: the lead view’s AC-20 rows acted before its lazy panels had read and before Approve & send, which has no loading marker, had mounted — the action moved Archive / nurture under the click, and a panel read answering 404 after the test’s reassignment closed the view); BUG-275 (forge-et-fe#356: expectNoAxeViolations, the axe-only check, skipped the shared wait for animations, and scanned the templates row menu while it faded in — BUG-127’s cause again; it now waits too); BUG-282 (forge-et-fe#359: the account form’s two columns measured one box at a time while the New account dialog zoomed in, so their top edges differed by more than the 1px allowed); BUG-356 (forge-et-fe#457, forge-et-pwa#114: the shared page check’s animation wait ended at its 5-second cap on a page still fading in, likely because the page drew no frames, and axe scanned the dialog part-way — at the cap it now finishes an animation that ends within the cap and fails on one that ends later); BUG-366 (forge-et-fe#459: the Email panes test gave the list 5 s from goto, covering the page load, the session, the route chunk and the connection read before the list read — it now waits for the list read’s answer first); BUG-351 (forge-et-fe#462: the mailbox keyboard rows pressed once the controls were visible, while the screen’s own re-read of the cached connection still kept every action busy and refusing a press); BUG-472 (forge-et-fe#576: six Email retry tests checked the heading’s focus as soon as the list or folder tree appeared, while the screen moves focus one render later, after the retry settles — BUG-135’s case again); BUG-469 (forge-et-fe#577: the roles AC-24 next-request test saved before the role page’s holders read had ended, so under load that read was refused after the save, the /me re-read showed the no-access state, and the list read the test waited for was never sent — BUG-115’s case again); BUG-470 (forge-et-pwa#164: the Leads kept-search test typed right after a section switch that React Router applies in a transition, so the keys went into the old section’s search box as it unmounted); BUG-489 (forge-et-fe#598: tests in six files checked a row menu’s action straight after the click, while RowActionsMenu runs it from Radix’s onCloseAutoFocus, on a timer after the menu has gone); BUG-519 (forge-et-fe#604: the same race in ten more files, mostly through each file’s menu helper, which now waits for what its item opens); BUG-494 (forge-et-pwa#194: the 409 test changed the double’s lead while the drawer’s own read of it could still reach the double, so a late read brought the new version and the convert was not refused — BUG-469’s case again)
  • Sync target: upstream
  • Synced: pending

Problem observed

Three browser-test bugs had the same cause: each test acted or checked as soon as an element was visible, while the page was still changing. BUG-033 (failing on every serial run): the axe scan ran while a dialog was still fading in, so it measured the buttons partly transparent. BUG-034 (failing on every serial run): the test pressed Space after Esc, before the dialog’s close event had reached React. BUG-039 (intermittent, in at least two rows of one file): the test expected an empty inbox while a background back-fill could still add mail. None was a product defect, but each cost a debugging session and made a red run untrustworthy. It is the other side of L-066: that lesson is about assertions that pass when they should fail; this one is about tests that fail when the product is right.

Change made

test-strategy.md’s selector and fixture conventions gain a sixth rule, which e2e-test-implementer reads there, and frontend-reviewer dimension 14 checks changed tests for it.

Lesson

  • Before a scan or an action that depends on it, wait for the state that makes it valid: every finite animation in the element finished (getAnimations({ subtree: true }), skipping infinite ones such as a spinner), the previous interaction’s effect visible (the closed dialog’s content gone), and background work the test started settled (or the assertion accepts both outcomes).
  • Assert the wait’s own target first (for example that the test id exists), so a renamed element fails the test rather than silently removing the wait.
  • Before an action whose request the test waits for, let any read of the same query end and show on screen (BUG-115). TanStack Query shares an in-flight read with a component that mounts during it, so the action sends no request and the wait never ends. A response reaching Playwright is not enough: the app has not yet stored it. Wait for the answer on screen (settleOwnerFilter in e2e/browser/leads/support.ts).
  • After an action whose focus move is deferred, wait for focus to land before the next one (BUG-135). Tiptap’s focus() runs in a requestAnimationFrame, so a test that clicks again at once can have that focus arrive after the next control took focus, and the frame’s timing differs between machines. Wait with waitFor(() => expect(<target>).toHaveFocus()), and assert focus is where the next key expects it.
  • When a visible change and the event that finishes it are a task apart, input in the gap is the product’s to keep (BUG-134). A <dialog> hides and returns focus at close(), but its close event comes a task later, and a busy Chromium runs a key press first. State released only by that event (a “busy” flag) drops the press. Keep the input and run it once the event arrives, rather than making the test wait. A test reproduces it by holding the event back (a capturing close listener that stops it and dispatches it again later).
  • A pinned page state pins every read the page makes, including one a later feature adds to the page (BUG-233). A read left to the shared backend answers differently in a full gate, where other tests have created data, than on a fresh stack, so content can appear after the state has settled and move the control under the next click. A read the whole page makes in every state is answered once, where every state passes (the size matrix answers the Pricing warnings read empty in size-matrix.spec.ts), and a state that needs another answer pins its own. To find such a read, log each response’s serverAddr() in a run: a routed answer has none.

L-102 — git grep -E '\b…\b' matches nothing on macOS; an empty result from it proves nothing

  • Date: 2026-09-30
  • Source commits in this repo: .forge/specs/F5-l-reach-from-reporting-line-spec.md (the 2026-09-30 correction of its /me bullet)
  • Sync target: upstream
  • Synced: pending

Problem observed

The F5-l stub (2026-09-27) said neither frontend read /me’s scope field, and cited git grep -n '\bscope\b' origin/main -- src e2e as the check. The frontend declares the field in its API types and session context, and seven unit-test files and two e2e seam specs assert or mock it. The cited command, a basic regular expression, does find those uses on macOS (68 lines on 2026-09-30). The check actually run used git grep -E with \b: -E switches to the platform’s POSIX extended regular expressions, which on macOS have no \b, so it matched nothing at all and exited 1 — exactly what a clean tree looks like. The stub then quoted a different command from the one that produced its conclusion. The false premise reached the tracker, features.md and the stub as “backend-only”. The same trap sits in FS-15’s AC-1 gate, git grep -n -E '\bProducts?\b|…|com\.empireteas\.catalog\b': on macOS its two \b alternatives can never match, so a reintroduced Product type would pass the gate there (it passed when re-run with -P on 2026-09-30).

Lesson

  • Never write \b in a git grep -E or grep -E pattern — use git grep -w for a whole word, or git grep -P when a pattern needs \b or look-arounds. A plan’s premise check that expects “nothing” must be one that can print something: run it once against a string you know is there.
  • Paste the premise check’s output next to the claim, from the command as written in the document — a cited command that differs from the one run hides the error.
  • A “returns nothing” premise is the riskiest kind (.claude/rules/source-trust.md § The same rule applies to claims about THIS repo): an error in the search looks exactly like a clean tree.

L-103 — A test that compares filesystem paths with string literals normalises the separator first

  • Date: 2026-10-01
  • Source commits in this repo: .forge/specs/F5-i-findings.md F-004; the fix is altrium-io/forge-et-fe#87
  • Sync target: upstream
  • Synced: pending

Problem observed

forge-et-fe’s src/app/programmaticFocusRing.test.ts built each stylesheet’s path with path.relative() and compared it with an allowlist of forward-slash literals. On Windows relative() returns backslashes, so nothing matched and the test failed. CI runs on Linux, so the test was green on every PR; it failed for the first time on a developer’s Windows laptop, during F5-i’s manual smoke run (WI-2.1 R-7), where it cost a re-run. Half of the delivery team develops on Windows.

Lesson

  • Normalise before comparing: relative(root, file).split(sep).join('/') (or path.posix throughout), then compare with forward-slash literals. Apply the same rule to globs, snapshot keys and any path that ends up in an assertion.
  • CI on Linux cannot catch this class, so a reviewer who sees relative(), join() or resolve() feeding a string comparison in a test asks for the normalisation rather than trusting a green run.

L-104 — An acceptance criterion about the scopes an identity provider grants says “includes”, never “exactly”

  • Date: 2026-10-01
  • Source commits in this repo: .forge/specs/F5-i-findings.md F-006; .forge/specs/F5-i-laptop-entra-sign-in-spec.md Rev 4
  • Sync target: upstream
  • Synced: pending

Problem observed

F5-i’s AC-17, its run sheet and the register’s F20-a consent row expected the stored granted_scopes to be exactly User.Read Mail.ReadWrite Mail.Send. The first live consent against Empire’s tenant returned more: Microsoft’s token response lists every delegated scope the tenant has consented for the app registration, not only those the request asked for, and Empire had consented calendar and contacts on purpose, for Phase 2. The criterion failed on a correct system and needed a spec revision and a lead decision to close.

Lesson

  • Write scope criteria as “the granted scopes include X, Y and Z”, and the code that depends on scopes checks for the ones it needs, never for an exact set — the tenant administrator’s consent decides the full list, and it changes without any change to the request.
  • The same applies to any list an external system returns under someone else’s configuration (roles in a token, groups, feature flags): assert what is required to be present, and what must be absent if anything, not equality.

L-105 — A manual run sheet tells the person to save every command’s output to its own file as they go

  • Date: 2026-10-01
  • Source commits in this repo: .forge/specs/F5-i-findings.md F-008; .forge/plans/F5-i/F5-i-WI-2.1-record.md
  • Sync target: upstream
  • Synced: pending

Problem observed

F5-i’s first manual wave (WI-2.1, live sign-in as CRM01) ran correctly, but its record kept little of the evidence. Five steps say what was seen with no output (“command output not kept”); one step’s evidence block shows a single error response and none of the ten values its success criterion lists; and one pnpm e2e run exited 1 with its cause unknown, because the next run wrote to the same log file. The lead accepted the record as it was, since the run could not be repeated cheaply. The run sheet had named a save folder for the smoke-run logs only, and used one log name for every run.

Lesson

  • A run sheet names an output file per step and per attempt — R-<n>-<step>-<attempt>.log, in one save folder set in Part 0 — and every command it gives ends in > "$SAVE/R-<n>-….log" 2>&1; echo "EXIT=$?". No two commands write the same file.
  • Each success criterion says which lines to paste into the record, so the record holds the values (and the file they came from), not a summary of them.
  • The person keeps the save folder until the wave PR merges, so a reviewer can ask for a file that was not pasted.

L-106 — The browser gate checks only the page states in its list, so failure-only screens escape it

  • Date: 2026-10-01
  • Source commits in this repo: .forge/bugs.md BUG-031, BUG-043, BUG-060; the fix is altrium-io/forge-et-pwa#44; BUG-200 (the CRM’s / route error page had no <main>; forge-et-fe#314 added its app-section-load-error page state)
  • Sync target: project-only
  • Synced: pending

Problem observed

F40’s shared page check (axe, no horizontal scroll, no clipped control, the target-size floor, nothing focusable inside aria-hidden) runs on every entry of each app’s page-state list (e2e/pageStates.ts) at every supported size. A screen a user reaches only when something fails is not in that list: the capture app’s router error element and its render error boundary. BUG-043 (both error-screen buttons under the 44px floor) shipped with the capture shell for that reason, as BUG-031 (the 404 button) had before the 404 page joined the list; and BUG-060 (no <main> on those screens) surfaced only when a reviewer tried to run the shared check on one by hand. The route-coverage test (F40 FR-5) cannot see them either, because they are not router paths.

Lesson

  • A screen that only a failure renders still needs the shared check. When a feature adds an error element, an error boundary or any fallback surface, add an entry for it to the page-state list, with an arrangement that forces it (a blocked route chunk renders the router’s error element; a thrown render needs a test-only module substitution), so the size matrix covers it at every size.
  • A reviewer who sees a new fallback surface asks for its page-state entry, because no automated check will notice its absence.

L-107 — A green re-run does not prove a fix for a load-dependent failure; force the failure to see the change

  • Date: 2026-10-01
  • Source commits in this repo: .forge/bugs.md BUG-045; the fix is altrium-io/forge-et-fe#104; BUG-107 (a count read right after a render, proved by delaying the read 50 ms — forge-et-fe#168)
  • Sync target: upstream
  • Synced: pending

Problem observed

BUG-045 gave the WebKit size projects a 15-second ready wait instead of 5. The first version chose the timeout from testInfo.project.use.browserName, which Playwright leaves unset when a project takes its engine from a device’s defaultBrowserType, so the longer wait never applied. The before-and-after evidence still looked right: 4 failures under load before, 213 passes after, then two full green gates. The machine had simply become quieter. A string | undefined parameter type let the unset value compile. The frontend-reviewer found it by printing the value; a temporary forced failure then showed Timeout: 15000ms on WebKit and 5000ms on Chromium with the corrected code.

Lesson

  • Prove a timeout or retry change with a failure you force, not a pass you observe. Point the wait at something that cannot appear (temporarily, then revert) and read the timeout the error reports. A load-dependent failure that passes on the next run says nothing about the change.
  • In Playwright, read the engine from the browserName fixture, never from testInfo.project.use.browserName, and type it as the non-optional union so an unset source fails to compile.

L-108 — When tests fail on every branch, check how the local services were started before changing the tests

  • Date: 2026-10-01
  • Source commits in this repo: .forge/bugs.md BUG-058; the fix is altrium-io/forge-et-fe#107, and altrium-io/forge-et-fe#105 was the wrong fix, closed unmerged
  • Sync target: upstream
  • Synced: pending

Problem observed

About 16 CRM mailbox browser tests failed on every branch. They were read as a race with the stub mailbox’s back-fill, and a test-only fix (forge-et-fe#105) pinned reads and loosened one state check until the gate passed twice. The real cause was the local backend’s start command: a launch entry passed --et.mailbox.public-base-url, which makes a stub connect subscribe and seed mail at once. The tests were right for a plain bootRun. The backend’s application-local.yml.example said the key “would change nothing” outside laptop mode, which made the setting look harmless. The frontend-reviewer on #105 found the cause by comparing the backend’s code path with the start command.

Lesson

  • Failures on every branch, including ones that change nothing near the tests, point at the environment first. Before editing a test, compare how each local service was started (launch entries, --args, environment variables, the gitignored local config) with what the suite’s README documents.
  • Make the suite check its own prerequisites. A prerequisite that changes test outcomes gets a check in the setup project that stops the run with a message naming the cause and the fix, as e2e/fixtures/auth.setup.ts now does for this key, so the next person sees one clear failure instead of sixteen that look like product bugs.

L-109 — A one-time message held in React state comes back when Chrome restores the page from its back/forward cache

  • Date: 2026-10-01
  • Source commits in this repo: .forge/bugs.md BUG-036 (fixed in altrium-io/forge-et-fe#99) and BUG-066 (the same cause on the mailbox screen, fixed in altrium-io/forge-et-fe#147)
  • Sync target: upstream
  • Synced: pending

Problem observed

The login page shows a sign-in failure message from the backend’s ?login=failed marker. The BUG-036 fix read the marker into React state and removed it from the URL with a replace navigation, so a reload or an ordinary Back no longer showed it. In real Chrome the message still came back: after a refused sign-in, a successful one and a sign-out, Back to the login page showed it again, with a clean URL. DevTools → Application → Back/forward cache said “Successfully served from back/forward cache”. Chrome had restored the frozen page, and React state with it. The mailbox screen’s ?connect=failed banner, which the BUG-036 fix had copied, does the same (BUG-066).

No automated test saw it. Playwright’s Chromium launches with --disable-back-forward-cache, so every browser row loaded the page again on Back, and the unit tests run in jsdom, which has no such cache. Only a manual check in Chrome on the built app showed it; the dev server’s HMR socket stops a page from entering the cache.

Lesson

  • Removing a one-time marker from the URL is not enough; clear the message it set on a back/forward-cache restore as well. A component that shows a message from a URL marker, a redirect result or any other one-time event, and keeps it in state, also listens for pageshow and clears the message when event.persisted is true. Since BUG-066 every such reset goes through one shared hook, usePageRestore (forge-et-fe src/lib/browser/usePageRestore.ts), which adds the listener once and removes it on unmount; the login page’s useLoginMarker (src/features/auth/LoginRoute.tsx) and the mailbox screen (src/features/email/MailboxRoute.tsx) are the models, and the sign-in and consent buttons’ busy state uses it too (BUG-027, BUG-024).
  • Check what the message was hiding, because that comes back frozen too. The first version of the login fix only cleared the message. The second review of forge-et-fe#99 found that the restored session store still held reason: 'expired' from before a deliberate sign-out, and the failure message had been hiding the expiry notice that reason produces. Clearing the message alone showed “Your session expired” after the sign-out. Where the page’s other state comes from the server, re-read it on the restore first (the login page calls the session’s refresh()) and clear the message after the re-read settles, so no notice is shown from the stale state in between.
  • Test it with a dispatched event, and prove it by hand. A unit row renders the message, dispatches new PageTransitionEvent('pageshow', { persisted: true }) inside act, and asserts both the settled page and that the message is gone, and that no other notice took its place; a second row shows persisted: false keeps it. A row with a session that changes on refresh() (the test file’s renderRetryingLogin) proves the re-read. Because no browser row can see the cache, the fix also needs a manual check in Chrome on pnpm build + pnpm preview, with the DevTools panel’s “served from back/forward cache” line as the receipt.
  • Reviewers check it. frontend-reviewer dimension 15 points here.

L-110 — A test that expects a temporary path in a message must build it from the resolved path

  • Date: 2026-10-02
  • Source commits in this repo: forge-et-harness#327 (a7fe8625); F41 finding F-001 (.forge/specs/F41-tooling-only-dependency-bumps-findings.md)
  • Sync target: upstream
  • Synced: pending

Problem observed

The harness hook test guard-browser-gate.test.sh built its fixture workspace under mktemp -d and expected the hook’s refusal to name a path under it. On macOS mktemp -d returns /var/folders/…, but /var is a link to /private/var, and the hook reports the resolved /private/var/folders/…. Five cases failed on every Mac, on main too, so the failures looked like noise to anyone running the test. F41’s boundary suite had already hit the same cause with dependency-cruiser (preserveSymlinks: false) and avoided it with fs.realpathSync(os.tmpdir()).

Lesson

  • Resolve a temporary directory once, when it is created, and build every expected path from the resolved form. In shell, TMP=$(cd "$(mktemp -d)" && pwd -P); in Node, fs.realpathSync(...) on the mkdtemp result. Any tool that resolves symlinks (realpath, git rev-parse --show-toplevel, dependency-cruiser, a hook that calls pwd -P) then prints the same string the test expects.
  • A test that fails the same way on main is still a defect. Fix it in its own PR rather than living with a known-red count, because a suite that always shows some failures stops anyone from noticing a new one.

L-111 — Comparing a dependency graph’s edges by their targets alone misses two aliases swapping versions

  • Date: 2026-10-02
  • Source commits in this repo: forge-et-fe d366ce7, forge-et-pwa b63a20d (forge-et-fe#98, forge-et-pwa#41); F41 finding F-003
  • Sync target: upstream
  • Synced: pending

Problem observed

F41’s gate-graph rule decided that a dependency-only change could skip the browser gate when each node of the lockfile graph kept the same set of edge targets. /forge-review-pr found a false pass: when two aliases of one package swap the versions they point at (a: pkg@1, b: pkg@2 becomes a: pkg@2, b: pkg@1), the set of targets is unchanged, yet import 'a' now loads different code.

Lesson

  • An edge is identified by its name and its target together. When comparing two dependency graphs to decide that nothing a program loads has changed, compare each edge as <dependency name> → <target identity>, at the roots as well as inside the graph. The target alone is enough only when a name can never point at more than one target, which aliases break.
  • Test the swap. A rule that clears changes needs a case where the set of targets is the same but the names point at different targets, and that case must not clear.

L-112 — Merge a refreshed PR as soon as its refreshed head is green

Withdrawn 2026-10-04 (lead): the pre-merge refresh rule this lesson refines was removed from .claude/rules/git-conventions.md § Branching, because it delayed merges more than the rare break it caught. Kept as a record.

  • Date: 2026-10-02
  • Source commits in this repo: forge-et-fe#98, forge-et-pwa#41 (refreshed on 2026-09-30, 2026-10-01 and 2026-10-02); F41 finding F-004
  • Sync target: project-only
  • Synced: not applicable — withdrawn 2026-10-04

Problem observed

.claude/rules/git-conventions.md § Branching asks for main to be merged into an app-repo code PR once, just before it merges, when main has gained code since its last green run. F41’s two PRs were refreshed three times over three days, because after each refresh they waited for the next step and main moved again. In forge-et-fe each refresh cost a backend start and a full browser gate, plus a CI run in both repos. None of the three merges conflicted, and none of main’s changes broke an F41 test.

Lesson

  • Treat the refresh as the last step before the merge. Do it after the review and its fixes, so one push carries both (one browser gate run in forge-et-fe / forge-et-pwa, one build record in forge-et-be); then record the new head with a delta review and merge as soon as it is green, in the same sitting. On F41 the refresh came before the review, so the review fixes cost a second gate run.
  • A refresh lasts for the sitting it was made in. A refresh followed by a wait buys nothing, because the next merge decision needs another one. If the merge slips to a later session, refresh again then.
  • Do not skip a refresh because main’s new commits touch other files. The rule exists because two branches can break each other’s tests without touching the same files (F5-k and F38-c did). An exception for “main touched none of the PR’s files” was proposed at F41’s Reflect and dropped for that reason. The rule is .claude/rules/git-conventions.md § Branching.

L-113 — Before deleting a test along with the behaviour it tested, check what else it guards

  • Date: 2026-10-02
  • Source commits in this repo: forge-et-be#126 (review finding I1, fixed on feature/F5-l-review-fixes); F5-l finding F-001
  • Sync target: upstream
  • Synced: pending

Problem observed

F5-l removed grant scopes and deleted the tests of the scope behaviour with it. One of them, ContactControllerIT’s view@all + manage@team row, was also the only test proving that a user who can read an account but not change it is refused a write, and that nothing is written — a rule F5-l keeps. The suite stayed green, so nothing showed that the rule had lost its only test. The backend-reviewer found it by asking what each deleted test asserted.

Lesson

  • When a change deletes a test because its behaviour is removed, list each assertion the test makes and name the test that still covers each one that remains true. An assertion with no other test is re-expressed in the new model, not deleted.
  • Record the list in the plan’s deviation notes, next to the deleted test, so the reviewer can check it rather than reconstruct it.
  • A green suite after a deletion proves nothing about coverage: a deleted test cannot fail.

L-114 — Removing a concept: search for its words, not only its identifiers

  • Date: 2026-10-02
  • Source commits in this repo: forge-et-be#126 (comment-only commit ddac09f); F5-l finding F-002
  • Sync target: upstream
  • Synced: pending

Problem observed

F5-l’s spec checked the removal of grant scopes with a search for the removed identifiers, and the work item’s ## Files to Modify came from the same search. Javadoc in about 25 files outside that list still described reach as “own-scoped”, “team scope” or “at no scope”. No identifier search finds that wording. The lead had it fixed in the wave by a comment-only commit, which widened the work item’s file list after its plan had been reviewed.

Lesson

  • When a spec removes a concept, its removal check also searches for the words the code and docs use for it (for F5-l: own-scoped, team-scoped, scope-aware, {@code team}), with an -i -w search over src/ and the repo’s docs, not only for the type and column names.
  • Build the plan’s ## Files to Modify from both searches, so comments that describe the removed concept are planned work, not a follow-up found during implementation.

L-115 — Drop a column one release after the code stops reading it, once anything is deployed

  • Date: 2026-10-02
  • Source commits in this repo: forge-et-be#126 (review finding N2, V31); F5-l finding F-005
  • Sync target: upstream
  • Synced: pending

Problem observed

F5-l’s V31 removed role_grant.scope in the same release as the code that stopped reading it. In a rolling ECS deploy the previous release’s tasks keep running while the new release migrates the database, and they fail on the missing column until they are replaced. It was accepted for F5-l only because no environment was deployed yet; the PR body records that.

Lesson

  • From the first deploy to dev (F38) onwards, a column is dropped in the release after the one whose code stopped reading it. Release N stops reading and writing it; release N+1’s migration drops it.
  • The same holds for a renamed column or table: add the new one, write both, move the readers, then drop the old one in a later release.
  • Until dev runs, a one-release drop is acceptable but is stated in the PR body, so the reviewer sees that it was a decision, not something nobody noticed.

L-116 — Under the dev server, the first browser test to reach a lazy route pays its transform; warm the routes in setup

  • Date: 2026-10-03
  • Source commits in this repo: .forge/bugs.md BUG-079 (and the Chromium recurrences under BUG-045), BUG-338 (the same cause in a Vitest file); BUG-370 (a component test that waited for a lazy action’s chunk inside findBy’s 1 s, forge-et-fe#451); BUG-413 (the capture app’s plan list, whose first test to open the lazily loaded booth drawer waited for its transform inside findByRole’s 1 s; preloaded in beforeAll, forge-et-pwa#158); BUG-449 (the Scheduled list’s first Edit and Send case waited for the compose dialog’s first import() inside its 5 s wait for the To field; loaded once by a top-level await loadComposeEmailLayer() in the test file); the fixes are in forge-et-fe (e2e/fixtures/routes.setup.ts; src/app/router.test.tsx; src/app/leadPanels.approveSend.test.tsx)
  • Sync target: upstream
  • Synced: pending

Problem observed

forge-et-fe’s browser suite runs against pnpm dev, where Vite transforms a module the first time it is requested. Every screen is a lazy() route, so the first spec to deep-link into one waited for that route’s whole module tree to be transformed inside its own 5 s expect timeout. On a busy machine the wait ran out with the page still on the route skeleton. The failure moved from spec to spec (whichever reached a route first) and passed on a re-run, so it was recorded as load noise under BUG-045 from 2026-09-30 rather than as one cause.

Lesson

  • When first-heading timeouts move between specs and pass on a re-run, suspect the dev server’s first transform before the spec. The error context shows the route skeleton (main: Loading…).
  • Pay the cost before the browser projects run, in a setup-project file, never with a longer timeout. forge-et-fe/e2e/fixtures/routes.setup.ts imports every module src/app/router.tsx loads through lazy(), in a browser, so each route’s whole tree is transformed and cached first. A lazy() added anywhere other than router.tsx is not warmed by it.

Update — 2026-11-06

The same cause applies to a Vitest file that renders the real route tree (BUG-338). Vitest transforms and evaluates a module the first time a file imports it, so src/app/router.test.tsx’s first case to reach a route paid that route’s first import inside its findByRole wait, and /pricing ran past 10 s in a loaded Windows run. The file now imports every module router.tsx loads through lazy() while it loads, before any test, reading the list from router.tsx as routes.setup.ts does. A component test that renders a lazy() screen loads its module before the test, never with a longer wait.

Update — 2026-11-08

BUG-370 is the same cause in a test that holds a lazy chunk on purpose. leadPanels.approveSend.test.tsx mocks Approve & send’s module with a factory that waits for the test to release it, and the cases that need the loaded chunk released it and then waited in findBy’s 1 s, which also covered the import. Calling the composition’s loader after the release was not enough on its own: an import() made while the mock’s factory is running skips the mock and answered after 61 ms, before the factory had finished. composeEmailComposition.aiDraft.test.tsx held the AI draft chunk the same way, with the same race. When a test holds a module with a vi.mock factory, call the loader first, then release the hold, wait for a mark the factory sets in a finally when its import has finished, and then await the loader call; assert that it answers with the real export. Calling the loader first lets each case run on its own: a wait for an import that only an earlier case started hangs when the case is run alone, as a red nightly run’s triage does.

L-117 — A verify WI that runs the whole existing suite records a baseline on main first, and classifies each failure against it

  • Date: 2026-10-03
  • Source commits in this repo: .forge/specs/F5-k-access-model-realignment-findings.md F-001; .forge/plans/F5-k/F5-k-decomposition-plan.md § Notes; .forge/plans/F5-k/F5-k-WI-1.3-verify-new-catalog.md § Notes § Baseline
  • Sync target: upstream
  • Synced: pending

Problem observed

F5-k changed the permission keys every screen’s navigation reads, so its verify WIs ran the whole existing browser suite on the integrated wave branch rather than only their own tests. On wave 1 that suite had 13 failures. All 13 were already failing on main (12 landing/superadmin tests, and BUG-033/BUG-034 in another feature’s dialog). Read against the wave alone, they looked like wave-1 regressions, and the auto-repair loop would have sent them to the wave’s implementers, who own none of that code.

Lesson

  • Before judging a wave against the whole existing suite, run that suite once on the commit the wave branch is based on (git merge-base origin/main feature/<ticket>-wave-<N>, in each repo) and record the result in the verify plan’s ## Notes § Baseline, before any wave run.
  • Classify every wave-run failure against it: (a) fails on the baseline for the same reason → out of the wave’s scope, a BUG candidate (or the existing bug); (b) fails on the baseline and passes on the wave → fixed by the wave, record it; © passes on the baseline and fails on the wave → a regression, routed by file ownership as Stage 7 Step 5d/5e routes it.
  • A wave whose own tests are the only ones run needs no baseline; the rule applies when the verify plan runs tests the wave did not write.

L-118 — Give orchestrator-run verify suites their own compose project, ports and volume, committed once

  • Date: 2026-10-03
  • Source commits in this repo: .forge/specs/F5-k-access-model-realignment-findings.md F-002; the § Runtime deviations in .forge/plans/F5-k/F5-k-WI-1.3-verify-new-catalog.md, F5-k-WI-2.3-verify-losing-access-plan.md and F5-k-WI-3.1-plan.md
  • Sync target: upstream
  • Synced: pending

Problem observed

A verify run needs the backend on a known database state (a baseline database, a migrated one, an empty one), while the developer’s own forge-et-be stack keeps running and holds host ports 5432 (Postgres) and 4566 (LocalStack). Three F5-k verify sessions each wrote the same scratchpad compose override by hand: Postgres on 55432, LocalStack on 45666, the datasource port and endpoints in application-local.yml set to match, and Postgres data in a named volume per compose project, because Docker Desktop refused a freshly bind-mounted ./.local/postgres (“data directory has wrong ownership”). The PostgreSQL 18 move on main changed the data mount path, and the last copy had to be edited again.

Lesson

  • Run each verify database state as its own compose project (-p <ticket>-<run>) with shifted host ports and a named volume, so it never touches the developer’s stack and “empty database” is checkable as docker volume inspect <project>_pgdata failing before up.
  • Keep that override in the backend repo, not in a session’s scratchpad, so it moves with compose.yaml (a Postgres major-version change included) and each verify plan’s § Runtime names one command instead of describing a hand-built file.

L-119 — A Playwright route callback that awaits the network can outlive its test; let it go when the test has ended

  • Date: 2026-10-03
  • Source commits in this repo: .forge/bugs.md BUG-057, BUG-063 and BUG-065 (all fixed in forge-et-fe#123)
  • Sync target: upstream
  • Synced: pending

Problem observed

Three intermittent browser-test failures in forge-et-fe had one cause. The /me route mock (mockPermissions, e2e/browser/auth/support.ts) answered the request with route.fetch(), read the body, and fulfilled with a rewritten body. The app re-reads /me in the background (on window focus, for example), so a read could still be inside that callback when its test ended. Playwright closes the test’s context at that point. That rejects a route.fetch() still in flight (route.fetch: Test ended.) or disposes a fetched response whose body has not been read (Response has been disposed). The rejection failed whichever test was running at the time, sometimes a later test that had no route of its own (BUG-063). Each failure looked like a different one-off, and the first two entries blamed the page dropping the request. A probe showed that an abort, a navigation or a second read leaves the callback working. Only the context closing at the end of the test causes either error.

Change made

The callback (permissionsRouteHandler) catches the errors that mean the test or the page is gone (Test ended, Target page, context or browser has been closed, response has been disposed) and returns. It rethrows anything else, so a real failure still fails the test. A spec (e2e/browser/auth/mock-permissions.spec.ts) builds each half of the race deterministically: it closes a context of its own with the reason Test ended. and runs the callback against it. frontend-reviewer dimension 16 checks changed route callbacks for it.

Lesson

  • A page.route callback that awaits route.fetch(), a body read or any other network call can still be running when its test ends. Either the callback ignores the gone-test errors and rethrows the rest (the shape to use in a shared helper, because callers cannot be relied on to clean up), or every test that registers it ends with await page.unrouteAll({ behavior: 'ignoreErrors' }), in an afterEach so a failed test runs it too.
  • Do not catch every error to make it quiet. Match only the gone-test messages, because Playwright exports no class for them. A callback that swallows everything hides a real backend failure.
  • Prove the race with a context of the test’s own, closed with { reason: 'Test ended.' }, rather than with a repeat count. A repeat run that passes shows only that the window was not hit.

L-120 — A migration version is not reserved by any open branch; check them all, and renumber by searching

  • Date: 2026-10-04
  • Source commits in this repo: F5-f findings F-002 and F-003; forge-et-be#153, #142, f1157c7, 41519d8
  • Sync target: upstream
  • Synced: pending

Problem observed

F5-f WI-1.1 took V32__record_share.sql while F26-b’s open branches carried V32__buying_standard_certification.sql. The file names differ, so git reported no conflict; whichever merged second would have failed Flyway at startup, because out-of-order migrations are off (L-014). Only backend-reviewer listing every remote branch’s migrations caught it. The rename that followed was described as “the file and its two documented copies”, but git grep V32 also found the file’s header line, two test comments and a test asserting version = '32', which after main merged in would have passed by counting the other feature’s V32 row. Another instance of L-057.

Lesson

  • When a plan picks a migration version, it lists the migrations on every open remote branch (git ls-tree --name-only origin/<branch> src/main/resources/db/migration), not only main, and names any branch holding the same number in its ## Risks.
  • A renumbered migration starts from git grep of the old version and file name over src/ and docs/, never from a list of known copies. A test that asserts a version number is one of the places it lives.
  • Just before merging a PR that adds a migration, check its number is still free on origin/main (forge-et-be docs/migrations.md step 2). The PR’s own record cannot see another PR’s file with the same number, and git merges the two cleanly because their names differ; BUG-438’s two V72s left main unable to start.

L-121 — A test-heap death reads as a short run; compare test counts and check the base commit

  • Date: 2026-10-04
  • Source commits in this repo: F5-f finding F-004; forge-et-be 886e8b5
  • Sync target: upstream
  • Synced: pending

Problem observed

F5-f wave 2’s full ./gradlew check died twice with OutOfMemoryError: Java heap space in the test executor. Gradle reported fewer tests and an executor failure, not a failing test, and the spec running at the time looked like the cause. Running the suite on the base commit (c35700d) showed the same death after 3,963 tests, so the 1 GB heap was already at its limit before the work item’s code. One green run on the same commit had passed, so the limit fails intermittently.

Lesson

  • A full run that reports fewer tests than the last record on main is a failed run, whatever its exit status says about individual tests. Compare the JUnit XML count with the last local build record.
  • Before changing code for a failure in a spec the change did not touch, run the suite on the base commit. If the base fails the same way, the cause is the environment or the build, not the change.

L-122 — The shared local database belongs to whoever is running the app; smoke on your own containers

  • Date: 2026-10-04
  • Source commits in this repo: F5-f finding F-005
  • Sync target: upstream
  • Synced: pending

Problem observed

F5-f wave 2’s local curl smoke and timing measurement needed the app running on the branch. The Postgres on 5432 belonged to another session’s running app, at an older migration. Starting this branch against it would have migrated that database forward, under another session that was still using it. L-118 gives the orchestrator’s verify suites their own compose project for the same reason; this is the implementer’s case.

Lesson

  • A work item’s local smoke runs the app on its own throwaway containers (Postgres and LocalStack on unused ports, the app on an unused port, set by command-line overrides), and removes them afterwards.
  • Never start a branch’s app against the shared 5432 database, and never stop a process you did not start.

L-123 — A PR title built from a template must be checked against commitlint before the PR opens

  • Date: 2026-10-04
  • Source commits in this repo: F5-f finding F-001; forge-et-be#153
  • Sync target: upstream
  • Synced: pending

Problem observed

forge-pr-open --wave builds the title as feat(<TICKET>): wave <N> — <ship state one-liner>. The ship state is a full sentence in the Decomposition Plan, so even a shortened title came to 79 characters and the Fast lane’s title check failed on commitlint’s 72-character header limit. The PR had to be retitled, which ran the Fast lane again.

Lesson

  • Run printf '%s' "$TITLE" | pnpm exec commitlint in the app worktree before gh pr create, and shorten the ship-state part, not the type or ticket, when it fails.

L-124 — Wait on an SDK future with a timeout, never join(); join() ignores interrupts, so a test timeout cannot end it

  • Date: 2026-10-03
  • Source commits in this repo: .forge/bugs.md BUG-078 (fixed in forge-et-be#161)
  • Sync target: upstream
  • Synced: pending

Problem observed

QueueProvisioner creates the SQS queues against LocalStack when a local or test context starts. It ended each AWS SDK call in CompletableFuture.join(). join() adds no bound of its own and ignores interrupts, so the wait lasts as long as the client’s own timeouts allow, which may be none. Nothing in the code set or checked those timeouts. A backend build run beside two other suites sat in it for over a minute with no test result, on a run that then passed (BUG-078). Writing the regression spec showed the interrupt half in practice. A first draft relied on Spock’s @Timeout(10), which interrupts the case’s thread. On the unfixed code, with a stubbed future that never completes, that case held the test JVM for 10 minutes, until the worker was stopped by hand. A timeout on the test does not bound a join().

Change made

Every call in QueueProvisioner goes through one helper that calls get(timeout, unit), here 3 minutes per call. The value has to clear the client’s own limits. Spring Cloud AWS builds the client on netty-nio-client with SDK defaults, so a silent read gives up after about 30 s and is retried (the SDK’s documented defaults, not measured here), and a call that stalls once can still answer after a minute. The 60 s first proposed would have cut that call off. The helper handles each outcome:

  • Timeout: it cancels the future and throws an IllegalStateException naming the queue and LocalStack.
  • ExecutionException: it rethrows the cause inside a CompletionException, the type join() threw, with a message naming the queue.
  • InterruptedException: it restores the interrupt flag.

The spec runs start() on a daemon thread of its own and gives up after a fixed time, so the unfixed code fails the case instead of holding the run. backend-reviewer checks changed code for the pattern.

Lesson

  • A wait on a CompletableFuture from an SDK call has a bound the code sets. Either it uses get(timeout, unit), or the client is built with apiCallTimeout (the equal answer when the code owns the client). It never uses a bare join() or get() on a client with no call timeout. This applies to LocalStack in local and test as much as to AWS in the cloud. Fail with a message that names the resource and the service, so a stalled start-up says why it failed. Handle ExecutionException (keep the cause) and InterruptedException (restore the flag) in one helper.
  • Set the bound above the client’s own timeouts and retries, not just above a normal call. A bound below the read timeout plus one retry cuts off calls that would have answered. Read the client’s defaults before choosing the number.
  • Spock’s @Timeout and JUnit’s timeouts interrupt the thread. Code that ignores interrupts outlives them. To prove that a wait is bounded, run the call on a thread of the spec’s own and stop waiting for it after a fixed time. The unfixed code then fails the case instead of hanging the suite.
  • Known remaining instances (as of 2026-10-04): seven join() calls on SQS futures in backend test helpers (MessagingContextSpec, MailboxIngestContextSpec, PoisonDlqIT, ScheduledJobRoutingIT). forge-et-be#163 replaces them with support/SqsCalls.await, a 3-minute bounded wait with its own spec; once it merges, git -C forge-et-be grep -n '\.join()' -- src/test/groovy returns nothing.

Update — 2026-10-20

The rule “set the bound above the client’s own timeouts” has one exception, first taken by forge-et-be#282 (BoundedSqsSend, a 5-second wait on every SQS send a request or a listener makes): a wait a person or a listener depends on may sit below the client’s timeouts when the call is replay-safe and every caller has a path that sends it again. The wait then ends but the SDK call does not, so a send can still land after it gave up, and the caller’s retry can queue the job twice; the consumers’ idempotency keys make the copy a no-op (AD #13). The client-wide apiCallTimeout was not the answer there, because the same SqsAsyncClient serves the @SqsListener long polls, which wait up to the 10-second poll timeout by design. Write the exception and its reason in the class’s Javadoc, as BoundedSqsSend does.

L-125 — A test that asserts what a time-bounded run got done fails on a loaded machine; remove the timing or let the next run finish

  • Date: 2026-10-04
  • Source commits in this repo: .forge/bugs.md BUG-081 (fixed in forge-et-be#168), BUG-082 (fixed in forge-et-be#169) and BUG-077 (the same cases as BUG-082 on Windows, fixed by the same change and checked on Windows on 2026-10-05); BUG-130 (a 5-second wall-clock bound in BulkReassignStatementCountIT, printed instead of asserted in forge-et-be#237) and BUG-147 (F4-a AC-22’s 30-second bound in PipedriveDryRunTimingIT, the same change in the same PR); BUG-172 (a Vitest self-test that starts many git processes ran past the 20-second default in every full run on Windows; given its own timeout in forge-et-fe#227 and forge-et-pwa#71); BUG-128 (a Vitest component case that clicked 25 rows one at a time ran past the 20-second default under full-suite load on Windows; its clicks cut to 6 in forge-et-fe#229); BUG-513 (knownFailureMarks.test.ts’s tree case stripped the comments of about 12 MB of e2e source twice, character by character, and ran past the 20-second default under load on Windows; stripped once, by one regular-expression pass, forge-et-fe#600); BUG-216 (the gate’s stopped-backend case timed the whole start-up, git included, against 5 s; it now asserts the probe’s configured bound, forge-et-fe#335); BUG-220 (a 49-box arrangement clicked one at a time, now one click event each, forge-et-fe#367) and BUG-213 (52 keystrokes of text the case does not test, now pasted, forge-et-fe#367); BUG-331 (one Vitest case rendered the account list three times for three requests and ran past the 20-second default under load on Windows; split into one case per request); BUG-347 (one Vitest case chose three data-bar selects, Country’s 250 options among them, and ran past the 20-second default under load on Windows; split into one case per select); BUG-372 (two LeadsScreen.test.tsx cases picked from the Country filter’s 250 options in cases not about Country, one of them twice, and ran past the 20-second default under load on Windows; split, with a status pill or the Owner filter in place of Country, forge-et-fe#490); BUG-367 (a Vitest case typed a search and chose an item with user-event, assuming both finished inside the search’s 300 ms debounce; now synchronous events, forge-et-fe#451); BUG-463 (the capture app’s search box test typed on the real clock against a 50 ms debounce and sent twice under load; now fake timers, forge-et-pwa#158)
  • Sync target: upstream
  • Synced: pending

Problem observed

Two backend jobs stop starting work once a time budget has passed: the mailbox back-fill and the subscription-renewal job. Each takes the budget as half the queue’s visibility timeout. The test profiles set that timeout to 2 s so that redelivery is fast, which makes the budget 1 s in every test. Three tests failed only in full builds on busy machines, and passed alone:

  • BUG-081. The renewal case expected one renewal event after one job run. The run starts its clock before its due query, so a query that took more than 1 s left the run reaching nothing (due=1, reached=0).
  • BUG-077 and BUG-082. A back-fill case expects exactly two 700 ms pages before the 1 s stop. A loaded machine’s first page passed 1 s and the run stopped after one. A second back-fill case resumed a run and asserted straight afterwards that its last page was stored. On an idle machine the run takes 32 ms, but under load it passed 1 s before its last page and handed that page to a continuation job, so the row was still queued when the case looked.

Each test was correct about the code. Each also assumed the machine would do a given amount of work within 1 s, and a machine running several Testcontainers suites at once does not.

Change made

For BUG-081 the test now runs the job through its handler until the case’s connection is no longer due. The service already promises that a subscription a run did not reach stays due for the next run. A new case holds an exclusive lock on the table until the run’s due query is seen waiting on it in pg_stat_activity, then past the budget, so the first run reaches nothing every time. A hold of fixed length, started before the run, was not enough: backend-reviewer pointed out that on a loaded machine the run could start late enough to finish inside its budget. That case failed with the old single-run helper and passes with the new one.

For BUG-082 (and BUG-077), the first case tests the time bound itself, so running the job again does not help it. The back-fill now reads the injected BusinessClock instead of System.nanoTime(), and a new unit spec, MailboxBackfillServiceSpec, moves a MutableClock by a fixed step per page to pin the page the run stops on, including the edge where two pages end exactly on the bound. The integration case now asserts only what holds on any machine: the run stopped after one or two pages, because each stub page waits at least 700 ms. The second case now waits for the whole back-fill, continuations included, before it asserts. Arming a longer stub page delay forced both failures with the reported messages before the fix, and the fixed cases pass under the same delays (forge-et-be#169).

Lesson

  • A test must not depend on how much work a real-time budget allows. When the code stops starting work after a budget, either assert something that holds whatever the machine’s speed, or remove the timing: drive the budget or the clock from the test.
  • When the code promises that the next run finishes what this run left, the test can rely on that promise. Run the job again until the outcome the case checks has happened, inside a bounded PollingConditions, and keep the assertion on the outcome (one event, not one run).
  • Prove the change by forcing the slow path, not by a green re-run (L-107). Hold a lock, or arm a delay, so that the budget is spent before the work the case checks, and show that the case fails without the change. Start the forced delay from something the run has done (its query seen waiting), not from a moment before the run starts, or the forcing is itself timing-dependent. Cap a test’s LOCK TABLE with SET LOCAL lock_timeout, so a lock it cannot get fails the case instead of queueing every later query on the table.
  • To pin where a run stops, give the code an injected clock and step it in a unit spec. A test that crosses the budget with real delays only moves the margin: a longer bound or a shorter delay changes how loaded the machine has to be, not whether the case can fail.
  • Known remaining instances (as of 2026-10-04): none among the tests named here; forge-et-be#169 fixes the two MailboxBackfillIT cases. Two budgeted runs still read System.nanoTime(): MailboxRenewalService.renewDue and MailboxDeltaPollJobHandler’s Deadline. A test that needs to pin where either stops needs the injected clock first.

L-126 — Gate the design vision pass on the wave shipping a screen, not on a work item’s tier

  • Date: 2026-10-05
  • Source commits in this repo: .forge/specs/F26-b-standards-book-findings.md F-001; .forge/plans/F26-b/F26-b-decomposition-plan.md ## Notes (the Step 5g workaround)
  • Sync target: upstream
  • Synced: pending

Problem observed

/forge-deliver Stage 7 Step 5g runs the design vision pass only when a wave has “a T3 WI touching frontend route/component files”. A type: sub frontend work item is never T3 in practice: frontend-implementer writes T1 and T2 tests only, and the orchestrator runs browser suites only for verify and e2e items. So a wave whose frontend work is a T2 sub item, with its browser coverage in a T-E2E item — F26-b’s wave 1, F1-b’s waves — ships a screen that Step 5g’s wording skips.

Change made

F26-b’s Decomposition Plan added a Note telling the orchestrator to run Step 5g for wave 1 anyway, and it ran after WI-1.5’s browser suite was green (verdict in F26-b-WI-1.3-test-verify.md).

Lesson

  • A check meant for every new screen must be triggered by the screen, not by the test tier of the item that built it. Gate Step 5g on “a sub WI in the wave changes frontend route or component files”, whatever its tier.
  • Until the command changes, a Decomposition Plan whose frontend sub items are T2 carries the Note that F26-b’s did.

L-127 — Freezing a wave contract checks that its seed can reach every error code the verify item must prove

  • Date: 2026-10-05
  • Source commits in this repo: .forge/specs/F26-b-standards-book-findings.md F-002; .forge/plans/F26-b/F26-b-WI-1.4-plan.md D10
  • Sync target: upstream
  • Synced: pending

Problem observed

F26-b’s wave 1 contract gave the verify item “every endpoint and error code”, but its ## Seed fixtures had no inactive certification and no endpoint could make one. No HTTP request on the local seed could produce 422 CERTIFICATION_NOT_ACTIVE. The gap was found while the work item plans were written, after the contract had frozen, so the verify plan recorded an exception and the code’s own integration test (AC-11) became the only proof.

Change made

WI-1.4’s plan recorded the exception (D10) and pointed at WI-1.1’s integration test as the authoritative proof; the contract was not reopened.

Lesson

  • Before a contract freezes, walk each error code the verify item is meant to prove and name the seed row or endpoint that creates its precondition. Where none exists, either add the seed row or write the exception into the contract’s ## Owners row at freeze time, so no plan discovers it later.
  • Candidate change: forge-contract-author performs this walk as one of its checks.

L-128 — Compare a timestamp from a write response with a later read as an instant, never as text

  • Date: 2026-10-05
  • Source commits in this repo: .forge/specs/F26-b-standards-book-findings.md F-003; forge-et-fe 29949a9 (WI-1.4 seam test); .forge/bugs.md BUG-288 (forge-et-be#344)
  • Sync target: project-only
  • Synced: pending

Problem observed

POST /api/v1/buying-standards returned createdAt with 100-nanosecond digits (…43.405718800Z), the instant the JVM generated, while the GET straight afterwards returned the value Postgres stored, rounded to the microsecond (…43.405719Z). Both conform to the contract’s “ISO-8601 UTC instant”. A seam test that compared the two as strings failed.

Change made

The seam test compares the two values as one instant, to under 1 µs (forge-et-fe 29949a9).

Lesson

  • In a seam or integration test, compare timestamps as instants with a tolerance of one database tick, not as strings, whenever one side is a write response and the other a later read. The JVM’s clock (100 ns on Windows) is finer than Postgres’s timestamptz (1 µs).
  • Set a timestamp the backend stores at the precision the database keeps. JPA auditing does this for every created_at / modified_at through MicrosecondDateTimeProvider (forge-et-be platform/config, BUG-288), so a write response and a later read now agree exactly; a timestamp set by hand and returned before a read is cut with Instant.truncatedTo(ChronoUnit.MICROS), as the mailbox services do. BUG-288 was the second instance: a contact’s no-change PATCH answered a modifiedAt different from its create on every Windows build.

L-129 — An accessible name built with aria-labelledby is proven only in a real browser; reference the visible label’s element, never the control itself

  • Date: 2026-10-05
  • Source commits in this repo: .forge/specs/F5-d-roles-editor-findings.md F-001; .forge/bugs.md BUG-092; forge-et-fe b62bd34 (the marked browser assertion)
  • Sync target: upstream
  • Synced: pending

Problem observed

The role editor’s blocked All records checkbox was named with aria-labelledby="<the checkbox's own id> <reason id>", meant to read “All records, Choose View or Manage first”. The jsdom component test passed. In Chromium the checkbox’s reference to itself contributes no text, so the name was only the reason, and the visible label “All records” was missing (WCAG 2.5.3, Label in Name). Two waves of component tests and reviews passed it; the wave-3 browser suite’s toHaveAccessibleName found it.

Change made

Filed as BUG-092. The browser assertion is its own test, marked markKnownFailure('BUG-092', …) until the fix, which references the label text’s own element.

Lesson

  • Assert a composed accessible name in a browser test. When a control’s name comes from aria-labelledby (or aria-label replacing a wrapping label), the jsdom name computation is not evidence; a Playwright toHaveAccessibleName is.
  • Point aria-labelledby at the visible label’s element and the extra text’s element, never at the control itself. A wrapping <label> has no id to reference, so give the label text an element with an id.
  • A reviewer reading a new aria-labelledby asks which browser test asserts the resulting name.

L-130 — A Playwright filter({ has }) locator is searched inside each candidate; one rooted at an outer element never matches

  • Date: 2026-10-05
  • Source commits in this repo: .forge/specs/F5-d-roles-editor-findings.md F-002; forge-et-fe 96b882a
  • Sync target: upstream
  • Synced: pending

Problem observed

Three new F5-d browser tests found a list row with card.getByTestId('roles-list-row').filter({ has: card.getByTestId('roles-list-name-link').and(…) }). Playwright resolves the has locator inside each candidate row, so an inner locator that starts from card looks for the card within the row and matches nothing. The tests failed as “element not found”, which reads like a missing row rather than a wrong locator. Typecheck, Biome and playwright test --list all passed; only a live run showed it.

Change made

A roleRow(card, name) helper builds the inner locator from page (page.getByTestId(…)), which Playwright treats as relative to each candidate (96b882a).

Lesson

  • Build a has or hasNot locator from page, never from the outer locator or one of its ancestors. Playwright documents that the inner locator is queried from the outer match.
  • A row helper that takes the list and a name keeps the pattern in one place.

L-131 — A known-failure mark covers the whole test, so the marked test holds only the failing assertion

  • Date: 2026-10-05
  • Source commits in this repo: .forge/specs/F5-d-roles-editor-findings.md F-003; forge-et-fe 58d5ed1 (forge-et-fe#144 review, Important #1)
  • Sync target: upstream
  • Synced: pending

Problem observed

The first BUG-092 test asserted the blocked state of every owned entity’s All records box (None chosen, aria-disabled="true") as well as the failing accessible name. markKnownFailure is test.fail(true, …) over the whole test, so any of those checks failing would also have counted as the expected failure, and the blocked state of entities other than Leads was asserted in no unmarked test. A regression there would have passed the gate while the bug stayed open. The PR’s review caught it.

Change made

The blocked-state checks moved into an unmarked test; the marked test keeps its setup and the one failing assertion (58d5ed1).

Lesson

  • When a test is marked as an expected failure, move every other assertion it makes into an unmarked test first. Leave the marked test with its setup and the single assertion the bug breaks.
  • When the bug is fixed and the mark removed, put back any precondition check the marked test needed (that the setup reached the state the assertion is about) — BUG-092’s Fix line is the example.

L-132 — A browser-gate result belongs to the checkout that ran it; a wave worktree at the same commit runs the gate again

  • Date: 2026-10-05
  • Source commits in this repo: .forge/specs/F5-d-roles-editor-findings.md F-004; .forge/plans/F5-d/F5-d-WI-3.1-plan.md ## Notes § Wave PR
  • Sync target: project-only
  • Synced: pending

Problem observed

Stage 11 fast-forwarded F5-d’s frontend wave branch to the e2e WI’s head b62bd34, the commit the WI worktree’s pnpm e2e:gate had just passed. In the wave worktree, node scripts/browser-gate.mjs covers --head HEAD answered “no gate result”, because the result is the checkout’s own .browser-gate/result.json. The wave worktree also had no node_modules, so the first gate attempt there failed at once. It cost a dependency install and a second full gate run (about five minutes) for a commit already proved.

Change made

None in the framework yet; the wave worktree was installed and gated again.

Lesson

  • Install dependencies in every app-repo wave worktree when it is created, as forge-worktree-up does for work-item worktrees.
  • When the last WI of a wave is the e2e or verify item and the wave branch fast-forwards to its head, open the wave PR from that WI worktree’s result, or run the gate once in the wave worktree only — not in both.

L-133 — A state change that removes the focused control must say where focus goes

  • Date: 2026-10-05
  • Source commits in this repo: BUG-026 (forge-et-fe#56), BUG-056 (forge-et-fe#118); F1-b finding F-006 (forge-et-fe#171 — Retry, Reset list, Go to page N and the edit route’s frames each needed a focus target, found over three review rounds because the plans listed none); BUG-159 (forge-et-fe#236 — the user editor’s Discard disabled itself under focus with no focus target and no announcement); BUG-251 (forge-et-fe#335 — the shared Select’s closing list swallowed a quick Tab, and its focus return to the trigger came from a timer); BUG-262 (forge-et-fe#344 — the Leads list’s Show all leads, Go to page N and Retry left with their own press and named no focus target, as F1-b F-006 had found on the contacts list); BUG-317 (forge-et-fe fix/BUG-317-refresh-notices — the Users and email templates lists’ refresh-failed Retry left once its re-read succeeded, with no focus target); BUG-321 (forge-et-fe fix/BUG-321-access-dialog-stale-lists — inside the Access dialog a Retry that answered left with its band, and Radix’s focus trap put focus on the dialog’s content, which useFocusAfterWrite did not count as nowhere); BUG-302 (the record Tags section’s Add tag chip sat in the empty state’s own list and in the tags’ list after the first tag, so the attach answer remounted it and lost the focus a pick had put on it; BUG-014 had the same cause in a wrapper); BUG-293 (the shared Select inside a dialog took the dialog trap’s fallback focus for a user’s move and kept focus off the trigger); BUG-379 (forge-et-fe#454 — the Activities edit dialog armed the “row left, focus the h1” check from its save but not from its Reopen, so a reopened row dropped by the re-read left focus on body); BUG-384 (the mailbox screen’s Reconnect / Try Again and the lapsed sync indicator’s Reconnect moved into an ErrorPanel on a refused start, a different parent, so the remount lost the focus the press left on them; useRefusedStartFocus puts it back)
  • Sync target: upstream
  • Synced: pending

Problem observed

Twice a control the user had just pressed was removed by the state change its own press caused, and the browser dropped keyboard focus to <body>, so a keyboard or screen-reader user started again from the top of the page. In BUG-026 a mailbox re-read replaced the connected or reconnect panel, buttons included. In BUG-056 the login page’s “Try again” re-read the session, and on a 401 the service-unavailable notice and its focused button unmounted together. Both passed review and a green suite: the tests asserted what the screen showed after the change, and none asserted where focus was.

Lesson

  • When a control’s action can remove that control — a notice that clears, a panel that swaps, a button that turns into a different state — the change names a focus target that stays on the page, and moves focus there only when, at the press, focus was on the control or on nothing (<body>), the control has since left the page, and nothing holds focus now. It never takes focus back from where the user moved it, and it leaves focus alone when the control survives (a failed retry).
  • Count settled actions, not state transitions. A fast answer can land in the same render as the press, so the component cannot see the change begin or end; increment a counter when the action settles and check focus in a layout effect keyed on it (features/email/useRefetchRestoringFocus, features/auth/LoginRoute.tsx useServiceRetry).
  • The test asserts toHaveFocus() on the target after the change, plus a row where the user moved focus during the wait (not stolen) and a row where the control survives (focus stays). A test that asserts only what renders afterwards cannot catch this.
  • “Held focus at the press” alone misses a press that never focused the control — a click or tap in Safari, a click in Firefox on macOS, some assistive-technology activations — which leaves focus on <body> before the control is removed. Treat a press made while nothing held focus as the control’s own, and pin it with a test that activates without focusing (fireEvent.click).
  • A library’s own focus return is not enough when it is late. An overlay that stays mounted through a closing animation still holds the keyboard (Radix’s Select prevents Tab inside it), and a focus return run from a timer after unmount arrives after a quick next key (BUG-251). The overlay unmounts at once, or the component takes the next key itself; the test presses the next key with no wait, in Chromium and WebKit.
  • A control that stays on screen across two states must keep the same parent element in both. React remounts everything under an element whose type or place changes, so a control drawn in an empty state’s own list, or in a wrapper drawn in one state only, is a new element after the change and loses its focus even though it is still on the page (BUG-014, BUG-302). Render one parent in both states and vary only its contents and attributes; the test asserts toHaveFocus() on the control after the state flips.
  • Inside a focus trap, “nothing holds focus” is not only <body>. When the focused element leaves a Radix dialog, the trap moves focus to the dialog’s content, so a check for <body> alone reads the trap’s fallback as the user’s own move (BUG-293). Count focus on an element that holds the control as nothing, and test the control inside the shared Dialog as well as on the page.
  • frontend-reviewer dimension 18 checks for it.

Update — 2026-11-03

Inside a shadcn (Radix) dialog, focus does not fall to <body> when the focused control leaves: Radix’s focus trap puts it on the dialog’s own content element. A check for “focus is nowhere” that looks only for <body> therefore never runs inside a dialog, and a test that renders the component without its dialog passes all the same (BUG-321). Count focus on a dialog that holds the region as nowhere — forge-et-fe’s useFocusAfterWrite does since BUG-321 — and test the focus target with the component inside its real dialog.

L-134 — A list API written before its first screen is specced must be checked column by column against that screen’s spec

  • Date: 2026-10-05
  • Source commits in this repo: BUG-095 (forge-et-be fix/BUG-095-account-list-ltv), F1-a spec Rev 7
  • Sync target: upstream
  • Synced: pending

Problem observed

F1-a built GET /api/v1/accounts before F1-b, the account list screen, was specced. Its row (AccountSummaryResponse) was a deliberate summary of the detail record, and F1-a FR-A1 listed its members. When F1-b’s spec added an Est. LTV column (FR-L2, AC-2), nobody compared the column list with the row’s members. The gap came to light only when F1-b’s plans were re-checked against main before dispatch, and it held up the screen’s first work item. The detail record carried both fields all along, so each review of F1-a had seen a complete account and found nothing wrong.

Change made

BUG-095 added estimatedLtv and ltvCurrency to the row. F1-a Rev 7 added them to FR-A1 with a new AC-30, asserting the row’s two values against the detail record’s.

Lesson

  • When a screen spec reads a list API that already exists, the spec lists each column it shows against the row member that feeds it (or names the extra read that feeds it), and its review checks every pairing against the row record on main. A column with no member is a contract change to the API’s feature, recorded as a spec revision there and delivered before the screen’s work item is dispatched.
  • A list API built ahead of its screen states which screen spec its row shape was checked against, or that none exists yet. “None yet” means the first screen spec must do the check.
  • None of backend-reviewer, frontend-reviewer or test-strategy.md is the place to catch it: the gap is between two specs, before any code. The catch point is the screen spec’s review (spec-reviewer), and adding a row there is a harness change left for a follow-up.

L-135 — A decision is recorded where it is made; every other statement of the old fact stays wrong until someone searches for it

  • Date: 2026-10-05
  • Source commits in this repo: .forge/audits/2026-10-05-project-audit-2.md group 1; this audit’s PR
  • Sync target: upstream
  • Synced: pending

Problem observed

Four decisions taken between 2026-09-29 and 2026-10-02 — the AWS account becoming the client’s own, OQ-15’s location half reopening, the region confirmed, and AD #38’s report-only scan — were each written into the document where they were made. architecture.md, the PRD, the proposal header, the AI strategy and the client pack still stated the old fact. The first audit (2026-10-04) did not catch them, because it checked Active Context, code and comments rather than every document against each recent decision.

Change made

.claude/rules/prd.md step 4 and the Architecture Decisions intro in .claude/CLAUDE.md: a decision, an OQ answer or a reopening updates every other statement of the fact in the same PR.

Lesson

  • A decision’s PR starts from git grep of the wording it replaces (and the OQ or AD id) across .forge/ and .claude/, client pack included, and updates each hit, or adds a post-issue note where the proposal states it. Dated records (revision logs, gate runs, the engagement log) stay as written.
  • An audit checks each decision taken since the last one against every document, not the documents against each other (L-001’s second rule).

L-136 — A sentence that waits on a feature goes stale the day the feature ships

  • Date: 2026-10-05
  • Source commits in this repo: .forge/audits/2026-10-05-project-audit-2.md group 2; BUG-096 (.forge/bugs.md)
  • Sync target: upstream
  • Synced: pending

Problem observed

After F5-f, F5-k, F5-d and F26-b shipped, six features.md status cells, the team guide’s chain table, the cloud register’s A-1 row and several “until F5-f lands” and “will be installed by” sentences still described the work as unfinished. Nothing updated them, because the tracker is the only file a feature’s close writes.

Change made

A Repo hygiene check that features.md’s status, phase and Blocked-By agree with tracker.yaml, and a /forge-reflect step that searches for sentences waiting on the feature just shipped.

Lesson

  • Generate or check every copy of tracker state; a hand-kept copy needs a CI comparison.
  • Write a dependency as a pointer to the tracker (“tracker.yaml holds the state”) rather than as a dated sentence, wherever the reader does not need the date.

L-137 — A coding rule enforced only by reviewer prose is broken again by the next feature

  • Date: 2026-10-05
  • Source commits in this repo: .forge/audits/2026-10-05-project-audit-2.md group 3; forge-et-be#191
  • Sync target: upstream
  • Synced: pending

Problem observed

The first audit swept bare comment pointers, missing TraceLines and leaky records out of the code. F26-b, built during the same days, added new ones: the rule lived in reviewer instructions, a bare pointer was graded a Nit, and the audit’s notes for work in flight went to per-WI PRs, which are closed as superseded, so the next wave session never read them.

Change made

Fast-lane checks over the added lines (check-comment-pointers, check-banned-markers.py) and an ArchUnit ProductionShapeSpec; the reviewers grade a missing pointer document or work item Important; notes for work in flight go to the Decomposition Plan’s ## Notes.

Lesson

  • A rule that can be checked from the source is checked by the build, over the PR’s added lines so old debt never blocks an unrelated PR; reviewer prose is for what a machine cannot see.
  • A note for in-flight decomposed work goes where the next wave session reads it: the Decomposition Plan’s ## Notes, not a per-WI PR.
  • A machine check binds open PRs as soon as it reaches main, because PR CI runs on the merge result; land the check before sweeping, and the sweep stays clean.

L-138 — A scripted sweep needs an independent check before it ships

  • Date: 2026-10-05
  • Source commits in this repo: forge-et-be#191 (a40d532, 8281971)
  • Sync target: upstream
  • Synced: pending

Problem observed

A script added the work item to several hundred decision pointers. Where more than one WI plan defined the decision, it chose the plan that listed the file under ## Files to Modify, which is the last WI to touch the file, not the one whose commit wrote the line. About a dozen pointers named the wrong plan, and an earlier sweep commit had inserted a wrong ticket into one line.

Change made

The pointers were checked against the commit ids that each WI plan’s ## Progress records (git blame --ignore-revs-file past the sweep commits, then the plan whose Progress names that commit), and the mismatches corrected.

Lesson

  • Verify a scripted rewrite with a second, independent signal before committing it — here, blame to the writing commit and the plan that records it — and read every case the two disagree on.
  • Blame past earlier sweep commits (--ignore-revs-file), or the sweep itself becomes the author of every line.

L-139 — Instruction files and the harness’s own tests drift unless a check runs them

  • Date: 2026-10-05
  • Source commits in this repo: .forge/audits/2026-10-05-project-audit-2.md group 4
  • Sync target: upstream
  • Synced: pending

Problem observed

The agent files still carried bootstrap text for another stack (password storage, server components, a component-library CLI), and the governance hook tests and the .claude/lib script self-tests ran only when someone remembered them. A review record could omit the security pass. None of it failed anything, so two audits passed before it was found.

Change made

Repo hygiene runs the governance hook tests and every script --self-test, checks every skill’s phases: and every workflow job’s timeout-minutes; forge-review-record.sh refuses an approve with no Security pass: line; the template text was removed from the agents.

Lesson

  • A test that CI does not run is not a guard. Every hook test and --self-test is listed in Repo hygiene.
  • An audit reads the agent and skill files against the repo CLAUDE.md files, since they are what every session acts on.

L-140 — A CI job cancelled with no step run is a runner problem; check GitHub’s status before touching the PR

  • Date: 2026-10-06
  • Source commits in this repo: .forge/specs/F11-b-lead-inbox-findings.md F-003
  • Sync target: upstream
  • Synced: pending

Problem observed

During F11-b’s merge, every Actions job in the three repos (harness Repo hygiene, both app Fast lanes, the backend’s nightly run on main) ended cancelled about 15 minutes after it was queued, with no step recorded. It looked like a failing PR. repo-hygiene.yml sets timeout-minutes: 10, so a job that had started would have been stopped sooner, and with steps in its log. githubstatus.com showed an open Actions incident about runner assignment.

Change made

Nothing was re-run and no code changed. The reviews, fixes, the backend build record and the browser gate ran locally, and the branches were pushed once the incident cleared, which started CI once.

Lesson

  • Read the job before the log: gh run view <id> --json jobs showing steps: [] means no runner took the job. A timeout or failure inside the job always has steps.
  • Then check whether it is everyone’s: gh run list on another repo or main, and curl -s https://www.githubstatus.com/api/v2/incidents/unresolved.json. When other repos fail the same way, it is not the PR.
  • Wait rather than re-run: a re-run during the incident queues and is cancelled again, and the PR’s next push starts CI anyway. Keep working locally and push once the incident is resolved.

L-141 — A compare-and-set on a value that can return to an earlier state lets a stale writer through; compare a counter every write moves on

  • Date: 2026-10-04
  • Source commits in this repo: .forge/bugs.md BUG-068 (the back-fill cursor, fixed in forge-et-be#195) and BUG-102 (the delta poll’s links, fixed with delta_generation); a general concurrency pitfall for any conditional UPDATE … WHERE column = :expected, checked by backend-reviewer
  • Sync target: upstream
  • Synced: pending

Problem observed

F20-b’s back-fill and delta poll each store progress on the mailbox_connection row with a conditional UPDATE: write the new value only if the column still holds the value the run read. That stops the slower of two concurrent runs from moving progress backwards. But a reconnect resets both columns to NULL, and NULL is also what a run that started from nothing read. So a run that began before the reconnect still matches after it and writes its progress into the new back-fill or poll, which may be for a different mailbox (BUG-068, BUG-102). Each statement was correct for the races its author considered, two runs at once; the reset made the compared value return to an earlier state, which the compare cannot see.

Change made

BUG-068 added backfill_generation, a counter that every write to the back-fill columns adds one to, the reset included. The run carries the generation it read, each write matches it, and a write the run wins leaves the row at exactly one more. A CHECK refuses a negative counter and a completed back-fill that keeps a cursor. A repository IT forces two writes expecting the same generation to meet on the row lock and shows one gets through, and shows that the run from before a reset writes nothing; that second case failed with the old cursor compare. BUG-102 applied the same fix to the delta poll with delta_generation, a counter of its own: the reset clears the links and the back-fill together, but every back-fill page moves backfill_generation while the first poll runs, so a poll compared with it would have lost its write.

Lesson

  • Compare a value that only moves forward. Before writing WHERE col = :expected (or IS NOT DISTINCT FROM), list every statement that writes col. If any of them can set it back to a value it held before — NULL after a reset, an empty string, a value cycled through — a stale writer can match. Add a counter (<thing>_generation BIGINT NOT NULL DEFAULT 0) that every one of those statements increments, and compare the counter instead.
  • The reset counts as a write. The statement that clears or restarts the state must increment the counter too; it is the write the stale run most needs to see.
  • Prove it with the stale writer, not only with two concurrent ones. The concurrent case passes under the old compare as well; the case that fails before the fix is a run that read the state, a reset, and then the run’s write.
  • One counter per set of columns a run owns. Share a counter between two sets of columns only when no writer of one set runs while a writer of the other is mid-run; otherwise each set’s writes fail the other’s compare.
  • Known remaining instances (as of 2026-10-09): none. In forge-et-be, grep -rnE 'IS NOT DISTINCT FROM|= :expected' src/main/java finds only the backfill_generation and delta_generation compares once BUG-102’s change is in; re-run it to re-check.

L-142 — A known-failure mark goes wrong when main fixes its bug before the branch merges

  • Date: 2026-10-06
  • Source commits in this repo: .forge/specs/F5-c-findings.md F-007; F5-c WI-4.1 plan ## Notes (§ Review fixes on forge-et-fe#160); forge-et-fe#160 (marks removed in c011793), forge-et-fe#150 (the BUG-089 fix)
  • Sync target: upstream
  • Synced: pending

Problem observed

F5-c WI-4.1 marked four browser page-check tests markKnownFailure('BUG-089', …), correctly for main as it stood when the wave branch was cut. While the wave PR was open, forge-et-fe#150 fixed BUG-089 on main. The PR still merged cleanly and nothing required the branch to be up to date, so it would have merged with four marked tests that now pass. A marked test that passes fails the run, so every later frontend PR’s browser gate would have failed. The gate result on the PR was green: it was taken on a tree without the fix. frontend-reviewer found it by checking the bug’s status on main.

Change made

main was merged into the wave branch (a change on main the PR’s tests rely on is a valid reason), the four marks were removed, and each state’s remaining test page-checks the open list clean. The gate was re-run on the merged head.

Lesson

  • A mark is a claim about main, not about the branch. Before a PR that adds or keeps a markKnownFailure('BUG-NNN', …) (or a size-matrix knownFailures entry) merges, check the bug is still open on main: its status in tracker.yaml on origin/main, and git log origin/main --grep BUG-NNN for a fix that has landed. If it is fixed, merge main in, drop the mark and re-run the gate.
  • A clean merge and a green gate do not catch it. The gate ran on the branch’s tree; the conflict-free merge with main is exactly the case nothing flags.

L-143 — On macOS, Home and the arrow keys do not change a closed native <select>; change it by type-ahead

  • Date: 2026-10-06
  • Source commits in this repo: .forge/specs/F5-c-findings.md F-008; .forge/bugs.md BUG-103, BUG-122, BUG-407, BUG-477 (forge-et-pwa#164, the capture app’s Edit Details keyboard test); forge-et-fe#160 (855dccc), forge-et-fe#194, forge-et-fe#517
  • Sync target: upstream
  • Synced: pending

Problem observed

Two F11-b keyboard tests pressed Home (back to “Any country”) and ArrowDown (Rows per page 25 → 50) on a focused, closed native <select>. On Windows and Linux Chromium those keys change the value, and the author’s browser gate passed. On macOS Chromium they open the picker or do nothing, so the value stayed and the list read the test waited for never came: every gate run on a Mac failed on the two tests. The browser gate runs on each developer’s own machine (.claude/CLAUDE.md § Quality Gates), so a test that holds on one OS is not enough.

Change made

Both steps change the select by type-ahead (type('Any'), type('50')), which works on every platform. Chromium keeps a select’s type-ahead text for about a second, so a second type-ahead straight after the first extends the search (“Sweden” + “Any” → no match); the test moves focus off the select and back (Shift+Tab, Tab) between the two, which starts a new search.

Lesson

  • In a browser test, change a closed native <select> by type-ahead, never by Home, End or an arrow key, and assert the value after each change. Keep the test keyboard-only; type-ahead is a keyboard action.
  • Two type-aheads on one select need a refocus between them (or a wait the test cannot afford).
  • Do not assume a native <input type="date">'s part order either. On macOS, Chromium takes it from the operating system’s region whenever the system language matches the page’s, so Playwright’s locale does not set it: a Mac with region Sri Lanka puts the year first. Read the order once (type a known date into a scratch date input on a blank page in the same context) and type each date in that order (BUG-122).
  • A keyboard test that passed on its author’s OS is proved on that OS only (the same point as L-046 for documents): the team’s gates run on macOS and on other systems.

L-144 — A rule about “every” case needs a check that lists the cases

  • Date: 2026-10-06
  • Source commits in this repo: .forge/specs/F5-c-findings.md F-005; .forge/bugs.md BUG-087, BUG-091, BUG-143 (the account form’s certification read, fixed in forge-et-fe#223 after F12 fixed only the lead form’s) and BUG-148 (F40 Rev 5’s known-failure mark built in forge-et-fe only, ported in forge-et-pwa#67); BUG-212 (the sign-in page’s service-unavailable notice, BUG-087’s rule, fixed in forge-et-fe#314); forge-et-fe#142
  • Sync target: upstream
  • Synced: pending

Problem observed

BUG-087’s rule says every error state for a failed API read or write shows its correlation id. Its fix, and the dispatch note to the next work item, named one example — the page-level read panel. The next screen’s save refusal, failed reload and picker read failures shipped without the id; the reviewer found them (forge-et-fe#142 fixed those), and the same gap in two other forms became BUG-091. Each author satisfied the example, not the rule.

Change made

The missing states were fixed in the wave PR and BUG-091 filed for the rest; the WI plans that followed listed each error state with its own test row.

Lesson

  • When a rule says “every X”, write down the Xs. A plan, dispatch note or reviewer checklist that carries such a rule lists each instance in its scope (each error state, each endpoint, each page state) with the test that proves it, rather than pointing at one example.
  • Prefer a check that enumerates for you — a test that walks every instance, or a grep a reviewer runs — over a sentence an author has to remember.

L-145 — Pin a contract’s order of checks to where the shipped code raises each error

  • Date: 2026-10-06
  • Source commits in this repo: .forge/specs/F5-c-findings.md F-001; .forge/plans/F5-c/F5-c-Wave-2-contract.md Rev 0 → Rev 1
  • Sync target: project-only
  • Synced: pending

Problem observed

F5-c’s Wave-2 contract (Rev 0) put the role and manager reference checks after the 404 and the 409 STALE_VERSION. Grounding the backend plan found that forge-et-be/docs/api/errors.md allows a RequestValidationException only from controller code, and that Wave 1’s create already checks the same references in its controller before the service runs. Rev 0’s order would have needed a 400 raised from the service, against the documented rule.

Change made

Contract Rev 1 moved the reference checks to the other 400s, before any plan used Rev 0.

Lesson

  • Before pinning a contract’s order of checks, read where the shipped code raises each error — the same resource’s existing controller validation and docs/api/errors.md’s rule on which layer raises which code — and order the checks to match. An order the layering cannot produce is a contract defect found late, by the implementer.

L-146 — A nested @TestConfiguration in one spec is found by another spec’s component scan, so it fails only in the whole suite

  • Date: 2026-10-07
  • Source commits in this repo: .forge/specs/F5-e-effective-permissions-viewer-findings.md F-002; .forge/plans/F5-e/F5-e-WI-1.1-plan.md § Failed Approaches
  • Sync target: upstream
  • Synced: pending

Problem observed

F5-e WI-1.1 registered a counting BeanPostProcessor for a statement-count spec through a nested @TestConfiguration. The spec passed on its own; the full ./gradlew build failed only LaptopModeIT > initializationError (No qualifying bean of type HikariDataSource). That spec’s ApplicationContextRunner component-scans com.empireteas without Spring Boot’s TypeExcludeFilter, which is what normally hides @TestConfiguration classes from scanning, so it picked up the nested class and wrapped its DataSource.

Change made

The counting class became a plain static class with no stereotype annotation, registered by the spec’s own @Import — the pattern ScanResultQueueIT.ImmediateAcknowledgement already used.

Lesson

  • Register a test-only bean with @Import of a plain class, not a nested @TestConfiguration. A stereotype-annotated class under src/test is visible to any context that scans the base package without TypeExcludeFilter (an ApplicationContextRunner, a hand-built context), and the failure appears in that other spec, in the whole suite only.

L-147 — Run-unique browser fixtures grow the local database, so a test that reads the first page of a shared list fails later

  • Date: 2026-10-07
  • Source commits in this repo: .forge/specs/F5-e-effective-permissions-viewer-findings.md F-003; .forge/bugs.md BUG-106 (fixed in forge-et-fe#168); BUG-112 (a test opened the newest row of a list another worker’s test renames — forge-et-fe#174); BUG-120 (a count compared with a later read — forge-et-fe#179); BUG-123 (the tags earlier runs left made the tag list scroll, which exposed a real axe defect — forge-et-fe#224 pins 25 tags); BUG-173 (tests that read every page of a growing list timed out — forge-et-fe#252 narrows them and makes the gate stop on an outgrown database); BUG-227 (the price-import seam walked every auction sale, which the gate’s limit does not count; forge-et-fe#332 gives refused and duplicate sales dates no other test writes and reads only up to them)
  • Sync target: upstream
  • Synced: pending

Problem observed

The browser suites make reruns safe by giving every fixture user and role a run-unique name, and users are never deleted (AD #34). After several pnpm e2e:gate runs on one local database it held 258 active users, and three F11-b leads tests failed: they read the user directory as one page of 100 and expected seeded user 6 on it. The same head passed on a fresh database. e2e/README.md says the local database does not need resetting, so nothing told the developer the failure was the database’s age.

Change made

Filed as BUG-106 with the fix: look each needed user up with the directory’s q search, and build the owner-filter fixture so that it sorts first.

Lesson

  • A browser test never relies on what the first page of a list holds when other suites add to that list. Find the records it needs by search or by id; when a test must see a record on the first page, create it so that it sorts first. Run-unique fixtures make reruns safe and make every shared list grow without bound.
  • The same holds for a control that offers a list’s first page — an owner picker, a filter select. A test that picks from it creates the person it picks so that they sort first, asserts the option is offered before choosing it (so a broken premise fails naming it, not as a timeout), and removes them afterwards. The BUG-106 fix found four more tests with this shape than the three the bug named, by running the suite against a database seeded with 110 users who sort first.
  • Nor on which row is newest. In a suite that runs in parallel, the newest record a user reaches may be another worker’s, which that worker is about to change (BUG-112). A test opens a record its own test created, by id or by a run-unique search.
  • Nor on a total read after the screen’s. Another worker can add a record between the screen’s read and a second read the test makes, so the two totals differ (BUG-120). Compare the screen with the response it received (loadLeadsList in e2e/browser/leads/support.ts).
  • Nor on reading every page of it. A test that walks a whole shared list gets slower with every run until it times out (BUG-173). Scope the read to the records the test names, with q or an id, and check a filter’s behaviour on its first page. Where the screen itself reads every page (the Owner filter, BUG-109), no test change helps: pnpm e2e:gate stops before the first test once the local database holds more than 1,000 active users or leads, and prints the reset.
  • Date: 2026-10-07
  • Source commits in this repo: .forge/specs/F5-e-effective-permissions-viewer-findings.md F-004; .forge/plans/F5-e/F5-e-decomposition-plan.md § Pre-PR Review — F5-e wave 1; .forge/bugs.md BUG-099 (links in a list, not running text, so no exemption — forge-et-fe#168); BUG-297 (the Auction sales table’s sale-round links, 15px tall) and BUG-292 (the user page’s Reporting line links, 19.5px), both links standing alone in a cell or a card, given the 24px box in forge-et-fe#390
  • Sync target: project-only
  • Synced: pending

Problem observed

F5-e’s effective-permissions section rendered the role link as <strong><a>…</a></strong>, 16 px tall. The browser gate’s page check exempts inline links from the 24 px target-size floor (WCAG 2.2 SC 2.5.8), but the <strong> wrapper made the link read as a standalone control, and 64 user-editor page states failed at every size. The component’s unit tests passed; only the browser gate measures targets.

Change made

frontend-implementer moved the <strong> inside the link (forge-et-fe 20509b9).

Lesson

  • Put emphasis inside a link (<a><strong>…</strong></a>), never around it, when the link sits in running text and relies on the inline-link exemption; otherwise give it a 24 px target. Run the browser gate before calling a new inline link done — no unit test sees the target size.

L-149 — A library-built HTTP client has no timeout until the code sets one

  • Date: 2026-10-07
  • Source commits in this repo: .forge/bugs.md BUG-101; the fix is altrium-io/forge-et-be#207; BUG-108 (the sign-in and consent code exchanges, altrium-io/forge-et-be#208); BUG-113 (the bounded exchange’s failure was shown to nobody and logged only at DEBUG, altrium-io/forge-et-be#210); BUG-116 (a refusal before the exchange, altrium-io/forge-et-be#211); BUG-174 (the KMS client built with the SDK’s defaults, while a mailbox connect holds the owner’s row lock, altrium-io/forge-et-be#244); BUG-178 (the bounded KMS call’s timeout reached a catch that logged every fault at WARN, so an outage raised no alarm, altrium-io/forge-et-be#245)
  • Sync target: upstream
  • Synced: pending

Problem observed

The mailbox token refresh used Spring Security’s RestClientRefreshTokenTokenResponseClient as built, whose RestClient sat on HttpComponentsClientHttpRequestFactory with no connect or read timeout. The refresh runs while MailboxTokenService holds the connection’s row lock and a pooled database connection, and during a deactivation the access.manage advisory lock too, so a stalled Entra endpoint could hold all user and role administration with no bound. The Graph client next to it had named short timeouts; the token client, built by the library rather than by the code, was never looked at.

Change made

RefreshTokenResponseClients gives the client its own RestClient with 3 s connect and 5 s read timeouts, re-adding the converters and error handler that setRestClient replaces. A spec against a stalled loopback server proves the bound. The first version copied the Graph client’s 15 s read timeout. The JDK client’s read timeout bounds the whole exchange, and the caller makes three attempts under its lock, so that would have been 45 s. The sign-in and consent exchanges have the same gap (BUG-108).

Lesson

  • Every outbound HTTP call has a connect and a read timeout that the code sets and a test asserts, including clients a library builds for you (OAuth2 token clients, SDK defaults). Look for the client where it is constructed, not only where the code calls it.
  • Size the timeout from what waits on it: the bound times the caller’s attempts is how long its locks and pooled connections are held. Do not copy another client’s value.
  • Replacing a library’s client replaces its configuration too. Re-add the converters and error handler it relied on, and test a success and a refusal through the replaced client. backend-reviewer checks this.
  • A bound turns a hang into a failure, so the failure needs a path too (BUG-113). Check what the user sees and what the log says when the call times out or is refused, at a level an outage would be noticed by, with the error code and never the request’s content.
  • The failure path also covers a refusal that happens before the call (BUG-116). A cancelled consent fails in the library before the token client runs, so an outcome recorded in that client never exists. Decide the result where every path ends (the landing), and clear any earlier result when a new attempt starts. An error code that arrives in the request is logged only when it matches a strict pattern.

L-150 — A live region around a list reads every row; a list announces through one status line

  • Date: 2026-10-07
  • Source commits in this repo: .forge/bugs.md BUG-104; the fix is altrium-io/forge-et-fe#168
  • Sync target: upstream
  • Synced: pending

Problem observed

coding-standards.md §3.2 said every region whose content swaps after first paint is wrapped in aria-live="polite". The Users list followed it and wrapped its whole table, so each search, filter or page change asked a screen reader to read up to a page of rows. The inbox and the Leads list had already departed from the rule with a one-line status, but the rule was not changed, so the next list built to it repeated the problem. Axe and the size matrix pass either way; only what a screen-reader user hears differs.

Change made

The Users table region is no longer live, and a visually hidden role="status" line announces the count or the state. §3.2, forge-et-fe/CLAUDE.md and frontend-reviewer dimension 19 now state the list exception.

Lesson

  • When two screens depart from a written rule for the same reason, change the rule. A departure left undocumented makes the rule wrong, and the next author follows the rule.
  • A list’s live part is one short status line, empty when an role="alert" panel already announces the error; the rows themselves are never in a live region.

L-151 — A control filled from a paged list reads every page, or says where it stops

  • Date: 2026-10-07
  • Source commits in this repo: .forge/bugs.md BUG-109 (fixed in altrium-io/forge-et-fe#172) and BUG-111; BUG-106 (the same premise in the browser tests); BUG-114 (the pricing reads, altrium-io/forge-et-fe#177), BUG-117 (the Tag filter, altrium-io/forge-et-fe#179) and BUG-119 (the account form’s certifications)
  • Sync target: upstream
  • Synced: pending

Problem observed

The leads owner picker and Owner filter read the user directory as one page of 100. The premise was that Empire has 10–20 users, so one page holds everyone. It held for Empire, but the browser suites filled every local database past 100 users, and nothing stopped the cap reaching a real deployment that grew. The Users screen’s manager picker was built on the same premise (BUG-111), and so were the leads browser tests (BUG-106). Each control showed a “Showing the first 100” helper, which said where the list stopped but left anyone past it unreachable.

Change made

listUserDirectory reads every page when the first reports more, keeps a user once, rejects on a failed page and stops at 50 pages. A pinned browser test serves a two-page directory, so the page-2 path is proved on any database. BUG-111 is filed for the manager picker.

Lesson

  • A picker, filter or select filled from a paged endpoint reads every page, bounded and cancellable, unless the product decides a cap. A deliberate cap is shown in the control and named in the spec, never left as a premise about how many records there are today.
  • Prove the further pages with a pinned test. A live run only reaches page 2 on a database big enough, which a fresh database never is. frontend-reviewer checks this.
  • A check that sends ids back as the whole set is the same case (BUG-114’s expectedCostIds): one page makes the server’s “the client saw every row” check untrue.
  • Finding one such read is the cue to look for the rest. Each of BUG-109, BUG-111, BUG-114 and BUG-117 was found by the review of the one before. git grep -n 'size=100\|SIZE = 100' src lists the candidates.

L-152 — Run the browser gate alone on the machine, with fewer workers where memory is short

  • Date: 2026-10-07
  • Source commits in this repo: F1-b finding F-001 (.forge/specs/F1-b-account-list-findings.md); forge-et-fe#171 9939951 (ET_E2E_WORKERS)
  • Sync target: upstream
  • Synced: pending

Problem observed

F1-b’s wave needed five browser-gate runs on one Windows laptop (12 cores, 16 GB, about 2.5 GB free with the usual desktop apps open). Runs made while an implementer ran the unit suite, a build or a dependency install failed 145 and 50 tests; a run at Playwright’s default six workers with nothing else running failed 4; the same head at three workers, alone, failed 1 (an open flake). Almost every failure was a timeout on a screen the change did not touch, and each failed run cost about 40 minutes. The full unit suite slowed the same way (784 s against about 330 s).

Change made

forge-et-fe playwright.config.ts reads an optional ET_E2E_WORKERS (a positive whole number; unset keeps Playwright’s default), documented in e2e/README.md. The orchestrator held background agents back from full-suite runs while a gate ran.

Lesson

  • A browser gate runs with nothing else heavy on the machine — no unit suite, build, install or second browser run beside it, from the session or from a dispatched agent. An agent that must run a full suite waits until the gate is finished (its dev server holding port 5173 is the signal).
  • On a machine short of memory, run fewer browsers: ET_E2E_WORKERS=3 pnpm e2e:gate. A slower clean run is cheaper than a fast run that fails on untouched screens and has to be repeated.
  • Read a gate failure before re-running it: failures spread across screens the change never touched, mostly timeouts, are load; failures in the changed screens are defects.

L-153 — Fetch and compare the remote head before every push to a branch someone else can push to

  • Date: 2026-10-07
  • Source commits in this repo: F1-b finding F-003 (.forge/specs/F1-b-account-list-findings.md); forge-et-fe#171, forge-et-harness#495
  • Sync target: upstream
  • Synced: pending

Problem observed

While the orchestrator fixed review findings locally on F1-b’s wave branch, the lead pushed six commits to the same branch (with the lead’s go-ahead, explained only in PR comments), and the harness wave branch was opened and merged as a PR by another session under the same account. The orchestrator learned of both only when a fetch showed an unexpected head. Nothing was lost, because the review fixes were merged onto the new head before any push, but a push from the stale local head would have been rejected or, with a force, would have dropped the lead’s work.

Change made

Before each push the orchestrator fetched, checked that the remote head was an ancestor of the local head, read the PR’s comments, and paused to ask the developer once it saw someone else pushing.

Lesson

  • Before every push to a wave or feature branch, git fetch and check that origin/<branch> is an ancestor of HEAD. When it is not, merge it in (never force-push), re-run the checks on the merged result, and read the PR’s comments for why it moved.
  • When someone else is pushing to the branch, stop and agree who drives it before pushing again. A shared branch with two drivers produces review records on stale heads and duplicated fixes.

L-154 — A plan must not list two paths that differ only by letter case

  • Date: 2026-10-07
  • Source commits in this repo: F1-b finding F-005 (.forge/specs/F1-b-account-list-findings.md); forge-et-fe#171 fd13689
  • Sync target: upstream
  • Synced: pending

Problem observed

F1-b WI-1.2’s plan listed src/features/accounts/AccountForm.tsx (the form component) beside accountForm.ts (the form model). On Windows and default macOS file systems, which ignore case, the import ./AccountForm resolved to the model file and tsc failed. The implementer put the 1,450-line component inside the route file instead, a deviation the review then had to undo by moving it to AccountFormPage.tsx. Two plan reviews passed the collision.

Change made

The component was moved to AccountFormPage.tsx on the wave branch, and the move recorded in the WI-1.2 plan.

Lesson

  • No two paths a plan creates or changes may differ only by letter case within one folder (AccountForm.tsx / accountForm.ts), and a new file’s name must not differ only by case from an existing one. Rename one (AccountFormPage.tsx, accountFormModel.ts) in the plan, before any code exists.
  • plan-reviewer checks ## Files to Modify for such pairs.

L-155 — A browser test opens a list once its options have loaded, and chooses from an open react-aria list by keyboard

  • Date: 2026-10-08
  • Source commits in this repo: BUG-110 (.forge/bugs.md); forge-et-fe#184 (19b81e2, 7a1ba02); BUG-234 (forge-et-fe#332: F11-f AC-31’s keyboard tag steps pressed ArrowDown and Enter without these waits; e2e/browser/leads/lead-detail-support.ts arrowDownAndChoose now makes them)
  • Sync target: upstream
  • Synced: pending

Problem observed

The Users browser tests that choose a manager failed now and then under load: the test picked an option and the field kept the old manager. There were two causes. The tests opened the manager list before the read that fills it had landed; when the read landed, the options were rebuilt and the option the test had found was detached. Once the tests waited for the read, about one run in two at two workers still lost a choice: before clicking an option, Playwright scrolled the page to it, although it was already in view, and react-aria closes an open combobox list when the page scrolls, without selecting, so the click arrived after the list had closed.

Change made

readyManagerList waits for the manager input’s aria-busy="false" (the Combobox is busy={candidates.isFetching}) and brings the field to the middle of the viewport before the list opens. chooseManager chooses the option with the arrow keys and Enter, waiting after each key for the input’s aria-activedescendant to move by one option.

Lesson

  • Open a list only once the read that fills it has landed. Wait for the state the product shows for it (aria-busy="false" on a Combobox), not for the page heading or another control.
  • Choose an option of an open react-aria Combobox list with the keyboard, not by clicking it: open the list, press the arrow keys until the input’s aria-activedescendant names the option, waiting for it to change after each key, then press Enter. Assert the chosen value afterwards. Only the Combobox was seen failing; a test of another react-aria popover that flakes the same way gets the same treatment.
  • .forge/test-strategy.md § Flaky Tests lists this as a likely cause.

L-156 — A read that decides an insert locks the row a concurrent writer changes, or the writer’s clean-up misses the insert

  • Date: 2026-10-08
  • Source commits in this repo: .forge/bugs.md BUG-090 (fixed in altrium-io/forge-et-be#215, 6ada7e5e, with ActiveEmailLookupConfinementSpec in a153b159); BUG-100 (the same cause on a deactivation and on an email change, fixed in altrium-io/forge-et-be#235, 2c0c1126 and 68c920f1: connectOrUpdate reads its owner through UserDirectory.lockActiveUser, matching the email the owner signed in with, proven by MailboxConnectOwnerChangeRaceIT); BUG-094 (the same cause where the insert is Spring Session’s own write, fixed in altrium-io/forge-et-be#224 by a check where the session is used, DeactivatedSessionFilter); BUG-093 (the same cause on an owner assignment, fixed in altrium-io/forge-et-be#241: every owner write reads its owner through UserDirectory.lockActiveUser(long), and a deactivation locks the user’s row before it counts their records, proven by OwnerDeactivationRaceIT and held by OwnerCheckConfinementSpec); BUG-359 (the same cause on a derived mark: the ranking sweep’s one-statement repair of lead_ranking.stale took no lead lock and could overwrite a concurrent writer’s result, fixed in altrium-io/forge-et-be#376, 5d780cb5, by finding repairs read-only and recomputing each under the lead’s lock, proven by LeadRankingStaleRaceIT); .claude/agents/backend-reviewer.md § Project-specific checks
  • Sync target: upstream
  • Synced: pending

Problem observed

The first Microsoft sign-in read the user by email with no lock and then inserted a user_identity row. An administrator’s email change updated the same app_user row and then removed the user’s identity links. Under READ COMMITTED the two did not wait for each other: the insert’s foreign-key check takes only a key-share lock on the parent, which a plain UPDATE does not conflict with, and the edit’s clean-up query could not see the uncommitted insert. Both committed, and the old address kept signing in as the user. The same shape was filed three more times on a deactivation, before this lesson existed: an owner assigned to a user being deactivated (BUG-093), a mailbox connected during the deactivation (BUG-100), and a session saved after it (BUG-094).

Change made

The read that decides the link is a new AppUserRepository.lockActiveByEmail, the same query with @Lock(PESSIMISTIC_READ) (FOR SHARE), which conflicts with the edit’s update in either order. findActiveByEmail stays lock-free, because the stub login calls it in a read-only transaction and PostgreSQL refuses FOR SHARE there. IdentityLinkRaceIT holds one transaction open and asserts the other waited, in both orders, the LastAdminRaceIT pattern. ActiveEmailLookupConfinementSpec keeps the lock-free read to the stub login, so a later first-link path cannot use it. backend-reviewer now checks for the shape.

Lesson

  • When a transaction reads a row to decide whether to insert something that depends on it, and another transaction can change that row and then clean up what depends on it, the read holds the row FOR SHARE. A foreign key does not protect this: its key-share lock does not conflict with an update of non-key columns. The alternative is a lock both sides already take (the access.manage advisory lock serialises the user edits).
  • FOR SHARE needs a read-write transaction. A read-only caller that decides nothing keeps the plain query; give the locking read its own method rather than adding the lock to a shared one.
  • The writer that cleans up, or counts, takes its conflicting lock before the read it decides on, not only at its own UPDATE. BUG-093’s deactivation counted the user’s records and then updated the row: with only the assignment’s FOR SHARE, an assignment that locked first made the deactivation wait at its UPDATE, after it had already counted and missed the record. The deactivation now locks the row (FOR NO KEY UPDATE) before it counts.
  • Prove it with a forced interleaving, in both orders, asserting the second transaction waited. A test that runs the two calls one after the other passes with or without the lock.
  • When the insert is a framework’s own write, check the state where the row is used. Spring Session saves the session row in its own transaction at the end of the sign-in request, so no lock can be held from the sign-in’s read to that write. The deactivation’s delete cannot see the row, so the security chain reads is_active on every signed-in request and ends a deactivated user’s session there (BUG-094).

L-157 — Before a PR goes ready, run every script step of the repo’s CI fast lane, not the plan’s check list

  • Date: 2026-10-09
  • Source commits in this repo: .forge/specs/F26-c-weekly-workbook-upload-findings.md F-001; altrium-io/forge-et-fe#191 (e4cde5c, 5047810); .forge/specs/F20-g-email-tracking-scheduled-send-findings.md F-001 (after review fixes, altrium-io/forge-et-fe#499)
  • Sync target: upstream
  • Synced: pending

Problem observed

F26-c’s test agents finished with the static checks their plan listed (pnpm check, typecheck, check:boundaries, the Playwright list). The fe wave PR’s first CI run then failed in 30 s on a Fast lane step none of them had run, check-comment-pointers.mjs: 187 bare spec and plan pointers in the new test files. On the first laptop, WI-1.1’s early pre-PR review had missed the backend’s check-comment-pointers.py the same way. Each miss cost a CI run, a fix round and a delta review.

Change made

Before the next push, every script step of forge-et-fe’s Fast lane (.github/workflows/pr-validation.yml) was run locally on the head, each with its own exit code: the work-marker, skipped-test, comment-pointer and testid checks with their self-tests, biome ci, typecheck, the import graph, the build, the three bundle checks and pnpm test:coverage. The next CI run passed first time.

Lesson

  • A plan’s check list is a minimum, not the gate. Before a PR is marked ready, and before an authoring agent reports “Ready to run”, run every script step of the repo’s CI fast lane, read from the workflow file itself, so the list cannot go stale.
  • A script’s pass is still not the whole rule. check-comment-pointers accepts a pointer whose plan names no work item; the reviewers grade that (the earlier comment-pointer lesson), so a fix for the script’s finding names the work item too.

L-158 — Check a shared dev-server port on IPv4 and IPv6, and take the shared lock, or Playwright reuses another session’s server

  • Date: 2026-10-09
  • Source commits in this repo: .forge/specs/F26-c-weekly-workbook-upload-findings.md F-002; .forge/plans/F26-c/F26-c-WI-1.3-test-verify.md § Phase 2 re-run on the second laptop; BUG-357 (forge-et-fe#455 — the browser gate’s clean-up requests to localhost timed out their ::1 attempt); BUG-196 (the same signature in seam and browser tests’ API calls, closed on the same fix)
  • Sync target: upstream
  • Synced: pending

Problem observed

Two feature sessions ran browser suites on one laptop, each against its own backend port. F26-c’s wrapper checked port 5173 with netstat -ano -p tcp, which lists IPv4 only, while Vite listens on localhost, which is [::1] on Windows. F11-f’s dev server was therefore invisible to the check, and Playwright’s reuseExistingServer (on outside the gate) used it. F26-c’s run tested F11-f’s code against F11-f’s backend and failed with 404s for every file F26-c adds. F11-f’s own check had the same blind spot.

Change made

The wrapper checks netstat -ano -p tcp and -p tcpv6, waits while anyone else holds 5173, and stops only Vite processes started from its own worktrees. Both sessions take one workspace lock (worktrees/.port-5173.lock, an atomic mkdir with an owner file) for every Playwright run.

Lesson

  • A port check reads both stacks. On Windows, localhost servers usually bind [::1]; an IPv4-only check reports a busy port as free.
  • Outside the gate, Playwright reuses whatever answers on the dev port. Two sessions on one machine take a shared lock for every Playwright run, or one session’s tests silently run against the other’s code and backend. A failure that looks like “my new files 404” is the first sign.
  • A test client on Windows calls the address the server binds, not localhost. Node’s autoSelectFamily (which Playwright’s request client uses) gives every address but the last a 5-second timer, so a worker whose event loop stalls for 5 s while connecting to localhost reports ETIMEDOUT ::1, then ECONNREFUSED 127.0.0.1, against a server that was up the whole time (BUG-357). Bind the test server to 127.0.0.1 and give its clients http://127.0.0.1:<port>; moving only the server leaves the client’s ::1 attempt to fail first.

L-159 — A contract’s label column is screen copy, reviewed as such

  • Date: 2026-10-09
  • Source commits in this repo: .forge/specs/F26-c-weekly-workbook-upload-findings.md F-003; .forge/plans/F26-c/F26-c-Wave-1-contract.md Rev 1; spec Rev 1
  • Sync target: upstream
  • Synced: pending

Problem observed

F26-c’s frozen seam contract gave each import problem reason a label for the screen. The private-label one read “Quoted per deal (OQ-61)”, carrying the team’s internal open-question id. The screen work item copied the contract’s labels verbatim, as it should, and the result card showed “OQ-61” to users. Only the design vision pass caught it.

Change made

Dinil changed the label to “Quoted per deal” (contract Rev 1, spec Rev 1, WI-1.2 Decision 28), and the browser suite asserts the new text.

Lesson

  • Any contract or spec column the screen shows verbatim is user-facing copy. When authoring or reviewing it, apply the copy rules — sentence case, plain words, no internal ids (OQ-n, D-n, ticket numbers) — not the rules for a code table.

L-160 — Never use git stash in a worktree of a repository other sessions also use

  • Date: 2026-10-09
  • Source commits in this repo: .forge/specs/F26-c-weekly-workbook-upload-findings.md F-004; 2026-11-12, BUG-411’s fix (forge-et-fe#518): a git stash push then git stash pop in a forge-et-fe worktree popped another session’s stash, made in the gap between the two commands, into the wrong worktree. Nothing was lost, because the pop conflicted and git kept the entry. The rule now sits in .claude/rules/git-conventions.md § Worktree Commands, where every session reads it.
  • Sync target: upstream
  • Synced: pending

Problem observed

During F26-c wave 1, several agents and sessions worked in separate worktrees of forge-et-fe and forge-et-be. The stash is one ref (refs/stash) in the repository’s shared .git, so a stash made in one worktree is listed in, and can be popped into, every other worktree of that repository.

Change made

The F26-c handoff and every dispatch prompt after it forbid git stash in app-repo worktrees; work in progress is committed to the worktree’s own branch instead.

Lesson

  • Worktrees share the stash. In a repository other sessions use through their own worktrees, keep work in progress on your branch with a commit (amend or squash it before the PR if needed), never in the stash.

L-161 — Reopen-after-Esc checks run in Playwright’s browsers, not the desktop app’s browser pane

  • Date: 2026-10-09
  • Source commits in this repo: .forge/specs/F26-c-weekly-workbook-upload-findings.md F-005; .forge/plans/F26-c/F26-c-WI-1.3-plan.md ## Progress (the keyboard walkthrough) and ## Notes
  • Sync target: project-only
  • Synced: pending

Problem observed

The agent-driven keyboard walkthrough of /pricing/import ran in the Claude desktop app’s built-in browser. There, Esc closed the replace confirmation but the confirmation could not be opened again. The pane’s Chromium 152 fires cancel but no close event when Esc closes a <dialog>, and the shared Modal reports a close to its caller only through close. A bare <dialog> behaves the same in the pane, while Playwright’s Chromium 153 and WebKit 26.6, Edge 154 and Chrome 155 all fire close.

Change made

Dinil chose to record it and change nothing (WI-1.3 plan ## Notes, option (a)). The replace step of the walk was completed in Playwright’s Chromium, keys only.

Lesson

  • The desktop browser pane is for reading and driving pages, not for proving dialog behaviour. A keyboard walkthrough step that closes a dialog with Esc and reopens it runs in Playwright’s Chromium (or WebKit). A failure seen only in the pane is checked against a bare <dialog> and a Playwright browser before it is called an app defect.

L-162 — A failure that appears only under load is reproduced with a throttled CPU before it is called flaky

  • Date: 2026-10-09
  • Source commits in this repo: .forge/specs/F11-f-lead-detail-findings.md F-001; .forge/plans/F11-f/F11-f-WI-1.6-test-verify.md (round 1, the throttled probes); forge-et-fe e1733c7; .forge/bugs.md BUG-151 (the throttle reproduced it, forge-et-fe#224) and BUG-125 (it did not; a held route loader did, forge-et-fe#224); BUG-175 (it did not; a forced late scroll did, and a WebKit Tab probe found the product side, BUG-181, forge-et-fe#242); BUG-181 (logging the open/close order in WebKit showed the tooltip always closed, forge-et-fe#246); BUG-194 and BUG-195 (forced load did not reproduce either; closed wontfix as machine overload under .forge/test-strategy.md § Flaky Tests, 2026-10-15); BUG-214, BUG-215 and BUG-225 (the same, closed wontfix on 2026-11-02); BUG-219 and BUG-224 (the same, closed wontfix on 2026-11-03); BUG-415 (the same, closed wontfix on 2026-11-13; its first attempt started the busy loops while its run waited for the heavy-run lock and held up the nightly full run, so test-strategy.md § Flaky Tests step 2 now starts them only once the run holds the lock); BUG-184 (forced load did not reproduce it either, and its run had no load record; closed wontfix as not reproduced, the lead’s decision, 2026-11-13, after forge-et-fe#529 and forge-et-pwa#126 made a size-matrix stall name its step)
  • Sync target: upstream
  • Synced: pending

Problem observed

A browser test that typed into Add tag lost the first character once in a full parallel run and passed 10 of 10 alone. Read as load noise, it would have been re-run until green. A throwaway Playwright test that set Chrome’s CPU throttling to 6× through CDP (Emulation.setCPUThrottlingRate) lost the character 3 times in 12, and 0 times in 12 on a similar picker that did not scroll on focus. The cause was a product defect: react-aria closes an open combobox list when any ancestor scrolls and commits as it closes, and the shared Combobox wrote that commit back as an empty input. Users on slow machines would have lost typed text.

Change made

The defect was fixed in the shared component, by the developer’s decision, with a component regression test; the same throttled probe then passed 20 of 20.

Lesson

  • A failure that passes alone is not yet a flake. Before re-running it or marking it, reproduce it with the CPU throttled (CDP Emulation.setCPUThrottlingRate, 4–6×) in a throwaway test, and compare a control that should not fail. A failure the throttle reproduces is a timing defect in the product or the test, and is classified and fixed as one.
  • A throttle that does not reproduce it is not the end. A race that needs one step to land late (a router commit, a lazily loaded chunk) may not appear under a slow CPU. Read the recorded value against the code for the order of events that produces it, then hold that step in a test (a route loader, a held response) — BUG-125 reproduced every time that way after 39 throttled runs showed nothing.
  • A UI library’s own closing behaviour can write state. When a component commits on close (react-aria’s close on ancestor scroll), a controlled input can be reset by an event the user never sees; a test that focuses an off-screen field triggers it.
  • Decide test or product with the user’s own input, in every engine the gate runs. A test that fixes the race (bring the control into view and let the scroll event pass first) proves nothing about the user, who reaches the control by Tab or click without settling. Before closing such a race as a test defect, run the user’s input repeatedly in each engine: BUG-175’s tooltip survived Tab 12 of 12 in throttled Chromium and was lost 7 times in 40 in WebKit (BUG-181).
  • A polling visibility check can pass on a moment that does not last. toBeVisible retries until the element shows, so it passes on a tooltip that is up for 25ms and then closes, or that sits where the control was before a scroll. Assert the state that must hold once things settle — the overlay inside the window (toBeInViewport({ ratio: 1 })), the page no taller than the window — and, when the sequence matters, log the order of opens, closes and positions in the browser before choosing a fix: BUG-181’s “always closes, sometimes caught” and “kept, but in the wrong place” were found that way.

L-163 — Count a react-aria list’s options by data-key; its empty state is also an option

  • Date: 2026-10-09
  • Source commits in this repo: .forge/specs/F11-f-lead-detail-findings.md F-003; forge-et-fe 15f9100b
  • Sync target: project-only
  • Synced: pending

Problem observed

A test asserting that an empty Add tag list offers no option (getByRole('listbox').getByRole('option'), count 0) failed once in a whole-tree run with a count of 1 and passed 5 of 5 alone. react-aria-components 1.21 renders renderEmptyState inside <div role="option" style="display: contents">, and Playwright counts that wrapper on some runs and not others.

Change made

The helper counts [role="option"][data-key]: react-aria sets data-key on every real option and never on the empty-state wrapper.

Lesson

  • Count a react-aria ListBox’s real options with [role="option"][data-key], not getByRole('option'). The empty-state message is an option element too, so an “offers nothing” assertion by role is timing- dependent.

L-164 — Two agents that commit run in separate worktrees, never one shared worktree

  • Date: 2026-10-09
  • Source commits in this repo: .forge/specs/F11-f-lead-detail-findings.md F-008; forge-et-fe 1d6461e, ec2d22a
  • Sync target: upstream
  • Synced: pending

Problem observed

To save time, a frontend-implementer (owning src/) and an e2e-test-implementer (owning e2e/) were dispatched at once into the same wave worktree, each told to stage only its own paths. The first agent’s commit still carried part of the second agent’s uncommitted change to a test-support file, so that commit does not type-check on its own. Path-scoped staging does not help when both agents’ work meets in one file, and either agent can stage a file the other is still editing.

Change made

Nothing was rewritten (the branch was still being committed to); the final tree is correct and the broken intermediate commit is recorded on the PR.

Lesson

  • Give each committing agent its own worktree and branch, then merge the branches. Parallel agents in one worktree share an index and a working tree; scoping their staging by path does not keep their commits apart. Reading agents (reviewers) may share a worktree; agents that commit may not.

L-165 — The evidential browser run uses a freshly reset test database, and a suspect failure is first tried on main

  • Date: 2026-10-09
  • Source commits in this repo: .forge/specs/F11-f-lead-detail-findings.md F-005; .forge/plans/F11-f/F11-f-WI-1.6-test-verify.md (round 2)
  • Sync target: upstream
  • Synced: pending

Problem observed

An isolated verify database stayed up for a day of browser runs. By the third whole-tree round it held 242 active users, and four tests of another feature’s Users screens timed out on manager options — a known pattern above about 100 users (BUG-106, BUG-110). The failures looked like a regression from this wave’s change to a shared component.

Change made

The same Users specs were run on the same database against main’s frontend (one failed) and the wave head (all passed), which cleared the wave. The isolated stack was then reset (docker compose down -v, fresh seed) and the round re-run: the Users failures were gone.

Lesson

  • Run the round whose result is the evidence on a freshly reset isolated database. Test data accumulates with every run, and features with list or picker thresholds start failing for reasons no diff explains.
  • Before attributing a failure in another feature’s test to the change under test, run that test on main’s code against the same database. Failing there too means the cause is the data or the test, not the change.

L-166 — Check at spec review that a test can create every record state an acceptance criterion names

  • Date: 2026-10-09
  • Source commits in this repo: .forge/specs/F5-h-offboarding-findings.md F-002; .forge/plans/F5-h/F5-h-decomposition-plan.md ## Notes (the revisions of 2026-10-08 and 2026-10-09); .forge/owed.md (the offboarding real-backend test for approved and converted leads)
  • Sync target: upstream
  • Synced: pending

Problem observed

F5-h’s spec passed two review cycles with two acceptance criteria that named states no test could create through the system on main. AC-11 covered a lead “in every status”, but approved and converted leads can only be made by routes later features build (F11-h, F11-e), and archived by F11-f’s route. AC-15 covered a deactivated user who still owns records, a state only a race bug (BUG-093) produces, because every write path refuses it. Each gap surfaced only when a test plan was written, needed a lead decision, and revised the approved Decomposition Plan after approval.

Change made

WI-1.5 meets AC-11’s “every status” with four tests together, and the real-backend approved/converted cases became an .forge/owed.md item owned by F11-h and F11-e. WI-3.1 runs the deactivated-owner case over pinned reads in the browser. A spec-reviewer check is listed as a follow-up framework change.

Lesson

  • For every acceptance criterion that names a record state, ask at spec review how a test creates that state on main today. “Through which route or seed?” is a one-line answer when it exists.
  • When no route creates it yet, decide at spec time, not at test-plan time: name the feature whose route will create it, record the deferred real-backend case in the follow-up list with that feature as its owner, and say in the criterion how it is met until then (a test over pinned responses, a fixture insert). A state reachable only through a bug is tested with pinned responses, never by reproducing the bug.

L-167 — JPA PESSIMISTIC_WRITE on PostgreSQL may not be FOR UPDATE; read the SQL before relying on what the lock blocks

  • Date: 2026-10-09
  • Source commits in this repo: .forge/specs/F5-h-offboarding-findings.md F-003; .forge/plans/F5-h/F5-h-decomposition-plan.md ## Notes (deferred from the forge-et-be#221 review)
  • Sync target: upstream
  • Synced: pending

Problem observed

A repository method’s Javadoc said its LockModeType.PESSIMISTIC_WRITE read takes FOR UPDATE. The forge-et-be#221 review read the SQL Hibernate 7.4.5’s PostgreSQLDialect issues and found FOR NO KEY UPDATE. The two block different things: FOR NO KEY UPDATE does not conflict with the FOR KEY SHARE lock PostgreSQL takes when checking a foreign key, so another transaction can still insert a row that references the locked row. F5-h’s races were safe because both sides take the same row lock, but a design that counted on the lock to stop such an insert would have had a gap no test showed.

Change made

The Javadoc correction is deferred to the next backend PR that touches RoleRepository. No code changed.

Lesson

  • Do not assume the SQL a JPA lock mode produces; read it (spring.jpa.show-sql, or the statement in a test log) and write the actual clause in any comment that explains a race.
  • When a lock must stop a concurrent insert of a referencing row, PESSIMISTIC_WRITE on Hibernate’s PostgreSQL dialect is not enough. Use a lock both writers take (the same row lock, or an advisory lock), as L-156 also advises, and prove it with a test that fails when the lock is removed.

L-168 — A browser test that depends on the operating system’s keyboard behaviour must pass on every OS the team runs the gate on

  • Date: 2026-10-10
  • Source commits in this repo: .forge/specs/F12-ai-inquiry-extraction-findings.md F-001; .forge/bugs.md BUG-131, BUG-231, BUG-236, BUG-241, BUG-500
  • Sync target: upstream
  • Synced: pending

Problem observed

F5-h’s WebKit keyboard walk (offboarding-keyboard-webkit.spec.ts) falls back to Alt+Tab because Safari on macOS reaches links only with Option+Tab. It passed on the macOS machine where F5-h’s gate ran and merged. On Windows, where most of the team runs pnpm e2e:gate, Playwright’s WebKit focused no link with Tab or Alt+Tab, so the test failed on every run, main included. The next Windows gate (F12’s) found it, spent several runs proving it was not F12’s, and had to file and mark it.

Change made

Filed as BUG-131 and marked with markKnownFailure('BUG-131', …) only when process.platform === 'win32', so the test still runs, and must pass, on macOS. The fix is F5-h’s owner’s decision.

Lesson

  • When a test relies on a key or focus behaviour that differs by OS or engine (Safari’s Option+Tab, a platform modifier key, native <select> type-ahead), prove it on Windows and on macOS before it merges, or state in the test which OS proves it and mark the other with a known failure in the same PR.
  • The machine’s settings count as well as its OS (BUG-231, BUG-241). F1-e’s WebKit trap tests pressed Tab and passed where they were written; on a Mac with keyboard navigation off (macOS’s default), WebKit’s Tab reaches text fields only, so the same tests failed on every run there. Choose the key in the test from the machine’s behaviour, not its platform: forge-et-fe e2e/support/focusKey.ts webkitFocusKey presses Tab between two buttons it adds and returns Tab or Alt+Tab.
  • The product must handle the key those machines use, too (BUG-231, BUG-236). Radix’s FocusScope loops a plain Tab only, so Option+Tab left both the shadcn Dialog and AlertDialog after their last control. Every focus-trapping shadcn content calls loopOptionTab (forge-et-fe src/ui/shadcn/loop-option-tab.ts) from its onKeyDown; a new one added to src/ui/shadcn does the same.
  • To diagnose a keyboard walk that never reaches its target, log document.activeElement after every press. One run shows the focus cycle and whether the target is ever reachable, which a repeated failure message does not.

L-169 — Sibling elements keyed by separate counters can collide; prefix each host’s key

  • Date: 2026-10-10
  • Source commits in this repo: .forge/specs/F12-ai-inquiry-extraction-findings.md F-002; .forge/plans/F12/F12-WI-2.5-test-verify.md § Design vision pass
  • Sync target: upstream
  • Synced: pending

Problem observed

Two hooks, useLeadForm and useInquiryExtraction, each rendered a dialog keyed by its own dialog.seq counter, as siblings under the Leads screen. When both counters held the same number, React matched the two elements as one keyed child, and a second, closed paste dialog stayed in the DOM after a reopen. Each hook’s component tests rendered it alone, so none could see the collision; the orchestrator’s keyboard walkthrough in a real browser found it.

Change made

The keys carry a host prefix (`inquiry-${seq}`, `form-${seq}`), with a screen-level test that opens both in turn and counts one dialog.

Lesson

  • A key derived from a counter is unique only within its own list. When two hooks or components render siblings under one parent, give each key a prefix that names its host, so the counters cannot meet.
  • Test the screen that hosts more than one dialog, not only each dialog’s hook: open one, close it, open the other, and assert exactly one dialog element is in the DOM.

L-170 — When a plan would copy another feature’s helper, move the helper to a shared package instead

  • Date: 2026-10-10
  • Source commits in this repo: .forge/specs/F12-ai-inquiry-extraction-findings.md F-003; .forge/plans/F12/F12-decomposition-plan.md ## Notes (the wave-2 review decisions); .forge/bugs.md BUG-240 (each AI feature wrote its own provenance-label date formatter, and the three drifted apart on one screen); .forge/bugs.md BUG-253 (F11-c’s research label, the fourth, kept its own formatter after BUG-240); .forge/bugs.md BUG-255 (F1-e copied the lead’s Add tag option limits, and BUG-203 and BUG-206 then changed only the lead’s)
  • Sync target: project-only
  • Synced: pending

Problem observed

Two F12 plans copied a helper from another feature so the new code would not import that feature: WI-2.1 copied the buying standard’s held-certification rule into lead (its Decision 9), and WI-2.2 copied the account form’s vocabulary and certification-option builders into the lead form. Both copies passed plan review and were flagged at code review under coding-standards.md §2 (Reuse), and both fixes moved the code to a package both features already depend on — compliance on the backend, src/ui and src/lib/certifications on the frontend — after the code was written, tested and integrated.

Change made

compliance/service/HeldCertifications (backend) and src/ui vocabularyGroup plus src/lib/certifications/useCertificationOptions.ts (frontend), each used by both features.

Lesson

  • “Do not import another feature” is satisfied by moving the helper down, not by copying it. The copy is the second consumer the rule of two waits for, so the plan that would copy is the plan that should move it: to the package that owns the concept (compliance for certifications), or to platform / src/ui / src/lib when no feature owns it.
  • A plan decision that copies code from another feature names the shared home it considered and why it was rejected, so plan review can catch it before the code is written.
  • The same holds for a format shown in one place by several features (BUG-240): each AI feature formatted its provenance label’s date in its own service, after its own contract, and one lead view showed two forms. A value with a design-system form gets one builder in the package that owns the shared record (AiProvenance.Source.dated), and a new feature uses it rather than restating the pattern.

L-171 — A request contract states a maximum size for every list member

  • Date: 2026-10-10
  • Source commits in this repo: .forge/specs/F12-ai-inquiry-extraction-findings.md F-004; .forge/plans/F12/F12-Wave-2-contract.md Rev 3
  • Sync target: upstream
  • Synced: pending

Problem observed

F12’s frozen Wave 2 contract pinned every member’s type, vocabulary and text length, but none of the three request lists (packaging, certificationIds, aiDraft.fields) had a maximum. The code review found that a caller with lead.manage controlled the size of a database IN query and of the 400 body, which carries one entry per bad element. Fixing it needed a revision to a frozen contract after both sides were built.

Change made

@Size(max = 100) on each list (the buying standard’s limit for the same kind of list), answered 400 OUT_OF_RANGE, with the contract’s ### Validation entries rows added as Rev 3 and integration tests for 100 and 101 elements.

Lesson

  • When a contract defines a request body, every array member gets a maximum size and its refusal code, next to the text lengths. Take the limit from an existing list of the same kind, or from the largest the screen can send with a margin.
  • Review the earlier frozen contracts’ lists the same way when one of their endpoints is next changed; the gap is in the contract template, not in one feature.

L-172 — A version check serialises writes to one row; writes that race for one partial unique index need a parent lock

  • Date: 2026-10-10
  • Source commits in this repo: .forge/specs/F1-d-account-detail-findings.md F-001; .forge/plans/F1-d/F1-d-WI-1.1-plan.md § Wave PR review — forge-et-be#225
  • Sync target: upstream
  • Synced: pending

Problem observed

F1-d’s contact service made a contact primary by demoting the account’s current primary, then setting the new row, under optimistic locking (@Version) and a partial unique index allowing one primary contact per account. Its plan said concurrent writes were “serialised by the version check”. That held for two writes to one contact. Two writes making different contacts primary, on an account with no primary, each read no current primary and each set its own row; the second failed at commit on the unique index, and the API answered 500.

Change made

The write locks the parent account row (SELECT … FOR NO KEY UPDATE) inside its transaction, after the permission gates and before reading the current primary, so writes on one account queue and the second sees the first’s committed primary. A race test holds one write open, starts the second, waits on pg_stat_activity for the lock wait, then commits the first; it answered 500 with the lock removed.

Lesson

  • Optimistic locking protects the row a write reads; it does not protect an invariant across rows. When a unique or partial unique index holds “at most one per parent” (one primary, one default, one active), lock the parent row before the read that decides the write, or translate the unique violation into the API’s conflict answer.
  • Write the race test that forces the interleaving, and confirm it fails without the lock: a test of two writes in sequence passes either way.

L-173 — Once main is merged into a frontend wave branch, its browser gate runs against backend main

  • Date: 2026-10-10
  • Source commits in this repo: .forge/specs/F1-d-account-detail-findings.md F-002
  • Sync target: upstream
  • Synced: pending

Problem observed

F1-d’s frontend wave branch merged main to resolve a conflict, which brought F12’s inquiry screens and seam tests. The browser gate still ran against F1-d’s backend wave branch, which had no F12 endpoints or migration, and eleven F12 seam tests and one F1-d test failed. Against backend main, which by then had both features, they passed.

Change made

The gate was re-run against backend main (b581c924, F1-d’s backend wave PR merged first, as the spec required).

Lesson

  • The backend a frontend gate runs against is the one the frontend will meet on main. Before the backend wave PR merges, that is the backend wave branch; once it has merged, or once the frontend branch has taken main (and with it other features’ frontend code), it is backend main.
  • A seam test failing on endpoints the PR never touched is a version mismatch first; check the backend’s commit before reading the failures.

L-174 — Each local verification run gets its own compose stack and ports; a stopped bootRun shell does not stop the backend

  • Date: 2026-10-10
  • Source commits in this repo: .forge/specs/F1-d-account-detail-findings.md F-003
  • Sync target: upstream
  • Synced: pending

Problem observed

During F1-d’s browser gates on Windows, stopping the shell that ran ./gradlew bootRun left the Spring process listening (it is a child of the Gradle daemon), and ending processes directly was refused. A second backend was started on another port against the same compose stack. The two shared LocalStack’s queues, and the older backend consumed the mailbox stub notifications, so the mailbox seam and inbox tests failed against the backend under test.

Change made

A third compose project on its own host ports (Postgres, LocalStack) with the backend on its own port; the mailbox files then passed 29 of 29.

Lesson

  • One backend per compose stack. A queue-consuming backend shares its queues with every other backend on the same LocalStack; a test that sends a message and waits for its effect can see it taken by the wrong process.
  • Check the port, not the shell, after stopping a bootRun: curl …/actuator/health on the old port. If it still answers, start the next run on a new stack and new ports rather than beside it.

L-175 — On a loaded Windows laptop the full browser gate fails a few different load-flaky tests every run

  • Date: 2026-10-10
  • Source commits in this repo: .forge/specs/F1-d-account-detail-findings.md F-004; .forge/bugs.md BUG-197 (the same on macOS, closed as an overload outcome)
  • Sync target: project-only
  • Synced: pending

Problem observed

F1-d’s frontend wave PR needed a passing pnpm e2e:gate on its head. Five full runs on one Windows 11 laptop (2,464 to 2,741 tests, 1.1 to 1.4 hours, 2 or 3 workers) each failed two to eleven tests, a different set every time and none in F1-d’s own files; every one passed run alone. The gate fails on any failure and has no allowance for a test that passes alone, so no run was ever clean. The PR merged with Browser gate: skipped — <reason> carrying the last run’s evidence, the developer’s decision.

Change made

None to the gate. The evidence (the full run’s counts, the failed tests, their passing re-runs) went into the skip line and the Decomposition Plan’s notes.

Lesson

  • Plan a large frontend wave’s gate time on Windows as more than one full run, start each on a fresh stack (L-165) with nothing else running, and record each failure’s alone-run as it happens, so the evidence for a skip exists if no run comes back clean.
  • The recurring load-flaky tests are the defects to fix (BUG-110, BUG-129 and the like); until they are, the gate’s pass on Windows depends on chance, which the gate’s design does not allow for. A gate that re-runs a failed test once alone and reports it as flaky would match how these runs were actually judged; that is a change to the gate for the team to decide.
  • macOS is not exempt. At the default worker count (half the cores, 4 on an 8-core Mac) a full gate’s own browsers can hold the CPU at 1.00, and a WebKit state timed out once that way (BUG-197). The cause is the run’s own load (BUG-129’s finding), so the remedy is the number of browsers a gate starts, not the test.

Update — 2026-10-30

The number of browsers was not the remedy on Windows: full gates at 8, 6 and 4 browsers still failed a few tests each. Most of the run’s own load was each test’s fresh browser context fetching and compiling the dev server’s unbundled modules, and running the suite against a development build fixed it (L-248; BUG-218 and the five bugs it closed). The gate now starts at most 6 browsers on Windows, which keeps room for other work.

L-176 — Absolutely positioned content inside an unpositioned scroll region escapes it and widens the page

  • Date: 2026-10-11
  • Source commits in this repo: .forge/specs/F26-f-price-review-publish-findings.md F-001; BUG-153 (forge-et-fe#236 — the same escape at the app frame: <main> was not positioned, so the screens’ hidden legends stretched the page’s height and the whole frame scrolled)
  • Sync target: upstream
  • Synced: pending

Problem observed

F26-f’s Weekly prices table sat in a scroll region with overflow-x: auto, yet every Weekly prices page state overflowed the page by the table’s whole width (1,200 px at 320, 334 px at 1440). Two visually hidden labels inside the table were position: absolute, and the region was not positioned, so they were placed against an ancestor outside it; the region’s overflow does not clip content positioned outside it. Component tests in jsdom could not see it, and the first fix brief guessed a flex min-width problem.

Change made

position: relative on the scroll region, with a source check in the feature’s stylesheet test (forge-et-fe f496231).

Lesson

  • A scroll region that can contain absolutely positioned content is position: relative — visually hidden labels, tooltips and badges are the usual sources — and a stylesheet source check pins it.
  • When a page overflows by a table’s whole width although the table has its own scroll region, look for an absolute descendant escaping the region before looking at flex or grid sizing.

L-177 — A per-record lock does not serialise writes that meet in a constraint spanning records

  • Date: 2026-10-11
  • Source commits in this repo: .forge/specs/F26-f-price-review-publish-findings.md F-002
  • Sync target: upstream
  • Synced: pending

Problem observed

F26-f’s publish took its own sale’s row lock. Two publishes of different sales that shared standards each wrote published price rows checked by an exclusion constraint (price_no_overlap), each waited on the other’s uncommitted rows, and Postgres reported a deadlock, which reached the client as a 500. It showed once in four full seam-suite runs and never in ten isolated runs, because only the parallel suite put two publishes on shared standards at the same moment.

Change made

One transaction-scoped advisory lock, taken after the sale lock by every writer of published prices (publish, round withdrawal, single-price withdrawal), with deterministic concurrency tests that fail without it (forge-et-be bad18804, da6b8d79). An ordered row lock would not do: UPDATE … FROM does not guarantee the order rows are locked in.

Lesson

  • When a write’s rows are checked by a constraint that spans records (an exclusion constraint, a cross-record uniqueness rule), list every writer that can meet in it and lock what they share — not only the parent record each request is about.
  • Run the full suite more than once before calling a concurrency path green; a race that needs another test running in parallel does not show in an isolated run.

L-178 — Measure a query fix as the requirement measures it: the endpoint, warmed up

  • Date: 2026-10-11
  • Source commits in this repo: .forge/specs/F26-f-price-review-publish-findings.md F-003
  • Sync target: upstream
  • Synced: pending

Problem observed

F26-f’s round summary read 980 ms against a 150 ms limit. The first fix brought the query to 20 ms measured once with EXPLAIN ANALYZE, but the endpoint, read as the requirement reads it (the 19th of 20 calls after warm-up), still took 177 ms: after five executions Postgres replaced the per-call plan with a generic plan that checked the 1,450 drafts one by one.

Change made

The summary’s rows computed once in a materialised CTE, the later-price check split so an existing index serves it, and plan_cache_mode = force_custom_plan set for that transaction only, on the summary and on publish’s draft read (forge-et-be fd964bdd, 4e0e9214, 76a1d2e5). The endpoint then read 71 ms.

Lesson

  • Prove a performance fix with the same measurement the requirement uses — the endpoint, after warm-up, at the stated percentile — never the query once.
  • A parameterised query whose good plan depends on its values can regress after the driver’s prepare threshold; force a custom plan for that transaction (set_config('plan_cache_mode', 'force_custom_plan', true)), never session-wide on a pooled connection.

L-179 — A spec decision that leans on an AD exception is checked against the AD’s text at spec review

  • Date: 2026-10-11
  • Source commits in this repo: .forge/specs/F26-f-price-review-publish-findings.md F-004
  • Sync target: upstream
  • Synced: pending

Problem observed

F26-f’s spec decided (D-2) to set a published price’s status to withdrawn in place, arguing it followed the line AD #14’s cost exception draws, but AD #14 named only the cost exception. Neither the spec review nor four plan reviews caught it; the backend reviewer did, on the wave PR, after the code was built and verified, and the merge then waited overnight for the lead’s sign-off on a refinement.

Change made

The lead accepted a second AD #14 exception for price withdrawal on 2026-10-11; every live statement of the exceptions was updated with it (forge-et-harness#558).

Lesson

  • A spec decision that relies on an Architecture Decision’s exception, or says it follows “the same line AD #N draws”, is checked against the AD row’s actual text at spec review, and a refinement the decision needs goes to the lead before the spec is approved — not at the code review, when the work is done and waiting.

L-180 — An async write’s follow-up that rewrites the URL first checks the location has not changed

  • Date: 2026-10-11
  • Source commits in this repo: .forge/specs/F26-f-price-review-publish-findings.md F-005
  • Sync target: upstream
  • Synced: pending

Problem observed

After a write, F26-f’s Weekly prices tab wrote the shown sale into the URL with replace. The callback ran after await mutateAsync, using the closure from the render at the press, so a Back pressed before or during the request let the write replace the history entry Back had landed on. Three review rounds were needed to close it.

Change made

Each dialog records the history entry it opened on; a ref, updated in a layout effect, tracks the current entry; a write that settles on a different entry writes nothing (forge-et-fe 9011591, with a test that holds the request open, presses Back, then resolves).

Lesson

  • Any follow-up to an async action that navigates or rewrites the URL compares the location key captured when the action started with the current one (read from a ref, not from the stale closure) and does nothing when they differ. Test it by holding the request open, navigating, then resolving.

L-181 — On Windows Git Bash, MSYS_NO_PATHCONV=1 breaks /c/… paths and the pnpm shim

  • Date: 2026-10-11
  • Source commits in this repo: .forge/specs/F26-f-price-review-publish-findings.md F-006
  • Sync target: project-only
  • Synced: pending

Problem observed

F26-f’s runtime scripts exported MSYS_NO_PATHCONV=1 so git show ref:path works. With it set, native git -C /c/… could not find the directory, and pnpm failed with Cannot find module 'C:\c\Program Files\nodejs\…\pnpm.js'; corepack pnpm run from another directory picked the wrong pnpm version. The baseline run failed twice before a single test ran.

Change made

None to the harness; the session’s scripts wrote paths as C:/… and ran pnpm with path conversion back on.

Lesson

  • In a Git Bash script that sets MSYS_NO_PATHCONV=1, write paths as C:/…, and run pnpm as (cd <dir> && env -u MSYS_NO_PATHCONV pnpm …) — from inside the project directory, so pnpm reads the project’s packageManager version.

L-182 — A TanStack query that passes its AbortSignal to the fetch is sent twice under StrictMode

  • Date: 2026-10-11
  • Source commits in this repo: .forge/specs/F5-g-record-sharing-findings.md F-001; .forge/bugs.md BUG-353 (MessageView.test.tsx’s StrictMode rows put StrictMode inside the query provider, fixed in forge-et-fe#429); .forge/bugs.md BUG-395 (renderWithQueryClient’s strict and seven other test files put StrictMode inside RTL’s wrapper or inside the ui given to it, fixed in forge-et-fe#479)
  • Sync target: upstream
  • Synced: pending

Problem observed

F5-g’s sharing panel read a record’s shares through a query whose queryFn passed TanStack’s signal to the fetch. TanStack cancels a query that consumed its signal when its last observer unsubscribes, so <StrictMode>'s mount → unmount → mount on the dev server cancelled the first read and sent a second one. The browser suite, which runs against the dev server, saw two reads and failed the spec’s “read once” criterion. The page’s other reads did not pass the signal and were sent once.

Change made

Neither sharing query passes the signal (forge-et-fe 23fc4ca). The regression tests render under a root <StrictMode> outside the query provider, because StrictMode inside the provider did not replay the mount on React 19.3.

Lesson

  • Do not pass the query’s signal to the fetch for a read that runs on mount, unless the read must be cancelled when the component goes away. A test that asserts how many times a read is sent renders under a root <StrictMode>, outside the query provider.

Update — 2026-11-09

BUG-395: “outside the query provider” was followed by putting <StrictMode> around the provider inside RTL’s wrapper. React rehearses the first mount (mount, unmount, mount) only for a tree whose root is inside StrictMode, and RTL renders the wrapper component above whatever it returns, so nothing in the first commit ran twice. The shared helper renderWithQueryClient and seven other test files did this, and their StrictMode rows passed while testing less than they said.

  • StrictMode goes at the render root. Pass reactStrictMode to render or renderHook, or { strict: true } to renderWithQueryClient, or call render(<StrictMode>…</StrictMode>) with no wrapper. Never put <StrictMode> inside a wrapper, or inside the ui given to a helper that wraps it.
  • A helper that forwards reactStrictMode sends it only when its caller set it, so RTL’s configure({ reactStrictMode }) still applies; an explicit false overrides it.

L-183 — TanStack v5 returns a key with no data to pending on a refetch, so an error panel’s Retry unmounts itself

  • Date: 2026-10-11
  • Source commits in this repo: .forge/specs/F5-g-record-sharing-findings.md F-002; .forge/bugs.md BUG-152 (the certification lists’ Retry, fixed in forge-et-fe#223 by moving useRetryHold to src/lib/hooks); .forge/bugs.md BUG-208 (the account list’s first-read Retry) and BUG-209 (the shared account and contact pickers’ Retry, now held in usePickerData), both fixed in forge-et-fe#316; .forge/bugs.md BUG-266 (the account and contact lists held a failure for any re-read of the failed key), fixed in forge-et-fe#345; .forge/bugs.md BUG-316 (the Roles list’s first-load Retry); .forge/bugs.md BUG-344 (the Users and email templates lists’ first-load Retry, fixed in forge-et-fe#429); .forge/bugs.md BUG-387 (the account and lead lists’ Owner select and the lead list’s Tag select, fixed in forge-et-fe#471, which made the hold one shared src/lib/query/readFailed.ts); .forge/bugs.md BUG-388 (the lead page’s Tags section, fixed in forge-et-fe#475); .forge/bugs.md BUG-394 (readFailed held a failure on any re-read, against the 2026-10-27 update; fixed in forge-et-fe#477, which replaced it with useHeldRead); .forge/bugs.md BUG-396 (New User’s and Edit User’s Role and Manager failure boxes, fixed in forge-et-fe#486, which added useHeldFieldRead for a field whose successful retry moves focus to the field)
  • Sync target: upstream
  • Synced: pending

Problem observed

F5-g’s sharing panel showed a first-read error with a focused Retry. Pressing Retry refetched a key that had never held data. TanStack v5 puts such a query back to pending and clears error, so the error panel unmounted, Retry went with it and focus fell to <body>. The review of forge-et-fe#221 found it (I3).

Change made

useRetryHold (forge-et-fe 2cf6a18, cdcd26e; now src/lib/hooks/useRetryHold.ts, moved for BUG-152) keeps the failure on screen, with Retry busy, until the read’s next result, matched on errorUpdateCount and errorUpdatedAt. It follows useAccountDetail’s kept-first-error pattern.

Lesson

  • An error state with a Retry for a query that has never held data keeps itself mounted until the retry settles. Do not render it from isError alone. Hold the failure until errorUpdateCount changes or data arrives, and test that focus stays on Retry after a retry that fails again.
  • Hold it in the shared data hook, not in each component that renders it (BUG-209). A hold kept in one consumer leaves every other consumer of the same hook without it.
  • The held Retry still leaves when the retry answers. Give that moment a focus target too — the field or heading the user goes on with — moved only when focus was on Retry or nowhere (BUG-209’s review, in RecordSearchPicker).

Update — 2026-10-27

BUG-266: the account and contact lists kept each key’s last failure and showed it as retrying on any re-read of that key, so a filter change back to a key that had failed showed the old failure, with a busy Retry, while it read. A refetch of a key with no data looks the same to the hook whether Retry or a filter change started it.

  • Start the hold from the Retry press, not from the key’s failure: refetch calls useRetryHold’s hold() before it refetches, and retrying comes only from the hold. Any other re-read of a key that failed shows the kept rows refreshing, or the skeleton.
  • Test the round trip with the app’s gcTime: a failed key, another filter, then back, with the read held. The test client’s gcTime: 0 drops the failed key and hides the defect.

Update — 2026-11-09

BUG-394: BUG-387’s shared readFailed worked out the hold from the query’s own state (isFetching, no data, errorUpdatedAt > 0), so it held a failure through any re-read, a screen’s mount re-read included. That was the 2026-10-27 rule broken again in a new helper.

  • A field that shows a read error with Retry uses useHeldRead (forge-et-fe src/lib/query/useHeldRead.ts, over useRetryHold): its retry() holds, then re-reads. A screen-level hook keeps useRetryHold.
  • Never work out a hold from isFetching or errorUpdatedAt. Only a press starts one.

L-184 — Remove a TanStack query only once no mounted component observes it

  • Date: 2026-10-11
  • Source commits in this repo: .forge/bugs.md BUG-144 (LeadsScreen leadGone and useLeadForm leave, fixed in forge-et-fe#223)
  • Sync target: upstream
  • Synced: pending

Problem observed

When the open lead answered 404, the lead screen cleared the selection, removed the lead’s detail query and showed a notice, all in one pass. The notice’s state update rendered the screen before the cleared selection reached the router, so the lead view was still mounted. Its useQuery observer saw the query gone, created it again and read the lead, and its notes section read again too, before the view unmounted. The edit form’s “lead left your reach” path had the same order. AccountFormRoute’s edit had already avoided it by dropping its account in an unmount clean-up.

Change made

forge-et-fe src/features/leads/useDropLeadDetail.ts removes the open lead’s query in the effect that runs once the selection has moved away, and any other lead’s at once; both call sites use it. The review of forge-et-fe#223 found that the 404 handlers compared the gone lead with a stale selection (they run after an await), so archiving one lead and opening another before the 404 landed cleared the other. Three delta reviews later, useLeadsUrlState’s select and clearSelection act on the screen as it is when they run: the filters on screen, nothing once the Leads screen has unmounted, and clearSelection({ ifSelected }) only while that lead is open. Tests count the reads of the dropped lead after the 404 and expect none beyond the read-back.

Lesson

  • removeQueries on a key a mounted component still observes does not drop it: the observer re-creates the query and fetches it. Remove a gone record’s query after the component that shows it has unmounted — in an effect that runs once the selection has changed, or in that component’s unmount clean-up. removeQueries already cancels a read in flight (query.destroy()), so no cancelQueries is needed.
  • A handler that runs after an await acts on the screen as it is now — refs kept by layout effects — not on the render that created it: the selection (or a late 404 for one record clears the record the user has since opened), the filters (or it puts back a filter the user changed), and whether the screen is still mounted (React Router’s navigate still runs after unmount, so a late answer pulls the user back). Put those checks in the hook that navigates, so every caller gets them.
  • Test it by counting requests, not by what is shown: the re-read’s answer is discarded once the view unmounts, so nothing on screen is wrong.

L-185 — A check over every user or record runs a fixed number of queries, never a per-item service call in a loop

  • Date: 2026-10-12
  • Source commits in this repo: .forge/bugs.md BUG-142 (AdminAuthorityGuard resolved every active user’s permissions one by one)
  • Sync target: upstream
  • Synced: pending

Problem observed

Deleting a role took 7–8 seconds on a local database holding 1,480 active users, and every Roles delete browser spec failed there. The delete’s last-administrator check loaded every active user and, for each, called EffectivePermissionResolver.resolve(userId), which runs its own queries. On a new database, and with Empire’s 10–20 users, it answered at once, so nothing showed the cost until the data grew. It is an N+1, but not the kind the reviewer checklist named: no entity association is touched, only a service method that looks up one item, called once per item.

Change made

forge-et-be: the guard counts active users per role in one grouped query and resolves those roles together with EffectivePermissionResolver.resolveForRoles, which reads all their grants in one query, so the check runs a fixed number of queries. RoleDeleteStatementCountIT counts the statements a role delete runs before and after 300 active users are added, each on a role of their own, and expects the same number (12 before the fix and 312 after). backend-reviewer’s N+1 item now names this shape.

Lesson

  • A check, guard or report that walks a whole population (every active user, every record of a type) reads it with a fixed number of queries. Group or batch the read: a grouped count, an IN read for the distinct keys, or a query that answers the question directly. A loop that calls a single-item service method (resolve(id), findById, a permission check) costs a query or more per item.
  • Batch through the component that owns the rule, not around it. When the per-item method is the one definition of something (here, “effective permissions”), add a batched method beside it that shares the per-item logic, rather than a second query that answers the same question another way.
  • Group by the attribute that decides the answer. Every user on a role holds what the role confers, so the guard asks per role, not per user. Check how many distinct groups a long-lived database holds before choosing a per-group query: test fixtures that create a role per user made 246 roles here.
  • Test it by counting statements at two sizes (CapturingStatementInspector), not by timing it: a wall-clock bound fails on a loaded machine (L-125).

L-186 — A browser check that something fits in the window allows half a pixel, and reports the overshoot

  • Date: 2026-10-12
  • Source commits in this repo: .forge/bugs.md BUG-171 (fixed in altrium-io/forge-et-fe#230)
  • Sync target: upstream
  • Synced: pending

Problem observed

BUG-123’s fix proved the open tag list fits by asserting toBeInViewport({ ratio: 1 }) on its last option. In WebKit, under a loaded gate run, the option sat a fraction of a pixel past the window’s edge (ratio 0.9917) and the size-matrix state failed now and then, while one worker passed every time. The list fitted; the check measured layout rounding.

Change made

The check polls the option’s bounding box and returns how many pixels it reaches past the window, passing at half a pixel or less — the tolerance the popover check beside it already used. A list whose rows do not fit leaves a whole row outside, so the check still catches BUG-123’s case, and a failure prints the overshoot.

Lesson

  • Assert geometry with a stated sub-pixel tolerance, never ratio: 1 or exact edges. Browsers place boxes on fractional pixels, and WebKit rounds differently under load. Half a pixel is enough; the defect it guards against is a whole row or control outside.
  • Make the assertion return the measured overshoot (expect.poll(...).toBeLessThanOrEqual(0.5)), so a failure says by how much, and read related boxes after the poll, from the settled layout.

L-187 — A check that finds secrets by component name misses a secret whose name says what it is for

  • Date: 2026-10-12
  • Source commits in this repo: .forge/bugs.md BUG-176 (fixed in altrium-io/forge-et-be#244); BUG-177 (found by the same fix’s probe; fixed in altrium-io/forge-et-be#245)
  • Sync target: upstream
  • Synced: pending

Problem observed

scripts/check-banned-markers.py fails a record whose component name contains a word such as token or secret and has no toString() of its own. Graph’s paging links carry a $skiptoken or $deltatoken, but four records named them for their use: cursor, nextCursor, nextLink, deltaLink. The check passed all four, and caught the fifth only because its field happened to be called token (DeltaPosition, BUG-102). A presigned S3 URL in DownloadUrlResponse.url passed the same way (BUG-177).

Change made

SENSITIVE gained cursor and link, and the four records print <redacted>. Before choosing, the script was run over src/main with each candidate word (cursor, link, url, key), which showed what each would catch: cursor and link caught only the paging records, url caught the presigned URL and two values that are not secret, and key caught twenty-two permission and idempotency keys.

Lesson

  • A provider’s opaque values are secret because of what they carry, not what they are called. Paging cursors and links, presigned URLs and resume tokens hold credentials or grants in their query string. A record that holds one overrides toString() whatever its field is named. backend-reviewer checks this.
  • Widen a name-based check by probing the whole tree first. Run it with each candidate word, fix the records that hold a secret, and put each record that is safe to print in the exemption list with its reason. A word that flags many safe records (key) belongs in no list.

L-188 — A component built on the headless library checks its disabled state on every part the library renders

  • Date: 2026-10-09
  • Source commits in this repo: .forge/bugs.md BUG-118 (forge-et-fe#200, 8f613b5) and BUG-121 (forge-et-fe#189, 0292e56)
  • Sync target: project-only
  • Synced: pending

Problem observed

Two src/ui components built on react-aria-components handled disabled on one part and missed another part the library renders. Combobox made its input aria-disabled and readOnly, but the library’s isReadOnly disabled the Show suggestions button with the bare disabled attribute (BUG-118). Tooltip passed disabled to TooltipTrigger but not to the Focusable around the trigger, which still added a tabIndex and press handlers and warned on every nav link (BUG-121). In both, the component’s tests asserted the disabled state only on the part the component itself set it on.

Change made

Combobox re-provides the library’s ButtonContext to the trigger without isDisabled and its press handlers, and with aria-disabled; Tooltip passes isDisabled to Focusable. Each component’s test now asserts the disabled state on the other part as well. frontend-reviewer dimension 20 points here.

Lesson

  • When a component wraps the headless library, test its disabled state on every element the library renders for it — the trigger, the popover and any wrapper — not only the element the component passes disabled to. The library passes a component-level state such as isReadOnly or isDisabled on to its other parts in its own way, which may be the bare attribute that design-system § Permission rendering forbids.
  • A prop on a library part cannot remove a handler the library supplies through context: the library merges its context props with the part’s own and chains their handlers. To change them, re-provide the context.

L-189 — The browser gate does not run the unit suite, and a gate input can break it

  • Date: 2026-10-13
  • Source commits in this repo: .forge/specs/F26-g-price-expiry-override-findings.md F-001; .forge/bugs.md BUG-188 (forge-et-fe d25db43, 0b130da on forge-et-fe#245)
  • Sync target: upstream
  • Synced: pending

Problem observed

F26-g’s frontend wave PR added an entry to scripts/browser-gate/expected-skips.json. The 34-minute pnpm e2e:gate --push passed, and the pnpm test:record that follows it then failed three unit tests in src/test/scripts/browserGateRun.test.ts, which pin the real expected-skip list. The fix needed another full gate run on the new head, and a flaky test in that run forced a third.

Change made

The test now counts the real list (forge-et-fe 0b130da). The framework change — run the unit suite before the gate in /forge-deliver Stage 12 — is a follow-up PR (F26-g Reflect).

Lesson

  • The gate and the test record check different suites. pnpm e2e:gate runs Playwright; the record runs Vitest, whose tests also read gate inputs (the gate scripts’ own tests read its config files). A change can pass one and fail the other.
  • Run the cheap suite first. Before pnpm e2e:gate --push on a head that will be recorded, run pnpm test (about three minutes), so a failure costs a fix and not a fix plus a 34-minute gate re-run.

L-190 — A file shared by copy with another repo makes its fix a two-repo change

  • Date: 2026-10-13
  • Source commits in this repo: .forge/specs/F26-g-price-expiry-override-findings.md F-002; .forge/bugs.md BUG-188 (forge-et-fe#245 and forge-et-pwa#74)
  • Sync target: project-only
  • Synced: pending

Problem observed

BUG-188’s fix in forge-et-fe changed src/test/scripts/browserGateRun.test.ts, which forge-et-pwa carries as a byte copy (scripts/shared-with-fe.json). Once the fe change merges, every PWA gate run’s live comparison with forge-et-fe main fails until the PWA re-copies the file and records its hash. The overnight run found this only when the test record failed, and the scope question went to the person. The PWA branch then also had to take in main for another shared file’s re-copy (forge-et-pwa#71) before its record passed.

Change made

forge-et-pwa#74 re-copies the test and updates src/ui/SHARED-WITH-FE.sha256. It merges right after forge-et-fe#245. A check in frontend-implementer and frontend-reviewer is a follow-up PR (F26-g Reflect).

Lesson

  • Check the shared list before editing. Before changing a file under scripts/browser-gate/, src/test/scripts/browserGate*, e2e/support/ or the shared design tokens in forge-et-fe, look it up in forge-et-pwa’s scripts/shared-with-fe.json.
  • A listed file comes with a companion PR. A listed file needs a PWA re-copy PR in the same delivery, merged after the fe PR. Widening the change to another repo is the person’s decision, so ask before starting it.
  • Cut the companion branch late. Cut it from PWA main right before re-copying, and take main in again if another shared file moved meanwhile.

L-191 — Never tell the user nothing changed when a write’s outcome is unknown

  • Date: 2026-10-13
  • Source commits in this repo: .forge/specs/F26-g-price-expiry-override-findings.md F-005; .forge/bugs.md BUG-190; forge-et-fe 791d286 on forge-et-fe#245; .forge/bugs.md BUG-207 (F1-d’s contact Modals and row actions, fixed in forge-et-fe#316) and BUG-238 (F1-b’s account list archive and restore)
  • Sync target: upstream
  • Synced: pending

Problem observed

F26-g’s EditSaleDatesDialog checked isWriteOutcomeUnknown and said it could not confirm the save. Two other write dialogs, built in the same wave, said “Nothing was … Try again.” Those were CorrectPriceDialog and NotInRoundDialog’s carry forward. They said it on a network failure, on a 5xx with no problem body, and on a 2xx body the client could not parse, where the server certainly committed. F26-f’s DraftPriceDialog does the same (BUG-190). The wave PR’s review caught it; the per-WI reviews had not.

Change made

Both F26-g dialogs now show “We couldn’t confirm …” with a Reload that re-reads what the write changes (forge-et-fe 791d286). A rule in coding-standards.md and frontend-reviewer is a follow-up PR (F26-g Reflect).

Lesson

  • A write dialog has three outcomes, not two. Refused (nothing changed, say why), succeeded, and unknown — a network failure, a 5xx with no problem body, or a response the client cannot parse. For unknown, say the change could not be confirmed and offer a re-read; never “nothing was changed”.
  • A retry after an unknown outcome must be safe. A version check refuses a write that already committed, so the dialog can leave the action available. A create has no version, so a second Save would add the record twice: an unknown create closes its form and says so over the re-read list (the lead’s decision on BUG-207, 2026-10-20).
  • The re-read can answer the question. After an unknown edit, a re-read still at the version the write was sent with proves nothing committed: keep what the user typed and say it was not saved (BUG-207).
  • A rule that lives in one component is rediscovered by the next one. Write it where every new dialog’s author and reviewer reads it.

L-192 — A check that scans a file must not be pasted into that file

  • Date: 2026-10-14
  • Source commits in this repo: .forge/specs/F20-c-compose-and-send-findings.md F-001; .forge/plans/F20-c/F20-c-WI-2.1-record.md R-9
  • Sync target: upstream
  • Synced: pending

Problem observed

F20-c’s WI-2.1 run sheet ends with a secret check: a grep over the record for key markers, SESSION=, XSRF-TOKEN= and token prefixes. Its success criterion R-9 then asked for that command to be pasted into the same record. The pasted command holds the strings it searches for, so the check fails on its own text. F20-h’s run sheet copied the same wording.

Change made

F20-c’s record names the two commands by run-sheet step, rather than pasting them, and records their EXIT=1 and empty output files. F20-h’s run sheet is corrected through owed.md.

Lesson

  • Evidence for a check that scans a file names the check; it does not copy the check into that file. Cite the step that holds the command, and record its exit status and output file.
  • A run sheet copied from an earlier one copies its defects. When a run sheet is reused, re-read every instruction that writes into the record against the checks that read the record.

Update — 2026-10-16

The owed.md correction of F20-h’s run sheet was not made before the sheet was run. So F20-h’s WI-2.1 record repeated the defect: its R-12 first pasted the commands, and the check’s second attempt matched the pasted pattern. The record now names the pattern <P> and points at the sheet’s step 16.5 (.forge/specs/F20-h-email-attachments-findings.md F-002). A correction owed against an approved run sheet is made before the run starts, or the person running it applies it as a stated deviation at the step it changes.

L-193 — Sign in as every test account before a manual run starts

  • Date: 2026-10-14
  • Source commits in this repo: .forge/specs/F20-c-compose-and-send-findings.md F-002; .forge/owed.md (the crm03 mailbox); .forge/specs/F20-g-email-tracking-scheduled-send-findings.md F-003 (the external Microsoft mailbox)
  • Sync target: upstream
  • Synced: pending

Problem observed

F20-c’s WI-2.1 sent its source email to crm03@empire.lk, which environments-and-identity.md §5 lists as provisioned. The mailbox did not exist: the email bounced, the first back-fill imported nothing, and the run went back to step 2 with a new tag and a changed recipient mapping. That took about an hour of the person’s time, partway through a run that could not be paused cheaply.

Change made

The run used CRM05 in CRM03’s place and recorded the mapping. Creating the mailbox is in owed.md.

Lesson

  • A list of accounts in a document is a dated observation (.claude/rules/source-trust.md), not a check.
  • A manual run sheet’s Part 0 signs in once as every external account the run uses — each mailbox, each identity — and records that each works, before the first step that depends on them. One failed sign-in found then costs a minute; found mid-run, it costs a restart.

L-194 — Test a missing-file failure the way the server really answers it, in every engine

  • Date: 2026-10-15
  • Source commits in this repo: .forge/bugs.md BUG-139 (fixed in forge-et-fe#280), BUG-258 (fixed in forge-et-pwa#95 — the capture app’s worker stored the distribution’s fallback page under a pruned chunk’s key, and its route-error browser test aborted the chunk instead of answering it as the distribution does)
  • Sync target: upstream
  • Synced: pending

Problem observed

BUG-139’s fix offers a reload when a route’s code chunk fails to load. It recognises the failure by the error message. The first browser check blocked the chunk’s request (route.abort()), and both engines gave a “failed import” message the fix matched. But the deployed site does not refuse a pruned chunk. It answers with index.html, status 200, as text/html. Answered that way, Chromium still says “Failed to fetch dynamically imported module”, while WebKit says “‘text/html’ is not a valid JavaScript MIME type for module script”. The fix did not match that, and the page kept offering the route that fails. The unit tests passed throughout, because they used messages written from memory.

Change made

The browser check was repeated with route.fulfill({ status: 200, contentType: 'text/html', … }) in Chromium and WebKit, the WebKit message was captured from the engine, and the fix and its tests gained it.

Lesson

  • Simulate a failure the way production produces it. For a missing file, find out what the server returns (here: the distribution’s fallback page) and answer the request with exactly that. Do not abort it; an abort is a different failure.
  • When code depends on an error’s wording, capture the wording from each engine the gate runs (a throwaway page.evaluate(() => import(url)) prints it), and copy it into the tests. Never write it from memory.

L-195 — Size a list that must not scroll by the window’s height, not its width

  • Date: 2026-10-16
  • Source commits in this repo: .forge/bugs.md BUG-123 (fixed in forge-et-fe#224), BUG-203 (fixed in forge-et-fe#262), BUG-206 (fixed in forge-et-fe#335 — a second height step below 600px, sized from measured row heights)
  • Sync target: upstream
  • Synced: pending

Problem observed

The lead page’s Add tag list shows a bounded number of options and never scrolls, because a list that scrolls holds nothing focusable and fails axe (BUG-123). The count was keyed on the window’s width: ten options from bp/tablet up, seven below it. What runs out is height: the list opens on the side of the field with more room, and that room depends on the window’s height and on where the field sits. BUG-123’s fix found ten rows overflowing at 320 × 640 and fixed that size only; its Resolved: line already noted that a shorter desktop window was unchecked. Four days later the app frame’s top bar was removed, which moved the field 64px up, and at 1280 × 720 the ten rows ran 9.8px off the window (BUG-203). Nothing in the list had changed. The size matrix had passed at every size each time, because it checks fixed sizes with the field wherever the layout happens to put it.

Change made

BUG-203’s fix lists ten only in a window at least bp/tablet wide and 860px tall, the height at which ten rows and the line under them fit on either side of the field with the field mid-window, and seven otherwise. A browser check at 1280 × 860 scrolls the field to the window’s middle before opening the list. frontend-reviewer gains dimension 24.

Lesson

  • Bound a list that must not scroll by the dimension it overflows in. For a popover that opens above or below its trigger, that is the window’s height. Key the count on a min-height condition (or measure the room when the list opens), never on a width breakpoint alone.
  • Work out the limit for the worst position of the trigger, not the position it has today. The worst case is the trigger at the window’s middle: the list needs its own height on one side, plus the trigger and the popover library’s edge padding. A layout change anywhere above the trigger moves it, so a fit that depends on today’s position breaks without the list changing.
  • Test the limit with the trigger placed at the worst position. Set the window to the limit’s height, scroll the trigger to the middle, assert that it is there, then check the fit. A fixed-size matrix with the trigger where the layout puts it proves only today’s layout.

L-196 — Closing a terminal does not always stop the server it started; check the port and stop it by process id

  • Date: 2026-10-16
  • Source commits in this repo: .forge/specs/F20-h-email-attachments-findings.md F-001; .forge/plans/F20-h/F20-h-WI-2.1-record.md R-11
  • Sync target: project-only
  • Synced: pending

Problem observed

F20-h’s WI-2.1 ran the laptop-mode backend with ./gradlew bootRun, from a Git Bash script inside a PowerShell terminal tab on Windows. At cleanup the tab was closed. The shell ended, but the Java process that Gradle had started kept running and kept port 8080. In laptop mode that is the only port the backend may use, because Entra’s laptop reply URLs name it, so the next laptop-mode run would have found the port taken.

Change made

The process holding 8080 was identified as the run’s own: its id was the 22380 that every line of the run’s backend log carries. It was stopped by that id, and ports 8080 and 5174 were checked free before the database reset.

Lesson

  • After stopping a server by closing its terminal, check that its port is free (netstat -ano on Windows, lsof -i :<port> on macOS). A child process can outlive the shell that started it.
  • Stop a leftover only when it is provably the run’s own — its process id appears in the run’s own log — and stop it by that id. Never stop a process on a shared port because it is in the way: another session may own it.

L-197 — A manual run sheet states its tools and its evidence form before step 1, for whoever carries it out

  • Date: 2026-10-16
  • Source commits in this repo: .forge/specs/F20-h-email-attachments-findings.md F-003, F-004; .forge/plans/F20-h/F20-h-WI-2.1-record.md (header deviations, R-13); .forge/specs/F20-g-email-tracking-scheduled-send-findings.md F-005
  • Sync target: upstream
  • Synced: pending

Problem observed

F20-h’s WI-2.1 run sheet was written for a person with Word, Excel and PowerPoint, two private browser windows and screenshots saved into a folder. The owner then had the run carried out as a shared, agent-driven run (the owner signed in and picked files; the agent drove the in-app browser and the checks). Two things went wrong:

  • the laptop had no Office, which came to light at step 2, so the real-Office check (R-13) could not run and every “opens in its app” check was replaced;
  • the agent’s browser could not save screenshots, drive the operating system’s file and save dialogs, or download into the run folder, and one browser served both roles.

The record needed five deviations, and each was accepted by the owner at M2.

Change made

The record lists every deviation in its header, with the owner’s acceptance. Notes written at the moment replace the screenshots; parsing the received file replaces opening it in Office; the owner closed the wave with R-13 NOT RUN.

Lesson

  • Step 1 of a manual run sheet checks every tool a later step needs — an installed app, a browser, a command-line tool — and stops the run before it starts if one is missing. L-193 says the same for accounts; it holds for software too.
  • A run sheet says what form its evidence takes, and who does which part, for each way it may be run. If an agent may drive it, the sheet states up front what the agent cannot do — save screenshots, drive operating-system dialogs — and what replaces it: a dated note per screenshot, the person doing each dialog. The deviations then become the sheet’s own instructions, not exceptions.
  • For an agent-driven run, read a toast from the page’s live region, not from a screenshot. Repeat a response’s request from the page and keep only the fields the record needs, so that ids never enter the transcript.

L-198 — Every text box inside a form handles Enter on purpose, because Enter submits the form

  • Date: 2026-10-16
  • Source commits in this repo: .forge/specs/F20-d-email-templates-findings.md F-001; forge-et-fe a9cd6407 (forge-et-fe#286); BUG-315 (F3-a’s activity dialog record search cancelled Enter only when it picked an option, the shape forge-et-fe#374 fixed in AttachAccountPicker; forge-et-fe#390); checked by frontend-reviewer dimension 9 (Enter in a form’s text inputs)
  • Sync target: upstream
  • Synced: pending

Problem observed

F20-d’s Insert template list put a search box inside the compose dialog’s <form>. Send sat outside that form and was linked to it with form="…". The list handled Escape and the arrow keys but not Enter, so Enter in the search box ran the browser’s implicit submission and sent the email. The template editor’s merge-field search saved the template the same way. Every keyboard test pressed ArrowDown before Enter, and jsdom does not submit through a form= button, so no unit test caught it. An adversarial review found it.

Change made

The search box cancels Enter’s default action. Its tests assert the keydown was cancelled (fireEvent returns false) and that no send or save request was made.

Lesson

  • A text input added inside a <form> decides what Enter does, in every widget that puts one there: a search box, a filter, an inline row. Either Enter is the form’s submit, on purpose, or the input cancels it. F20-c’s link row already did this (“Enter applies the link, never submits the email”).
  • A submit button outside the form still counts. A button linked with form="…" makes Enter in any of the form’s text inputs submit the form.
  • Test Enter with nothing chosen, not only after an arrow key, and assert the default was cancelled. jsdom will not show the submission itself.

L-199 — Check a rule against what is stored, not only against what was sent, when a cleaner runs between them

  • Date: 2026-10-16
  • Source commits in this repo: .forge/specs/F20-d-email-templates-findings.md F-002; forge-et-be ed523cfa (forge-et-be#268); checked by backend-reviewer (STACK-SPECIFIC CHECKS, A validation rule runs on the form that is stored)
  • Sync target: upstream
  • Synced: pending

Problem observed

F20-d refuses a merge token inside a link address (FR-T3). The rule read each href of the body as sent. jsoup’s HTML cleaner then strips ASCII control characters from an absolute href. So a token split by &#10; or a tab passed the check, was stored joined up inside the link, and the fill-in put a merged value into the URL. An adversarial review confirmed it in jshell against the jsoup version in the lockfile.

Change made

The rule now also runs on the cleaned body. The body is cleaned once, and every rule reads that string.

Lesson

  • When input is sanitised, normalised or decoded before it is stored, run each rule on the form that is stored (or both). A rule on the raw input proves nothing about bytes the cleaner produces.
  • Look for the transformation’s side effects: stripped characters, entity decoding, joined text nodes. Write one test case per effect that could turn refused input into accepted input.

L-200 — A backend change that turns a refusal into an acceptance lands with the frontend tests that assert the refusal

  • Date: 2026-10-16
  • Source commits in this repo: .forge/specs/F20-d-email-templates-findings.md F-003; BUG-204 (forge-et-harness#731); the pre-merge grep in /forge-review-pr step 2, pointed at from .claude/rules/git-conventions.md § Branching
  • Sync target: project-only
  • Synced: pending

Problem observed

F1-e’s backend wave (forge-et-be#265) made account a valid tag type and added an active filter to the tag list. Its frontend half, forge-et-fe#284, still a draft, updates two older seam tests that assert those requests are refused. Once the backend was on main, every frontend pnpm e2e:gate failed those two tests, F20-d’s included. F20-d had to file BUG-204, merge it to harness main, and mark both tests known failure before its own gate could pass.

Change made

BUG-204 and the two known-failure marks. forge-et-fe#284 removes the marks when it changes the tests.

Lesson

  • Before a backend wave PR merges, list the frontend tests on main that assert anything it changes, above all a 400, 403 or 404 that becomes a success. Grep the frontend’s e2e/seam for the route and the refused value.
  • If any exist, merge the two wave PRs together (the frontend one first, or within minutes), or have the backend PR’s owner mark those tests known failure against a bug in the same window. Leaving main red for every other frontend gate is not an option.
  • This is the reverse of L-173’s case (a frontend gate run against a backend without the change): here the backend moved on and the frontend’s tests did not.

L-201 — For list state a widget compares against, React state is the source and the URL follows it

  • Date: 2026-10-16
  • Source commits in this repo: .forge/specs/F20-d-email-templates-findings.md F-004; forge-et-fe e1e68909, f155f48e (forge-et-fe#286); .forge/plans/F20-d/F20-d-overnight-log.md O-7, O-10; .forge/bugs.md BUG-221 (the search debounce putting back filters Clear filters removed, on the contacts and Users screens; the account list’s first fix in forge-et-fe#262) and BUG-228 (the Leads inbox’s AI tag select and Existing customer? switch), both fixed by the shared hook src/lib/hooks/useListSearchParams.ts in forge-et-fe#330; checked by frontend-reviewer dimension 4 (List state read back from the URL); BUG-223 (the email templates list skipped writing Clear search because it compared with the rendered URL, forge-et-fe#367) and BUG-290 (the shared hook itself takes a discarded render’s newer location key as seen, so an older location then reads as Back; fixed in forge-et-fe#372 by adopting only in a layout effect, with ListSearchParamsProvider so a page’s parts share one copy); BUG-211 (the Standards book’s functional setSearchParams dropped the chosen client when Show archived was pressed before it rendered, forge-et-fe#368); BUG-291 (Activities, Weekly prices, Auction sales and the Weekly prices status filters, forge-et-fe#372); BUG-314 (the shared hook matched a landed write by its query string, so the same query written twice left stale pending writes and a later link to one was ignored; fixed by an id each write carries in its route state); BUG-261 (the Leads keyboard walk’s switch write started from a query string older than the search and the second AI tag; fixed by forge-et-fe#372 and #411, and the slow render that gave it room by forge-et-fe#437, lesson L-273); BUG-430 and BUG-431 in the capture app (forge-et-pwa#136): a campaign change’s clear of the plan list’s filters and its drop of view were two writes from the same render’s parameters, so the second put the filters back (fixed by leaveCampaign, one write), and two hall presses in one tick sent only the second (fixed by src/features/plan/latestSearch.ts, where each write starts from the previous write’s result)
  • Sync target: upstream
  • Synced: pending

Problem observed

F20-d’s templates list kept its tab, search and page in the URL and read them back with useSearchParams. React Router 7 updates the params a render late. Radix Tabs’ automatic activation skips onValueChange when it sees the tab as already selected. So when a user typed a search right after an arrow-key tab change, the keystroke wrote back the old tab. A first fix, a ref holding the latest list state, did not cure it. jsdom never reproduced it; only the real-browser keyboard walk did, and only now and then.

Change made

The tab, search and page are React state. The URL follows them, and is read back only on a Back or Forward navigation. The real-browser walk then passed 10 of 10 runs, twice.

Lesson

  • When a control decides what to do by comparing against the current value (Radix Tabs, a select, a toggle group), that value must be the one the component holds now, not a URL that lags a render behind.
  • Make the state React state, write the URL from it, and read the URL only when history moves. Writing to the URL and reading it back as the source is an L-065 lost update in a new form. The same lag hurts a write that fires later — a search’s debounce timer — because React Router’s functional setSearchParams starts from the URL of the render that made it (BUG-221). For a list screen’s query string, use src/lib/hooks/useListSearchParams.ts in place of useSearchParams: it is this rule as a drop-in hook.
  • Reproduce the lag deterministically before fixing it. A data router keeps the rendered URL until a navigation’s loader settles, so a held route loader (src/test/heldLoader.ts) keeps a write pending in jsdom every run, with the real Radix controls (BUG-221, BUG-228). Without it, jsdom never shows the race, and a real browser shows it only now and then; a single passing run proves nothing.

Update — 2026-11-03

  • Match a pending write when it lands by an id it carries, never by the value it wrote. Two writes of the same query string cannot be told apart by the string, so useListSearchParams matched the first of two and kept the writes after it pending; a later link to one of them then read as the screen’s own write and was ignored (BUG-314). Each write now carries an id in its route state (NavigateOptions.state, kept beside any state the caller passes). A screen that acts on any route state on arrival reads it through the hook’s callerRouteState, or its own filter changes look like arrivals.

L-202 — A review’s fix dispatch names every finding, so one left out shows before the delta review

  • Date: 2026-10-17
  • Source commits in this repo: .forge/specs/F26-d-send-weekly-prices-findings.md F-001; forge-et-fe a3e0c006 (forge-et-fe#292); .forge/plans/F26-d/F26-d-overnight-log.md decision 25
  • Sync target: upstream
  • Synced: pending

Problem observed

The full review of F26-d’s frontend wave PR found seven Importants. The orchestrator’s fix dispatch to the implementer listed six of them and the nits. Important 5 was in neither the fix list nor the “leave as is” list. Two delta reviews passed: a delta reviews the fix commits, and a fix that was never made leaves no commit to review. The gap showed only when the review record’s summary was written finding by finding. forge-review-record.sh refuses an approve with an open Blocker or Important, but only one the summary lists.

Change made

Important 5 was fixed by four test rows (a3e0c006) and reviewed as a fourth delta before the record was written.

Lesson

  • Number every finding in the fix dispatch, and give each one an outcome there: fix, or leave as is with its reason. Then compare the count against the review’s own counts before the dispatch goes out. Do the same for an adversarial pass, whose findings arrive in a separate report.
  • Write the record’s summary from the review’s findings list, not from the fix agent’s report. The fix report lists what was done; only the review lists what was asked.
  • A delta review cannot find an omission. It checks the commits it is given, so the completeness check belongs to whoever builds the dispatch.

L-203 — Run gitleaks locally over the branch’s history before marking an app-repo PR ready

  • Date: 2026-10-17
  • Source commits in this repo: .forge/specs/F26-d-send-weekly-prices-findings.md F-002; forge-et-be df94cbd4 (forge-et-be#271), 1288ee1d (the F20-c instance); L-081
  • Sync target: upstream
  • Synced: pending

Problem observed

The local Fast-lane run before marking F26-d’s backend wave PR ready skipped gitleaks, because it was not installed on the machine, and noted it as “runs in CI”. After gh pr ready, CI’s gitleaks 8.30.1 run over the branch’s full history flagged two made-up UUIDs in a test as generic-api-key. Each sat right after idempotency_key = '. F20-c’s EmailSendSchemaIT had hit the same rule with the same kind of literal. The fix needed a new commit, so it needed a new build record and a new delta review on a PR already marked ready.

Change made

The same gitleaks version, run from the ghcr.io/gitleaks/gitleaks:v8.30.1 container against a fresh clone of the branch, reproduced both hits (L-081). Two fingerprints scoped to commit, file, rule and line cleared them (df94cbd4). The frontend wave branch was scanned the same way before it was marked ready, and was clean.

Lesson

  • A Fast-lane step the machine cannot run is still run before the PR is ready. For gitleaks, use the container at the CI workflow’s pinned version against a clone of the branch (a worktree’s .git is a file, so mount a clone): docker run --rm -v <clone>:/repo -w /repo ghcr.io/gitleaks/gitleaks:v<V> git --no-banner --redact --verbose --log-opts=HEAD .
  • A test fixture written as <name>_key = '<random-looking string>' will trip generic-api-key. Prefer a fixture value that does not look random ('f26d-seed-send-1'), or add its fingerprint in the same commit, while the PR is still a draft.

L-204 — When a write moves an item between two separately read lists, list it on the newer read’s side

  • Date: 2026-10-17
  • Source commits in this repo: .forge/specs/F1-e-notes-and-tags-findings.md F-004; forge-et-fe 0e9c18c9, cf98749d, 087f112b (forge-et-fe#284)
  • Sync target: upstream
  • Synced: pending

Problem observed

F1-e’s Settings › Tags page reads active and retired tags as two queries and re-reads both after Retire or Restore. The two answers arrive one after the other, so the moved tag was briefly in both lists: a duplicate row (a Playwright strict-mode failure in the browser suite) and a duplicate React key. Component tests passed, because they settle both reads before asserting. The first fix let the active list always win; the delta review showed that after Retire with a failed active re-read the tag then showed as active, with Retire and no Restore, so focus could not land on the counterpart action.

Change made

tagSettingsViewOf compares the two reads’ dataUpdatedAt and drops the shared item from the older read’s side (the active one wins a tie), with unit rows for each arrival order, a failed re-read on either side, and the tie.

Lesson

  • Two queries that partition one set are briefly inconsistent after every move between them. When a screen renders both, remove the overlap in the mapping from reads to view, and decide it by which read is newer (TanStack’s dataUpdatedAt), never by a fixed side: either read can be the stale one, including when its re-read fails and keeps its last good data.
  • Test the in-between states, not only the settled one: a unit row per arrival order (A then B, B then A, one fails) catches what a component test that awaits both reads cannot.

L-205 — When the unit-test record times out tests under its own load, run it with fewer Vitest workers

  • Date: 2026-10-18
  • Source commits in this repo: .forge/specs/F1-e-notes-and-tags-findings.md F-005; BUG-220; L-152
  • Sync target: project-only
  • Synced: pending

Problem observed

Two full pnpm test:record runs for forge-et-fe#284 on a 12-core Windows laptop each failed one test, F26-d’s PriceEmailDialog Also copy case, at 20,214 ms against its 20 s budget. Alone it takes about 6 s on both main and the PR branch. Nothing else heavy was running: the load (0.99 average) came from Vitest’s own workers, with Windows Defender scanning their files. The record script records nothing when a test fails, so the PR could not merge.

Change made

A third run with VITEST_MAX_WORKERS=6 pnpm test:record ran the whole suite (427 files, 8,016 tests), passed, and set Test record. The slow case is BUG-220.

Lesson

  • Before retrying a record that failed only on timeouts in tests the PR does not touch, lower Vitest’s worker count with VITEST_MAX_WORKERS=<half the cores> (Vitest 5 reads it from the environment, which scripts/local-test-evidence.mjs passes through). The full suite still runs; it takes longer and each test gets more of the machine. File the slow test as a bug either way.
  • Time the failing test alone on main and on the branch before calling it load: equal times rule out the PR, and the numbers go in the bug.

L-206 — A polled state reader reads the page once; never an auto-waiting call on an element that may just have gone

  • Date: 2026-10-19
  • Source commits in this repo: BUG-205; .forge/plans/F11-h/F11-h-WI-1.4-test-verify.md (runs 11–19); forge-et-fe 3b90b5a8
  • Sync target: project-only
  • Synced: pending

Problem observed

F20-h’s attachments-a11y.spec.ts:164 failed in most runs on main and in every full run of F11-h’s browser suite, with “the forward list is loaded, failed with Retry idle, or absent” after 14 s. Its trace showed the Retry read answering 200 in 59 ms and the list loaded on screen about 13 s before the poll gave up. The helper forwardListState, called from an expect.poll, counted the error block, then called getAttribute('aria-busy') on Retry. getAttribute is a Playwright action that waits for its element: when the read succeeded between the two calls, Retry had left the page, and the call waited for it until the poll’s timeout. expect.poll does not interrupt a callback that is still waiting. The window is milliseconds wide, so it opens more often under load (beside other specs, or on a busy machine), which is why it looked like a flaky product read for three days.

Change made

forwardListState reads the list’s state in one evaluateAll over the compose dialog, which never waits, checking the loading line, the error block with Retry’s aria-busy, and the rows in the same order as before (forge-et-fe#301, commit 3b90b5a8).

Lesson

  • A function that reports the page’s current state for expect.poll makes no waiting call. Read every element it needs in one evaluate / evaluateAll, or use only calls that return at once (count(), isVisible()). getAttribute, textContent, innerText, inputValue and click wait for their element and turn a state that just changed into a hang until the poll’s timeout.
  • When a poll times out while the screenshot shows the awaited state, suspect the reader before the product: the state arrived and the reader was stuck. The trace’s network timings show it (the read answered long before the timeout).
  • A reviewer of e2e helpers that feed expect.poll looks for a separate check followed by an auto-waiting read of the same element — frontend-reviewer dimension 14 carries the check.

L-207 — A query-cache entry two components observe is removed only when nothing observes it, and its tests render in StrictMode

  • Date: 2026-10-19
  • Source commits in this repo: .forge/specs/F11-h-ai-drafted-follow-up-findings.md F-001; .forge/plans/F11-h/F11-h-WI-1.4-test-verify.md (runs 1–2); forge-et-fe 8ae639c1
  • Sync target: upstream
  • Synced: pending

Problem observed

F11-h’s Follow-up draft panel and its Approve & send action share one TanStack Query entry, the lead’s draft. The panel removed the entry in its unmount cleanup, so leaving the lead drops the draft. The app renders in <StrictMode>, whose rehearsed unmount ran that cleanup on first mount; when the panel’s lazy chunk mounted after the action’s, the action kept observing a Query the cache no longer held and never saw the draft written later. Approve & send opened an empty compose dialog, and nine browser tests failed. Every component test passed: none rendered in StrictMode with both observers mounted.

Change made

The cleanup waits a microtask, then removes the entry only when its observer count is zero, and otherwise empties it. Component tests cover both chunk orders.

Lesson

  • Remove a shared cache entry only when query.getObserversCount() is zero; otherwise reset its data. removeQueries under a live observer detaches that observer for good.
  • A component test of shared client state renders the way main.tsx does — in <StrictMode>, with every observer mounted, in each mount order the app can produce (lazy chunks arrive in any order).

L-208 — A lazily loaded control placed into a settled layout reserves its room from the first paint

  • Date: 2026-10-19
  • Source commits in this repo: .forge/specs/F11-h-ai-drafted-follow-up-findings.md F-002; .forge/plans/F11-h/F11-h-WI-1.4-test-verify.md (runs 5–9); forge-et-fe 4d9f09b9; .forge/bugs.md BUG-265 (Approve & send in the lead page’s heading row, the same null fallback in F11-h’s other filler), fixed in forge-et-fe#345
  • Sync target: upstream
  • Synced: pending

Problem observed

F11-h filled F20-c’s compose-dialog aiDraft place with an AI draft button loaded by lazy() behind Suspense fallback={null}. The toolbar’s end group is right-aligned, so the button’s arrival, after the dialog had settled, pushed Insert template left. A mouse press on Insert template blurred the subject, the re-render committed the arrived button during the press, and the release landed outside Insert template: no list opened. Only F20-d’s existing browser test caught it (0 of 4 on the wave, 4 of 4 on its base); jsdom has no layout and could not.

Change made

The composition wraps the lazy button in its own Suspense whose fallback is a hidden, inert stand-in of the same size, rendered under the button’s own rule, so the arrival moves nothing.

Lesson

  • A lazily loaded component that renders into an existing row or toolbar has a same-size, hidden, inert fallback, never null, wherever its arrival could move a neighbour.
  • A feature that fills another feature’s place runs that feature’s browser specs (here e2e/browser/email) before its wave gate; the owning feature’s tests are the ones that notice the shift.

L-209 — Review a frontend wave PR before its browser gate, and run the gate once on the head the review approves

  • Date: 2026-10-19
  • Source commits in this repo: .forge/specs/F11-h-ai-drafted-follow-up-findings.md F-005; .forge/plans/F11-h/F11-h-overnight-log.md O-12 to O-16; .forge/specs/F11-d-ai-summary-spam-duplicate-findings.md F-008 (the second instance, forge-et-fe#308)
  • Sync target: project-only
  • Synced: pending

Problem observed

/forge-deliver Stage 12 ran F11-h’s pnpm e2e:gate (4,992 tests, 1.1 h) before forge-pr-open --wave would open the forge-et-fe wave PR, and reviewed the draft afterwards. The review found 9 Importants and a delta round one more; every fix touched src/, a gate input, so the first result stopped covering the head. Two more gate runs followed (one stopped, one failing on two unrelated load timeouts), and the result that covered the merged head came from the fourth — over seven hours of gate time for one result. The backend wave PR, which needs no gate, was opened early and reviewed while the first gate ran.

Change made

F11-h’s framework follow-up PR moved the frontend browser gate in /forge-deliver Stage 12 to after the review (the last step’s item 5, pnpm e2e:gate --push on the approved head), and forge-pr-open --wave now opens a frontend wave PR as a draft with no Browser gate: line when no result covers its head.

Lesson

  • Open a frontend wave PR as a draft before its gate (a draft’s Fast lane does not read the Browser gate: line), review it and its fix rounds, and run pnpm e2e:gate --push once, on the head the review approves. Stage 12’s order and forge-pr-open --wave’s gate condition need the change.
  • Reset the test database before every gate run and keep the machine awake: a gate that ran 4.1 h instead of 1.1 h failed on timeouts in screens it did not touch (BUG-218’s class).

L-210 — A build record runs alone in its worktree: a targeted Gradle run beside it recompiles the classes it is testing

  • Date: 2026-10-20
  • Source commits in this repo: .forge/specs/F11-d-ai-summary-spam-duplicate-findings.md F-001; .forge/plans/F11-d/F11-d-overnight-log.md decision 10; refines L-085
  • Sync target: upstream
  • Synced: pending

Problem observed

F11-d’s backend wave PR got its first build record (python3 scripts/local-build-evidence.py, which runs ./gradlew build) while review-fix agents ran ./gradlew test --tests … in the same worktree. Each targeted run recompiled build/classes under the running build, which then failed 40 tests with “Failed to read candidate component class” and ran a stale copy of a changed spec. The code had no defect: the record re-run alone passed 9,054 tests. L-085’s machine lock says targeted runs need no lock, which holds only across worktrees.

Change made

The failed record was discarded and re-run with nothing else touching the worktree. F11-h’s framework follow-ups (forge-et-harness#789, merged while F11-d ran) start no gate or record until the session’s sub-agents are idle, which covers this case.

Lesson

  • Nothing else runs Gradle in a worktree while its full build or build record runs — not a targeted --tests run, not a compile. Two Gradle runs share one build/ folder, and the later one’s compile changes the classes the earlier one is loading.
  • A review-fix agent dispatched into a worktree whose record is running waits for it, or works in a worktree of its own; the orchestrator does not start a record while fix agents are still active there.
  • A record that fails with class-loading or stale-class errors right after other work touched the worktree is re-run alone before anything is fixed.

L-211 — An aria-label that replaces a button’s visible text fails Label in Name; catch it where the name is first chosen

  • Date: 2026-10-20
  • Source commits in this repo: .forge/specs/F11-d-ai-summary-spam-duplicate-findings.md F-002; forge-et-fe c7f0df41, 3140c48f (forge-et-fe#308); BUG-401 (forge-et-fe#518: hidden “, in ” between a folder’s visible name and its count); related to L-129
  • Sync target: upstream
  • Synced: pending

Problem observed

F11-d’s WI-1.2 plan named Dismiss tag’s accessible name “Dismiss the Spam tag” and Link to this customer’s “Link this lead to ”. Neither contains the words on the button, so a speech-input user who says them cannot press it (WCAG 2.1 SC 2.5.3, level A). The plan review, the component tests, axe and two browser suites passed it, because each was written to the plan’s names; only the PR review caught it, after the plan, the jsdom queries and the Playwright toHaveAccessibleName assertions all had to change.

Change made

The names became Dismiss tag: <tag> and Link to this customer: <name>, the visible text first, and the tests assert them built from the visible-text constants so the two cannot drift. plan-reviewer checks it as DC-10 and frontend-reviewer in its accessibility dimension (F11-d’s framework follow-up).

Lesson

  • An accessible name that differs from a control’s visible text must start with that text (<visible text>: <context>), so speech input and the screen reader agree. Axe does not check this.
  • Check it where the name is first written — the plan’s ## UI / Design Adherence — because every test written afterwards encodes the name and stops being able to catch it.
  • Build the asserted name from the same constant as the visible text in component and browser tests.

L-212 — An adapted shadcn component needs its own test of every prop path it keeps from upstream

  • Date: 2026-10-20
  • Source commits in this repo: .forge/bugs.md BUG-192 (the busy shadcn Button grew wider, forge-et-fe#262) and BUG-201 (the shadcn Button with asChild gave Radix’s Slot two children, forge-et-fe#314); BUG-235 (the shadcn Dialog’s InertWhileOpen made Radix’s focus guards inert, forge-et-fe#321); BUG-274 (the busy spinner, sized for the default padding, overlapped a leading icon at the has-[>svg] padding, forge-et-fe#356)
  • Sync target: upstream
  • Synced: pending

Problem observed

The CRM’s shadcn Button is shadcn’s component with the CRM’s rules added (aria-disabled, a busy spinner, AD #39). It shipped with no test file of its own. Two of the paths it keeps from upstream broke in the adaptation and were found only when a feature first used them: busy, whose spinner widened the button (BUG-192, found by the role editor’s browser test), and asChild, where the spinner’s empty slot beside the child made Slot throw (BUG-201, found when F20-d added the alert dialog, which worked around it). Each time, the feature that found the bug had to stop, and the alert dialog carried a workaround until the fix.

Change made

forge-et-fe#314 fixed asChild and added src/ui/shadcn/button.test.tsx and src/ui/shadcn/alert-dialog.test.tsx, which test the paths the CRM’s code relies on. frontend-reviewer’s shadcn dimension (23) now asks for such a test when a diff adds or adapts a shadcn component.

Lesson

  • When a shadcn component is added or adapted, its own test file covers every prop path it keeps from upstream (asChild, each variant and size the CRM uses, disabled, busy), not only the one the first screen uses. The CRM’s adaptations are new code on top of a library whose own tests do not cover them.
  • A workaround for a shared component inside another component is a bug to file, not a pattern to copy. F20-d filed BUG-201 instead of keeping its workaround silent, which is why this fix could remove it.

Update — 2026-10-21

BUG-235: the shadcn Dialog’s InertWhileOpen (added for axe aria-hidden-focus) made inert everything Radix hid, Radix’s own focus guards included, and so broke the focus trap’s fallback for a Tab that leaves the content. Its tests checked the marks it adds, never the trap it sits beside. The lesson covers behaviour an adaptation keeps from upstream as well as props: an adaptation that changes the DOM a Radix primitive works on (attributes on what Radix hid, elements Radix inserts) needs a test that the primitive’s own behaviour still works — here, that the guards stay focusable while the dialog is open (src/ui/shadcn/dialog.test.tsx) and a plain-Tab WebKit row (notes-tags-keyboard-webkit.spec.ts).

L-213 — Prove where a transaction starts with Spring’s own interceptor, and undo an external effect only after a known roll-back

  • Date: 2026-10-20
  • Source commits in this repo: BUG-199 (.forge/bugs.md); forge-et-be 345b7546, c46a05ee, 9e048ccb, a579299a (forge-et-be#285)
  • Sync target: upstream
  • Synced: pending

Problem observed

FS-11’s AttachmentService.upload was @Transactional and called ObjectStore.put for the whole file inside it, so every upload held a pooled database connection for as long as the transfer took. The rule against it was already written (coding-standards.md §2 Transactions, backend-reviewer’s layering checklist), and the F20-h review found the breach, but no test could have: the T1 specs built the service with new and called it directly, where @Transactional does nothing, so they passed with or without the annotation.

The first fix put the object first and wrapped the row in a TransactionTemplate, keeping the compensating deleteAllVersions in a catch around execute. That catch also caught a commit whose outcome was unknown — a connection lost after COMMIT was sent — where the row may have committed. Deleting the object then leaves a row whose file is gone, which is worse than the orphan object the delete exists to prevent. The PR review caught it.

Change made

The upload puts the object with no transaction open, refuses to run inside a caller’s transaction scope (TransactionSynchronizationManager.isSynchronizationActive()), then writes the row, its audit events and the scan request in one TransactionTemplate transaction. The callback’s first statement registers an afterCompletion synchronization that records the outcome; the object is deleted only when the transaction never began or rolled back, and kept with an ERROR line when the outcome is unknown or the row committed. UploadTransactionSpec wraps the real service in Spring’s TransactionInterceptor reading @Transactional, with a resourceless RecordingTransactionManager (forge-et-be support/), and records whether a transaction was active at each collaborator call. It failed 8 of 8 against the old code.

Lesson

  • To prove where a transaction starts and ends in a T1 spec, put the bean behind Spring’s TransactionInterceptor (ProxyFactory, AnnotationTransactionAttributeSource) and capture TransactionSynchronizationManager.isActualTransactionActive() inside the fake collaborators. A spec that calls the bean directly cannot see @Transactional at all.
  • Undo an external effect after a failed transaction only when the roll-back is known: the transaction’s afterCompletion status is STATUS_ROLLED_BACK, or it never began. Any exception from execute also covers a commit with an unknown outcome and an after-commit action that failed after the row committed; in those cases keep the effect and log ERROR, because a leftover external object is recoverable and a committed row pointing at a deleted one is not.
  • Enforce “no I/O inside a transaction” in the method that does the I/O, by refusing an active synchronization scope, rather than relying on every caller to stay non-transactional.

L-214 — A TanStack placeholder is the earlier key’s answer as it was when the key changed; it does not follow later changes to that entry

  • Date: 2026-10-20
  • Source commits in this repo: .forge/bugs.md BUG-229 (F11-d’s AI summary panel, fixed in forge-et-fe#315)
  • Sync target: upstream
  • Synced: pending

Problem observed

F11-d’s panel reads its lead’s triage under a key that carries the lead’s version, with placeholderData: keepPreviousData, so a new version keeps the earlier body on screen while it is read. A refused Link to this customer re-read the version the panel was leaving, and that re-read removed the proposal, but the panel had already moved to the new key and went on offering the button until the new key’s first read landed. TanStack 5.104’s queryObserver reuses the placeholder it first showed (prevResult.data), so a later write to the earlier key’s cache entry never reaches it. The adversarial delta pass on forge-et-fe#308 found it; the component tests had all released the reads in the order that hid it.

Change made

While query.isPlaceholderData, useLeadTriage shows the lead’s latest answer instead of query.data (the hook’s kept last good answer, then the cache’s latest entry), and a component test holds both reads to cover the window.

Lesson

  • Treat query.data while isPlaceholderData as a snapshot of the earlier key, not a live view of it. When something can still change the earlier key’s entry during the new key’s first read (a mutation’s re-read, a setQueryData edit), read the value to show from the cache, or from state the component keeps, and rank it explicitly.
  • Test the window with both reads held: release the earlier key’s re-read before the new key’s first read, and assert what the screen shows in between.
  • An entry nothing observes can leave the cache as soon as its read settles (gcTime: 0 in the test client), so a value read back from the cache needs a kept copy as well.

L-215 — A rule that moves where state is written must also move where a resumed run reads it

  • Date: 2026-10-21
  • Source commits in this repo: found while handing off F38-g wave 2 (feature/F38-g-wave-2, commit 9517281e); .claude/commands/forge-deliver.md Stage 0 Step 0a, the Resume Protocol and the manual-wave path changed by the PR that adds this lesson
  • Sync target: upstream
  • Synced: pending

Problem observed

L-086 sent the orchestrator’s tracker writes to the harness wave branch feature/<ticket>-wave-<N>, cut from origin/main, once the plan PR has merged. Stage 0 Step 0a, which decides where a fresh /forge-deliver <ticket> reads the live tracker row, was not changed with it: with no plan or spec branch it read origin/main. For a manual wave the wave branch stays unmerged while the person carries out the run, so a resumed run would read main’s older row — F38-g’s wave 2 still planned and wave 1 still pr-open, while feature/F38-g-wave-2 already recorded wave 1 merged and WI-2.1 with-person — heal again and repeat the M1 hand-off instead of going to M2. The M1–M3 text also still named only feature/<ticket>-plan as the branch that carries the orchestrator’s writes.

Change made

Step 0a now looks for a live harness wave branch when neither the plan nor the spec branch exists — on the remote, with no merged or closed PR from it — reads the row there, and does the session’s harness work in that branch’s worktree. Two live wave branches with different rows halt and ask. A wave branch deleted from the remote while a local copy holds commits not on main halts rather than falling back to main’s row. The manual-wave path says that, once the plan PR has merged, its references to the plan branch mean the wave branch, and the orchestrator commits only its own files there, never the person’s record.

Lesson

  • When a rule changes the branch a workflow writes its state to, change the step that finds where to read it in the same PR, and test the change by asking what a fresh run started from another checkout would read.
  • Search for every statement of the old location (git grep for the branch name and the step that reads it) and update each one, including the hand-off text a person follows and the resume tables.

L-216 — A check that runs only on clean builds cannot see a failure that needs an incremental one

  • Date: 2026-10-21
  • Source commits in this repo: BUG-237 (.forge/bugs.md); forge-et-be 899a466d, de011591, 36d3de04, 8596c806 (forge-et-be#288)
  • Sync target: upstream
  • Synced: pending

Problem observed

A targeted ./gradlew test in a forge-et-be worktree failed compileJava with NullAway “mismatched nullability of type parameters” at EmailSendController.java:157, and --rerun-tasks made it pass. It was first put down to an edit in an unrelated class. On JDK 21, javac drops a type-use @Nullable inside a type argument when it reads a class from its class file (JDK-8225377, fixed in JDK 22). When Gradle recompiled the controller alone, NullAway read SendEmailRequest’s List<@Nullable JsonNode> as List<JsonNode>. The same held wherever one file named another file’s @Nullable type argument, in LeadService and the email-template code. CI compiles clean every time, so no gate saw any of them. The first run of the new check was also wrong: a failed probe left Gradle recompiling the failed files on the next one, and a restore with no compile after it let two files recompile together, which hid a failure.

Change made

The signatures stopped putting @Nullable inside type arguments where the value is never null (a JSON null entry is a NullNode; a map leaves the key out), and one reader takes the value into var. A review suspected a lambda passed to a Function<String, @Nullable MailMessage> parameter too; probing that caller on its own passed, so the interface written for it was reverted. scripts/check-incremental-compile.py changes each file that names a @Nullable type argument, on its own, runs an incremental compile, and recompiles before the next probe; it stops when Gradle turns a probe into a full recompilation. The rule is in coding-standards.md §7.2, the backend CLAUDE.md and backend-reviewer. Compiling on JDK 25 with --release 21 removes the cause and is deferred to the next analyzer upgrade (.forge/owed.md).

Lesson

  • When a compile fails locally and passes with --rerun-tasks or on CI, suspect what the compiler reads from class files, not the class that was edited. Reproduce it by changing only the failing file and compiling incrementally; that is deterministic, where waiting for the edit that first triggered it is not.
  • A failure that only an incremental build shows needs its own check. A gate that always builds clean proves nothing about it, so the check has to make the incremental case happen on purpose and confirm the build tool really compiled incrementally.
  • A check that probes one change at a time must restore the build after each probe, or the next probe inherits the previous one’s state and its result describes two changes.

L-217 — After merging main into a wave, diff the test stack’s application-local.yml against the example before booting it

  • Date: 2026-10-21
  • Source commits in this repo: .forge/specs/F1-c-communication-timeline-findings.md F-001; .forge/plans/F1-c/F1-c-WI-1.4-test-verify.md (the stopped gate run); related to L-058
  • Sync target: upstream
  • Synced: pending

Problem observed

F1-c’s isolated verify stack booted its backend from a worktree whose gitignored application-local.yml had been copied days earlier. Merging origin/main into the wave brought F11-d’s lead-triage listener, which runs only when et.messaging.lead-triage-queue is set, and main’s application-local.yml.example had gained that key. The stale copy lacked it, so every lead-triage test in the browser gate failed, and the first 30 minutes of a 2.6-hour run were thrown away before the cause was found.

Change made

The two keys were copied from the example, the stack was reset and the gate run again; the local file now has every key the example has.

Lesson

  • A merge of main can change what the local config must contain, and nothing re-reads a gitignored copy. L-058 covers a worktree with no copy; this is a copy that has fallen behind.
  • Before booting a stack after a merge of main, compare the keys: diff <(tr -d '\r' < application-local.yml) <(tr -d '\r' < application-local.yml.example), and copy across any key the example has and the copy lacks.
  • When many tests of one other feature fail together, check that feature’s configuration first: a queue, a flag or a provider switch the local profile does not set looks like a code failure.

L-218 — Before a multi-hour run, confirm the machine is on mains power, not only that idle sleep is off

  • Date: 2026-10-21
  • Source commits in this repo: .forge/specs/F1-c-communication-timeline-findings.md F-002; .forge/plans/F1-c/F1-c-WI-1.4-test-verify.md (the run invalidated at 19:02); related to F11-f findings F-006
  • Sync target: upstream
  • Synced: pending

Problem observed

Before F1-c’s browser gate the idle-sleep setting was checked (powercfg /query SCHEME_CURRENT SUB_SLEEP STANDBYIDLE → 0 on AC and DC). Three hours into a later gate run the laptop was on battery; Windows hit Critical Battery Trigger Met and slept from 19:02 to 22:35 whatever the idle setting. The two tests running then failed after “3.5 h”, more failed after the wake, and the run could not be used as evidence.

Change made

The run was stopped, and the PR carried Browser gate: skipped — … by the developer’s decision (the gate had passed in full on the previous head). The remaining records ran with the charger in.

Lesson

  • Idle sleep set to Never does not stop a sleep at critical battery. Before a run of more than an hour, check that the machine is on mains now (Win32_Battery BatteryStatus 2, or PowerOnline true) and ask the developer to keep the charger in for the whole run.
  • When a run’s failures are timeouts lasting hours, read the system log first (Get-WinEvent for Kernel-Power 42, 107 and 524) before attributing them to code.
  • A run that slept is not evidence, however many tests passed around the sleep; record it as stopped and why.

L-219 — A table column pinned at every width can cover the last column’s controls at the narrowest width

  • Date: 2026-10-21
  • Source commits in this repo: .forge/bugs.md BUG-232 (the contacts table’s Edit at 320 × 640, fixed in forge-et-fe#320); .forge/owed.md, the 2026-10-15 row on a focused row action scrolling under the sticky first column at 320px (F1-f-WI-1.5’s browser runs), settled by the same fix; design-system §9 Rev 68; BUG-310 (the leads table’s Est. value header at 768 × 1024) and BUG-345 (the scroll positions in between); design-system Rev 94
  • Sync target: upstream
  • Synced: pending

Problem observed

Eleven CRM tables pinned their first column with position: sticky “at every width”, on the reasoning that sticky does nothing until the region scrolls. At the 320px reflow size the app’s sidebar rail left the contacts table a 206px scroll region; the pinned Name column took 101px and the Actions cell needed 154px. With the table scrolled to its end, Edit sat under the pinned column with 18.7px showing (axe target-size). F1-f’s browser runs had seen the same overlap on 2026-10-15 and opened the actions by keyboard to get past it; it was recorded as a decision for later, and failed every full gate from F1-f’s merge until it was fixed.

Change made

The lead decided to keep the reflow and pin the first column from bp/tablet up only, for every table: one hook, usePinnedFirstColumn, sets data-pin-first on the table, which the shadcn cells (a named Tailwind group) and the CSS-module rules key on. src/ui/pinnedFirstColumn.test.tsx fails any stylesheet that pins at the inline start outside [data-pin-first], and any class string with a bare left-0.

Lesson

  • A layout rule applied “at every width” holds only if it fits at the narrowest supported width. A pinned column needs the room beside it to be at least the widest column that scrolls under it; at 320px that is rarely true, so pin from the breakpoint where it is (bp/tablet in the CRM), not everywhere.
  • When a test works around a layout problem (opening a control by keyboard because a click lands on the wrong element), the problem is a defect: file it as a bug with the measurement, not as a later decision, so the size matrix’s failure has an owner.
  • Guard a shared layout rule with a source scan, so the next table cannot reintroduce the pattern by copying an older one.

Update — 2026-11-05

Pinning from bp/tablet up does not remove the overlap on a table wider than its region there. At 768 × 1024 the leads table scrolled to its end left its Est. value sort button 22.7px clear of the pinned Name header’s button (BUG-310). Reaching a row’s ⋯ menu scrolled the table there, so the size matrix’s row-menu state failed. The ⋯ column is now pinned at the inline end as well (design-system Rev 94), so reaching it scrolls nothing. A size-matrix state checks one scroll position only. A sweep of the scroll in 20px steps, running axe at each step, found the same overlap at other positions, including new ones under the pinned ⋯ column (BUG-345). When a pinned table fails target-size, sweep its scroll before choosing a fix.

L-220 — A gate failure that main shares on one platform only is marked on that platform, not skipped

  • Date: 2026-10-22
  • Source commits in this repo: .forge/specs/F13-ai-account-briefing-findings.md F-001; .forge/plans/F13/F13-overnight-log.md O-23, O-24; BUG-246; the BUG-131 lesson’s change
  • Sync target: upstream
  • Synced: pending

Problem observed

F13’s frontend wave gate failed four pinned-column tests that fail the same way on main on Windows Chromium only (BUG-246). The overnight run concluded they could not be marked, because markKnownFailure takes no platform argument and a plain mark fails every gate where the tests pass. So no gate could pass on a Windows machine, and the PR merged on a Browser gate: skipped line. BUG-131 had already been handled by calling the mark only when process.platform === 'win32'.

Change made

None in F13: the developer chose the skip line. A Windows-only mark for BUG-246 is owed (owed.md).

Lesson

  • When a gate failure reproduces on main on one platform only, mark it on that platform: wrap markKnownFailure('BUG-NNN', …) (or the size matrix’s knownFailures entry) in a check of process.platform (or the browser engine), so the test still runs and must pass elsewhere. File the bug in the same change.
  • Before concluding that a gate cannot pass, search lessons.md and bugs.md for the same failure shape (grep -n -i "known failure\|markKnownFailure" .forge/lessons.md). A skip line costs every later Windows PR the same skip; a platform mark costs one small PR.

Update — 2026-10-22

Fixing BUG-246 showed three limits of this lesson. Find the cause before marking: BUG-246 was a real 10px jump that Windows Chrome users see (L-224), and a plain page in Playwright’s Chromium isolated the cause within minutes; a mark would have hidden a defect. BUG-131’s test is skipped on Windows, not marked: test.skip(process.platform === 'win32', …) with an entry in scripts/browser-gate/expected-skips.json. A mark is not always possible: markKnownFailure is test.fail over the whole test, so a test holding other checks must be split first (L-131), and the size matrix’s knownFailures has no platform field and names only page-check kinds, not an assertion inside an arrangement.

L-221 — Agents never run ./gradlew --stop on a shared machine

  • Date: 2026-10-22
  • Source commits in this repo: .forge/specs/F13-ai-account-briefing-findings.md F-002; .forge/plans/F13/F13-overnight-log.md O-11
  • Sync target: upstream
  • Synced: pending

Problem observed

An implementer agent ran ./gradlew --stop to start a clean build. The command stops every daemon of that Gradle version for the user, not only the one the caller started, so on a laptop where parallel sessions run builds it can fail another session’s build with a lost daemon. Nothing showed whether one did.

Change made

The agent was told to use --no-daemon. .claude/lib/forge-deliver/agent-prompt-template.md § Running the app locally now says so to every implementation agent.

Lesson

  • Never run ./gradlew --stop (or gradle --stop) where another session may be building. For a build that must not reuse a daemon, run it with --no-daemon; for a daemon in a bad state, stop that one process by its PID.
  • A command that acts on the whole machine (--stop, docker system prune, taskkill /IM) is one any parallel session can feel; prefer the form scoped to the caller’s own process, container or port.

L-222 — A feature’s new tests can push forge-et-be’s test compile over the compiler’s heap cap

  • Date: 2026-10-22
  • Source commits in this repo: .forge/specs/F13-ai-account-briefing-findings.md F-003; .forge/plans/F13/F13-overnight-log.md O-9, O-20; F13 WI-1.1 plan ## Notes
  • Sync target: project-only
  • Synced: pending

Problem observed

F13’s integration tests took a clean compileTestGroovy over the forked Groovy compiler’s 1536m heap (Java heap space, twice) while main still compiled at that cap. An incremental local build would not have shown it; CI’s Fast lane compiles from scratch and would have failed on the wave PR.

Change made

build.gradle’s forked compiler heap was raised to 2048m in F13’s backend wave (forge-et-be#296), and a requested CI run proved the compile on the Linux runner.

Lesson

  • Before a backend wave PR opens, build it from a clean test compile (./gradlew clean build or the build record from a fresh worktree), not only incrementally: the test sources grow with every feature, and the cap is hit by whichever feature tips it.
  • A Java heap space error in compileTestGroovy is the compiler’s fork heap, set in build.gradle, not the test JVM’s; raise it in its own commit with the measured result on main and on the branch.

L-223 — forge-et-be’s nightly Slow lane has outgrown its 30-minute job limit

  • Date: 2026-10-22
  • Source commits in this repo: .forge/specs/F13-ai-account-briefing-findings.md F-005; .forge/plans/F13/F13-overnight-log.md O-20 (run 39689717589)
  • Sync target: project-only
  • Synced: pending

Problem observed

A requested “PR validation” run on F13’s backend wave compiled and then ran :test until the Slow lane’s timeout-minutes: 30 cancelled it after 27 minutes. The nightly run on main had been cancelled every night from 16 to 21 October (the 16 October Slow lane ran 30 minutes to the limit; the 14th and 15th passed), so the nightly run that catches two clean merges breaking each other (git-conventions.md § Branching) had not finished since then, and a cancelled run looks like noise rather than a failure.

Change made

None: changing a workflow needs the lead’s approval. An owed.md row asks the lead to decide.

Lesson

  • Read a cancelled nightly run as a missing check, not a passed one. When the Slow lane is cancelled rather than failed, compare its duration with the job’s timeout-minutes before re-running it.
  • The suite’s length grows with every feature; the local build record’s time (about 41 minutes on 2026-10-22) is the early sign that a CI time limit is about to be reached.

L-224 — A layout proved where scrollbars overlay the content can be wrong where they take room

  • Date: 2026-10-22
  • Source commits in this repo: .forge/bugs.md BUG-246 (forge-et-fe#320’s pinned first column; the fix on fix/BUG-246-pinned-column-gutter); BUG-313 and BUG-354 (a Reporting line note that could not wrap passed <main>'s inner edge by 2px only where the scrollbar takes 15px, forge-et-fe#450); BUG-492 (a question’s scrollbar-gutter on <main> took 15px under Playwright’s headless Chromium on a Mac with a mouse connected, forge-et-fe#592); related to L-219 and the BUG-131 lesson
  • Sync target: upstream
  • Synced: pending

Problem observed

Seven CRM tables pin their first column (position: sticky) inside a scroll region set to scrollbar-width: thin with scrollbar-gutter: stable both-edges. On macOS the scrollbar overlays the content, so the reserved strip is 0px and everything lined up; forge-et-fe#320’s gate passed there. On Windows the thin scrollbar takes 10px, both-edges reserves the same 10px on the left, the first cell starts after it, and Chromium sticks the pinned cell at the region’s edge, inside the strip: the Name column jumped 10px as the table scrolled, and four browser tests failed on every Windows machine, main included.

Change made

The pinned tables reserve the strip on the right only (scrollbar-gutter: stable), and a source scan in src/ui/pinnedFirstColumn.test.tsx fails a file that pins a first column and keeps both edges.

Lesson

  • Anything that depends on a scrollbar’s width — scrollbar-gutter, 100vw, a sticky offset, a measured clientWidth — is proved on a machine where scrollbars take room, Windows or macOS with “Show scroll bars: Always”, before it merges. A pass where scrollbars overlay the content proves nothing about it.
  • When a browser test fails by the same few pixels on one platform only, suspect the scrollbar first, and isolate it on a plain page before marking or skipping the test: a few lines in Playwright’s Chromium showed BUG-246’s cause in minutes.
  • Playwright’s headless Chromium hides scrollbars but not a scrollbar-gutter (BUG-492). It launches with --hide-scrollbars, so an overflow: auto scrollbar takes 0px, but a scrollbar-gutter: stable still reserves the platform’s classic width: 15px on a Mac while a mouse is connected, 0px otherwise. A browser test of anything that sets a gutter can then pass at night and fail in the afternoon on the same commit. To reproduce classic scrollbars on a Mac, launch the browser through a wrapper script that execs the real binary with -AppleShowScrollBars Always (Playwright’s executablePath); injected ::-webkit-scrollbar CSS is not a faithful copy. In code, set a gutter only for the room a scrollbar was measured to take (offsetWidth - clientWidth less the borders), never because the region overflows.

L-225 — Size a queue’s visibility timeout from its job’s worst-case run, not the estate’s default

  • Date: 2026-10-22
  • Source commits in this repo: .forge/specs/F11-c-lead-research-job-findings.md F-001; the review record on forge-et-be#297; .forge/cloud-gated-validation.md §B F11-c item 2
  • Sync target: upstream
  • Synced: pending

Problem observed

F11-c’s lead-research job makes up to two web searches with retries and one AI call: about 110 s in the worst case. Its plan and the wave contract copied F11-d’s rule, a queue visibility timeout of “at least et.messaging.visibility-timeout” (30 s), because F11-d’s job is short. With 30 s, SQS hands a message that is still being worked on to a second consumer, which pays for a second search and a second AI call. The idempotency key (AD #13) stops a second write, not the second spend. The backend review of the wave PR caught it; no test did, because local runs finish fast.

Change made

LeadResearchJobListener asks SQS for 240 s of visibility on every receive, the local queue is provisioned with 240 s, and the Terraform queue is asked for 240 s as a backstop (register item 2, .forge/owed.md’s DevOps row). forge-et-be docs/search/README.md keeps the arithmetic.

Lesson

  • A queued job’s visibility timeout is a property of that job, not of the estate. Before a spec or plan names one, add up the job’s worst case — every outside call’s timeout times its retries, plus any wait a rate limit can impose — and set the timeout clearly above it.
  • An idempotency key protects the record, not the bill. A job that calls a paid service must also not be run twice at once; a visibility timeout shorter than the run lets that happen.
  • Copying a queue rule from an earlier feature carries its timing assumption with it: check the earlier job’s run time against the new one’s before reusing the rule.

L-226 — Before filing a bug for a test that fails on main, look on the other open branches for the same failure

  • Date: 2026-10-22
  • Source commits in this repo: .forge/specs/F11-c-lead-research-job-findings.md F-003; .forge/bugs.md BUG-242 and BUG-244
  • Sync target: upstream
  • Synced: pending

Problem observed

On 2026-10-21 F11-c and F13 each found smokeRun.test.ts failing on Windows on main. F11-c filed it as BUG-242 and F13 as BUG-244, on their own unmerged branches, and each fixed it in its own wave. Both fixes reached the merge of main into F11-c’s frontend wave, where F11-c’s was dropped in favour of F13’s and BUG-242 was closed as a duplicate. next-bug-id.sh gave each a distinct number because it sees the ids open PRs hold, not what their bugs are about.

Change made

BUG-242 is closed as a duplicate of BUG-244 (fixed, forge-et-fe#327), with a note on each.

Lesson

  • A failure on main is found by every feature that runs the same suite on the same kind of machine, and parallel features run it the same day. Before filing, search the open harness PRs’ and branches’ bugs.md for the failing file or test name, for example gh pr list --repo <org>/<harness-repo> --state open --search "<test file name>" and git grep -n "<test file name>" $(git branch -r --list 'origin/feature/*') -- .forge/bugs.md.
  • When the same bug is already filed elsewhere, add to that bug (a note, a second operating system, your evidence) rather than filing and fixing it again.

L-227 — A stalled agent with local commits is resumed, not re-dispatched

  • Date: 2026-10-22
  • Source commits in this repo: .forge/specs/F11-c-lead-research-job-findings.md F-007; .forge/plans/F11-c/F11-c-overnight-log.md O-1, O-2, O-9
  • Sync target: upstream
  • Synced: pending

Problem observed

During F11-c’s unattended run three implementer agents stopped on the stream watchdog (600 s without output), not on a failed check. Each had committed work in its worktree and pushed nothing. That is exactly the state /forge-deliver Stage 0 reads as “nothing on the remote: safe to reset to pending and re-dispatch”, and a fresh dispatch would have redone the committed work or clashed with it.

Change made

Each agent was resumed from its own transcript and worktree and told to finish only what was left, after reading its plan’s ## Progress and git log origin/main..HEAD.

Lesson

  • “Nothing on the remote” is not “nothing done”. Before resetting a dispatched work item to pending, look in its worktree: git -C <worktree> log --oneline origin/<base>..HEAD and git -C <worktree> status.
  • Commits there mean resume, not re-dispatch: continue the stalled agent, or brief a new one to read the plan’s ## Progress and those commits and finish only the remaining subtasks and the final skills.
  • Only a work item whose worktree has no commits and no changes is safe to re-dispatch from scratch.

L-228 — A test that reads a captured log event on another thread must freeze it on the logging thread

  • Date: 2026-10-23
  • Source commits in this repo: .forge/bugs.md BUG-252 (ScheduledFreshTraceIT AC-4 read a null traceId once on CI); BUG-464 (CardReadPipelineIT AC-24 iterated a plain ListAppender’s list on the root logger while other threads logged, and threw ConcurrentModificationException; switched to MdcCapturingAppender, forge-et-be#466); BUG-467 (CardReadLogHygieneIT, the same, forge-et-be#468); BUG-466 (the same shape in every other log test, swept to MdcCapturingAppender with LogCaptureGuardSpec failing a new plain ListAppender, forge-et-be#471)
  • Sync target: upstream
  • Synced: pending

Problem observed

ScheduledFreshTraceIT attached a Logback ListAppender to a queue handler’s logger and polled the captured events from the test thread for the traceId in their MDC. Logback copies an event’s MDC lazily, from the thread that first calls getMDCPropertyMap(), and a logger’s own appenders run before its parents’. In the moment after the ListAppender kept the event and before the root console appender read it on the worker, a poll copied the test thread’s empty MDC into the event, and every later poll read the same empty map. It failed once in about 10,000 tests on a CI runner and never locally. QueueTraceIT had the same exposure, and MailboxBackfillIT the same on the event’s thread name, which Logback fills in lazily the same way.

Change made

forge-et-be test support gained MdcCapturingAppender, a ListAppender that calls prepareForDeferredProcessing() in append and keeps its events in a list safe to read while the worker appends. The three specs use it, and MdcCapturingAppenderSpec holds the logging thread inside the moment so the race fails the same way every run.

Lesson

  • A captured event’s lazy fields belong to the thread that reads them first. When a test reads an event’s MDC, thread name or formatted message on a thread other than the one that logged it, freeze the event on the logging thread: MdcCapturingAppender, or prepareForDeferredProcessing() before handing it over. An appender on the logging class’s own logger runs before the root console appender, so it is the one exposed.
  • Reproduce a rare race by holding it open, not by running it many times. A parent appender that waits turned a once-in-10,000 failure into one that fails every run, on any machine, which is what made the fix provable on macOS when it had been seen only on Linux CI.

L-229 — A bulk write path built from per-record service calls pays a check, a lock and an audit row per record; plan it set-based

  • Date: 2026-10-26
  • Source commits in this repo: .forge/specs/F4-d-migrate-accounts-contacts-findings.md F-001; .forge/plans/F4-d/F4-d-WI-2.1-plan.md revisions 2 and 3 (D17, D18)
  • Sync target: upstream
  • Synced: pending

Problem observed

F4-d’s Pipedrive write run was planned through the same per-record service methods the screens use, so every account, contact and tag link took its own grant check, its own advisory lock and its own audit row. At the size of the real exports (4,235 organisations, 4,977 people, 2,339 tagged records) the first load took 154 s against a 30-second bound. The timing test was in the plan and caught it before merge, but only after wave 2’s code had been built and reviewed, so the fix took two plan revisions and a change to another feature’s audit service.

Change made

Revision 2 attached tags in one ON CONFLICT DO NOTHING insert per entity type, gated once by the run’s grant (82–87 s). Revision 3 created accounts and contacts with one insert per entity type and recorded their created events with AuditService.recordAll, a batch insert added to F39’s audit service for raw-SQL writes (3.2–4.7 s).

Lesson

  • Count the per-record cost when a plan designs a bulk write path. For an import or any write over thousands of records with a time bound, the plan lists what each record costs — queries, locks, permission checks, audit rows — multiplies it by the real size, and chooses set-based writes (one insert per entity type, one check per run, one batch of audit events) wherever that product misses the bound.
  • Measure the bound in the first subtask, not the last. A timing test at real size run against a first, thin version of the path shows the cost while changing the design is still cheap.

L-230 — An up-front lock in id order must also take the rows a later write locks as a side effect

  • Date: 2026-10-26
  • Source commits in this repo: .forge/specs/F4-d-migrate-accounts-contacts-findings.md F-002; .forge/plans/F4-d/F4-d-WI-2.1-plan.md ## Notes, “Wave 2 PR review — D16 extended to contacts”
  • Sync target: upstream
  • Synced: pending

Problem observed

F4-d’s write run took every account it would change in one ORDER BY id FOR NO KEY UPDATE statement before writing, so it could not deadlock with the bulk reassignment on accounts. Contacts were left out because no single statement locked several contact rows. The wave PR’s review found that the question is the transaction, not the statement: ContactService.patch making a contact primary locks the contact’s account, then the old primary contact, then the new one, so the run could still deadlock with a person editing the same contacts.

Change made

The run locks, up front and in id order, every contact it merges into or updates and those contacts’ accounts, as well as the accounts it changes directly.

Lesson

  • List every row the transaction will lock, including the ones locked inside the services it calls. An up-front lock in a fixed order prevents deadlocks only if it covers each row any later statement locks — a parent row a child write locks, an old and a new row a swap locks. Read the services’ own locks before deciding a table needs no up-front lock.
  • Compare with every other writer’s order, per transaction. Two writers deadlock when they lock the same rows in different orders anywhere in their transactions, even if each single statement locks only one row.

L-231 — Count bugs by reading their records, not by matching their titles

  • Date: 2026-10-26
  • Source commits in this repo: .forge/design/harness/test-run-cost.md E-6, E-10 and its Draft 4 revision entry (forge-et-harness#931)
  • Sync target: upstream
  • Synced: pending

Problem observed

Draft 1 of the test-run cost design counted flaky and Windows bugs by searching .forge/bugs.md titles for “flaky” and “Windows”, and found 39 and 15. Reading every record with its tracker.yaml status and notes found 47 and 42. Many titles name the failing test, not the platform or the symptom, and the platform is in the Found in line. The title counts also could not say what the bugs were, so the decisions based on them had missed three things:

  • most fixed flaky bugs were races in the tests, which load exposed but did not cause;
  • one flaky test was hiding a product defect;
  • one bug closed as machine overload came back ten days later.

Change made

Draft 4 classified every matching record by operating system, suite, status, week found and cause, and added three decisions for causes no rule covered (F-5, M-8, P-9). The design’s appendix states the method.

Lesson

  • A number that sizes a decision comes from the records themselves. A title search is fine for finding candidates. Before the count goes in a design, read each match’s body and tracker row, and search the Found in and Affects lines as well as the title.
  • Classify by cause, not only by count. “How many” says how large the problem is. “Why” decides what to do about it, and a test race needs a different fix from an overloaded machine.

L-232 — Before a PR closes an owed item, check that no other open or just-merged PR closes it too

  • Date: 2026-10-26
  • Source commits in this repo: forge-et-harness#933 and #934 (F38-b WI-6.1’s close-out written by both); .forge/specs/F38-b-dev-estate-findings.md F-002
  • Sync target: upstream
  • Synced: pending

Problem observed

F38-b WI-6.1 waited on one event, the backend’s next deploy. When it happened, two sessions recorded it: one opened and merged forge-et-harness#933, and another, working on wave 4, put the same close-out in #934 (the spec’s AC-13 tick, the work item’s criteria, the owed.md row closed, an engagement-log entry). Each had read the owed.md row on main before the other’s PR existed. Nothing showed the overlap until GitHub reported #934 as conflicting, and the merge of main then had to keep one copy and delete the other across six files.

Change made

#934 merged main in, kept #933’s text and removed its own copy, and recorded the overlap in the plan’s ## Notes.

Lesson

  • An event that several sessions are waiting on gets closed once. Before a PR ticks a criterion or removes an owed.md row that another work item or session also tracks, fetch origin/main and read the open harness PRs (gh pr list --state open, then gh pr diff <n> on any that touch the same files). If another has closed it, cite that PR instead of closing it again.
  • Close it in the PR that is about it. A close-out that rides along in a PR about other work is the one most likely to be done twice, because nobody looking for that item looks there.

L-233 — The person who runs a manual wave closes it as soon as the record is pushed

  • Date: 2026-10-26
  • Source commits in this repo: feature/F38-b-wave-3 (record pushed 2026-10-23), forge-et-harness#940 (closed 2026-10-26); .forge/specs/F38-b-dev-estate-findings.md F-003
  • Sync target: upstream
  • Synced: pending

Problem observed

F38-b’s manual wave 3 was carried out and fully recorded on 23 Oct, but the person who ran it read the M1 hand-off’s “re-run /forge-deliver” step as something for later. The wave stayed in-progress with no PR for three days. Its record branch fell behind main, wave 4 merged first and could not do the feature’s closing sweep, and the lead found the state only by asking in the team channel.

Change made

The lead’s session confirmed with the person (M2), merged main into the record branch, ticked the criteria, did the closing sweep and merged the wave PR the same day (#940). A change to the M1 hand-off block is listed for a framework follow-up (.forge/owed.md, “F38-b Reflect: framework follow-ups”).

Lesson

  • A manual wave is not done when the run is done. The run ends with the record pushed and /forge-deliver <ticket> re-run straight away, by the person who ran it, so M2’s confirmation and the wave PR follow while the run is fresh. A record branch left open falls behind main and holds up every step that waits on the wave.
  • A hand-off needs an owner on a list the team walks. Until the wave PR opens, the hand-off is visible only on an unmerged branch; an owed.md row naming the person makes an unclosed manual wave findable.

L-234 — A pgrep -f wait loop matches its own command line

  • Date: 2026-10-26 (the incident: 2026-10-20)
  • Source commits in this repo: none — moved here from one developer’s local Claude notes on 2026-10-26
  • Sync target: upstream
  • Synced: pending

Problem observed

A session waited for a sibling session’s browser gate with until ! pgrep -f 'e2e:gate|…'; do sleep 60; done. Claude Code runs a command as zsh -c '<the command>', and that shell’s own command line contains the pattern, so pgrep -f always found a match. The loop ran for 5.5 hours, until another session killed it while cleaning up, and never saw that the gate had ended (in the session fixing BUG-199).

Change made

The wait was rewritten with a pattern that cannot match its own text.

Lesson

  • Bracket one character of each alternative in a pgrep -f or pkill -f pattern: pgrep -f '[e]2e:gate|[b]rowser-gate.mjs|[l]ocal-build-evidence'. The regular expression still matches the target process, but the literal text [e]2e:gate in the shell’s own command line does not.
  • Run a wait loop in the background (run_in_background), so a loop that never ends is visible instead of blocking the session.

L-235 — A check that waits on an outside party with no date moves to the register, so the feature can close

  • Date: 2026-10-26
  • Source commits in this repo: F38-a spec Rev 4 and F38 Rev 29 (harness PR #949); F38 Rev 25 (F38-f’s Sonnet 5.5 call); F38-a’s Reflect (.forge/specs/F38-a-account-baseline-findings.md F-001)
  • Sync target: upstream
  • Synced: pending

Problem observed

F38-a recorded every criterion but one within a week. The last, one call each to Sonnet 5.5 and Haiku 5.5 in dev, needed a Bedrock quota that AWS refused nine times and then put off with no date. No wave gate kind can express “AWS raises a quota”, so the manual wave sat planned for eleven days with its reason only in prose, and the feature stayed open on work nobody on the team could do. F38-f had the same problem with its Sonnet 5.5 call.

Change made

Spec revisions moved each call, with its permission rule and its run sheet, to a row in the cloud-gated register (§C-5, “Sonnet 5.5 and Haiku 5.5 answer one call each in dev”), owned and re-checked weekly. The wave left the tracker, and F38-a closed the same day on what it had recorded.

Lesson

  • When a criterion waits on an outside party with no date (a cloud provider’s quota, another team’s change), move it by spec revision to the team’s walk-list for outside waits (here the cloud-gated register), with the run sheet and the condition that starts it, and close the feature on what the team controls. A feature held open on such a wait hides finished work and blocks nothing it should.
  • Decide this at the first refusal, not after the wait has run for days: a wait with no date that is still open at the next session is the signal.

L-236 — Re-read a gated plan’s target files at dispatch, because other PRs can deliver part of it while the gate holds it

  • Date: 2026-10-26
  • Source commits in this repo: .forge/specs/F38-d-pipelines-first-deploy-findings.md F-001; .forge/plans/F38-d/F38-d-WI-4.1-plan.md Rev 1; altrium-io/forge-et-be#300
  • Sync target: project-only
  • Synced: pending

Problem observed

F38-d WI-4.1’s plan, approved on 2026-10-19, listed four task-definition values as its first four items. Its wave waited three days on a gate (F38-b’s wave 2). Meanwhile forge-et-be#300 set exactly those four values in .aws/td.dev.json, and three other PRs added keys to the same file. #300 recorded nothing in the harness, so the plan, the wave’s opening prompt and the harness all still described the four values as WI-4.1’s work. The plan’s stop rule, which compared the file’s blob with the one read at drafting, caught it, but only because the orchestrator re-read the file before dispatching.

Change made

The lead re-approved the list as items 5–10 (WI-4.1 plan Rev 1) before the agent was dispatched.

Lesson

  • A plan approved before its gate opened is a dated observation of its target files. At dispatch, re-read each file in its ## Files to Modify on the trunk (git log <approval date>.. origin/<trunk> -- <file>); a commit since approval means the plan is checked against it before an agent starts, not by the agent mid-run.
  • The longer the gate, the likelier the drift. A file that other features also change (a task definition, a shared config) is the one to check first.

L-237 — Editing a merged PR’s description starts a CI run on it; cancel the run

  • Date: 2026-10-26
  • Source commits in this repo: .forge/specs/F38-d-pipelines-first-deploy-findings.md F-003; environments-and-identity.md §4 “F38-d — the dev deploy pipelines, checked”, AC-12
  • Sync target: project-only
  • Synced: pending

Problem observed

F38-d WI-7.1 added a missing line to the descriptions of three merged app-repo PRs (forge-et-be#275, forge-et-fe#298, forge-et-pwa#91), on the lead’s approval. Each edit started a PR validation run on the merged PR’s old head (40352469741, 40352542448, 40352553328): every app repo’s pr-validation.yml runs on pull_request edited, so that a retitle can clear the PR-title lint, and GitHub sends the event for a closed PR too. A run on a merged PR checks nothing that can still change, and spends Actions minutes.

Change made

The three runs were cancelled within a minute (gh run cancel <id> --repo altrium-io/<repo>).

Lesson

  • After editing a merged PR’s title or description in an app repo, cancel the run it starts. Find it with gh run list --repo altrium-io/<repo> --workflow "PR validation" --event pull_request --limit 3; its headBranch is the merged PR’s branch.
  • Prefer a PR comment to a description edit on a merged PR where a comment says the same thing, because a comment starts no run. Edit the description when a check or rule reads the description itself (AC-12’s Browser gate: and “Shyamin Ayesh was told” lines).

L-238 — A list’s last-good snapshot held for one mount is lost when opening a record unmounts the list

  • Date: 2026-10-27
  • Source commits in this repo: .forge/bugs.md BUG-267 (the Leads list, fixed in forge-et-fe#345), BUG-270 (the account list, fixed in forge-et-fe#349) and BUG-273 (the contact list, on main once forge-et-fe#337 added its contact page; fixed in forge-et-fe#356); BUG-278 (the Users list, fixed in forge-et-fe#356 by one shared hook, src/lib/hooks/useLastGoodSnapshot.ts, which all four lists now use); BUG-280 (the email templates list, moved onto the same hook in forge-et-fe#356); BUG-281 (the Roles list, fixed in forge-et-fe#375 by reading the cached rows, since its one unpaged key does not fit the hook)
  • Sync target: upstream
  • Synced: pending

Problem observed

The Leads and account lists keep the last read that produced rows in a useRef snapshot, which their stale state (a failed refresh over the last good rows, coding-standards §3.2) shows. A record’s page is a sibling route of its list (leads/:id, accounts/:id), so opening a record unmounts the list and drops the ref. When the list’s refresh had failed before the user opened a record, TanStack v5 kept the key at status: 'error' with its data; on return the new mount had no snapshot and no fresh data, so the list showed the error panel with no rows. The rows were still in the query cache. A reviewer found it by reading the code (frontend-reviewer, forge-et-fe#344).

Change made

useLeadsList (forge-et-fe#345) takes the key’s own cached data — query.data that is not placeholder data, with rows, not a page past the last — as the snapshot when the ref is empty. The account list’s copy of the gap is BUG-270.

Lesson

  • A hook’s ref lasts one mount; the query cache outlasts it. When a list derives a view from state kept in a ref, ask what the view is after the list unmounts and mounts again with the cache unchanged — a record page on a sibling route, Back from it, a tab switch that unmounts the screen.
  • Fall back to the cache, not to the error. A key in error with data still holds its last good rows; read them before showing an error panel with nothing in it.
  • Test the return trip with the app’s gcTime: a list whose refresh failed, a record opened and closed, and the cached rows expected under the stale notice. The test client’s gcTime: 0 drops the key on unmount and hides the defect.

L-239 — A place that collapses with :empty is kept open by any node a filler renders, an invisible one included

  • Date: 2026-10-27
  • Source commits in this repo: .forge/bugs.md BUG-012 (a filler that renders null still drew its wrapper) and BUG-269 (Approve & send’s toast nodes inside the lead heading row’s actions group, fixed in forge-et-fe#349)
  • Sync target: upstream
  • Synced: pending

Problem observed

The CRM’s record places (LeadActionsPlace, AccountPanelPlace and the others) take no room when nothing is in them, through :empty { display: none; } (BUG-012). Approve & send hosts its outcome toast for a role holding email.manage and lead.manage whether or not the button shows, and src/ui’s Toast renders two nodes — a visually hidden live region and a closed [popover] — so on an archived or converted lead, where the button is hidden, the actions group stopped being :empty once the action’s chunk loaded. The group became a zero-width item in the heading row, added one gap, and Edit and Restore moved left by it. Nothing on screen was in the group, so a look at the page did not show why. A reviewer found it by reading the code (frontend-reviewer, forge-et-fe#345).

Change made

The action renders its Toast through createPortal(…, document.body) (forge-et-fe#349). The popover is in the top layer and the live region is out of flow, so moving them out of the group changes nothing else on screen.

Lesson

  • :empty counts nodes, not what is drawn. A visually hidden live region, a closed popover and an empty wrapper div each keep a place open. A filler that renders into a place that collapses with :empty renders no node at all when it shows nothing.
  • Render out-of-flow companions outside the place. A toast, a live region or a dialog a filler owns goes through a portal to document.body (or into a host the screen owns), not beside the filler’s button.
  • Test the place’s emptiness after every chunk has loaded, for each case where the filler shows nothing: toBeEmptyDOMElement() on the group, not only “no button”.

L-240 — A wait loop’s pattern can match another shell that names the command it waits for

  • Date: 2026-10-28
  • Source commits in this repo: the git-conventions.md wait-loop rule on chore/test-run-cost-phase-1-rest
  • Sync target: upstream
  • Synced: pending

Problem observed

A session waited for another session’s browser gate to end, then started its own, in one background shell: until ! pgrep -f '[e]2e:gate' …; do sleep 30; done; pnpm e2e:gate --full --push. The bracket stops the pattern matching its own text (L-234), but the shell’s command line also held pnpm e2e:gate --full --push, the command it would start, which a pattern can match. The loop never ended; the other gate had finished hours earlier, and the gate was started by hand at 01:29.

Which process matched was not recorded. macOS pgrep leaves out itself and its ancestors (man pgrep, -a), so the waiting shell alone does not match there, as a test of the same loop shapes on 2026-10-28 showed; Linux pgrep leaves out only itself. The likely match on the Mac is another shell of the same session whose command line named e2e:gate. A first fix suggested ps -ax -o command | grep -c '[n]ode .*e2e:gate', but ps leaves out no ancestor, so that check matches the waiting shell itself whenever its command line holds node before e2e:gate (a fresh-context review of the rule found it, 2026-10-28).

Change made

git-conventions.md § The test suites run locally says a wait loop matches only the real process: a bracketed pattern, anchored on the program that runs the command when the same shell starts it after the loop (pgrep -f '[n]ode .*e2e:gate'), never ps … | grep, and checked once by hand while nothing is running.

Lesson

  • Any text in a shell’s command line can match, the waiting shell’s own included. Bracket the pattern and anchor it on a field only the real process has (node …e2e:gate); prefer pgrep to ps … | grep.
  • Check a wait loop once by hand while the awaited process is not running: it must report “not running”.

L-241 — A launchd job with ProcessType Background runs about four times slower on Apple Silicon

  • Date: 2026-10-28
  • Source commits in this repo: 678c19a7 (.claude/lib/nightly/install.sh, run-nightly.py)
  • Sync target: upstream
  • Synced: pending

Problem observed

The nightly full run passed every suite when started by hand on 2026-10-27. Its first scheduled night, started by its LaunchAgent, hit every suite’s time limit: the backend build stopped at 60 minutes against 19, the capture app’s Vitest at 20 against 3. The agent’s ProcessType was Background, which confines the job to the efficiency cores. One CPU benchmark took 12.8 s as a Background launchd job and 3.3 s as an Interactive one. A second defect hid the cause: killpg answered EPERM (one member of the group could not be signalled), which the runner did not expect, so a suite stopped at its limit was reported “could not run”.

Change made

install.sh writes ProcessType Interactive; kill_group never raises on EPERM, with a self-test case.

Lesson

  • A job is not proved until it has run the way it will run. A hand-started run proves the code, not the scheduler’s priority, environment or permissions; check the first scheduled run before relying on it.
  • Measure a priority setting with a two-line benchmark under each value rather than reading the docs: launchd’s descriptions of Standard and Background are vague, and the measurement took seconds.
  • On macOS, killpg can answer EPERM for a group that is partly stopped; catch it with ProcessLookupError, never let clean-up turn a result into an error.

L-242 — An element every screen has needs one shared component and a scan that refuses a hand-built one

  • Date: 2026-10-28
  • Source commits in this repo: .forge/bugs.md BUG-163 (every screen title but Leads at the browser’s default h1), BUG-164 (the Leads title row on a baseline), BUG-165 (a description under the title on one screen only) and BUG-168 (table header rows that differed from page to page), all fixed in forge-et-fe#356
  • Sync target: upstream
  • Synced: pending

Problem observed

Each CRM screen built its own title row and styled its own table header. Nothing styled h1 globally (the shared base.css must stay identical with the capture app’s), so most screens set only margin: 0 and their titles rendered at the browser’s default of about 26–32px bold; Leads, the one screen thought right, measured 26px too. Title rows aligned differently, one screen in six had a description, and five tables’ header rows differed from the Users table’s even after they all moved onto shadcn’s Table, through classes each screen added. A manual test pass found four separate bugs with one cause, and each screen had passed its own review, because each looked reasonable on its own.

Change made

forge-et-fe#356 added src/ui’s PageHeader and PageTitle, moved every screen onto them, and added src/app/pageTitleOnly.test.ts, which fails on a raw <h1> in src/features. Design-system Rev 74 (forge-et-fe#355) did the same for tables, one set of header and cell classes in src/ui/dataTable.ts, and src/app/tableHeaderStyle.test.ts holds the tables BUG-168 named to it. Design-system Rev 76 states the screen-header rule.

Lesson

  • An element that every screen has — the title row, a table header, an empty state — is one shared component from the first screen that needs it, not a pattern each screen repeats from the design system’s words.
  • Enforce it with a scan test, as shadcnOnly.test.ts and pageTitleOnly.test.ts do: a review of one screen cannot see that it differs from the others.
  • Check such an element by measuring it on every screen at once, the computed size, weight and alignment against one reference screen, not by reading each screen’s code.

L-243 — Code that waits by a clock needs one time base per decision, and a bound that does not read the clock

  • Date: 2026-10-29
  • Source commits in this repo: forge-et-be#333 (12daafcc, ab675c08, 800437ad, 411c1a51, f5e8d156); .forge/specs/F42-bedrock-call-pacing-findings.md F-001
  • Sync target: upstream
  • Synced: pending

Problem observed

F42’s pacer keeps its own window time, clamped so it never runs backwards, while each caller reads the wall clock. The review of the wave PR took a full review and four delta rounds, and each round found one more place where the two were mixed: a give-up instant taken from window time; a deadline fixed by the clock at asking, which a step back during the sleep still stretched; a background call’s deadline started at the window’s instant; and the time left of a call recomputed from the clock after a step. Each fix was small, but each was written for the case the review had named, so the next round found the neighbouring one. The bound at stake, maxWait, is what the queue’s visibility timeout is computed from.

Change made

Each decision in AiPacer and AiCallRunner now reads one stated time base; a waiting call’s total sleep is counted apart from the clock and capped at maxWait; a background call’s deadline starts from the runner’s own clock; and the time left of a call is capped at its deadline. Specs step a fake clock back an hour before the call, during the sleep and during an attempt.

Lesson

  • Give each time decision one time base, and say which in its Javadoc. Mixing an internal monotonic time with the wall clock in one comparison is where every one of these defects came from.
  • A bound that must hold is also counted from what the code itself did — the time it asked to sleep, the attempts it made — never only from clock readings, which a clock step can move either way.
  • Test the step in every phase of the wait (before the call, during a sleep, during an attempt), not only the one a reviewer named; on a fix round, fix the rule, then check its neighbours.

L-244 — A regression test written from a reviewer’s recipe can pass on the old code

  • Date: 2026-10-29
  • Source commits in this repo: forge-et-be#333 (ab675c08); .forge/specs/F42-bedrock-call-pacing-findings.md F-002; BUG-403’s fix, forge-et-be#409 (three rows passed on the pre-fix commit because a fixed list of allowed values already refused the input; they were moved to free-text fields)
  • Sync target: upstream
  • Synced: pending

Problem observed

A review of F42’s pacer suggested a spec for its finding: drain the window an hour ahead, then make a call. The drain removed the start that kept the window full, so the call found a free slot and was granted at once on the unfixed code as on the fixed code; the spec could not fail. The implementer found this only because the brief asked that every new spec be shown failing on the pre-fix commit first.

Change made

The spec that went in steps the real clock instead (take the only slot an hour ahead, then step back), and it failed on the old code with the wait the finding described. Every later fix round of the PR recorded the assertion that failed before the fix.

Lesson

  • Run each new regression test on the commit before the fix and record what failed, in the commit or the report, whoever designed the test. A reviewer’s suggested test is a starting point, not a proof.
  • Put “show it failing first” in every fix brief given to an implementer, so the check does not depend on the implementer thinking of it.

L-245 — A spec that changes shipped code needs every caller read before it is drafted

  • Date: 2026-10-30
  • Source commits in this repo: .forge/specs/F20-l-findings.md F-001; the F20-l spec’s six review passes (spec PR #1016)
  • Sync target: upstream
  • Synced: pending

Problem observed

F20-l’s spec added a contact’s other email addresses to code that already shipped. Six reviewer passes each found one more caller the author had not read:

  • F11-d’s trimmed email key;
  • the account panel opening the contact form from a list row, which would have wiped the other addresses;
  • getContactItem narrowing the contact page’s record;
  • the contact picker sharing the list’s q;
  • F4-d’s re-check.

Each find meant another revision and another pass.

Change made

A sweep of every writer, reader and opener of each surface the spec changes found the rest in one pass. The spec then listed them under ## Constraints and Dependencies.

Lesson

  • Before drafting a spec that changes shipped code, list every caller of each surface it changes: each writer, reader and opener, found by git grep on main. Write the list into ## Constraints and Dependencies, naming the command, so the reviewer checks the list instead of discovering it.

L-246 — A gate’s exit status gets its own line before any outward step that depends on it

  • Date: 2026-10-30
  • Source commits in this repo: .forge/specs/F20-l-findings.md F-002; forge-et-fe#363 (6e88c6df, d5340cc2)
  • Sync target: upstream
  • Synced: pending

Problem observed

The orchestrator marked forge-et-fe#363 ready with gitleaks … | tail -1 && gh pr ready …. Gitleaks printed leaks found: 1. The chain tested tail’s exit status, so gh pr ready ran anyway, and the full Fast lane then failed on the same finding.

Later in the same session, git push -q … | tail -1 hid whether a push had reached GitHub.

Both are the shape L-043 and .claude/CLAUDE.md § Boundaries forbid for evidence. Here the cost was an outward action, a PR marked ready with a red scan, not only a wrong report.

Change made

The scan was re-run on its own line with echo "EXIT=$?". The false positive was cleared by a reviewed .gitleaksignore fingerprint. The PR was re-recorded before merging.

Lesson

  • Run a gate alone and read its EXIT before any step that acts on the result: gh pr ready, a push, a merge or a record. Never join the gate and the action with && behind a pipe, whose status is the last command’s.
  • A gitleaks ignore comment must not quote the code it explains. The rule matches the comment too, and the full-history scan CI runs then fails on the ignore file itself.

L-247 — A fix round after a review needs its own delta review, even when the fixes are only tests

  • Date: 2026-10-30
  • Source commits in this repo: .forge/specs/F20-l-findings.md F-003; forge-et-be#341 (6d14722d → a3aab0a1); forge-et-fe WI-3.2 (d960467e → 556bcba5)
  • Sync target: project-only
  • Synced: pending

Problem observed

Two fixes an implementer made, after a review or after a run, were themselves wrong:

  • forge-et-be#341: a new 1,001-row assertion selected rows by a filter that was not unique to the run. The build record’s single retry would then read both attempts’ rows and could never pass.
  • WI-3.2: a focus-ring colour check read the outline colour during the button’s CSS transition.

Both were test-only. The first was caught by the delta review of the fix commits; the second by the orchestrator’s live run.

Change made

Each was sent back to its implementer:

  • the 1,001-row assertion selects by the run’s own ids;
  • the colour read is polled until it settles.

Each fix was reviewed or re-run before the record was written.

Lesson

  • Review every fix round as a delta, test-only fixes included (/forge-review-pr step 9). Check in each new test the things a first pass checks:
    • data unique to the run;
    • no exact count over shared rows;
    • nothing read while it is still changing (a transition, an animation, a pending request).

L-248 — A browser suite that opens a fresh context per test pays the dev server’s whole module graph in every test

  • Date: 2026-10-30
  • Source commits in this repo: .forge/bugs.md BUG-218, BUG-198, BUG-129, BUG-013, BUG-183, BUG-226 (forge-et-fe#365, forge-et-pwa#103)
  • Sync target: upstream
  • Synced: pending

Problem observed

On a 16-core Windows laptop a full pnpm e2e:gate (5,886 tests) rarely passed: each run had a different handful of tests fail on their first attempt, mostly size-matrix pages that had not appeared within the 5-second ready wait and WebKit page checks that ran out their 30 seconds. Six bugs were filed for them over three weeks (L-175). Fewer browsers did not fix it: 8, 6 and 4 browsers gave 4, between 1 and 20, and 5 flaky tests. A watcher probing the dev server every second through a full gate saw no answer slower than 0.65 s, so the server was not stalling.

Playwright opens a new browser context for every test, with an empty cache. Vite’s dev server sends the app unbundled: a page took some 270 requests, each a source module the browser parsed and compiled again, test after test. That was most of the gate’s own CPU load, and under it a page now and then missed its wait.

Change made

The suite runs against a development build (vite build --mode development with NODE_ENV=development, so the stub sign-in and React’s development build are in it) served by vite preview through the same /api proxy. A cold page load fell from 1.3 s to 0.8 s with some 70 requests, and three full gates in a row passed with a full backend build alongside, with no size-matrix test flaky. A test that named a module by its source path (to import it, hold it or abort it) now asks the build’s manifest for the chunk, and a wait for a lazily loaded component also waits for the stylesheets Vite’s preload helper waits for, by the helper’s own <link>.

Lesson

  • Run a browser suite against a build, not the dev server, once it opens a fresh context per test and has more than a few hundred tests. Keep it a development build when tests rely on development-only code.
  • Before lowering parallelism for a load-flaky suite, measure what one test’s page load costs (requests, time to ready, on a quiet machine). Fewer workers trade time for a lower peak; a cheaper page lowers both.
  • A test that names a module by its source path is tied to the dev server. Name it through one helper that asks the server where the module is served. frontend-reviewer’s stack-specific checks point here.
  • In a build, lazy() resolves only after the chunk’s stylesheets have loaded, later than the chunk’s own import() does. A test that waits for a lazy component by importing its module also waits for those stylesheets, and must not add stylesheet links of its own, which change the cascade.

L-249 — A PATCH whose null means “leave unchanged” needs a stated way to remove each optional value

  • Date: 2026-11-02
  • Source commits in this repo: .forge/bugs.md BUG-283 (forge-et-be#345, forge-et-fe#375; F1-a Rev 12, F1-b Rev 12)
  • Sync target: upstream
  • Synced: pending

Problem observed

The account and contact PATCH requests read a null member as “leave unchanged”, because the request records cannot tell an absent member from an explicit null. F1-a specified that rule and named one consequence for contacts: detaching a contact from its account got its own flag (detachAccount), because accountId: null would read as “unchanged”. Nobody asked the same question of the account’s optional fields. The edit form could not send a removal, so it refused an emptied Website or Est. LTV instead (F1-b FR-C2, Rev 10), and the lead then decided that those values must be removable (BUG-283).

The two requests now answer it differently: the contact form sends an emptied text field as "", and the account patch takes a clear list of field names, which also covers the Est. LTV number.

Change made

F1-a Rev 12 gives the account patch an optional clear list; F1-b Rev 12 has the edit dialog send an emptied field in it. An absent or null member still means “leave unchanged”, so no caller written before it changes.

Lesson

  • When a spec defines a PATCH whose null means “leave unchanged”, it lists every nullable field and says how each is removed — an explicit form (a clear list, an empty string for text, a flag), or “cannot be removed” with the reason. A field the form lets the user empty and the patch cannot remove becomes a refusal in the UI and, later, a defect.
  • Reuse the convention a sibling resource already uses before adding a second one. Two now exist (the contact’s "", the account’s clear). A new patch that needs removal picks one of them and says why; clear is the one that also works for numbers and dates.
  • spec-reviewer and plan-reviewer can catch it: an FR that adds a nullable field to a PATCH without saying how it is removed is a finding.

L-250 — A hook whose work grows with the repo outgrows its fixed timeout without anyone seeing it

  • Date: 2026-11-03
  • Source commits in this repo: .forge/bugs.md BUG-322; .claude/settings.json hooks.Stop; .claude/hooks/README.md § Stop hooks — foreground and background
  • Sync target: upstream
  • Synced: pending

Problem observed

Four Stop hooks were registered in the foreground with a 5-second timeout. The reference-graph generator grew with the harness until it took 5.6 s on its own, and the usage hooks read a session transcript and a global usage file that grow with use. In 50 sessions, 1,001 of 1,005 Stop records were timeouts, so every turn ended about 5 s late and the generated mirrors were rarely rebuilt. Nothing showed it: Claude Code ends a timed-out hook quietly, and the mirrors were still there from an earlier run, only stale. The hooks README also said the hooks ran in registration order; Claude Code starts an event’s hooks together, which is why the turn waited about 5 s and not 20.

Change made

The four hooks run with "async": true and a 60-second timeout, so the turn no longer waits for them; the hooks that print a systemMessage or can block stay in the foreground. governance-guards.test.sh checks the wiring, and the README describes how Claude Code runs the hooks.

Lesson

  • A hook that only writes local files and takes more than a second or two runs in the background ("async": true); a hook whose output the turn needs, or that can block, stays in the foreground. No hook relies on another of the same event having finished.
  • A fixed hook timeout is a size limit on the work the hook does. When a hook’s input grows with the repo or with use, measure it against its timeout when it is added and when its input changes shape, and look for hook_cancelled records with timedOut: true in the session transcripts — the only place a quiet timeout shows.

L-251 — A port check reads lsof’s output for each port, never its exit status over several

  • Date: 2026-11-03
  • Source commits in this repo: .forge/plans/F43/F43-WI-2.3-plan.md ## Notes (“O2 and O3 on port 8081”), .forge/plans/F43/F43-WI-2.3-test-verify.md § O2 and O3
  • Sync target: upstream
  • Synced: pending

Problem observed

Before F43 wave 2’s browser runs, the orchestrator waited for ports 5173 and 8080 with ! lsof -nP -iTCP:5173 -iTCP:8080 -sTCP:LISTEN. lsof exits 1 when any one of several -i selections finds nothing, so with 5173 free and another session’s backend on 8080 the check read both as free. The run’s own bootRun then failed with “Port 8080 was already in use”, the health poll on localhost:8080 was answered by the other session’s backend, and the whole browser run tested that backend’s code. Two of its failures looked like a defect in the wave (a 503 where the wave answers 429).

Change made

The run was discarded and repeated with the backend on 8081 (SERVER_PORT=8081, ET_BACKEND_PORT=8081, as forge-et-fe’s e2e/README.md describes for a second backend). The checks now test each port alone by lsof -nP -tiTCP:<port> -sTCP:LISTEN output, and the readiness poll also waits for the started backend’s own Started … in line and stops if its process has died.

Lesson

  • Test each port on its own, by output: [ -n "$(lsof -nP -tiTCP:<port> -sTCP:LISTEN)" ]. Never read the exit status of one lsof over several ports.
  • A readiness poll proves the process you started is ready, not that something answers on the port: check that its PID is alive and that its own log shows it started, then poll the port. A port shared by parallel sessions can be answered by someone else’s server.

L-252 — Muted normal-size text takes --et-text-secondary, never a palette step or an opacity

  • Date: 2026-11-03
  • Source commits in this repo: .forge/bugs.md BUG-301 (the contact page’s No phone number, --et-neutral-500), BUG-298 (the lead’s Customer card’s An account you cannot open, --et-neutral-500), BUG-307 (the timeline’s pressed All chip count, opacity: 0.7); fixed in forge-et-fe#390; checked by frontend-reviewer dimension 6
  • Sync target: upstream
  • Synced: pending

Problem observed

Three pieces of muted text on three screens failed axe’s colour contrast check on main after the UI revamp’s colour layer (theme-revamp.css). Two used the palette step --et-neutral-500, which the revamped theme sets to 4.09:1 on a white card. The third faded the text with opacity: 0.7, which gave 3.8:1 on the pressed chip’s primary fill. Each looked muted and passed its unit tests; only the browser’s axe scan, in the theme the page actually loads, measured them. tokens.css already says that normal-size text needs 4.5:1 and takes --et-text-secondary (BUG-019), but it says so on --et-text-muted, and a palette step carries no such note.

Change made

Both neutral-500 uses became --et-text-secondary (6.16:1 on the card), and the pressed chip draws its count at full opacity, told apart by weight (5.91:1).

Lesson

  • Muted text under 24px (or under 18.66px bold) takes --et-text-secondary. WCAG’s large text is 18pt, or 14pt bold, in CSS pixels 24px and 18.66px. A palette step (--et-neutral-*) and --et-text-muted are for large text and non-text marks, which need only 3:1, and a theme may set them to anything that clears 3:1.
  • Never mute text with opacity. The ratio then depends on the fill behind it, so text that passes on one background fails on another (a pressed chip, a hover row, a tone band).
  • A colour change is proved by the axe scan in the browser, in the theme the page loads, not by the token’s value in tokens.css.

L-253 — A design rule that changes every list names the lists from the code, not from memory

  • Date: 2026-11-03
  • Source commits in this repo: .forge/bugs.md BUG-334; .forge/design/ui/design-system.md Rev 83 and Rev 85
  • Sync target: upstream
  • Synced: pending

Problem observed

Design-system Rev 83 (2026-11-02) changed every data table’s re-read: skeleton rows in place of the kept rows. Its scope named the specs that carried the change (F1-f, F11-b, F26-f) and “each list screen’s table”, and the code changed Accounts, Contacts, Leads and the Pricing tabs. The Users list (F5-c), the first list built, was not named and kept its old rows; a day later the developer found the difference by using the screens (BUG-334).

Change made

The Users list now draws skeleton rows as Contacts does (forge-et-fe#392). Design-system Rev 85 records that Users follows Rev 83 and why Roles, which sorts a list it already holds, has nothing to show a skeleton for.

Lesson

  • When a design rule changes every list (or every dialog, every form), list the screens from the code before writing the scope: search for the component or pattern the rule changes (here git grep -l "view.kept" src/features and every *Table.tsx), and name each one in the revision’s scope as changed or as not applying, with the reason. A list written from memory leaves out the oldest screen, which predates the pattern the others share.
  • Check the result the same way: after the change, the same search finds no screen still on the old form.

L-254 — A UI pattern has one look across the product; a screen never takes its own variant

  • Date: 2026-11-05
  • Source commits in this repo: .forge/design/ui/design-system.md Rev 84 and Rev 91; forge-et-fe#403 (the folder column, the inbox list and the sidebar on one selected look); .forge/bugs.md BUG-333 (the Weekly prices filters, a variant of the filter pill, put on the Leads pills’ look by forge-et-fe#392, design-system Rev 85); BUG-360, BUG-361 and BUG-364 (the Email search box’s width, its filters’ width and its action order, each its own variant; forge-et-fe#435, design-system Rev 101); checked by frontend-reviewer dimension 28
  • Sync target: upstream
  • Synced: pending

Problem observed

The CRM marks a selected row with a gold bar in three places: the sidebar’s current page, the Email list’s open message and the Email folder column’s current folder. Each was built at a different time with its own values. The list row first had a square border and was reworked to the sidebar’s look (Rev 84). The folder column, built next, kept a square 1px border while its CSS comment said it matched the list row. Bringing it in line on a shorter row then showed that the shared 12px corner left the bar’s ends outside the fill, so the lead chose a 6px corner and required it on all three (Rev 91). Each variant was found by eye after the screen was built, and each cost a design-system revision and a rework PR.

Change made

The three selected looks now share one set of values, and mailboxTokens.test.ts fails if any of them changes its corner alone. The design system opens with a One look per pattern rule; plans.md’s UI / Design Adherence asks each plan to name the pattern and an existing instance for every visible state it builds; frontend-implementer copies the instance’s values and escalates instead of varying them; frontend-reviewer dimension 28 compares the diff’s values with the pattern’s other instances.

Lesson

  • Before styling a state the design system has a pattern for, find its instances on main and copy their values. Reading the design-system text alone is not enough: the instances carry values the text may not state, such as insets and padding.
  • A pattern changes everywhere or nowhere. A change one screen needs is a design-system revision the lead decides, and the same PR changes every instance and the test that binds them.
  • Bind a shared pattern with one test that reads every instance, so a later change to one of them fails.
  • A comment that says one element matches another is a claim to check against both files’ values.

L-255 — To ask whether an index can serve a predicate, leave the planner only bitmap scans

  • Date: 2026-11-03
  • Source commits in this repo: .forge/bugs.md BUG-289 (ContactAddressLookupIT’s NFR-1(a) plan check); fixed on forge-et-be fix/BUG-289-plan-check-any-index; checked by backend-reviewer § Test isolation
  • Sync target: upstream
  • Synced: pending

Problem observed

ContactAddressLookupIT checked that each branch of F20-l’s address lookup can be served by its address-key index. It ran EXPLAIN with enable_seqscan = off and asserted both index names were in the plan. Now and then on Windows the other-address branch was served by contact_email_contact_id_lower_email_key instead: a full scan of an index that leads with contact_id, with the address as a filter. Postgres 17 and later can remove a UNION’s duplicates with a Merge Append of inputs already in id order, and the query also orders by id, so an index that gives that order competes with the address-key index plus a sort. Which one costs less depends on the statistics of a small table that every test shares. With sorts and hash aggregation also switched off, the wrong plan came out every time, on every table size and statistics state tried.

Change made

The check also switches off enable_indexscan and enable_indexonlyscan. That leaves only bitmap scans, and Postgres builds a bitmap scan only from an index condition. So a branch is served by a disabled scan unless its predicate matches an index. Postgres 18 counts disabled plan nodes before it compares costs, so the address-key indexes win in every state. The test asserts Bitmap Index Scan on <index>, and keeps a case with sorts and hash aggregation off, which fails on the old check every time. A negative control changes the other-address branch to lower(e.email) and asserts that the branch is then served by Bitmap Index Scan on contact_email_contact_id_lower_email_key and that contact_email_address_key_idx is no longer in the plan, so a check that accepted any index would pass on the wrong one.

Lesson

  • enable_seqscan = off alone does not decide which index serves a predicate. An index that supplies an order the plan wants (an ORDER BY, a merge join, a UNION removing duplicates by Merge Append) can serve the branch as a full scan with the predicate as a filter.
  • To ask whether an index can serve a predicate, switch off enable_seqscan, enable_indexscan and enable_indexonlyscan, and assert the Bitmap Index Scan on <index> line. This does not apply when the question is whether an index serves an order: a bitmap scan returns no order.
  • Name the index the requirement names. “Some index serves it, with no sequential scan” passes on an index that only has the column as a later key.
  • Prove the check against an adversary that does not depend on statistics. Switching off the planner’s other ways of doing the work (here enable_sort, enable_hashagg) leaves the wrong plan as the only plan with no disabled nodes, so a check that is not deterministic fails every time.

L-256 — A component test’s wait for the screen a navigation renders needs the page budget, not Testing Library’s one-second default

  • Date: 2026-11-03
  • Source commits in this repo: .forge/bugs.md BUG-329 (leadResearchComposition.test.tsx’s 404 row waited the default second for the list screen after the view handed the lead back, and failed under load on Windows); the same budget was already set, with no bug filed, by LeadsScreenActions.test.tsx’s PAGE_TIMEOUT and the lead composition tests’ LAZY_PANEL
  • Sync target: upstream
  • Synced: pending

Problem observed

A Vitest case removed a person from a lead’s research, got a 404, and checked that the lead view handed the lead back to the list: the router’s location moved to /leads, then the research panel left the page and the list’s notice said why. The last two checks were waitFor calls with Testing Library’s default one-second timeout. React Router 7 applies each navigation in a startTransition, so React keeps the old view on screen until it has rendered the new one, and in a parallel run on a loaded Windows machine rendering the list screen took more than a second. The case failed on expect(element).not.toBeInTheDocument() at 2,085 ms, and passed alone. Nothing in the code raced: the same outcome comes every time, only later. LeadsScreenActions.test.tsx had already met the same wait and given it five seconds (PAGE_TIMEOUT), with that reason in its comment.

Change made

The two waits after the navigation take the page budget, five seconds, as a named constant that says why (forge-et-fe, BUG-329’s fix).

Lesson

  • A wait on what a navigation, a lazy chunk or a large list renders gets a named budget — five seconds for a page, ten for a lazy chunk, as the existing constants use — with a comment naming why the default second is not enough. The default second measures the machine, not the code.
  • Only for an outcome that is certain. First check that the case waits on something the code always does, and that nothing it waits on can arrive in a different order (.forge/test-strategy.md § Flaky Tests, “never lengthen a timeout”). A longer wait on a race only makes the race slower.
  • Prove it by holding the slow step (L-107): make the screen the navigation renders not ready for longer than the default (a component that suspends on a timed promise, which the transition keeps off screen), and show the case fails without the budget and passes with it.

L-257 — A test suite that builds git fixtures takes the git-fixture timeout on its describe, not Vitest’s 5 s default

  • Date: 2026-11-05
  • Source commits in this repo: .forge/bugs.md BUG-350 (browserGateSelect.test.ts’s “selectGate against a repository” suite, fixed in forge-et-fe#425 and copied by forge-et-pwa#112) and BUG-349 (sharedDrift.test.ts’s first describe, same cause; fixed in forge-et-pwa by building the template in a beforeAll and giving the fixture’s hooks and the readBlobs suite the git-fixture timeout); BUG-425 (the same file’s other git-fixture suite, “the browser gate’s selected run”, which BUG-350’s fix did not reach — when one suite in a file hits this, check every suite in the file); BUG-427 (localTestRecord.test.ts’s “Fast lane documentation-only decision” suite, which runs git on the repository itself rather than on a fixture — the timeout is for any synchronous git work, not only fixtures)
  • Sync target: upstream
  • Synced: pending

Problem observed

Two tests in forge-et-pwa’s copy of browserGateSelect.test.ts timed out at 5,000 ms in the local test record four runs out of four on Windows, and passed when the file ran alone. Each builds a git repository fixture (createGitFixture, synchronous git processes) and runs the selection over it. The record runs many Vitest workers at once, each spawning git, and that fixed amount of work took longer than five seconds. The repo’s other git-fixture suites already set { timeout: 60_000 } (or 120 s) on their describe; this one had kept Vitest’s default. BUG-349’s sharedDrift.test.ts has the same shape: its first test pays for building the template workspace under the default, while its later describes set 60 s.

Change made

The suite takes { timeout: 60_000 } on its describe, with a comment naming why (forge-et-fe#425). Nanndish decided on 2026-11-05 that this is a fix, not a wontfix, and not the lengthened timeout that .forge/test-strategy.md § Flaky Tests bans.

Lesson

  • A describe whose tests build git fixtures (or any other fixed, synchronous setup measured in seconds) sets the git-fixture timeout, 60 s, as its siblings do. The default 5 s measures the machine, not the code.
  • Only where nothing races. The ban on lengthening a timeout is about races, which a longer wait only makes slower. A synchronous fixture has no race, and a hung git blocks the worker whatever the limit, so the longer limit hides nothing. Check both before raising one.
  • Look at the suite’s first test. A shared fixture built lazily by the first caller charges its cost to that test alone (BUG-349).

Update — 2026-11-06

For a fixture shared by a whole file and built lazily, build it in a beforeAll with the git-fixture timeout instead of raising the timeout of whichever describe happens to call it first. The build then belongs to no test, every describe in every file that uses the fixture is covered at once, and the tests keep the timeout their own work needs. BUG-349’s registerWorkspaces() (forge-et-pwa src/test/scripts/sharedDriftFixture.ts) does this.

Three more things BUG-349’s loaded runs showed:

  • Moving the build is not enough on its own. Copying the built workspace for a case and running git in the copy is git-fixture work too: at a load of 1.00 the copy alone took about 10 s. A describe whose cases copy the fixture takes the git-fixture timeout like one that builds it.
  • A case that needs only a folder makes an empty temporary folder, not a copy of the git fixture. The shared-file list test went from 10 s under load to under 0.1 s.
  • A describe’s timeout does not reach its hooks. Vitest gives every beforeAll, beforeEach, afterEach and afterAll its hookTimeout, 10 s by default, whatever the describe sets; a hook that builds or deletes git fixtures takes the timeout as its last argument (afterEach(fn, 60_000)).

Update — 2026-11-18

60 s is not enough for a large fixture on Windows. BUG-471: localTestRecord.test.ts’s W-5 test builds a fixture of about 40 commits, one git process per step. It had 60 s, and on Windows 11 it took 79 s alone and about 99 s per attempt inside the local record, so no capture-app PR could be recorded on that machine. It now has 180 s, nearly twice the slowest time measured (forge-et-fe#580, forge-et-pwa#168). A test whose fixture builds dozens of commits takes a limit set from its slowest measured Windows time with room to spare, or builds the fixture with fewer git processes.

L-258 — A timing fixture must put most rows on the branch production rows take

  • Date: 2026-11-06
  • Source commits in this repo: .forge/specs/F11-g-ai-lead-ranking-findings.md F-002; .forge/owed.md “Make the Leads list’s priority filter and sort fast at 20,000 leads”; forge-et-be 5114630a (the realistic fixture), forge-et-be#372
  • Sync target: upstream
  • Synced: pending

Problem observed

F11-g’s list computes each lead’s ranking-input fingerprint in SQL, so a priority filter or sort costs one fingerprint per lead. The work item’s 20,000-lead timing fixture had no research rows: every lead took the no-research branch, and the findings hash — the expensive part — never ran. The three timed requests also carried status=new, a quarter of the leads. All three came in under the 300 ms target (51–284 ms) and the plan’s success criterion was ticked. The wave PR’s adversarial review asked what the fixture exercised. Re-timed with research rows and current rankings on most leads and no status filter, the same requests took 2.2–4.4 s.

Change made

The fixture was rewritten to carry done research rows with findings on 90% of the leads, and the requests were re-timed without the status filter. The gap went to owed.md with the measurements and the design options, as the plan directed for a median over the target.

Lesson

  • A performance fixture puts most rows on the branch production rows take. Before timing, name the code’s expensive branch and check the fixture reaches it for most rows — here, research done with findings. A fixture that only exercises the cheap branch measures the cheap branch.
  • Time the requests users make, unnarrowed. A filter that cuts the rows (a status, an owner) shrinks the work the query does; time the unfiltered request and the worst filter as well.
  • A plan’s timing criterion names the data shape, not only the volume: “20,000 leads, 90% with research done and findings, no status filter”.

L-259 — A comment that says why code works around a library cites what the installed library does

  • Date: 2026-11-06
  • Source commits in this repo: .forge/specs/F11-g-ai-lead-ranking-findings.md F-004; forge-et-fe 7766f337 (the fix and its first comment), 0d54be52 (the comment corrected), forge-et-fe#428
  • Sync target: upstream
  • Synced: pending

Problem observed

The Priority filter’s popover got a key handler so Tab past the last checkbox closes it and moves focus on. The handler’s comment said that without it the browser’s Tab “would leave the page with the popover still open”. The delta review read the installed @radix-ui/react-focus-scope: the non-modal popover’s scope has loop: true, so Tab wrapped inside the popover; only WebKit’s Option+Tab, which the scope ignores, left the page. The code was correct and its explanation wrong — and a reader trusting it, removing the handler, would have got looping, not an exit.

Change made

The comment was rewritten from the installed source, naming the loop prop, the Alt exclusion and the order in which Slot calls the two handlers.

Lesson

  • Before writing why a workaround is needed, read the library at the version the lockfile installs (node_modules/<package>, or the jar’s sources) and cite the prop or line that makes it needed. Memory of a library, or its documentation for another version, is a guess.
  • A reviewer of such a comment checks it the same way. A comment that misstates a library’s behaviour is an Important finding: it invites the next change to break the code it explains.

L-260 — A lock taken for a detached run is released by the detached script itself

  • Date: 2026-11-06
  • Source commits in this repo: .forge/specs/F11-g-ai-lead-ranking-findings.md F-006; .forge/plans/F11-g/F11-g-WI-1.4-plan.md ## Notes (the agent’s wait)
  • Sync target: project-only
  • Synced: pending

Problem observed

The orchestrator took the per-feature machine lock (worktrees/<ticket>/.heavy-run.lock) with mkdir in one Bash call, then started its browser runs from a detached script in the next. The script released the per-port lock it took for each run but never the machine lock, and no later call removed it. The e2e agent’s finalize, waiting on the same lock, retried for 90 minutes until the lock counted as abandoned.

Change made

None in code: the agent took the stale lock by the abandonment rule. Later runs in the same session took no lock outside the script that held it.

Lesson

  • Whoever starts a detached run takes and releases its locks inside the detached script, with trap 'rm -rf <lock>' EXIT placed right after the mkdir, so a failure, a kill or an early exit still releases it.
  • Never take a lock in one tool call for work another call runs: the release then depends on a call that may never come.

L-261 — A test starts once what it drives has rendered, not on a state that already holds before the first load

  • Date: 2026-11-06
  • Source commits in this repo: BUG-337 (.forge/bugs.md); forge-et-fe branch fix/BUG-337-held-url-state-tests
  • Sync target: upstream
  • Synced: pending

Problem observed

Three forge-et-fe hook tests (pricingUrlState.held.test.tsx, activitiesUrlState.held.test.tsx, standardsBookUrlState.held.test.tsx) rendered a router whose probe component captured the hook’s update function into a module variable and rendered null. Each test began with await waitFor(() => expect(router.state.navigation.state).toBe('idle')). React Router never sets navigation.state to loading during the router’s first load (7.18.5, handleLoaders: shouldUpdateNavigationState = !isUninterruptedRevalidation && !initialHydration), so the wait passed at once, before router.state.initialized was true and before the probe had rendered. On a loaded Windows machine the test then called the module default, or the previous test’s function, which reached no router, and failed with expected 'idle' to be 'loading'. Delaying the first loader call by 100 ms failed all five tests every time.

Change made

Each probe renders a marker element, and the setup awaits it with screen.findByTestId('probe') before the test acts, as useListSearchParams.test.tsx already did. The captured functions reset in afterEach to one that throws, so a call made before the probe renders fails with its cause. The waitFor on the short-lived loading state became a synchronous check of what the change caused: the pending navigation’s URL holds the first value and the rendered URL does not. The final checks wait for the whole end state in one waitFor.

Lesson

  • Start a test once the thing it drives is on the page: a rendered element (findBy…), never a state that is also true before the first load. navigation.state === 'idle' is true while a data router’s first load runs; router.state.initialized or a rendered element is the signal that it has finished.
  • A function captured from a component into a module variable defaults to one that throws, and is reset after each test. A silent no-op default, or the previous test’s function, turns a setup race into a confusing assertion failure several lines later.
  • To reproduce a load-only failure in a test’s setup, delay the step that may land late (here, the first loader call by 100 ms, in the shared helper, for the run only). It fails the old test every time and proves the fix (L-162).

L-262 — A stylesheet that sets display on an element the page hides with hidden also hides [hidden]

  • Date: 2026-11-06
  • Source commits in this repo: BUG-362 (.forge/bugs.md); the same cause fixed twice before it, each on its own: forge-et-fe c9e9aec0 (the email templates screen’s inactive tab panel, EmailTemplatesScreen.module.css .panel[hidden]) and src/ui/recordPage/RecordPage.module.css .tabPanel[hidden]
  • Sync target: upstream
  • Synced: pending

Problem observed

On the Email screen at desktop width the message list filled only half its pane and scrolled inside that short box. Radix’s TabsContent keeps the tab not chosen in the page as an empty panel with the hidden attribute. The panels’ CSS Module class set display: flex and flex: 1 1 0; an author rule beats the attribute’s built-in display: none, so the empty Other panel was drawn and took half the list pane’s height. The browser spec that measured the panes passed, because it compared the pager’s bottom edge, which sat under both panels, with the reading pane’s, and never the list’s own height. The email templates screen and the record page had each met the same cause and fixed it locally, with nothing to stop a third instance.

Change made

EmailRoute.module.css gained .tabPanel[hidden] { display: none; }; mailboxTokens.test.ts reads both rules; the browser spec now measures the list card’s own bottom edge against the reading pane’s. frontend-reviewer gained check 30, and src/ui/shadcn/tabs.tsx and design-system §5 Tabs state the rule.

Lesson

  • Any class that sets display on an element that can carry hidden — a Radix TabsContent, a forceMount panel, anything the code hides with the attribute — comes with <selector>[hidden] { display: none; } in the same stylesheet. The attribute is only a user-agent style, and any author display beats it.
  • A layout test measures the box the person sees, not a neighbour of it. A pager under the list ending level with the pane does not prove the list fills the pane.

L-263 — Strip invisible characters by their Unicode category, not by a hand-kept list of code points

  • Date: 2026-11-07
  • Source commits in this repo: .forge/specs/F33-a-file-attachments-findings.md F-001; forge-et-be 746b333a, 1b6bbb37, afa8d554 (forge-et-be#382)
  • Sync target: upstream
  • Synced: pending

Problem observed

F33-a’s download-name cleaner had to remove characters a person cannot see but that change how a name reads (bidirectional controls, zero-width characters). The first fix listed the bidirectional and zero-width code points by hand; a review found more it missed, and a second list of ranges was added; the next review found that one still missed the soft hyphen, U+180E, U+206A–U+206F, the interlinear annotation characters and the tag characters. Two review rounds and two fix rounds went on a list the Unicode standard already keeps.

Change made

AttachmentDownloadHeaders.isInvisibleFormat became Character.getType(c) == Character.FORMAT (category Cf), applied per code point, with test rows for format characters that must go and for their non-format neighbours that must stay; the Javadoc, the test’s header and docs/api/README.md state the one rule the same way.

Lesson

  • When code must remove or allow a class of characters, use the Unicode general category that defines the class (Character.getType in Java, \p{Cf} in a regex, unicodedata.category in Python), never a list of code points written by hand. A hand list is incomplete from the start and does not follow new Unicode versions.
  • Test both sides of the boundary: rows for characters of the category that must be removed, and rows for their neighbours of another category that must be kept, including a supplementary code point (above U+FFFF), so a change to the rule shows which side moved.

L-264 — An untrusted BigDecimal is bounded from its precision and scale before anything expands or strips it

  • Date: 2026-11-08
  • Source commits in this repo: BUG-374 and BUG-375 (.forge/bugs.md), fixed in forge-et-be#384
  • Sync target: upstream
  • Synced: pending

Problem observed

Two backend paths took a BigDecimal from outside — a cached number in an uploaded workbook, a JSON number in a lead edit — and ran an operation whose cost or validity depends on the exponent before anything had checked the number’s size. SheetCell.of wrote a cell’s plain notation (stripTrailingZeros().toPlainString()), so a cached 1E999999999 built about a billion characters and ran the test JVM out of heap. The lead patch’s bounds check called stripTrailingZeros() first, which throws ArithmeticException: Overflow on 100E2147483647, and counted digits in an int; a zero with a scale above 16383 passed every digit check and PostgreSQL then refused it. Both requests ended in a 500 or an unbounded allocation, and every existing test passed, because none sent a number whose exponent or scale was extreme.

Change made

The workbook reader counts the first digit’s power of ten as a long from precision() and scale() and reads a non-zero number outside a double’s range as Excel’s #NUM! error cell; the lead patch uses the shared LeadFieldRules.estimatedValue, which counts integer digits as a long before stripping, and every lead write stores the value at the column’s scale (LeadFieldRules.storedEstimatedValue). backend-reviewer gained a check that points here.

Lesson

  • Bound the size first, from precision() and scale() counted as a long. toPlainString(), setScale(), toBigInteger() and stripTrailingZeros() can allocate without limit or throw on an exponent near Integer.MIN_VALUE or Integer.MAX_VALUE; none of them is safe on a value nobody has bounded. precision() - scale() in int arithmetic overflows on the same values.
  • A zero passes every digit count at any scale. Store an accepted decimal at the column’s own scale, so a zero sent as 0E-16384 is written as 0.00 instead of reaching the database with a scale it refuses.
  • Test the exponent and the scale, not only the digits. A boundary test for a decimal field sends 1E+huge, 1E-huge and 0E-huge as raw JSON or file text, alongside the digit and sign limits L-073 asks for.

L-265 — A size check for a shared dialog frame covers every dialog that uses it

  • Date: 2026-11-08
  • Source commits in this repo: BUG-277 (.forge/bugs.md), fixed in forge-et-fe#407 and forge-et-fe#442
  • Sync target: upstream
  • Synced: pending

Problem observed

BUG-277’s first fix (forge-et-fe#407) gave the shared dialog frame a short spacing so its body holds a field at 320 × 256, and its browser test measured the four dialogs the bug named. Two more dialogs on the same frame were left out because they did not fit. Later changes broke the fit in dialogs the test did not list. forge-et-fe#442 moved the follow-up dialogs onto the frame, and at 320 × 320 their description left a 39px body. It title-cased the button labels, which wrapped the template editor’s buttons to three rows and pushed the Edit follow-up dialog’s buttons past its edge. Nothing failed, because the test listed only the original four.

Change made

e2e/browser/shell/record-edit-dialog-short-viewport.spec.ts now lists every dialog on the frame that has a size-matrix state with a field, at the short heights and at the lowest ordinary height. The threshold moved to 400px tall, and the narrow labels were shortened (forge-et-fe#442).

Lesson

  • A check that a shared component works at an extreme size lists every screen that uses it, not the ones a bug named, and a change that moves a screen onto the component adds it to that list. Find them from the code (git grep for the component) when writing the check.
  • A change to wording or casing is a layout change at the narrowest size. Measure the buttons and titles it touches at 320px, because longer labels can wrap or overflow where shorter ones fitted.
  • A dialog that is “not fitted, awaiting a decision” stays in the check as a known failure with its bug, so the check shows when a later change fixes it or makes it worse.

L-266 — A change to a composed list breaks every test that renders the real composition, so a plan finds those tests by import

  • Date: 2026-11-08
  • Source commits in this repo: F3-a finding F-002 (.forge/specs/F3-a-follow-up-tasks-findings.md); .forge/plans/F3-a/F3-a-WI-3.1-plan.md ## Progress (forge-et-fe 4ccb40cc)
  • Sync target: upstream
  • Synced: pending

Problem observed

F3-a WI-3.1 added Add follow-up to the lead view’s actions list and a Follow-ups panel to its places. Twice an existing test that renders the real composition broke, and neither was in the plan’s ## Files to Modify. leadPanels.approveSend.test.tsx failed five cases once the actions group filled, and the implementer had to stop and escalate. leadRankingComposition.test.tsx arrived with a merge of main; the review-fix runs, scoped to the changed files, did not run it, and only the full local test record caught it, which cost a further commit and a second record. The plan’s premise check had searched for the literal lists of place names, which neither test contains.

Change made

The implementer rendered only Approve & send’s place in the first test (no assertion changed), and the second was fixed in 4ccb40cc.

Lesson

  • When a plan adds an entry to a shared composition (a list of places, panels or actions), it lists every test that imports that composition, found by searching for its module’s importers (git grep -l <composition module> in the test folders), not for literal entries. Each goes in ## Files to Modify, or the plan says why it does not break.
  • After a merge of main, repeat that search, because the other branch may have added such a test; a run scoped to the changed files does not run it.

L-267 — A browser run whose result is acceptance evidence needs the same load check and machine lock as the records

  • Date: 2026-11-08
  • Source commits in this repo: F3-a finding F-003 (.forge/specs/F3-a-follow-up-tasks-findings.md); .forge/plans/F3-a/F3-a-WI-3.1-plan.md ## Progress; .forge/plans/F3-a/F3-a-overnight-log.md (wave 2, second night); BUG-369 (closed wontfix as an overloaded machine on call-log evidence alone, because its failing size-matrix runs were direct pnpm e2e runs with no load record)
  • Sync target: upstream
  • Synced: pending

Problem observed

Once PRD Rev 81 removed the browser gate from PRs into main, F3-a proved its browser criteria with direct pnpm e2e runs. Those runs take neither the load check nor the heavy-run lock that pnpm e2e:gate and the local records take. WI-3.1’s size matrix ran while other sessions kept the CPU at 100%: it failed 347 tests, of which 342 were load; a re-run failed 214, of which 213 were load; on an idle machine the same runs failed 5 and then 1. Another run met port 5173 held by a vite preview that another worktree had started without the lock. L-175, L-205 and L-218 describe load failures under the gate; the direct runs went around the guard those lessons led to.

Change made

Each evidence run was repeated on an idle machine, on a freshly reset isolated stack, with the CPU load recorded, and only those runs were cited.

Lesson

  • A direct browser run whose result is cited as evidence for an acceptance criterion runs under the heavy-run lock and only when the load check passes, exactly like the browser gate and the records (.claude/rules/test-record.md). Check the load and that the app port is free before starting, and record both beside the result.
  • A failure count from a run on a busy machine is not evidence either way: re-run the failed tests alone on an idle machine before classifying any of them.

L-268 — Whether axe sees <main> behind an open Radix dialog depends on an [aria-live] element inside it

  • Date: 2026-11-08
  • Source commits in this repo: F3-a finding F-004 (.forge/specs/F3-a-follow-up-tasks-findings.md); .forge/plans/F3-a/F3-a-WI-1.2-plan.md ## Progress, Stage 12 auto-repair 1 (forge-et-fe 7fff933e)
  • Sync target: upstream
  • Synced: pending

Problem observed

F3-a WI-1.2’s plan (Decision 26) said every dialog-open page state expects the size matrix’s accepted scrollable-region-focusable finding on <main> (DIALOG_OPEN_MAIN), as the existing entries did. The first wave-1 gate failed all four Activities dialog states at every size: axe never reported the finding. Radix hides the page through the aria-hidden package’s hideOthers, which keeps the dialog and every [aria-live] element and its ancestors unmarked. The account page’s <main> holds an explicit aria-live line, so <main> stays visible to axe and is flagged; the Activities <main> holds only a role="status" line, so its branch is marked aria-hidden and axe skips it.

Change made

7fff933e removed the expectation from the four Activities entries, with a comment saying why, and DIALOG_OPEN_MAIN’s comment now names the [aria-live] condition. No check was weakened and no exemption added.

Lesson

  • An accessibility exemption expected for a kind of page state (every open dialog) holds only when its cause holds on that page. Before a plan copies an expected finding from existing entries, it reads why the finding occurs and checks the new page has that cause.
  • Behind an open Radix dialog, axe scans <main> only if <main> contains an [aria-live] element; a role="status" element alone does not keep it unmarked.

L-269 — A review round that is not run through the review command leaves no record, and the next full review finds what it missed

  • Date: 2026-11-08
  • Source commits in this repo: F3-a finding F-006 (.forge/specs/F3-a-follow-up-tasks-findings.md); .forge/plans/F3-a/F3-a-overnight-log.md (wave 2, second night)
  • Sync target: upstream
  • Synced: pending

Problem observed

On forge-et-fe#353 (F3-a wave 2), three delta rounds of review fixes were made overnight without running /forge-review-pr. No review record was written for them, so the PR’s head had no Forge review status, and the next night needed a full review of 88934c12. That review found four more Important findings.

Change made

The full review ran, its findings were fixed, and a delta through /forge-review-pr wrote the record.

Lesson

  • Every review round on an app-repo PR, a delta included, runs through /forge-review-pr, which reads the diff since the last record and writes the next one (.claude/rules/review-record.md). Fixing findings and checking them by hand is not a round.
  • When a PR’s head has no record after fixes, review the whole range since the last record, not only the last fix commit.

L-270 — A held answer released outside act leaves several whole-screen renders inside one 1-second wait

  • Date: 2026-11-08
  • Source commits in this repo: BUG-382, BUG-365 (.forge/bugs.md); fixed in forge-et-fe#456 (85def261, 38d150c3, 6dac638a); BUG-404, fixed in forge-et-fe#507 (1fb1e3be)
  • Sync target: upstream
  • Synced: pending

Problem observed

Two component tests on one day failed only under load, on Windows. In each, the test released a held server answer (or a fireEvent.click let a stubbed one land) and then made one RTL findBy or waitFor, with its default 1 s, cover everything the answer caused. For BUG-382 that was four renders of the whole account or lead list ending in a Sonner toast; for BUG-365, three renders of the compose dialog ending in a focus move. Timed with marks, the chain took 0.3–0.9 s idle and 2–2.8 s with one busy loop per core. No single step was late, so there was no step to wait for, and the product’s order was correct in both.

Change made

Each test releases the held answer inside await act(async () => …). React 19’s async act keeps flushing until a turn passes with no new React work, so the renders run before the wait starts, and the existing findBy or waitFor covers only what follows on another timer (Sonner’s toast). No timeout was raised. Cases that confirm through user.click were measured and needed no change: user.click already flushes inside act, and their wait took under 0.4 s under the same load.

Lesson

  • When a test releases a held answer, or a fireEvent lets one land, and then waits for something several renders of a large screen later, release it inside await act(async () => …) before the findBy or waitFor. A 1 s wait should cover the last step, not the whole chain.
  • Find such a case by timing the steps (marks from a MutationObserver, or performance.now() around each wait) under one busy loop per core. When no single step is late, the chain is the problem, and act is the wait for what the code causes, not a longer timeout.
  • test-strategy.md § Flaky Tests cause 6 points here.

L-271 — A focus move that must follow a render is made in an effect, never in a frame callback

  • Date: 2026-11-08
  • Source commits in this repo: BUG-355 (.forge/bugs.md; fixed in forge-et-fe#459, 17f47ca1, 21a0a442); BUG-383 (the same code shape in CreateUserModal.tsx, found by the review of forge-et-fe#459; fixed the same way)
  • Sync target: upstream
  • Synced: pending

Problem observed

After a user’s activation succeeded, the user page moved focus to its h1 inside a requestAnimationFrame, on the reasoning that the closed dialog would have rendered before the next frame. Under load the frame ran first. Focus was still on the dialog’s confirm, so the move refused, and the dialog’s close sent focus back to its trigger: a browser test that failed now and then on Windows, filed as a flaky test. The New user dialog’s refused save uses the same shape: it focuses the first error or the summary in a frame callback, which can run before they exist.

Change made

The answer sets a focus request in state in the same batch as the dialog’s close. A passive useEffect on that request moves focus after the render that removed the dialog: it runs after Radix’s focus trap and aria-hidden are undone, and before Radix’s own setTimeout return of focus. A component test that mocks requestAnimationFrame to run at once fails on the old code.

Lesson

  • A focus move that depends on a render (a dialog closed, an error or summary shown) is made in an effect of state set in the same batch as that render’s cause. Never in a requestAnimationFrame or setTimeout: React does not promise to render before the next frame, and under load it often does not.
  • Test it with frame callbacks run at once (vi.spyOn(window, 'requestAnimationFrame').mockImplementation((cb) => { cb(0); return 0; })), the order a loaded browser can give.
  • A browser test that misses such a focus move now and then is a product timing defect, not a slow test. Look for a frame callback before any change to the wait.
  • frontend-reviewer dimension 18 points here.

L-272 — A size-matrix state checks what its page shows; a section under a dialog is not checked by it

  • Date: 2026-11-08
  • Source commits in this repo: BUG-381 and BUG-385 (.forge/bugs.md), forge-et-fe#454
  • Sync target: upstream
  • Synced: pending

Problem observed

BUG-381’s first size-matrix state, user-editor-reporting-deep, ran on the user’s edit route, where the Edit user dialog covers the user’s page and its Reporting line. The state passed the page check at 320px, and its horizontal-scroll check did see the page beneath, but its target-size and axe scans covered only the dialog: the content under a modal is inert. When the review asked for a check of how the tree looks, the state moved to the user’s page (view mode), and the page check at once failed on the third level’s name links, about 8px wide — a defect on main that no state had shown, because the only states with a tree deeper than two levels ran on the edit route (BUG-385). A pixel check also showed that hit-testing (elementFromPoint) could not see a line drawn under a transparent row, because the row hit-tests above it.

Change made

The state runs on the user’s page, with BUG-385 marked as a known failure at 320px, and its own check reads the pixels of the gap above each flat row instead of hit-testing.

Lesson

  • Put a section’s page state on the route where the section is seen with nothing over it. Before trusting a state’s pass for a section, check that no dialog, sheet or menu covers that section in the state’s final screen; content under a modal is inert, so the page check’s target-size and axe scans skip it while still passing.
  • A check of what is drawn reads pixels, not hit-testing. A positioned, transparent element above a line hit-tests as the topmost element while the line still shows through it; to prove a line does or does not cross something, read the screenshot’s pixels (decode it in the page with createImageBitmap, which needs no new dependency).

L-273 — A text box’s typed text lives in the box, not in the screen around it

  • Date: 2026-11-06
  • Source commits in this repo: .forge/bugs.md BUG-261 (fixed in forge-et-fe#437)
  • Sync target: upstream
  • Synced: pending

Problem observed

The Leads screen held what was typed in its search box as its own state, for the debounce and for Clear filters. Every key press therefore re-rendered the whole screen: the filter bar, whose Country select builds some 250 options on every render because Radix renders a closed Select’s options for its hidden native <select>, and the table. In WebKit on a Windows laptop, typing a 17-character search took about 7 s, against 0.4 s for a bare input on the same page. BUG-228’s keyboard walk spent most of its 30 s typing and timed out at whichever step came next, and the slow renders also gave the old URL race (L-201) the time it needed. jsdom and Chromium on an idle machine hid it.

Change made

LeadsSearchBox owns the text, the debounce and the rule that the box follows the URL; the screen only tells it to empty itself, through a counter prop, when Clear filters is pressed. Typing the same search takes about 1.1 s, and a component test counts the table’s and the filter bar’s renders while a word is typed (5 and 5 before, 0 and 0 after).

Lesson

  • State that changes on every key press belongs to the smallest component that shows it. A screen holds only what the rest of the screen reads: the applied value (the URL), not the text being typed.
  • When the screen must reset the box, send it a signal (a counter or a key), not the text itself.
  • Test it by counting renders, not by timing: a test that wraps the expensive children and counts their renders while typing fails on every run, where a timing check passes on a fast machine.
  • The Users, account, contact and email-template list screens hold their search text the same way; a measurement of each is owed (.forge/owed.md).

L-274 — Re-run named browser specs with E2E_GATE=1, not --selected or plain pnpm e2e

  • Date: 2026-11-09
  • Source commits in this repo: F32-c WI-2.1 and WI-2.2 plans (.forge/plans/F32-c/), finding F-003 in .forge/specs/F32-c-bulk-reassign-findings.md; BUG-385 (forge-et-fe#466: hand-run size-matrix checks of a component change used another worktree’s pnpm dev on 5173, so a fixed and an unfixed version both measured the old code’s 82px)
  • Sync target: project-only
  • Synced: pending

Problem observed

F32-c WI-2.1’s plan named pnpm e2e:gate --selected for re-running the list specs its change touched. The branch changes src/lib/, and a selected run then runs every spec (forge-et-fe e2e/README.md § A selected run), so the “targeted” re-run would have been the whole suite. The named-file form, pnpm e2e --project=chromium <files>, was proposed next, but playwright.config.ts sets reuseExistingServer: !process.env.CI && !process.env.E2E_GATE, so plain pnpm e2e reuses any server already listening on 5173 — another checkout’s pnpm dev or the capture app’s — and the run tests that code. The plan review caught it before a run did.

Change made

Both WIs ran their named specs with E2E_GATE=1 ET_BACKEND_PORT=<port> pnpm exec playwright test --project=chromium <files>, which serves the worktree’s own app on the gate’s port 15173 and never reuses a server.

Lesson

  • To run a chosen set of browser specs, name the files and set E2E_GATE=1: E2E_GATE=1 pnpm exec playwright test --project=chromium <files>. It builds and serves the worktree’s own app on 15173.
  • pnpm e2e:gate --selected is not a targeted run on a branch that changes src/app/, src/ui/, src/lib/, e2e/support/, e2e/fixtures/, the configuration or scripts/: it runs every spec. Check the branch’s changed paths before choosing it.
  • Plain pnpm e2e reuses whatever answers on 5173. Use it only after lsof -nP -iTCP:5173 -sTCP:LISTEN prints nothing.

L-275 — Return the page to its top before a page check that follows a keyboard walk

  • Date: 2026-11-09
  • Source commits in this repo: finding F-004 in .forge/specs/F32-c-bulk-reassign-findings.md; F32-c-WI-2.2-test-verify.md (Step 5e attempts 1–4); forge-et-fe 1d9a02d1
  • Sync target: upstream
  • Synced: pending

Problem observed

F32-c’s lead hand-out journey tabbed down the list to Next and back, then ran expectPageClean at 768 × 1024. Axe target-size (serious) reported the table’s header checkbox and its first row checkbox as overlapping. Logging showed the header box at y≈525 and the first row box at y≈-855: the window and table were still scrolled from the walk, so the first row sat under the sticky header row. A freshly loaded list with the header box ticked was clean at 768, 1280 and 320. It failed the same way with retries off, so it looked like a product defect until it was measured.

Change made

Before each page check, the journey scrolls the window, every <main> and the table’s scroll region to 0, 0, waits until each reads 0, waits two animation frames and settles the list. The check itself, its rules and its exemptions are unchanged.

Lesson

  • A page check after a keyboard walk, a paging step or anything else that scrolls starts from the top of the page and its scroll regions. Content scrolled under a sticky header makes axe target-size report the sticky control and the control beneath it as overlapping.
  • Before calling such a finding a product defect, measure where the two elements are (getBoundingClientRect) and run the same check on a freshly loaded page. Never answer it with an axe exemption or a disabled rule.

L-276 — When another session holds the verify stack’s ports, bring up your own on other ports

  • Date: 2026-11-09
  • Source commits in this repo: finding F-005 in .forge/specs/F32-c-bulk-reassign-findings.md; F32-c WI-2.1 plan ## Progress (the isolated stack it ran on); F32-c-WI-2.2-test-verify.md
  • Sync target: project-only
  • Synced: pending

Problem observed

While F32-c wave 2 ran, another session’s backend held 8080 and its compose.verify.yaml stack held Postgres 55432 and LocalStack 45666 — the ports forge-et-be README.md § Running an isolated stack for a verify run names. Running the wave’s browser specs against those servers would have tested another branch’s backend and written into another session’s database; stopping them would have broken that session’s run.

Change made

The wave ran on its own stack: a forge-et-be worktree at origin/main, a compose project per run (et-f32-c-wi2-1, et-f32-c-wi2-2, …) with a gitignored port-override file (Postgres 55433, LocalStack 45667), SERVER_PORT=8082 for bootRun, and ET_BACKEND_PORT=8082 for the frontend. Each project was removed with down -v after its run; a fresh project gave the timing readings their reset database.

Lesson

  • Check the ports before bringing up a verify stack (lsof -nP -iTCP:<port> -sTCP:LISTEN for 8080, 55432, 45666 and 5173). A port in use belongs to someone; never stop or reset it.
  • Move your stack instead: a port-override compose file (services.postgres.ports: !override ["<free>:5432"], the same for LocalStack), ET_DATASOURCE_PORT and the endpoint variables pointing at it, SERVER_PORT for the backend and ET_BACKEND_PORT for the frontend.
  • One compose project per run, removed with down -v afterwards, gives every run a fresh database without touching anyone else’s.

L-277 — A dialog that refuses its ✕ and Esc while a request runs refuses its own Cancel on the same flag

  • Date: 2026-11-09
  • Source commits in this repo: BUG-376 (.forge/bugs.md) — PublishRoundDialog, WithdrawDialog, RemoveDraftDialog, CorrectPriceDialog and DraftPriceDialog in forge-et-fe, forge-et-fe#468
  • Sync target: upstream
  • Synced: pending

Problem observed

The Pricing dialogs pass their request’s pending flag to the frame as closeDisabled, which refuses the ✕ and Esc. The frame does not touch the dialog’s own Cancel, which each dialog renders in its footer, and five of them left it enabled, so Cancel closed the dialog while the request was still running and the user never saw its answer. Two other Pricing dialogs (NewSaleDialog, EditSaleDatesDialog) disabled it, and a comment in the shared wrapper described both behaviours as acceptable. The tests pressed ✕ and Esc while the request was held, never Cancel.

Change made

Each dialog disables Cancel on the same flag it passes as closeDisabled, and the wrapper’s comment says so for every dialog that passes it. A test per dialog holds the request, waits for Cancel to be aria-disabled, asserts that pressing it calls no onClose, then answers the request and asserts Cancel works again.

Lesson

  • Every way out of a dialog is refused on one flag while its request runs: the ✕, Esc and the dialog’s own Cancel. A frame or wrapper refuses only what it renders; the buttons the dialog passes in are the dialog’s to disable.
  • The test holds the request and presses Cancel, not only Esc or the ✕.
  • frontend-reviewer dimension 9 points here.

L-278 — A tool that CI downloads is cached and checked against a SHA pinned in the workflow, and its retries span minutes

  • Date: 2026-11-09
  • Source commits in this repo: forge-et-harness#1239 (repo-hygiene.yml); in the app repos, forge-et-be#392, forge-et-fe#469 and forge-et-pwa#115 (pr-validation.yml)
  • Sync target: upstream
  • Synced: pending

Problem observed

On 2026-11-09 GitHub Releases answered HTTP 504 for well over half an hour (GitHub’s incident: “Increased timeouts due to surge in anonymous users”). Every Fast lane in the app repos downloads gitleaks, and on a full run Trivy, from GitHub Releases, so the secret scan and then the dependency scan failed before either tool ran. The developer saw a red “No secrets in any commit (gitleaks)” step and first read it as a secret finding. curl --retry 3 uses curl’s default backoff, so all four attempts were spent within about 7 seconds. In the first version of the fix, the cached gitleaks tarball was checked against the release’s checksum file, which was cached alongside it. A poisoned cache entry could then have replaced both files and still passed the check (backend-reviewer’s finding on forge-et-be#392).

Change made

Each tool’s tarball is cached with actions/cache, keyed on the workflow file’s hash with a prefix restore-keys. The step downloads the tarball only when the cache lacks it, deletes files for any other version, and on every run checks the tarball against a SHA pinned in the workflow beside V. The curl retries are --retry 5 --retry-delay 15 --retry-max-time 90. After the merge, one manual run on main per repo filled main’s cache entry, which every pull request reads.

Lesson

  • Cache a tool that CI downloads, so an outage at its host fails only a run whose cache is empty. Key the cache on the workflow file’s hash, so a version bump changes the key.
  • Check a cached download against a SHA written in the workflow, on every run. Never check it against a checksum file that comes from the same source or the same cache; a cache entry can replace both. Bump V and SHA together.
  • Space the retries over minutes, for example --retry-delay 15 --retry-max-time 90. Plain --retry N spends all its attempts within seconds, and an outage lasts minutes. Size --max-time and the retry window against the job’s timeout-minutes, because a retry can start at the end of the window and run for the full --max-time.
  • Fill main’s cache after merging (gh workflow run … --ref main). A pull request reads main’s entry and its own, so until main has one, every pull request’s first run downloads the tool.
  • A failed scan step can be a failed download. Read the step’s log before treating it as a finding.

L-279 — A test of the page during a write’s re-read runs while the write’s dialog is still open

  • Date: 2026-11-10
  • Source commits in this repo: .forge/bugs.md BUG-389, fixed in forge-et-fe#487
  • Sync target: upstream
  • Synced: pending

Problem observed

F1-f AC-12’s browser test archived a contact from the Contacts list, held the list’s re-read, and expected the rows to stay on screen. It failed with the archived contact’s row “not found”, which was filed as the list dropping the row early (BUG-389). The row was there. A contact write settles once the lists are re-read (F1-d WI-1.2 plan, subtask 3: the mutation’s onSuccess returns the invalidation, so mutateAsync resolves after it), so the Archive Contact? confirmation stayed open and busy for the whole held re-read. An open modal hides the rest of the page from the accessibility tree: Radix marks it aria-hidden and inert, and a native showModal() makes it inert. The test found the row with getByRole('link', { name }), which skips hidden content. Playwright’s snapshot at the failure showed the dialog open, with both buttons disabled, over a main that held only its status lines. The jsdom test of the same moment hit the same problem: Testing Library’s role queries skip aria-hidden content too.

Change made

The browser test checks that the write’s submit is aria-busy over the held re-read, finds the kept row with includeHidden: true, and checks that the dialog closes after the release. A component test holds the re-read and finds the row with hidden: true, asserting that it is still in the table but not exposed, and fails if the write stops waiting for the re-read. The review found the other side of the same cause in three tests: toHaveCount(0) on an archived row, checked right after the write answered, passed at once behind the open confirmation whether or not the row left; each now waits for the confirmation to close first. frontend-reviewer’s dimension 12 points at this lesson.

Lesson

  • A write whose mutation returns its invalidation from onSuccess keeps its dialog open until the re-read answers. A test that holds that re-read is looking at the page through an open modal.
  • Behind an open modal, find page content with includeHidden: true (Playwright) or hidden: true (Testing Library), and say why in a comment; or wait for the dialog to close before checking the page. A role query that finds nothing there is not evidence that the content left, and an absence check made there (toHaveCount(0), queryByRole(...) === null) cannot fail: wait for the dialog to close before it.
  • Before filing “the element is gone”, read the failure’s page snapshot (error-context.md): an open dialog at the top of it explains a role query that found nothing.

L-280 — Postgres stores no U+0000, so a text field with no NUL check answers 500

  • Date: 2026-11-11
  • Source commits in this repo: F34-c finding F-001 (.forge/specs/F34-c-custom-fields-accounts-contacts-leads-findings.md); forge-et-be 44efd380, d9185728 (forge-et-be#405); BUG-403
  • Sync target: upstream
  • Synced: pending

Problem observed

backend-reviewer sent a custom text value holding U+0000 to forge-et-be#405’s account PATCH. Every request check passed, and the database flush failed with a 500: Postgres refuses the NUL character in text, varchar and jsonb. The same gap is in the app’s other free-text request fields (BUG-403). The first fix ran its check before the value was trimmed, so a tab-padded or blank value — which the contract treats as “no value” — was refused; the first delta review found it.

Change made

The wave 2 contract’s Rev 2 refuses a text value holding any control character (Unicode category Cc, U+0000 included) or U+2028/U+2029 as INVALID, checked on the trimmed value; the seam tests assert U+0000, a tab, U+0085 and U+2028 inside a text, and a blank text with a tab stored as “no value”.

Lesson

  • Every request field that reaches a Postgres text or JSON column refuses U+0000 at the request edge, as a 400 naming the field, never a 500 from the flush.
  • Run the check on the value as it will be stored — after trimming or any other normalising — so whitespace the field accepts is not refused by the new rule.
  • A review of a text field sends U+0000, a tab and a line separator, not only long and empty strings.

L-281 — A JSON number read as BigDecimal is bounded before any scale operation

  • Date: 2026-11-11
  • Source commits in this repo: F34-c finding F-002; forge-et-be 03e80b8f, b10e654b (forge-et-be#405)
  • Sync target: upstream
  • Synced: pending

Problem observed

A custom number such as 100e2147483647 parsed into a BigDecimal without complaint, then stripTrailingZeros() overflowed the scale and the request answered 500. Jackson’s BigDecimal reading accepts any exponent that fits an int, and the overflow appears only in the arithmetic that follows.

Change made

The value’s magnitude is checked against fixed bounds (MAGNITUDE_MAX 309, MAGNITUDE_MIN -323) before any scale operation, and a number outside them is refused as OUT_OF_RANGE.

Lesson

  • Bound a BigDecimal from a request by precision and exponent first (precision() - scale() gives the magnitude), and refuse it as a 400 before calling stripTrailingZeros(), setScale() or any arithmetic.
  • Test the edge with an exponent near Integer.MAX_VALUE, not only with many digits.

L-282 — A numeric input is checked on the number JavaScript will send, not only on the typed text

  • Date: 2026-11-11
  • Source commits in this repo: F34-c finding F-003; forge-et-fe 4414e0dc, 00e4f497 (forge-et-fe#497)
  • Sync target: upstream
  • Synced: pending

Problem observed

The custom number input counted digits after ignoring leading and trailing zeros, so “1” followed by 400 zeros passed. Number() turned it into Infinity, JSON.stringify wrote Infinity as null, and the PATCH read null as “clear this value”, so a long number silently removed the stored one. A non-zero decimal with 400 leading zeros became 0. The other direction failed too: a stored 1e21 was shown in the form with String(), as 1e+21, which the form’s own check then refused.

Change made

The check refuses a text whose number is not finite, or is zero when the text is not, with the digits message; the request sends the typed text should one get past it; a stored number is shown back as plain decimal text through Intl.NumberFormat('en-US') with no grouping and at most 15 significant digits.

Lesson

  • Validate the value that will be sent: Number.isFinite(n), and n !== 0 when the text has a non-zero digit, besides any check on the text.
  • Never let JSON.stringify decide what a non-finite number means — it writes null, which a PATCH may read as a clear.
  • Format a number back into an input with Intl.NumberFormat, not String(), whose exponent form the input’s own check may refuse.

L-283 — In headless Chromium a date input’s year moves to the next part by itself after four digits

  • Date: 2026-11-11
  • Source commits in this repo: F34-c finding F-004; forge-et-fe 442a8a5c (reverting b0584ab1)
  • Sync target: upstream
  • Synced: pending

Problem observed

F34-c’s browser test filled an <input type="date"> by typing the year, pressing ArrowRight, then typing the month and day. Chromium had already moved to the next part after the fourth year digit, so ArrowRight skipped the month and the stored date was wrong. An agent first committed a fix for a guessed cause (a leading zero); a probe in the browser — type the year, read which part has focus — showed the auto-advance.

Change made

The helper types the parts in the locale’s order (year, month, day in the test locale) with no navigation key between them, and the test asserts the input’s stored value.

Lesson

  • Type a date input’s parts in sequence, with no ArrowRight or Tab between them: Chromium moves to the next part when one is full.
  • Assert the input’s value, not that the keystrokes were sent.
  • Before committing a fix for a browser-only failure, probe the cause in the browser (focus, value, each part after each key); a guessed cause that passes once can mask the real one.

L-284 — Inside a Radix dialog, a render that removes a node while focus leaves a field sends focus to the dialog

  • Date: 2026-11-12
  • Source commits in this repo: BUG-402 (.forge/bugs.md); fixed in forge-et-fe#505
  • Sync target: upstream
  • Synced: pending

Problem observed

In the compose dialog, the first Tab out of To (or Subject) sent focus to the dialog element itself, so the next Tabs went through Close and the body region back to To; three keyboard browser tests failed every time on main. Traced in Chromium: the Tab moved focus towards Cc, but the blur of To rendered (the field turned touched), and that render swapped the AI Draft button’s lazy-load stand-in for the button, removing a node. Between focusout and focusin, document.activeElement is <body>; Radix FocusScope’s MutationObserver reads “focus on <body> and a node removed” as the focused element having gone, and focuses the dialog container. The first attempt at a fix moved the swap, but a place mounted before the chunk arrived could still swap later, which would remount the button and remove a node again (caught by review).

Change made

The button’s chunk loads with the composition module, and a place renders the loaded button directly, choosing once per mount whether it is the loaded button or the Suspense path, so nothing inside the dialog is swapped while a person tabs.

Lesson

  • Inside a Radix Dialog or AlertDialog, no node may be removed by a render that runs as focus leaves a field — a Suspense fallback giving way to its content, a field’s hint replaced by its error on blur, a lazy panel arriving. Keep the node and change its content, or make the swap happen before or after focus moves.
  • A component that chooses between two element types by a module-level flag chooses once per mount (useState(() => flag)): a flag that changes while it is mounted remounts its child on the next render.
  • Trace a focus jump before fixing it: log keydown, focusout with its relatedTarget, focusin with a stack, and the removed nodes; the stack names who moved focus, which a guessed fix cannot.

L-285 — A Sonner Toaster replays the store’s toasts when it mounts, so a test clears the store before mounting it

  • Date: 2026-11-12
  • Source commits in this repo: forge-et-fe#503 (01f0a56f, 76f2a3a4, aac97f69), the jsdom 31 upgrade
  • Sync target: upstream
  • Synced: pending

Problem observed

Under jsdom 31, two NotInRoundDialog tests found 9 toasts where they expected 1. Sonner’s store outlives each test; ToastState.subscribe replays every active toast to a new Toaster, which adds them on a setTimeout, while toast.dismiss() reaches a mounted Toaster on an animation frame. The tests dismissed after mounting, so they relied on the timer running first; jsdom 31 runs the frame first, the dismissal found nothing, and the replayed toasts stayed. Their “no toasts yet” waitFor passed on its first check, before the replay landed, so it guarded nothing. Review found the same shape in EmailTemplateEditorRoute.test.tsx and four files that mounted a Toaster without ever clearing the store.

Change made

Every test file that mounts a Toaster calls toast.dismiss() in its afterEach, and a test that mounts one after others have raised toasts dismisses before it mounts. A hidden-region test’s toast, held by notifySuccess for up to MAX_WAIT_FRAMES, can reach the store after its afterEach, so a file with such tests dismisses before each mount rather than asserting an empty store.

Lesson

  • A test that mounts a Sonner Toaster clears the store first (toast.dismiss() in afterEach, and before the mount when earlier tests in the file raised toasts); a dismissal sent after the mount races the replay.
  • A “nothing on screen yet” wait right after a mount checks the store, not the screen (toast.getToasts()): work the mount scheduled on a timer has not drawn anything yet, so a screen check passes before it lands.
  • A major test-environment upgrade (jsdom, the test runner) can change timer and frame order: a test that fails only after it is relying on an order nobody guaranteed — find that order, do not pin the old version.

L-286 — A pull-request CI run stuck in the queue with no jobs is restarted by closing and reopening the PR

Narrowed 2026-11-12: reopening does not always clear the check. On forge-et-harness#1298 the reopened PR’s new run passed, but the lost run kept holding the required check and the PR stayed blocked; only a new head cleared it. .claude/rules/git-conventions.md § Pull Requests is the rule in force: check GitHub’s status page first, then push the PR’s next change, or an empty commit.

  • Date: 2026-11-12
  • Source commits in this repo: forge-et-harness#1299 (its first Repo hygiene runs, 43096954481 and 43098215186)
  • Sync target: upstream
  • Synced: pending

Problem observed

Two Repo hygiene runs for forge-et-harness#1299’s pull_request event stayed queued for over half an hour with no job created, while later runs for other branches started and finished. gh run cancel answered “Cannot cancel a workflow run that is completed” and gh run rerun answered “This workflow is already running”, although the API still reported the run as queued. A workflow_dispatch run of the same workflow on the branch passed and put a Repo hygiene success check on the PR’s head commit, but gh pr merge was still refused (“the base branch policy prohibits the merge”): the PR’s check list showed only the stuck pull-request run, so the required check stayed pending.

Change made

Closing and reopening the PR (gh pr close <N> then gh pr reopen <N>) fired a new pull_request event; its run started at once on the same head commit, passed in under two minutes, and the PR merged. No commit was added.

Lesson

  • A pull_request run that has sat queued with no jobs while later runs finish is stuck, not waiting. Check with gh api repos/<owner>/<repo>/actions/runs/<id>/jobs: an empty job list confirms it.
  • Restart it by closing and reopening the PR, which starts a fresh pull_request run on the same head without a new commit or a new local record. A workflow_dispatch run does not count towards the PR’s required check, and an empty commit costs a new head (and, in an app repo, a new local test record and a delta review).
  • This is not a re-run of a green or cancelled run (.claude/rules/git-conventions.md § Pull Requests): the stuck run never ran.
  • When the reopened run passes but the PR stays blocked, the lost run still holds the required check, and only a new head clears it: push the next real change, or an empty commit (forge-et-harness#1298, the same day; .claude/rules/git-conventions.md § Pull Requests). Check the PR’s checks after the reopen before assuming it worked.

L-287 — In WebKit a click does not focus a button, so a dialog that returns focus to “the control that opened it” finds none

  • Date: 2026-11-12
  • Source commits in this repo: .forge/bugs.md BUG-397, fixed in forge-et-fe#515; BUG-406, the wider gap, fixed in forge-et-fe#523
  • Sync target: upstream
  • Synced: pending

Problem observed

The weekly-prices import’s Replace and Create confirmation lost focus in WebKit only (BUG-397). Since the UI revamp it is a Radix dialog built on RecordEditDialog, which records document.activeElement when it opens and gives focus back to it on close. In Chromium a click focuses the button, so the opener was Create. In WebKit (Safari, and Playwright’s webkit) a click does not focus a button, so document.activeElement was <body>, the dialog treated that as no opener, and with no returnFocusTo named, focus stayed on <body>. Keyboard tests passed in both engines, because a key press does focus the button; only the size-matrix page state, which opens the dialog with a click, failed.

Change made

The caller names its trigger in returnFocusTo, which the dialog uses when it has no opener. A component test opens the dialog without moving focus, the way a WebKit click does, and expects focus back on the trigger; it fails without the change. Other callers that name no returnFocusTo have the same gap, filed as BUG-406.

BUG-406 then fixed every caller at once: forge-et-fe src/ui/overlays/openerControl.ts, installed from src/main.tsx, tracks pointer presses, and RecordEditDialog, ConfirmDialog and ComposeEmailProvider read their opener through openerControl(). Its review found that WebKit does not always leave focus on <body>: it focuses the nearest focusable ancestor of the button (a tabindex section or scroll region, a dialog’s content), so a fix that handled only <body> returned focus to the container.

Lesson

  • “Focus goes back to the control that opened it” cannot rely on document.activeElement at open time. In WebKit a mouse click does not focus a button, a link or a form control: focus goes to the nearest focusable ancestor (a tabindex section, a scroll region, a dialog’s content) or, when there is none, stays on <body>. Only a key press or a programmatic focus() moves it to the button.
  • In this codebase a dialog reads its opener through openerControl() (src/ui/overlays/openerControl.ts), never document.activeElement directly; returnFocusTo stays the fallback for an opener that has gone (a menu item) or that the dialog was opened without (a route).
  • To test it, open the dialog with no focus move (fireEvent.pointerDown on an element that is not focused, then set open), and for the ancestor case move focus to the container after the press, rather than userEvent.click, which focuses the element as Chromium does; check where focus lands on close. A *-webkit.spec.ts that opens the dialog with a real mouse click and a touch tap is the proof in the engine itself (e2e/browser/accounts/dialog-focus-return-webkit.spec.ts): the two orders differ — for a click WebKit moves focus at mousedown, before pointerup; for a tap, after it — and jsdom shows neither.

L-288 — A heavy command that skips the machine lock still slows the nightly run beside it

  • Date: 2026-11-12
  • Source commits in this repo: the nightly full run of 2026-11-12 (forge-et-be#412, forge-et-fe#484)
  • Sync target: upstream
  • Synced: pending

Problem observed

The nightly full run took the heavy-run lock at 02:00, and the records and browser gates other sessions started waited for it as designed. Other sessions’ direct commands did not: a ./gradlew check in one worktree, a backend Gradle run of about 50 minutes in another, and two vitest run jobs, beside Docker’s virtual machine. The load average stayed between 50 and 76 on an 8-core Mac for the first hour. The backend build, which takes about 39 minutes, stopped at its 60-minute limit; Gradle writes its test results only when the test task ends, so the night left no result at all. The CRM Vitest suite took 7 min 42 s against 3 min 35 s the night before.

Change made

.claude/rules/test-record.md now says to read the lock before a heavy command that does not take it, and to run one test file or wait while it names the nightly full run. The backend build was rerun by hand under the lock after the night.

Lesson

  • A lock only protects the runs that take it. A direct ./gradlew build, check or test, a vitest run over many files or a second bootRun competes with whatever holds the lock as if there were no lock.
  • Read the lock before such a command on a shared machine; while the nightly run holds it, run one test file or wait.
  • A suite stopped at its time limit leaves nothing to triage when its tool writes results only at the end (Gradle’s JUnit XML), so the night costs a rerun, not just a slower result.

L-289 — A defect filed from reading code on an import path is first reproduced with a file in the real format

  • Date: 2026-11-12
  • Source commits in this repo: BUG-405’s record; its fix is forge-et-be#413
  • Sync target: upstream
  • Synced: pending

Problem observed

BUG-405 was filed by a reviewer from the code: the Pipedrive migration’s writers check lengths but not control characters, so “a value holding U+0000 reaches PostgreSQL and the write fails”. The fix’s first test built a workbook holding U+0000 and failed for a different reason: the file was refused as NOT_A_WORKBOOK. XML 1.0 cannot hold U+0000, raw or as &#0;, nor any other C0 control but tab, LF and CR, so both of the import’s XML parsers refuse such a file before any row is read. The filed failure could not happen. What could happen was different: tabs, line breaks, C1 controls and U+2028 do pass through XML, and were written into one-line columns the CRM’s own requests refuse. The C1 controls in real data are mostly Windows-1252 punctuation read as Latin-1 (U+0092 is ’), which plain removal would have lost.

Change made

A throwaway spec fed each way a control character can be written into an .xlsx (raw, as a character reference, under XML 1.1, as Excel’s _xHHHH_ escape) through the real reader and printed what arrived. The fix was rebuilt on that table: C1 controls are read as Windows-1252, the rest are cleaned to one line, and a test pins that U+0000 refuses the file.

Lesson

  • Before fixing a defect found by reading code on a path that reads files, reproduce it with a file in the real format, built by the same test builder the path’s tests use. The format may refuse the input before the code under suspicion runs, or deliver it in another form. A test that fails for a different reason than the bug says is the first sign.
  • Probe every encoding the format allows, not only the raw character. For XML that is the raw character, a character reference, the XML 1.1 declaration and any escape the producing application uses.
  • A C1 control (U+0080–U+009F) in text from outside is usually Windows-1252 read as Latin-1. Map it to its Windows-1252 character before deciding what to remove.

L-290 — A rule that lets CI skip a check lists what is safe to skip, never what is unsafe

  • Date: 2026-11-12
  • Source commits in this repo: forge-et-be#411 (scripts/spotless-scope.py, commits 8781f37, 1722504, 48ffd77, 2ff8576)
  • Sync target: upstream
  • Synced: pending

Problem observed

The backend’s Fast lane formats every Groovy file whenever build.gradle changes, so each Dependabot Gradle bump took 10 to 14 minutes. The first version of spotless-scope.py named what can change formatting (the Spotless plugin line and the spotless { } block) and let every other build.gradle change check only the changed files. Each backend-reviewer round found more Spotless settings that list missed, and each would have let a formatting change through: a second spotless block, a setting written outside the block, an indented block, a formatter version kept in a variable or returned by a method, a multi-line string the block reads. It took three fix rounds.

Change made

The rule was turned round. build.gradle now lets the changed files be enough only when every changed line is a version Dependabot bumps (a plugin version, a group:name:version coordinate passed to a configuration, a def set to a literal, an ext['<lib>.version'] override), a comment or a blank line, and the Spotless settings are unchanged. Anything else checks every file. Each shape a reviewer found became a self-test case that failed before its fix. The real dependency bumps in the repository’s history still pass.

Lesson

  • When a script decides that CI may skip or narrow a check, write down what is safe to skip and treat everything else as unsafe. A list of what is unsafe is only as complete as the author’s imagination, and a file such as a build script can say the same thing many ways.
  • Make every unknown answer the full check: a git error, a file the parser cannot read, a shape it does not recognise. The cost of a wrong “skip” is a defect on main; the cost of a wrong “full check” is a few minutes.
  • Prove the rule with paired cases in a self-test that the workflow runs first: each change that must be checked in full, and each real change that may be narrowed, taken from the repository’s own history.

L-291 — Measure the CI runner’s memory before running tests in parallel on it

  • Date: 2026-11-12
  • Source commits in this repo: forge-et-be#411; runs 43108810043 and 43111979033 in forge-et-be
  • Sync target: upstream
  • Synced: pending

Problem observed

The backend’s whole test suite took 47 minutes in its Slow lane against a 60-minute cap, so the plan was two test JVMs (Gradle maxParallelForks), each with its own Postgres and LocalStack containers. GitHub’s standard hosted runner for a private repository has 2 processors and 7.9 GB of memory, and a test JVM here needs a 3 GB heap. Both tries were stopped about 11 minutes into the tests, at 3 GB per JVM and again at 2 GB with the compiler run first in a Gradle run that exits. The job showed “The runner has received a shutdown signal”, the step was marked cancelled, and GitHub kept no log for the job afterwards.

Change made

CI stays at one test JVM. The fork count became a Gradle property (et.testForks, default 1) for machines with more memory, and the Slow lane prints nproc and free -m before the build. A larger runner or a higher cap is the lead’s decision (.forge/owed.md).

Lesson

  • Before adding parallel test processes to a CI job, add up the memory they need against the runner’s: each JVM’s heap, its containers, the build tool’s own daemons (here a 2.5 GB Groovy compiler that stays alive in the Gradle daemon). Print nproc and free -m in the job, so the log shows the limit.
  • A job stopped with “The runner has received a shutdown signal” part-way through a heavy step, with no log kept, is the runner running out of memory, not a failing test. A smaller heap that still fits the suite is the only setting to try; otherwise keep one process or use a larger runner.
  • Try it on a throwaway branch with a workflow_dispatch run, not on the PR, so a failed try costs no review or test record.

L-292 — A check on shared, live data asserts only what nothing in the product can change

  • Date: 2026-11-13
  • Source commits in this repo: .forge/bugs.md BUG-417, fixed in forge-et-fe#525
  • Sync target: upstream
  • Synced: pending

Problem observed

The dev smoke run’s check 8 asserted that the reserved SMOKE buying standard had exactly two published prices. The reservation said nobody edits the SMOKE records, and nobody did: the product itself added a third price. Carry forward (F26-g, built after the smoke run) drafts the current price of every standard a round does not price, and publishing that round made it a published price on the SMOKE standard. From then on every smoke run failed at check 8, so a real failure there could not be seen.

Change made

Check 8 now asserts only what effective-dated prices (AD #14) keep fixed: the SMOKE standard’s first two prices, their dates, and the price as of each of their weeks. Later prices are allowed. The reading moved into a helper with unit tests over pinned histories.

Lesson

  • A check that runs against shared data — dev, UAT, a seeded demo — asserts what no product action can change, never a closed set (“exactly N rows”, “no other price”). A reservation stops people editing the records; it does not stop a feature built later from adding to them as part of its normal work.
  • When a feature writes to every record of a kind (a carry forward, a sweep, a back-fill), check the reserved records it reaches, and whether any check reads them as a closed set.

L-293 — Work waiting for the nightly’s lock must not hold the night’s CPU or ports while it waits

  • Date: 2026-11-13
  • Source commits in this repo: the nightly full run of 2026-11-13 (forge-et-fe#484)
  • Sync target: upstream
  • Synced: pending

Problem observed

A session reproducing a load-dependent browser failure (BUG-415) started eight yes busy loops at 02:12, then a Playwright run under the heavy-run lock. The Playwright run waited for the nightly full run, which held the lock; the busy loops did not wait, and kept the CPU 0.98 busy. The nightly’s browser gates refuse to start above 0.65 and retry every five minutes, so neither run could move until the nightly gave up. The same session’s backend was listening on port 18080, the port the nightly’s CRM gate starts its own backend on, and the runner reported the CRM gate as not run at once (“port 18080 is already in use”). The night’s CRM gate was lost, and forge-et-fe#484 stayed open another day.

Change made

run-nightly.py now waits up to 30 minutes for port 18080, checking every five minutes, as the gate already waits for its own port, and names the process and folder holding it when it gives up. .claude/rules/test-record.md now names the nightly’s ports and says to start load on purpose only after the run that needs it holds the lock. The CRM gate was run by hand after the night.

Lesson

  • Anything started before a lock is taken runs beside whatever holds the lock. A command line that starts load and then waits for the lock (yes & …; pnpm e2e:gate) applies the load to the run it is waiting for. Start load on purpose from inside the run that holds the lock, or after it has the lock.
  • A server left listening is part of the machine’s state the night depends on. The nightly’s backend uses 18080, its CRM gate 15173, its stack 56432 and 46666; a developer’s process on any of them costs the night a suite.
  • A check that finds a resource busy waits and retries within the suite’s limit, and names the holder when it gives up, so the morning’s triage starts from the process, not from a guess.

L-294 — Read a client’s timeout and retry defaults before setting them as a fix, and bound each network step of a workflow

  • Date: 2026-11-13
  • Source commits in this repo: .forge/bugs.md BUG-254, fixed in forge-et-fe#528 and forge-et-pwa#125
  • Sync target: upstream
  • Synced: pending

Problem observed

One CRM dev deploy run sat in its first aws s3 sync step until the deploy job’s 10-minute timeout-minutes cancelled it, and GitHub no longer had the log, so where it stopped was unknown (BUG-254). The workflow had a timeout only on the job, so the hang cost the full 10 minutes and ended cancelled, not as a failed step.

The bug’s own candidate fix, “a shorter --cli-read-timeout”, was first applied as --cli-read-timeout 60, which is the AWS CLI’s default, so it changed nothing. AWS_RETRY_MODE: standard was also already the CLI v2 default. With a 60 s read timeout, a stalled request reached only about three attempts before the new 3-minute step timeout, so the comment’s “five attempts” was untrue. frontend-reviewer caught it by reading aws help.

Change made

Each S3 step and the CloudFront invalidation now give up on a request after 10 s without a connection or 20 s without a reply, the CLI retries up to five times, and each step has its own timeout-minutes (3 for S3, 2 for the invalidation), so five attempts and their backoff fit inside the step. The comments say which settings are the CLI’s defaults.

Lesson

  • Before setting a client’s timeout, retry count or retry mode as a fix, read its default (aws help, aws help config-vars, the SDK’s documentation). An option set to its own default looks like a fix in review and changes nothing.
  • A timeout and a retry count only work together when the attempts fit inside the timeout around them: attempts × per-request timeout + backoff, below the step’s timeout-minutes.
  • Give each workflow step that waits on a network service its own timeout-minutes, below the job’s. A job-level timeout alone turns a hung request into a run cancelled at the job’s limit, with the time spent and no failed step to point at.

L-295 — main changes under a wave reach it through shared code, not through a conflict

  • Date: 2026-11-13
  • Source commits in this repo: .forge/specs/F32-d-list-views-accounts-leads-contacts-findings.md F-001 and F-013; F32-d wave 4’s merge of main into forge-et-fe#527
  • Sync target: upstream
  • Synced: pending

Problem observed

F32-d’s waves were cut from main and built over several days while other features merged. Three times, main changed code a wave relied on without any merge conflict. BUG-394 deleted a helper the wave used, and the wave branch stopped typechecking only at Pass 1. F34-c changed a pill class, and a test failed only on the wave branch. F34-c changed RecordEditDialog to open on its first field, and the wave’s tests relied on the old behaviour; the wave PR merged cleanly, and only the review’s base check found it, by reading the commits that touched the same files. In wave 4, BUG-406 changed ConfirmDialog and the dialog opener while the wave’s tests used both.

Change made

Pass 1 runs typecheck and the full suite on the wave branch built from the latest main. The review’s step 2 reads main’s commits to the files the PR shares. Stage 12 merges main into the wave branch when another code PR has merged, and the selected browser run then runs on the merged head.

Lesson

  • A clean merge says nothing about behaviour. A deleted helper breaks the build. A changed component behaviour, or a changed class a test reads, breaks only the tests, and only on the integrated branch.
  • Before a wave’s verify run, list main’s commits since the wave’s base that touch the shared components and helpers the wave uses (git log <base>..origin/main -- <paths>), and read the behaviour changes. Do the same again at review. A per-work-item suite cut from an older main cannot see them.

L-296 — A rule that resolves state from two async sources is a check over every combination, not a set of event handlers

  • Date: 2026-11-13
  • Source commits in this repo: .forge/specs/F32-d-list-views-accounts-leads-contacts-findings.md F-002; .forge/plans/F32-d/F32-d-WI-3.2-plan.md (three review passes)
  • Sync target: upstream
  • Synced: pending

Problem observed

WI-3.2’s plan resolved an open view (view=<id>) from cached and fetched data across two queries, written as events: “when X changes, do Y”. Each of three review passes found a new reachable sequence the events missed: a new view judged gone, a background re-read flashing a skeleton, Back to a deleted view stuck on its skeleton, a failed re-read with cached data left resolving, a running read not counted, a known view flashing during Retry.

Change made

The rule was rewritten as a check: “while resolving, and row 1 is idle, and no read has started since the change, start one”, with one required test per sequence found. The builder then broke the hook seven ways, and each break failed a test.

Lesson

  • When state is derived from two or more async sources, write the rule as a check over the combinations (cached or not, fetching or not, last read failed or not, a read started since the change or not), and test each combination that can occur. Event handlers (“on change, refetch”) miss the combinations no event announces.
  • A review that keeps finding new sequences is telling you the rule’s form is wrong, not that one more case is missing.

L-297 — A hidden, absolutely placed measuring element still widens its scroll container

  • Date: 2026-11-13
  • Source commits in this repo: .forge/specs/F32-d-list-views-accounts-leads-contacts-findings.md F-008; forge-et-fe c4e19d4e
  • Sync target: upstream
  • Synced: pending

Problem observed

The saved-views row measured tab widths from a copy of the tabs that was invisible absolute w-max. Neither visibility: hidden nor absolute placement removes a box from its scroll container’s scrollable overflow, so the page scrolled sideways by however much wider the copy was than the row: 1px with no views at 320px, about 2,300px with 15 views. Every jsdom test passed, because jsdom has no layout. Only the size matrix’s horizontal-scroll check found it, on 182 states at once.

Change made

The measuring copy moved into a zero-size, overflow: hidden box.

Lesson

  • An element kept on the page only to be measured goes inside a zero-size, overflow: hidden wrapper. visibility: hidden, opacity: 0 and position: absolute all leave it in the scrollable overflow.
  • A plan that adds such an element names the wrapper, and its verify includes one state with many items at the smallest supported width, where the overflow is largest.

L-298 — Give every Playwright run its own output folder, and re-run failed tests by name

  • Date: 2026-11-13
  • Source commits in this repo: .forge/specs/F32-d-list-views-accounts-leads-contacts-findings.md F-009 and F-014
  • Sync target: upstream
  • Synced: pending

Problem observed

Playwright clears test-results/ at the start of every run. In F32-d wave 3 the orchestrator started a second browser command while the test author was still diagnosing the first one’s failures, so the screenshots, traces and error-context.md it needed were gone, and four failures were classified from the log and the code alone. In wave 4, after every run had been given its own --output folder, a re-run of four failed tests was started as --last-failed --output=<new folder>. Playwright keeps the failed-test record (.last-run.json) in the output folder, so the new folder had none, and the command ran the whole Chromium project: about 1,600 tests in 17 minutes on a shared machine at load 20.

Change made

Each run in wave 4 had its own --output="$RT/results-<run>-<n>" folder, and later re-runs named their tests (-g, file:line).

Lesson

  • Pass --output=<a folder of its own> to every browser run whose artefacts someone may still need. The next run in the default folder deletes them.
  • Re-run failed tests by name (-g '<title>' or file:line), or give --last-failed the earlier run’s own output folder. --last-failed with a new folder has no record and runs everything.

L-299 — A Radix overlay that is still closing swallows the next focus move or click

  • Date: 2026-11-13
  • Source commits in this repo: .forge/specs/F32-d-list-views-accounts-leads-contacts-findings.md F-011 and F-016; forge-et-fe ed63a12d and ee11a4a4
  • Sync target: upstream
  • Synced: pending

Problem observed

After Delete View in a Radix modal dialog, the code focused the default tab as soon as the dialog’s state was closed. The dialog’s content was still mounted during its close, and Radix keeps the rest of the page inert while modal content is mounted, so the focus() did nothing, and focus fell to <body> when the content unmounted. The unit tests passed because jsdom has no inert; only a keyboard walkthrough found it. In wave 4, a browser test chose a view through the More Views Radix menu, then clicked More Views again while the first menu was still closing, and the click did not open it. This happened only under load.

Change made

The focus request is kept until the target actually holds focus, and is run again from the dialog’s onCloseAutoFocus; its unit test emulates inert. The test helper that chooses a view through the menu now returns only once no menu is present.

Lesson

  • Code that moves focus after a Radix dialog or menu closes checks document.activeElement afterwards and retries from the overlay’s close callback. A unit test of it emulates inert, because jsdom ignores it (L-024).
  • A browser test or helper that acts through a menu or dialog waits until the overlay has gone (toHaveCount(0) on its content) before the next interaction. The race shows only under load, so a green run on an idle machine does not prove its absence.

L-300 — A leftover sweep must not match state a test creates on purpose

  • Date: 2026-11-13
  • Source commits in this repo: .forge/specs/F32-d-list-views-accounts-leads-contacts-findings.md F-012; forge-et-fe 95423d1d
  • Sync target: upstream
  • Synced: pending

Problem observed

Every saved-views browser file swept leftovers at its start and end: shared views with the run’s name prefix whose owner was deactivated. One test made exactly such a view on purpose (a deactivated owner’s shared view stays listed), then read the list. It passed in four runs and alone, and failed once when failures in another file restarted that file’s worker, whose afterAll and beforeAll swept in the gap between the deactivation and the read. The plan’s isolation rule assumed a running file’s users stay active until its own end.

Change made

The test’s view uses a name prefix the sweep does not match.

Lesson

  • A sweep’s match excludes every state a test creates deliberately, by a separate name prefix or marker. A sweep that matches it races that test whenever another worker starts or ends in parallel.
  • A plan that adds a leftover sweep lists the tests that create its target state on purpose.

L-301 — A test that waits on an emulator is reproduced by slowing the emulator, and takes no more round trips than its assertion needs

  • Date: 2026-11-13
  • Source commits in this repo: .forge/bugs.md BUG-259 (the fix is altrium-io/forge-et-be#422); BUG-195 and BUG-285 (dead-letter waits in backend integration tests, closed wontfix when busy loops on the host did not reproduce them)
  • Sync target: upstream
  • Synced: pending

Problem observed

ScanResultQueueIT’s not-JSON row waits up to 60 seconds for a message to reach the dead-letter queue. It failed twice in full builds, polling about every 8 to 90 seconds when the poll should return in about one, so LocalStack was answering slowly. Busy loops on the host did not reproduce it (BUG-195), and neither did limiting the LocalStack container’s CPU: LocalStack runs in Docker’s virtual machine and is idle most of the time. Freezing the container with docker pause for 7 seconds of every 8 reproduced the failure in 3 of 5 runs, with the same 8-second polls. The cause was in the test: the queue’s retry limit was 8, so the message needed eight receives, each a LocalStack round trip plus the visibility timeout, and a slow LocalStack’s delay was multiplied by eight. The row proved only that the message was not acknowledged and was dead-lettered.

Change made

The row sets the queue’s retry limit to 2 for its own message and puts the old limit back in its cleanup: block. Under the same stall it passed 4 of 4; unstalled, the row went from about 28 to 6.5 seconds.

Lesson

  • Reproduce a slow emulator by slowing the emulator. For a test that waits on LocalStack, Postgres or another container, freeze the container for most of each few seconds (docker pause and docker unpause in a loop, started once the test’s resources exist; pick the newest container, docker ps -q -n 1 --filter ancestor=<image>, and only the one your run started). Busy loops on the host and a CPU limit on the container do not reproduce it.
  • A test takes no more round trips to an emulator than its assertion needs. Each one multiplies the emulator’s delay. Where a shared setting (a retry limit, a page size, a poll count) is larger than one test needs, set it for that test and restore it, rather than lengthening the test’s wait.

L-302 — A record people type in needs a way to put a typo right, stated with the rules that lock it

  • Date: 2026-11-14
  • Source commits in this repo: .forge/bugs.md BUG-422 (fixed in altrium-io/forge-et-be#430 and altrium-io/forge-et-fe#533); F26-g spec Rev 5; BUG-435 (fixed in altrium-io/forge-et-fe#538), a consequence of the same change
  • Sync target: upstream
  • Synced: pending

Problem observed

F26-g locked an auction sale’s dates once it started or once a price was published, and its year and number always, for good reasons: a started sale had already ended other prices, and a published round had closed them at the sale’s start. The spec put “changing a sale’s year or number, deleting a sale” Out of Scope and said nothing about a mistyped sale. In use, one typo (sale 433 for 43, or next week’s sale entered with today’s date) could not be undone, and each did real harm: the wrong sale became the current one, so a week’s price emails listed every price as left out, or that night’s sweep ended every current price.

Change made

A sale with no published or withdrawn price can now have its year, number and dates corrected, started or not, or be deleted with its drafts; a sale with one can change only its end, because the end bounds no price. Each change carries a reason and is audited. The New sale and Edit sale dialogs say in plain words, before saving, what a start of today or earlier does, because the prices the sweep ends stay ended (AD #14).

Lesson

  • When a spec locks a record that people type in, it says in the same place how a typo in it is put right, and from which state on it cannot be. The lock rules protect what other data already rests on; they are usually narrower than “nothing may change”. Work out which fields other rows depend on (here: the start, once a publish closed prices at it) and leave the rest correctable, and allow a delete while nothing rests on the record.
  • Where a typo’s harm cannot be undone, warn before the save. A plain-words notice of what the value will do, shown while it can still be changed, costs less than a correction path for the harm.
  • A spec reviewer can catch the next instance by asking, for every immutable field and every refused edit or delete: “if someone types this wrong, what do they do?”
  • When a change makes a record correctable or deletable, list every flow that holds its id while a person works, and decide what each does when the record changes under it. BUG-435: a price email was filled for the current sale, the sale was deleted while the rep wrote, and the email went out with no record. A check just before the irreversible step (the send) is the cheap answer; a check only when the flow started is not enough.

L-303 — A browser test that reads answer bodies from a response listener lets every read in flight land before it navigates

  • Date: 2026-11-14
  • Source commits in this repo: .forge/bugs.md BUG-424 (the fix is altrium-io/forge-et-fe#536); .claude/agents/frontend-reviewer.md dimension 14
  • Sync target: upstream
  • Synced: pending

Problem observed

F33-a AC-21’s browser test records every list answer the page receives with page.on('response') and reads each body with response.json(), to check that it narrows as an AttachmentList. After deleting a file it reloads the page. The card removes the file on the delete’s 204 and then re-reads the list in the background, so the row is gone before that re-read answers. When the re-read’s answer arrived just before the reload, the listener’s body read ran after the page had navigated, and Playwright refused it: “Response body is not available for a response that was navigated away from”. The test failed about one attempt in six on an idle Mac, and in two nightly runs.

Change made

The test starts page.waitForResponse for the list’s next answer before confirming the delete, and waits for it and for the listener’s pending body reads before it reloads.

Lesson

  • A test that reads answer bodies from a page.on('response') listener waits, before a reload or goto, for the answer of every read still in flight and for the listener’s body reads. A body can be read only while the page that received it has not navigated.
  • A write whose screen updates before its background re-read answers (a cache update on the 204, then an invalidation) leaves that re-read in flight after every visible check has passed. Start waitForResponse for it before the action, since the answer may arrive before the test’s next line runs.

L-304 — An exception written into a rule outlives the screen it excused, and quietly covers what is added there later

  • Date: 2026-11-16
  • Source commits in this repo: .forge/bugs.md BUG-444 (the fix is altrium-io/forge-et-fe#546); .forge/design/ui/design-system.md Rev 133; .claude/agents/frontend-reviewer.md (the row-actions check)
  • Sync target: upstream
  • Synced: pending

Problem observed

Design-system Rev 94 said the auction-sales table would “keep plain buttons in their last column”, when that column held one Edit dates button. BUG-422 later added Delete Sale beside it. The plan, the review and the prototype all read the exception as permission, so the table shipped with two buttons per row, unlike every other CRM list table. The lead noticed it by eye.

Change made

Rev 133 withdrew the exception and states the rule with its one remaining exception (a table inside a dialog whose rows have a single action). forge-et-fe’s pinnedFirstColumn.test.tsx now fails any feature file that uses the plain actions cell outside a two-file allow-list, and frontend-reviewer checks row actions against the rule, not against an exception.

Lesson

  • An exception to a UI rule names what it excuses and why, and is enforced by a list a test reads, so a later change that widens it fails the test instead of passing review.
  • A reviewer checks an exception against the rule it excepts, not only against the plan: if the reason no longer holds for what is there now, the exception goes.

L-305 — A response-time target says where it is measured from, because a far network path measures the distance

  • Date: 2026-11-16
  • Source commits in this repo: .forge/specs/F20-g-email-tracking-scheduled-send-findings.md F-002; .forge/plans/F20-g/F20-g-WI-3.1-record.md R-10; .forge/owed.md (“Decide NFR-3’s measure after F20-g’s wave-3 run”)
  • Sync target: upstream
  • Synced: pending

Problem observed

F20-g’s NFR-3 asked for the 95th percentile of each tracking endpoint’s response at or under 300 ms, measured with curl “from outside AWS”. The dev run measured it from Sri Lanka against us-east-1: 0.97 s and 1.18 s on new connections, 0.35 s and 0.49 s on one reused connection. One network round trip was about 0.27 s, and a new TLS connection needs several, while the server’s own time was about 0.06–0.07 s. The target failed on distance alone, which the run sheet’s review had predicted, and AC-31 was left unmet.

Change made

AC-31 carries a Not met note, and the choice between revising the spec’s method and accepting the figure is an owed.md item. The run recorded the times in parts (connect, server wait, total), so the server’s share could still be read.

Lesson

  • A response-time requirement names where it is measured from and what it counts: the server’s own time (measured inside the hosting region, or from the server’s logs), or the user’s whole wait from a named place. A total from an unnamed place outside the hosting region mostly measures the network path, and the server cannot meet it by being faster.
  • When the measurement must be from far away, record the time in parts — connect, time to first byte, total — on a new and on a reused connection, so the server’s share can be worked out.
  • A spec reviewer can catch the next instance by asking, for every millisecond target: “measured from where, and does the network round trip alone already exceed it?”

L-306 — A browser test that searches seeded data reads a result no other test’s records can crowd out

  • Date: 2026-11-16
  • Source commits in this repo: .forge/bugs.md BUG-454; forge-et-fe PR #553
  • Sync target: upstream
  • Synced: pending

Problem observed

The account list’s AC-4 test searched vol and expected Volga Tea Imports, a seeded account, on page 1. Other tests in the same run create accounts named E2E f32c … <token>, with a random base-36 token. One run’s token contained vol, so page 1 of the search held those accounts and not Volga. The test failed on its run, on its retry, and alone afterwards, because the accounts stay in the database.

Change made

The test opens the list sorted by name, descending. Generated names start E2E, which sorts after Volga, so they cannot push it off page 1. The search term stays vol, as the spec’s AC states.

Lesson

  • A test that searches or lists data it did not create reads a result other tests’ records cannot crowd out. Order the list so the expected row comes first, narrow it with a filter only the seeded row passes, or search for a record the test created with its own run token. Random tokens contain any short run of letters sooner or later, and a database the browser runs share keeps every record created earlier.
  • frontend-reviewer can catch the next instance by asking, for every search or list assertion on seeded data: “what if another test created many records that also match?”

L-307 — A test that releases or aborts a held request waits until the mock holds it

  • Date: 2026-11-16
  • Source commits in this repo: .forge/bugs.md BUG-441; forge-et-pwa PR #144; BUG-515 (forge-et-pwa#196: edit-details.spec.ts read the held PATCH, and released the held re-read, after only a UI change; card-read-again.spec.ts aborted the held Read Again the same way); BUG-491 and BUG-538 (forge-et-pwa#208: lead-customer-check.spec.ts and lead-customer-check-a11y.spec.ts released held checks on seeing only Checking… or Checking again…)
  • Sync target: upstream
  • Synced: pending

Problem observed

The capture app’s lost-import-answer test set the import to hold, clicked Import, saw the button turn busy, and called abortHeld(). The button turns busy as soon as the click starts the request, before the request reaches Playwright’s route. Under load the abort ran first, found nothing held and did nothing. The import then waited for ever, so the Not confirmed message never came (1 run in 10 at load 40 to 90 on 8 cores).

Change made

Before aborting, the test polls the mock’s own requests list until the import is there. The mock records a request and holds it in the same synchronous step, so once the request is listed it is held.

Lesson

  • A test that releases or aborts a held request first waits until the mock holds it, by the mock’s own record of the request (list.requests, api.requests) or Playwright’s page.waitForRequest. A busy button or a spinner says the app started the request, not that the route has it.
  • The capture app’s campaigns.spec.ts and plan-offline.spec.ts already wait this way; frontend-reviewer dimension 14 checks that every release(), abortHeld() and read of a held request follows such a wait (added after BUG-515, the second instance).

L-308 — A check carried from an earlier commit measures a merge of the base branch by its resolutions, not by the diff since that commit

  • Date: 2026-11-18
  • Source commits in this repo: .forge/design/harness/test-run-cost.md W-5; forge-et-be PR #457
  • Sync target: upstream
  • Synced: pending

Problem observed

The local test records carried an earlier record forward when git diff <recorded> <head> showed only documentation. After main was merged in, that diff also held every commit main brought, so it was never documentation only. forge-et-be#457’s merge changed four lines of docs/api/README.md beyond what git merged by itself, yet its 100-minute full record had to run again, while more PRs landed on main.

Change made

The records walk back from the head along first parents. They pass a merge of main when every path it decided itself is documentation no test or build step reads, and pass a documentation-only commit. They stop at a recorded commit. The first version read the merge’s own paths from git show --remerge-diff --name-only. The backend review found that this lists nothing for a modify/delete, rename/rename or binary conflict resolved to the version git left in the tree, because such a conflict leaves no markers. One of those resolutions left two classes with the same name, which does not compile.

Lesson

  • To judge what a merge of the base branch added to a branch, read the paths the merge decided itself, not the diff from a commit before it. The diff counts the base branch’s commits as the branch’s own, and they were checked on the base branch.
  • The paths a merge decided are its conflicted paths plus the paths where it differs from git’s automatic merge. git merge-tree --write-tree --name-only -z <p1> <p2> gives the automatic tree and the conflicted paths; git diff --name-only <tree> <merge> gives the rest. git show --remerge-diff alone misses a conflict that left no markers.
  • Pass a merge only when its second parent is on the base branch; any other merge brings untested commits.

L-309 — An agent that holds the machine’s run lock can stop and leave the lock and its build processes behind

  • Date: 2026-11-18
  • Source commits in this repo: .forge/specs/F36-b-ai-card-reading-findings.md F-002; .forge/plans/F36-b/F36-b-wave-3-overnight-log.md (18:20 to 20:02 UTC on 2026-11-17)
  • Sync target: upstream
  • Synced: pending

Problem observed

Sessions sharing one machine agreed per-session heavy-run lock directories. A sub-agent hit the account’s usage limit mid-run while it held its session’s lock. Its Gradle daemon and test worker kept running, and another session waited about an hour and three quarters for a lock nobody would release. After a resume, an agent that ran its lock-wait loop in the background ended its turn at once and reported nothing.

Change made

The orchestrator matched the leftover processes to the lock’s timestamp, stopped them, and removed the lock. It told the waiting session, and resumed the agent with two rules: Gradle runs with --no-daemon, and the lock is removed in the same shell command as the run. Every later run on the machine followed them.

Lesson

  • Release a run lock in the same shell command as the run it guards, whatever the run’s exit (mkdir <lock> && <run>; e=$?; rm -rf <lock>), and run Gradle with --no-daemon. Then an agent that stops mid-command leaves no lock and no daemon behind.
  • A sub-agent waits for another session’s lock in a foreground loop. A background wait ends the agent’s turn, and its report never comes.
  • When a lock outlives its owner, match the running processes to the lock’s timestamp before stopping anything, and tell the waiting session.

L-310 — A direct Playwright run on a shared machine can test another session’s dev server

  • Date: 2026-11-18
  • Source commits in this repo: .forge/specs/F36-b-ai-card-reading-findings.md F-003; forge-et-pwa#159’s review fixes
  • Sync target: project-only
  • Synced: pending

Problem observed

corepack pnpm exec playwright test <spec> --project=chromium in the capture app failed every test with “element(s) not found”. The page snapshot showed the CRM’s sidebar. Outside the browser gate, the configuration reuses whatever server is on its default port, and another session’s forge-et-fe dev server was listening there.

Change made

The same specs were run with E2E_GATE=1, which starts the worktree’s own dev server on the gate’s port (15174), and passed 28 of 28.

Lesson

  • On a machine other sessions use, run a frontend’s Playwright specs with E2E_GATE=1, or through pnpm e2e:gate, so the run starts its own server on its own port instead of reusing one.
  • When every test fails at its first assertion, read the first failure’s page snapshot (test-results/<test>/error-context.md) before the code. It shows which app answered.

L-311 — Ids a harness branch takes are invisible to other sessions until it has an open PR

  • Date: 2026-11-18
  • Source commits in this repo: .forge/specs/F36-b-ai-card-reading-findings.md F-004; forge-et-harness#1475
  • Sync target: upstream
  • Synced: pending

Problem observed

F36-b’s harness wave branch took BUG-465, BUG-466 and design-system Rev 137 to 139 on 2026-11-17, and opened its PR the next day. By then main had its own BUG-465, an open PR claimed BUG-466, and Rev 137 was held. Two bugs and three revisions were renumbered, with every reference changed: tracker entries, plans, PR descriptions. A pushed commit’s message still carries the old bug number.

Change made

The bugs became BUG-467 and BUG-468 and the revisions Rev 138 to 140. A comment on the open PR that held BUG-466 said which test it lists was already fixed, under BUG-467. On 2026-11-18 next-id.py began reading pushed branches with no PR as well (.forge/design/harness/ids-on-pushed-branches.md), so pushing a branch that has taken an id is now enough. Do not open the wave PR early as a draft, as the lesson below says: a checkpoint PR that copies the wave branch’s ids would then fail --check-pr against it.

Lesson

  • next-id.py sees main and open harness PRs, not pushed branches. A number held only on a branch with no PR can be taken by anyone.
  • Open the harness PR, as a draft, as soon as its branch takes its first id (a bug, a lesson, a design-system revision), and run python3 .claude/lib/next-id.py --check-pr <N> before it merges.

L-312 — A migration takes the next number on main, never a number above another feature’s unmerged one

  • Date: 2026-11-18
  • Source commits in this repo: .forge/specs/F11-i-person-search-switch-findings.md F-001; .forge/plans/F11-i/F11-i-overnight-log.md D-21; forge-et-be PR #469
  • Sync target: project-only
  • Synced: pending

Problem observed

F11-i’s backend plan took V79 so as not to collide with F36-c’s V78, which existed only on F36-c’s unmerged branch. main ended at V77, and GrantSchemaSpec requires the applied versions to be a contiguous run from 1, so the branch could never pass the full check on its own. It failed once, after a 76-minute run. The plan review approved the number without seeing the gap.

Change made

The migration was renumbered to V78, the next number on main. The rule agreed with F36-c was that whichever feature merges second renumbers its migration; F11-i merged first and told F36-c on its PR.

Lesson

  • A migration takes the next free number on origin/main, whatever other branches hold. When another feature’s unmerged branch holds the same number, the feature that merges second renumbers its migration and the references to it. Reserving a higher number leaves a gap that GrantSchemaSpec refuses. This is L-070’s rule across features rather than within one wave.
  • plan-reviewer can catch the next instance: a plan whose migration number is not origin/main’s highest plus one is a finding.

L-313 — A Sonner toast raised again is given a new id, never the id of one being closed

  • Date: 2026-11-18
  • Source commits in this repo: .forge/specs/F11-i-person-search-switch-findings.md F-002; forge-et-fe PR #574 (commit c6ff10c2)
  • Sync target: upstream
  • Synced: pending

Problem observed

The Lead Research page closed its earlier failure toast at the start of the next save and raised the next failure under the same fixed id. In Sonner 2.0.8, toast.dismiss(id) marks the entry for deletion one frame later and removes it by id about 200 ms after that. A toast created with the same id inside that window is merged into the closing entry and removed with it, so a second refusal showed no message at all.

Change made

Each failure toast gets its own id, <base>-<n>, kept in a ref; the page dismisses the open toast by that ref, and the toast’s own dismiss handlers clear the ref only when it still holds their id. A component test holds the second request until the first toast carries data-removed="true", then answers it; it failed on the old code.

Lesson

  • When a page closes a toast and may raise another of the same kind, it gives the new one its own id. A fixed id is safe only for a toast that is updated in place and never dismissed and re-raised. Keep the stable testId for tests; vary only the toast’s id.
  • frontend-reviewer can check every toast.dismiss(<fixed id>) that is followed by toast(…, { id: <the same fixed id> }).

L-314 — An unattended session follows the owner’s newest explicit answer and only notes a conflict with an older one

  • Date: 2026-11-18
  • Source commits in this repo: .forge/specs/F11-i-person-search-switch-findings.md F-003; .forge/specs/F11-i-person-search-switch-spec.md Rev 3; .forge/plans/F11-i/F11-i-overnight-log.md D-9 and § Morning review
  • Sync target: upstream
  • Synced: pending

Problem observed

Before logging off, Dinil answered “the switch starts on everywhere”. His own owed.md row of 11 Nov said it should stay off until Empire’s written agreement and Exa’s data processing agreement were in place. The spec review flagged the conflict, and the overnight session kept “on” but added a new rule — turn the switch off before real leads enter an environment — to the spec, the UAT checklist, the cloud-gated register and two owed.md rows. In the morning Dinil rejected it: Empire had already agreed. Removing it took a spec revision, two plan revisions, a register change and a fresh-context reword review.

Change made

The rule was withdrawn everywhere (F11-i spec Rev 3, F11-c Rev 10, lead-research-source-options.md Rev 13, WI-1.1 plan Rev 2); the agreement and the DPA stay owed in owed.md, not as a gate.

Lesson

  • In an unattended run, the owner’s newest explicit answer wins over anything older they wrote. Build to that answer, and record the conflict with the older note in the run’s log for the owner to settle. Do not resolve the conflict by inventing a new rule, step or gate the owner never asked for: undoing one costs more than the morning question it was meant to avoid.
  • spec-reviewer raising such a conflict as a Blocker is right; the fix recorded at the gate is “kept the owner’s answer; conflict logged for the owner”, not a new requirement.

L-315 — Every heavy run on a shared machine takes one machine lock, whoever starts it

  • Date: 2026-11-18
  • Source commits in this repo: .forge/specs/F11-i-person-search-switch-findings.md F-004; .forge/plans/F11-i/F11-i-overnight-log.md § Other sessions
  • Sync target: project-only
  • Synced: pending

Problem observed

Three sessions (F11-i, F36-b, F36-c) ran on one machine overnight. The harness’s shared heavy-run lock covers the local records, the browser gate and the nightly run, but agents’ own ./gradlew check and targeted Gradle runs, bootRun and Playwright runs outside the gate take no lock. F11-i’s verify backend and a Gradle build ran beside F36-c’s full build, which took about 5 hours instead of about 85 minutes. The F36 sessions had agreed their own per-ticket lock directories (worktrees/<ticket>/.heavy-run.lock), which F11-i did not know to check until F36-c sent a message.

Change made

F11-i followed the F36 sessions’ rule from then on: before any Gradle build, bootRun, full suite or Playwright run, it checked every other ticket’s lock directory, waited while one existed, and took its own.

Lesson

  • On a machine shared by parallel sessions, every heavy run takes the one machine lock — a full or targeted Gradle build, bootRun, a Playwright run, a local record, the browser gate — not a lock per ticket that other sessions must know to look for. A per-ticket lock only works when every session knows every other ticket’s name. L-309 covers releasing such a lock when its holder stops.
  • The change belongs in .claude/rules/test-record.md’s heavy-run lock and in the agent prompt template’s § Shared machine lock (an owed.md row holds the framework change).

L-317 — The frontends’ Content-Security-Policy exists only on deployed environments, so no local run checks against it

  • Date: 2026-11-18
  • Source commits in this repo: .forge/bugs.md BUG-473; forge-et-pwa src/ui/brand/Logo.tsx, scripts/validate-pwa.mjs, vite.config.ts
  • Sync target: upstream
  • Synced: pending

Problem observed

The capture app’s logo was imported with ?inline, so it shipped as a data: URL. CloudFront serves the capture app with img-src 'self' (.forge/design/environments-and-identity.md §4), which blocks data: images, so the logo was a broken image on dev. Unit tests, pnpm dev, pnpm preview and the browser gate all passed, because none of them sends a policy. The same cause already blocks the capture app’s blob: photo previews on dev (.forge/owed.md, “Allow blob: images in the capture app’s CSP”).

Change made

The logo is imported as a file, the service worker’s allow-list gained .webp so the file shows offline, and vite.config.ts sets build.assetsInlineLimit: 0 so Vite never inlines a small asset by size. validate-pwa.mjs, run by pnpm build, now fails a build whose JS or CSS carries an image, font or media file as a data: URL.

Lesson

  • Before a frontend change loads anything from a new kind of source — a data:, blob: or other-origin URL, an inline style or script, a frame — check it against that app’s policy in environments-and-identity.md §4. Nothing local will report the violation; it shows only as a console error on a deployed environment.
  • In forge-et-pwa, import an image or font as a file, never with ?inline, and add its type to SHELL_EXTENSIONS in shouldCache.ts and public/sw.js when it is new, so the worker serves it offline.
  • When a change needs the policy itself to change, the change is a forge-et-iaac PR to dev, and the deployed check is a row in .forge/cloud-gated-validation.md.

L-318 — A plan that changes a class’s constructor lists every test that builds the class directly

  • Date: 2026-11-18
  • Source commits in this repo: .forge/specs/F37-a-weekly-price-broadcast-findings.md F-001; .forge/plans/F37-a/F37-a-WI-1.1-plan.md ## Notes (the subtask 8 escalation) and Rev 2
  • Sync target: upstream
  • Synced: pending

Problem observed

F37-a-WI-1.1’s plan added three constructor-injected collaborators to F26-d’s PriceEmailService and also required, as a success criterion, that every existing spec under priceemail/ pass unedited. PriceEmailServiceSpec.groovy builds the service with new PriceEmailService(…), so its 33 features failed with Could not find matching constructor. The implementer stopped, as it should for a needed file outside ## Files to Modify, and the plan needed a revision mid-implementation. The plan author and two plan-review passes had not searched the tests for direct construction. Dependency injection hides the constructor from production callers, so the class looks safe to change; tests that build it by hand are the callers left.

Change made

WI-1.1’s plan Rev 2 added the spec to ## Files to Modify and to the success criterion’s exceptions, for its constructor call only. A plan-reviewer check is a framework change for a follow-up PR (F37-a Reflect). That PR (2026-11-18) added the check to .claude/agents/plan-reviewer.md §5 and the author’s side to .claude/skills/forge-plan-author/SKILL.md § 3 (## Files to Modify).

Lesson

  • When a plan adds, removes or reorders a constructor parameter of an existing class, it runs git grep -n 'new <ClassName>(' -- src/test (and the frontend equivalent for a class or a factory) and lists every hit in ## Files to Modify, with the reason “constructor call only”.
  • A success criterion that says existing tests pass unedited is checked against that search before approval. If a hit exists, the criterion names the file as an exception or the plan changes the approach.
  • plan-reviewer checks both when a plan’s ## Decisions or ## Files to Modify change an existing class’s constructor.

L-319 — An infrastructure change a handler consumes is held as a draft PR until the handler runs where the change applies

  • Date: 2026-11-18
  • Source commits in this repo: .forge/specs/F37-a-weekly-price-broadcast-findings.md F-002; .forge/plans/F37-a/F37-a-decomposition-plan.md ## Notes item 1; .forge/plans/F20-g/F20-g-decomposition-plan.md ## Notes item 2
  • Sync target: project-only
  • Synced: pending

Problem observed

F20-g’s scheduled-email-send and F37-a’s price-broadcast-send schedules each needed a forge-et-iaac change that must not reach dev before the backend handler for the job kind is deployed there. Every merge to forge-et-iaac dev runs terraform apply, and a schedule that fires before its handler exists is refused every minute and dead-lettered. A per-wave gate blocks dispatch, not merge, so it cannot hold this back. Both features worked out the same answer in their own Decomposition Plan Notes: dispatch the infrastructure wave at once, open its PR as a draft, and mark it ready only after the code wave is merged and running on dev. Nothing outside those two plans states it, so the next feature with a new schedule or queue has to find it again.

Change made

F37-a’s wave 2 (forge-et-iaac#20) stayed a draft until dev’s running backend (task definition 151, image build-b901e4bb) was confirmed to contain wave 1’s merge commit; it then merged and applied with no refused firing and the dead-letter queue at 0. A line in .claude/rules/forge-et-iaac.md is a framework change for a follow-up PR (F37-a Reflect). That PR (2026-11-18) added the rule there, with pointers to it in /forge-wave-decompose step 5b (no gate for such a change) and in /forge-deliver Stage 7’s “Work items in forge-et-iaac” step 4 (open the PR with --draft).

Lesson

  • A forge-et-iaac change that a backend handler consumes — a schedule, a queue’s consumer wiring, a route — goes in its own wave with no gate, opened as a draft PR. It is marked ready only after the code wave’s PR is merged and dev’s running task definition is confirmed to use an image that contains it (aws ecs describe-services, then the image’s commit). The PR body says why it is a draft.
  • The same applies to each later environment: base/ is shared, so the next UAT or production apply from a dev that holds the change creates it there too, and that environment’s backend must already include the handler. Give it an owed.md row for the owners of those applies.
  • A per-wave gate is the wrong tool here: it blocks dispatch, and the infrastructure work can be planned, reviewed and opened in parallel with the code.

L-320 — Before filing a bug, search the open harness PRs for the same test, not only main’s bugs.md

  • Date: 2026-11-18
  • Source commits in this repo: .forge/specs/F36-a-capture-and-upload-findings.md F-004; .forge/bugs.md BUG-471 and BUG-474; related to L-311
  • Sync target: project-only
  • Synced: pending

Problem observed

The capture app’s local-record test “carries a record across a merge of main” timed out on Windows in two sessions on 2026-11-18. One session filed BUG-471 on the F36-a wave 5 harness branch, whose PR had not merged; a few hours later another filed BUG-474 on main for the same test, and Biseni claimed it. Neither could see the other: a bug filed on an unmerged branch is not in main’s bugs.md, and next-id.py (L-311) keeps the numbers apart but does not compare what the entries describe. The duplicate came to light only when harness#1476 merged main in, after BUG-471’s fix had already merged.

Change made

BUG-474’s Fix: line now points at BUG-471’s merged fix (forge-et-fe#580, forge-et-pwa#168); Biseni keeps her claim and closes it, and a comment on harness#1476 told her.

Lesson

  • Before filing a bug for a failing test, search the open harness PRs as well as main: gh pr list --repo <github-org>/<harness-repo> --state open --json number --jq '.[].number', then gh pr diff <N> --repo <github-org>/<harness-repo> | grep -n '<test name or file>' for each, besides git grep on origin/main. A bug for the same test in an open PR is extended with the new occurrence (a “Seen again” line), not filed again.
  • Searching by the test’s file and name finds it, where a title search does not: the two entries above had different titles and severities for the same test.
  • A duplicate found after the fact is pointed at the other entry, not closed for its owner: the person who claimed it confirms and closes it.

L-321 — A test that acts as soon as an element appears cannot also check the state before that action

  • Date: 2026-11-18
  • Source commits in this repo: .forge/bugs.md BUG-436; forge-et-pwa#148
  • Sync target: upstream
  • Synced: pending

Problem observed

The capture app’s camera-refused browser test failed under load on Windows: it timed out waiting for the camera-off message, and on its retry for the Choose a Photo button. The spec had installed choosePictureWhenShown, an init script that gives the file input a picture the moment the input appears. The input appears only in the camera-off state, and the chosen photo’s preview replaces that state at once. On an idle machine Playwright’s first poll still caught the message; under load the photo had already replaced it. Under forced load it failed 8 of 20 runs. The bug’s first guess was a longer assertion timeout, which would not have helped: the state was gone, not late.

Change made

The spec asserts the camera-off message and the button first, then presses Choose a Photo itself through choosePicture, which answers the file chooser with the same picture. 40 of 40 runs passed under the same load.

Lesson

  • A helper that acts when an element appears (an init script with a MutationObserver, a pressWhenShown, a route that answers at once) leaves the state before its action on screen for no fixed time. A test that asserts that earlier state races the helper. Assert the earlier state first, then take the action from the test, so the test decides when the state changes.
  • Such helpers are right for page states and specs that check only the state after the action. Before using one, check whether the test also asserts anything the action removes.
  • When a flaky assertion’s element is missing rather than slow, look for something that replaced it before reaching for a longer timeout. A failure snapshot that shows the next state (here, the photo preview and Retake) is the sign.

L-322 — A Vitest test that times out keeps running, so its retry’s failure message is not a second defect

  • Date: 2026-11-18
  • Source commits in this repo: .forge/bugs.md BUG-450
  • Sync target: upstream
  • Synced: pending

Problem observed

forge-et-fe’s “AccountsFilters › reports each tick” timed out at 20 s in one full pnpm test:record on Windows, and its retry then failed with a different message: the last onChange call was not { customerTypes: ['Importer'] }. That looked like a second, functional defect. It was not: Vitest marks a timed-out test failed but does not stop it. The first attempt kept running after cleanup() and after the retry rendered. Its helpers query the global screen and send keys to document, so its later Escape and clicks closed the retry’s popover, and the retry’s click on Importer did nothing. Holding the first attempt back just before its Escape until the retry’s list was open reproduced the retry’s failure every time.

Change made

None to the test: the 20 s timeout did not reproduce under forced load, and the retry’s message is explained by the first attempt. The bug’s Resolved: line records both.

Lesson

  • Triage a timed-out test by its first failure. When a retry, or the next test in the same file, fails right after a timeout with an assertion that has nothing to do with time (a missing dialog, a wrong last call), treat it as the timed-out attempt still acting on the new screen, not as a separate defect.
  • To check it, hold the first attempt back at its next action until the retry or the next test has rendered: if the second failure then appears every time, it follows from the first.

L-323 — A write that puts its answer into the query cache must cancel the record’s read again just before it does

  • Date: 2026-11-19
  • Source commits in this repo: .forge/bugs.md BUG-481; forge-et-pwa#179 (and F36-c’s aee3a44 on forge-et-pwa#171)
  • Sync target: upstream
  • Synced: pending

Problem observed

The capture app’s writes on a captured lead (Research Again, the person removal, Read Again, and convert, reject and reopen) each cancelled the lead’s detail read in TanStack Query’s onMutate, then wrote the server’s answer with setQueryData in onSuccess. A read that started while the write was out (a 5- or 10-second re-read on a lead being read or researched, a reconnect) was not cancelled. It could answer after the write’s answer and put back the lead as it was before the write. F36-c found it on the two research writes (I-12); a review of that fix found it on Read Again (BUG-481), and the fix for that found it on the review writes too.

Change made

Each of those onSuccess handlers is now async and awaits client.cancelQueries({ queryKey: <the record's detail key>, exact: true }) before setQueryData. Each fix has a hook test that holds the write, starts a read during it, answers the write, then answers that read with the older record, and asserts the write’s answer stays. Each test fails without the fix.

Lesson

  • Cancelling in onMutate covers only reads already out when the write starts. Any write that puts its answer into the cache also cancels the record’s read in onSuccess, right before setQueryData. A write that reads the same query again after its answer instead does not need it: invalidateQueries on that query in onSuccess or onSettled cancels a read still out and fetches again (useSaveLeadDetails, the capture app’s campaign and notification writes).
  • Test the late read, not only the early one. The usual test starts a read before the write. The race needs a read started during the write and answered after it.
  • When one write in a file shows the race, check every write in that file and its siblings for the same onMutate-only cancel before closing the fix.

L-324 — Two Radix parts composed on one element share one data-state; style the inner part on its ARIA state

  • Date: 2026-11-19
  • Source commits in this repo: .forge/bugs.md BUG-488 (the selected saved view’s tab never looked selected, forge-et-fe#586)
  • Sync target: upstream
  • Synced: pending

Problem observed

The CRM’s saved-views row wraps each saved view’s TabsTrigger in a TooltipTrigger with asChild, so one <button> is both. Radix’s Tabs sets data-state="active" on the selected trigger, and Radix’s Tooltip sets data-state too (closed, delayed-open), on the same element. The Tooltip’s value won, so the shadcn pill tab’s selected look, written as data-[state=active]: classes, never drew on a saved view’s tab. Only the default tab, which has no tooltip, ever looked selected. The unit tests checked aria-selected, which was right, so nothing failed; Nanndish found it by eye in a UI review, a week after the row shipped.

Change made

forge-et-fe#586 draws the selected tab on aria-selected: classes (ViewsRow.tsx SELECTED_TAB_CLASS), which the Tooltip does not touch, and its test checks the classes on a saved view’s tab whose data-state is not active. frontend-reviewer dimension 34 now flags the pattern.

Lesson

  • When one element is two Radix parts (asChild composition), only one data-state survives. Style and test the inner part’s state on its ARIA attribute (aria-selected, aria-pressed, aria-expanded), which each part owns separately, never on data-[state=…].
  • A test of a visual state checks it on the element as composed, not on the bare component: a unit test of TabsTrigger alone would have passed.

L-325 — Decode a URL an outside service returns the way that service encodes it, and test with one it really returned

  • Date: 2026-11-19
  • Source commits in this repo: .forge/bugs.md BUG-497 (the live inbox refused the second page of a category, Focused or Other view; forge-et-be#486, whose commits and test names call it BUG-495, the number it held before a clash); .forge/plans/F20-i/F20-i-WI-5.1-record.md R-9
  • Sync target: upstream
  • Synced: pending

Problem observed

The live inbox keeps Graph’s @odata.nextLink inside its page cursor and, when the cursor comes back, checks that the link’s $filter equals the filter the request asks for. GraphMailboxProvider.PageCursor decoded the link’s query with URLDecoder.decode(component.replace("+", "%2B")), which reads + as a plus: the encoding the CRM’s own requests use (%20 for a space). Graph writes its links form-encoded, a space as + and lower-case escapes, so on real Graph the filter never matched and every second page of a filtered view was refused. The tests built their links with UriUtils.encode, the CRM’s encoding, so they passed; the same file’s ConversationCursor form-decoded and worked. The spec had named the question (WI-3.1 escalation E-20, “whether a filtered page’s nextLink keeps the $filter text exactly”), and only the laptop walk against a real mailbox answered it, two weeks after the code merged.

Change made

forge-et-be#486 form-decodes the query of the link (+ a space, %2B a plus) and keeps the plus-preserving decode for path segments, and its tests follow a link written exactly as Graph wrote it in the walk. backend-reviewer now flags the pattern.

Lesson

  • A URL, link or token an outside service hands back is parsed in that service’s encoding, not in the one the code uses to build its own requests. For a query string from a .NET service such as Graph, that is form encoding (+ is a space); a path segment keeps + as a plus.
  • A test of code that reads such a value uses a value the service really returned, captured from a run against it, not one the test builds with the code’s own encoder: a self-built value only proves the code agrees with itself.

L-326 — A Playwright run whose later check reads testInfo.attach values needs the JSON reporter

  • Date: 2026-11-19
  • Source commits in this repo: .forge/specs/F36-d-existing-client-check-findings.md F-001; .forge/plans/F36-d/F36-d-WI-2.8-test-verify.md (Run 3)
  • Sync target: upstream
  • Synced: pending

Problem observed

F36-d’s journey test records the values it creates with testInfo.attach({ body }), and the log check after the run reads them back from the run’s results. The first run used the list reporter alone. That reporter keeps no attachment body, so the values were gone, the log check had nothing to search for, and the run had to be repeated. The journey spec’s header still gave the command without the JSON reporter.

Change made

The run was repeated with --reporter=list,json and PLAYWRIGHT_JSON_OUTPUT_NAME set to a path outside the worktree, and the log check read the values from that file.

Lesson

  • When a step after a Playwright run reads values the tests attached, the run’s command names a reporter that keeps attachment bodies — --reporter=list,json with PLAYWRIGHT_JSON_OUTPUT_NAME pointing outside the worktree. Write that command in the plan and in the spec file’s header, so a person running it from either place gets the values.
  • The later step fails loudly when the attachments are missing instead of searching for nothing: an empty value list means the run lost them, not that the check passed.

L-327 — On Windows, Git Bash’s grep can abort on a large log; search with a fallback and a control value

  • Date: 2026-11-19
  • Source commits in this repo: .forge/specs/F36-d-existing-client-check-findings.md F-002; .forge/plans/F36-d/F36-d-WI-2.8-test-verify.md (the AC-26 log check)
  • Sync target: upstream
  • Synced: pending

Problem observed

F36-d’s log check searched a backend log of about 24,000 lines for several values at once. On Windows, Git Bash’s grep -n -i -F with several -e patterns aborted with exit status 134, and LC_ALL=C grep -a did the same. An aborted search prints no matches, so without checking the exit status it reads as “the values are not in the log”.

Change made

The search was run as a short Python script instead, together with a control search for a value known to be in the log.

Lesson

  • A plan that searches a large log on Windows gives a fallback (a short Python search) for when grep aborts, and reads the search’s exit status on its own line.
  • Every “this value must not appear” search also searches for a control value that must appear. An empty result then means “not found”, not “the search did not run”. This applies on every platform.

L-328 — A version-based idempotency key is claimed by a write that updates the row, never by the insert that creates it

  • Date: 2026-11-20
  • Source commits in this repo: .forge/specs/F36-c-capture-research-notify-findings.md F-001; F36-c spec Rev 9 (FR-JB3); .forge/plans/F36-c/F36-c-overnight-log.md W3-40; forge-et-be F36-c-WI-3.1 (deviation D-5, merged with forge-et-be#484)
  • Sync target: upstream
  • Synced: pending

Problem observed

F36-c’s research jobs used the key <subject>#<version> (AD #13), and the spec had every research write claim the key of the row it wrote. A subject’s first write inserts its row at version 0 and claimed …#0. A campaign focus edit made before any later write sent its message with the same …#0, and the consumer skipped it as already claimed, so the subject was not ranked again until the hourly sweep. The integration tests found it during the build; the spec rule itself was wrong.

Change made

The writer claims a key only when it updates an existing row (WI-3.1 D-5); a redelivered first message is still stopped by the per-subject lock and the completed-run re-check. Spec Rev 9 states the rule.

Lesson

  • A key built from a row’s version names a change to that row. The write that creates the row has no earlier version to protect, and the next message about the row is sent at the version the insert produced, so the insert must leave that key unclaimed. Guard a duplicate first delivery with a lock or a state check instead.
  • At spec review, walk the key through a row’s first two writes: the insert, then the first change a user can make before any other write. If both would carry the same key, the second is lost.

L-329 — A UI change that rebuilds an element updates every test helper that selects the old element, in the same work item

  • Date: 2026-11-20
  • Source commits in this repo: .forge/specs/F36-c-capture-research-notify-findings.md F-002; .forge/plans/F36-c/F36-c-overnight-log.md W3-42, W3-49; forge-et-pwa 49205e6, 339d568, 71b30e6; .forge/bugs.md BUG-498, BUG-499, BUG-502
  • Sync target: upstream
  • Synced: pending

Problem observed

In F36-c wave 3 a UI work item rebuilt the capture app’s To Review row so that a marker was not inside the row’s button, and later turned the campaign Focus field from an input into a text box. Each change broke tests outside the work item’s own run: a seam helper that looked for the row’s old link (a[data-testid="lead-row"]), four seam tests that read the row’s content inside a link that had become an empty full-card link, and a helper that filled the Focus field as an input. The verify work item found each one later and had to fix it and run again.

Change made

The work item that broke the first helper fixed it (“the change that breaks a test fixes it”, W3-42); the other three were fixed during the verify run (49205e6, 339d568, 71b30e6).

Lesson

  • When a change alters an element’s tag, or what a link or button contains, search every test folder (e2e/seam, e2e/browser, their support/ helpers) for the element’s test id, its role and its tag before the PR, and update each match in the same work item. A helper that fills or reads an element is as bound to its tag as a selector is.
  • The plan names those files. A plan that restructures a shared element lists the helpers and specs that select it in ## Files to Modify, so the review sees them and the verify work item does not find them.
  • A change that puts a new control into a tab order updates every test that asserts what comes next. Search the tests for the test id of the control that used to follow (an afterColumns value, a “next control” constant) and for keyboard walks across that spot. F32-d Rev 6 put Save View after Columns and F36-c put Campaign Focus after Hot / Cold; both PRs left tests expecting the old neighbour, and the nightly full run on main found them (BUG-498, BUG-499), as it found the two seam specs F36-c wave 3 did not run (BUG-502).

L-330 — Run a wave PR’s final records after the other open PRs on the same files have merged

  • Date: 2026-11-20
  • Source commits in this repo: .forge/specs/F36-c-capture-research-notify-findings.md F-003; .forge/plans/F36-c/F36-c-overnight-log.md W3-50, W3-51; forge-et-be#484 (dddf68e5, record on ce975e9f), forge-et-pwa#187 (5199219)
  • Sync target: upstream
  • Synced: pending

Problem observed

F36-c wave 3’s backend and capture-app PRs were reviewed and recorded, ready to merge, when F36-d wave 2 merged to main first. Both features change the capture convert service, its wire test and the To Review row, so both F36-c PRs then conflicted with main. Each needed a merge of main, a delta review of the resolutions and a new local record; the backend’s record alone took 1 h 15 m. F36-d’s merge had been expected that evening.

Change made

main was merged into both PRs, the resolutions were reviewed as deltas, and both were recorded again; the three wave 3 code PRs then merged together.

Lesson

  • Before the final records, list the other ready or nearly ready PRs in the same repository that change the same files (gh pr list --state open --json number,title,files, matched against the PR’s own files). When one is due to merge first, let it merge, merge main once, and record once, after it. A record taken before a known conflict is paid for twice.
  • Two features on the same files agree their merge order in writing, as F36-b and F36-c did (F36-b findings F-001), and the second one records last.

L-331 — After a dependency update moves Playwright, install that version’s browsers before the first browser run

  • Date: 2026-11-20
  • Source commits in this repo: .forge/specs/F36-c-capture-research-notify-findings.md F-004; .forge/plans/F36-c/F36-c-overnight-log.md W3-47, W3-49
  • Sync target: upstream
  • Synced: pending

Problem observed

The November dependency upgrades moved the frontends to a newer Playwright (1.65.1 in forge-et-fe). Playwright keeps its browsers per version and pnpm install does not fetch them, so F36-c’s browser runs on a Windows laptop needed that version’s browsers installed before they could run. The session also reported the machine’s Node version out of step with the repositories’ pin.

Change made

The browsers for both frontends’ Playwright versions were installed (pnpm exec playwright install in each repository), and the runs passed with no code change.

Lesson

  • After merging main or pulling a branch that changes a frontend’s Playwright version, run pnpm exec playwright install in that repository before the first browser run, and check node --version against the repository’s pin. A browser that will not start is the machine’s state, not a test failure, and is not filed as a bug.
  • Each frontend keeps its own Playwright version, so a machine that runs both repositories installs the browsers for each.

L-332 — A test check that encodes a rule a spec revision changed is run against a fresh database

  • Date: 2026-11-20
  • Source commits in this repo: .forge/bugs.md BUG-501; forge-et-fe#593 (the nightly run of 2026-11-20); forge-et-fe#596
  • Sync target: upstream
  • Synced: pending

Problem observed

F32-d Rev 6 stopped drawing the saved-views row for a user with no view to choose. The shared check expectRowMatchesRead still expected the Default tab first in every case. forge-et-fe#586, which built Rev 6, passed views-across-users.spec.ts because its database held a shared account view left by an earlier run, so the test’s second user had a view to choose and the row was drawn. The nightly run starts from an empty database; there the second user had none, no row was drawn, and the test failed (BUG-501).

Change made

The check now expects no tab list when the read holds no view (forge-et-fe#596).

Lesson

  • When a spec revision adds a case where something is not drawn, or is drawn differently, find the shared test checks that assume the old case and give each the new branch, in the same PR.
  • Run the specs that use such a check against a fresh database before the PR is marked ready (docker compose … down -v, then up -d --wait, as .forge/guides/test-runs-explained.md § The nightly full run shows). A developer’s database keeps what earlier runs left, so a test can pass there only because old data keeps the old case alive.

L-333 — A Tailwind utility loses to any unlayered CSS Module rule on the same element; prove it in a browser

  • Date: 2026-11-19
  • Source commits in this repo: .forge/bugs.md BUG-508 (a busy shadcn button drew its leading icon beside the spinner, a recurrence of BUG-274)
  • Sync target: upstream
  • Synced: pending

Problem observed

The CRM loads Tailwind’s utilities inside a cascade layer (src/ui/styles/shadcn.css: @layer theme, base, components, utilities), while its CSS Modules are unlayered. In the cascade an unlayered rule beats every layered one, whatever the selectors’ specificity. The shadcn Button hid a leading icon while busy with [&>[data-leading-icon]+svg]:hidden, but the registry Icon’s module rule .icon { display: inline-block } won, so the icon stayed beside the spinner on every busy button with a leading icon (Refresh on the Email page, the saved views’ ⋯). The unit test checked the class name, and jsdom applies no layers, so it passed; Nanndish found it by eye in a UI review.

Change made

The rule became !important (hidden!), since an important declaration in a layer beats a normal unlayered one. A browser test holds a saved view’s Share request and checks the computed display of the busy ⋯'s glyphs. frontend-reviewer dimension 35 flags the pattern.

Lesson

  • A Tailwind class aimed at an element that also carries a CSS Module class loses on any property the module sets. When the module sets that property (display, width, color, …), use the important form (hidden!) or move the rule into the module; and know which elements carry module classes — every registry Icon does.
  • A test of a rule’s effect reads the computed style in a browser; a class-name assertion in jsdom proves only that the class is there.

L-334 — A popover whose height is capped to the room below never flips; cap a window-bounded list at a fixed size

  • Date: 2026-11-20
  • Source commits in this repo: .forge/bugs.md BUG-509 (the Add Tag list clipped at the window’s bottom edge)
  • Sync target: upstream
  • Synced: pending

Problem observed

The Add Tag popover set max-block-size: min(var(--radix-popover-content-available-height), …). Radix’s positioning flips a popover to the other side only when its measured size overflows, and the available-height variable is the room on the side it is already placed. A popover capped that way always fits where it is: a list a few pixels too tall for the room below scrolled inside the popover, and its last line ended past the window, with ample room above.

Change made

For the Add Tag list only, whose row count is chosen from the window’s height, the cap became a fixed size (12 rows), so the measured size is the real one and Radix flips the popover when it does not fit below. The first version dropped the available-height cap for every caller of the shared picker, and the match modal’s 25 account results then ran 12px past a 320×640 window: neither side held that list, so Radix kept it below at full height. That caller keeps the available-height cap.

Lesson

  • Cap a Radix popover with a fixed size, not with --radix-popover-content-available-height, when it should flip to the side with room and its content is bounded to fit one side. The available height is a fit for a popover whose content may be longer than either side holds: it keeps that list on screen and scrolling, at the cost of never flipping. A shared popover with both kinds of caller takes the choice as a prop.
  • A popover’s fit is proved at the size and position that leave the least room, in the size matrix, not only where the trigger happens to sit on the default page.

L-335 — In Git Bash, set MSYS_NO_PATHCONV=1 on the one command whose argument starts with /

  • Date: 2026-11-20
  • Source commits in this repo: .forge/specs/F43-ai-quota-backlog-and-busy-answer-findings.md F-001; .forge/plans/F43/F43-WI-5.1-record.md (R-7’s attempt 2, R-4’s attempts 2–4)
  • Sync target: project-only
  • Synced: pending

Problem observed

F43’s dev-run sheet was written on a Mac. Run in Git Bash on Windows, aws logs filter-log-events --log-group-name /ecs/dev/backend failed with InvalidParameterException: Git Bash had rewritten /ecs/dev/backend into a Windows path. Exporting MSYS_NO_PATHCONV=1 for the whole command line fixed the AWS argument but broke the native jq and git -C calls on /c/Users/... paths in the same line (L-181), and date -u -r <seconds> read a file’s time instead of formatting a timestamp.

Change made

None to the harness. The run put MSYS_NO_PATHCONV=1 in front of the AWS command alone, wrote local paths as C:/…, and used date -u -d @<seconds>.

Lesson

  • In Git Bash, put MSYS_NO_PATHCONV=1 in front of the single command whose argument starts with / and is not a file path (an AWS log-group name, a git show <ref>:<path>), never export it for a script that also passes /c/… paths to native tools.
  • A run sheet that may run on Windows avoids BSD-only forms: date -d @<seconds> (GNU) instead of date -r <seconds> (BSD), and no pbcopy / pbpaste; or it says which shell it was tried in.

L-336 — A command block a person pastes into zsh must not rely on word splitting or exit

  • Date: 2026-11-20
  • Source commits in this repo: .forge/specs/F20-i-live-inbox-findings.md F-001; .forge/plans/F20-i/F20-i-WI-5.1-plan.md (the note under step 2.1)
  • Sync target: upstream
  • Synced: pending

Problem observed

F20-i’s WI-5.1 run sheet said every command worked in zsh and bash, and it passed a two-pass /forge-plan-review. Step 2.1 looped with for spec in "inline 200" "attach 64"; do set -- $spec; …. zsh, the default shell on macOS, does not split an unquoted variable into words, so $1 held the whole string and $2 was empty. The block also ended a failure with || exit 1 inside a { …; } group, which closes an interactive terminal. The same set -- $var shape failed again in a Claude Code command at F20-i’s Reflect, because Claude Code’s Bash tool runs zsh on macOS.

Change made

The run sheet was corrected before the run reached the step: a function called twice with &&, checked in zsh and in bash, with a note under step 2.1. A follow-up harness PR adds the check to forge-plan-author’s run-sheet case and to plan-reviewer (.forge/owed.md).

Lesson

  • In a block a person pastes, or a command Claude runs on macOS, split values without word splitting: call a function once per case (run inline 200 && run attach 64), or use ${=var} only in a zsh-only block; never set -- $var or for x in $list on an unquoted variable meant to split.
  • Never exit in a pasted block. It closes the person’s terminal. End a failure with return inside a function, or let the command’s own status stand.
  • A block that claims “zsh and bash” is run once in each before review, and the reviewer checks for set -- $, an unquoted for … in $, and exit.

L-337 — A waiter on a shared lock that nobody yields to never gets it while others hand it on; give the job that must run a reservation

  • Date: 2026-11-21
  • Source commits in this repo: .forge/bugs.md § BUG-521; forge-et-harness#1624 and #1626, forge-et-fe#603, forge-et-pwa#198, forge-et-be#495
  • Sync target: upstream
  • Synced: pending

Problem observed

The nightly full run of 2026-11-21 ran no suite. It waited an hour for the machine’s heavy-run lock, looking every 30 seconds, while other sessions’ runs passed the lock from one to the next within two seconds of each release, often the next command of the same session. The lock had no order: whoever looked first after a release took it, and the waiter that looked least often lost every time. A test case written for the fix then failed on a CI runner that had started minutes earlier, because it dated a lock two minutes back and the lock’s boot rule called that a leftover.

Change made

While it waits, the nightly run writes a reservation (et-heavy-run.next) beside the lock, and every taker leaves a free lock to a live reservation, so the nightly run takes the lock at the next release. The reservation never hides a lock the taker already holds (a review found that a Playwright UI run would otherwise wait on itself), and it is ignored once its process has ended, after 90 minutes, or when dated before the boot or more than a minute ahead. The test case now writes its lock at the real time.

Lesson

  • A job that must run on a shared lock gets a reservation that every other taker honours; polling faster only narrows the race, and a taker that starts right after a release (a chained command) never polls at all.
  • A reservation check never hides a lock the caller already holds, and a reservation expires on its own (its process gone, a time limit), so a crashed holder cannot stop the machine.
  • A test of a rule that reads the boot time writes its timestamps at the real time, or passes the boot time in: a CI runner may have started a minute ago.

L-338 — A plan that moves or renames a type searches the whole repository for its name, the build’s own scripts included

  • Date: 2026-11-21
  • Source commits in this repo: .forge/specs/F45-findings.md F-002; .forge/plans/F45/F45-WI-1.1-plan.md ## Notes (the plan revision that added scripts/check-banned-markers.py)
  • Sync target: upstream
  • Synced: pending

Problem observed

F45 WI-1.1 moved the record GraphEmailAddress from GraphMailboxProvider to a new class, GraphWire. Its plan searched src/main, src/test and docs for the old name. forge-et-be’s scripts/check-banned-markers.py also names records by <Owner>.<Record>, and fails on a key that names no record, so the move would have failed the Fast lane. The implementer found it, stopped and escalated, and the plan was revised before the PR opened.

Change made

The plan added the script to ## Files to Modify, and the key became GraphWire.GraphEmailAddress.

Lesson

  • A plan that moves or renames a type lists every file that names it, from a search of the whole repository (git grep -n -w <Owner>.<Type> and git grep -n -w <Type> at the root), not of the source folders alone. Build scripts, CI configuration and check lists that name classes are part of the build and break on a rename just as code does.

L-339 — A plan that moves code into another file runs the checks that see across files, in the move commit

  • Date: 2026-11-21
  • Source commits in this repo: .forge/specs/F45-findings.md F-003 and F-004; forge-et-be 9387d5a2 (the fix on forge-et-be#418), WI-1.2’s move commit d5762cd9
  • Sync target: project-only
  • Synced: pending

Problem observed

Two checks in forge-et-be behave differently once code moves between files. First, a call GraphWire.<@Nullable X>sending(…) made from another file passes a clean compile and CI, and fails NullAway on an incremental compile (the JDK 21 class-file shape of L-216, coding-standards §7.2). WI-1.3’s plan ran scripts/check-incremental-compile.py; WI-1.1’s did not, and the wave head failed it on seven lines, found only by the wave PR’s review. Second, the plans expected a {@link #member} broken by a move to surface only in the package-level Javadoc check, so the links could be fixed in a later wording commit; Error Prone’s InvalidLink runs inside compileJava under -Werror and stopped WI-1.2’s move commit.

Change made

sending takes a SendCall<T> whose @Nullable is on the result (9387d5a2). WI-1.2’s move commit qualified the link (LocalMailboxProvider#DEFAULT_LIVE_ADDRESS); WI-1.1 and WI-1.3 had already planned to.

Lesson

  • A forge-et-be plan that moves code holding a @Nullable type argument into another file includes python3 scripts/check-incremental-compile.py in its checks.
  • A move commit qualifies every same-class Javadoc link whose target stays behind ({@link Owner#member}): the link is checked when the code compiles, not later.
  • In short: a move is checked by the checks that look across files, on the move commit, not only by the clean build.

L-340 — A run sheet that Claude may drive in the browser pane says how accounts are switched and how files are attached

  • Date: 2026-11-21
  • Source commits in this repo: .forge/specs/F45-findings.md F-005; .forge/plans/F45/F45-WI-2.1-record.md (its header and R-16, commits bf70a023f, f6e837f6d); the lead’s waiver in .forge/plans/F45/F45-WI-2.1-plan.md ## Notes
  • Sync target: project-only
  • Synced: pending

Problem observed

F45 WI-2.1’s run sheet was written for a person in two private browser windows. Under the lead’s waiver, Claude drove the Claude desktop app’s browser pane in the person’s session (invariant 4’s exception). Claude does not type passwords, and the pane cannot drive the operating system’s file chooser; Outlook on the web also refused a local file path. The run had to work out both while it ran: the person signed each of the five test accounts in once and the run switched them through Microsoft’s account picker, and pictures were attached by giving the page’s file input the same bytes as the files, with received files compared by a SHA-256 computed in the page.

Change made

The record’s header states both differences once, for every entry, and R-16 records that all five accounts were signed out at the end.

Lesson

  • When a run sheet may be carried out with Claude driving the browser pane, the sheet says from the start: the person signs in each test account once (Claude never types a password) and the run switches accounts through the identity provider’s account picker, signing every account out at the end; files are attached by setting the page’s file input to the same bytes as the prepared file, and a received file is compared by a hash computed in the page.
  • The record names these differences once in its header, so every entry need not repeat them.

L-341 — A PR that moves a screen to shadcn runs that screen’s browser specs, even when it skips the selected run

  • Date: 2026-11-22
  • Source commits in this repo: .forge/bugs.md BUG-534 and BUG-535 (forge-et-pwa#208); BUG-525 and BUG-523’s commit cb55537 (forge-et-pwa#199), the same inert-sheet cause after forge-et-pwa#201; BUG-537, where forge-et-pwa#207 changed the shared Dialog without a browser run and failed nine page checks on main
  • Sync target: upstream
  • Synced: pending

Problem observed

forge-et-pwa#204 moved the lead page’s parts to shadcn, and #205 moved the lead drawer to a modal shadcn Sheet. Both skipped the selected browser run, because in the capture app --selected runs the whole browser suite (about an hour), and relied on the nightly full run. The night after they merged did not run (forge-et-pwa#197). Three browser tests on main were then broken:

  • the drawer makes the page behind it inert, so openLeads with a /?lead= path no longer found the Leads heading by role whenever the drawer opened first (BUG-534, 2 of 5 runs);
  • card-read-again.spec.ts no longer found the To Review row behind the open drawer by its listitem role (BUG-534, every run);
  • the shadcn Button always renders aria-disabled="false", so leads-offline.spec.ts’s not.toHaveAttribute('aria-disabled') failed every run (BUG-535). #205 had already updated the same file’s aria-busy checks for the same reason, but not this one.

The notifications sheet’s move (#201) had the same inert-page effect on the bell’s accessible name (BUG-525, and BUG-523’s fix commit).

Change made

forge-et-pwa#208 queries behind the drawer with includeHidden: true and expects aria-disabled="false". frontend-reviewer check 36 now looks for both patterns in a shadcn move and asks for a run of the moved screen’s own browser specs.

Lesson

  • A move to a modal Radix Sheet or Dialog changes the accessibility tree of the page behind it: it is inert while the sheet is open, so a role or accessible-name query for anything behind it finds nothing. In a test that means to read the page behind, query with includeHidden: true (or read an attribute, as BUG-523’s fix does), with a comment saying why.
  • The shadcn Button always renders aria-disabled and aria-busy, "false" when not set. An enabled or idle button is asserted with toHaveAttribute('aria-disabled', 'false'), never not.toHaveAttribute(...).
  • A PR that moves a screen to shadcn runs that screen’s own browser specs before it merges, even when it skips the full selected run (for a capture-app screen, playwright test e2e/browser/<feature> --project=chromium; the leads folder takes about five minutes). The nightly full run is not a substitute, because a night can fail to run.

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