docs(#3942): ADR — the emitted-drift ack belongs in a commit trailer (#3943)

The acknowledgment explains one PR's unattributable emitted-artifact delta.
The moment that PR merges the delta is in the base, so the acknowledgment can
never clear anything again — its useful life is exactly the PR's open window.
It is stored in permanent, shared, merge-path state. That single lifetime
mismatch is the origin of six consecutive rounds of defect-and-fix (#2789,
#2914, #3078, #3823, #3842, #3875), each fix generating the next defect, ending
in a scheduled sweeper whose own PR (#3927) could not merge itself.

ADR-3942 supersedes ADR-2719 section 3 only, and its #2789 Amendment. Sections
1, 2 and 4-7 are retained and depended upon: the conservation law itself is not
in question, only where its escape hatch is stored.

Also lands the root-cause research note behind the decision, and regenerates
the ADR index.

Two corrections to earlier framing, recorded here rather than dropped:

- Per-commit trailers do NOT reliably survive squash-merge; the repo's own
  ship.md:306 reconstructs a gate trail precisely because squash discards it.
  The ADR therefore claims no durable audit record on next. Non-survival is the
  property being bought, not a cost.
- The test job checks out at depth 1 (test.yml:107-110, no fetch-depth key). A
  depth-1 checkout cannot see the PR's commit range and fails VACUOUSLY rather
  than erroring, so fetch-depth: 0 is a named decision in the ADR and the
  acceptance criterion requires a test that fails under depth 1.

Docs-only; no code, no changeset.

Refs #3942

Co-authored-by: sim <sim@local>
This commit is contained in:
Tom Boucher
2026-08-27 14:06:29 -04:00
committed by GitHub
parent bbecc6a08b
commit 34399eed70
3 changed files with 246 additions and 0 deletions

View File

@@ -276,6 +276,7 @@ Decided in principle, not yet ratified. Do not cite as settled architecture.
| [ADR-1953](1953-complexity-triggered-refactor.md) | Complexity-triggered refactor — the loop measures the entropy it just added | Proposed | — |
| [ADR-3128](3128-adaptive-runtime-evidence.md) | Adaptive runtime evidence for GSD Debug | Proposed | — |
| [ADR-3889](3889-process-exit-contract.md) | One exit-code registry — 0 and 1 are free, everything else is allocated | Proposed | — |
| [ADR-3942](3942-emitted-drift-ack-commit-trailer.md) | The emitted-drift acknowledgment is PR-lifetime data — it belongs in a commit trailer, not the working tree | Proposed | — |
### Superseded, Retired, and Legacy