* test(#3942): failing-first suite for the emitted-drift ack commit trailer Binds 37 input classes from the phase test matrix to the behavior ADR-3942 specifies, before any of it exists. Stubs return benign empty values rather than throwing, deliberately: several rows assert that something DOES throw (cap overflow, uncomputable commit range), and a throwing stub would turn those green for the wrong reason and destroy the red. The two rows that carry the design's load: - merge-base semantics. The range is $(git merge-base base HEAD)..HEAD, not base..HEAD, because changedPaths comes from `git diff base...HEAD` (three dot). Two-dot would let the ack set and the change set disagree about which commits are this PR's. The fixture forks a topic branch, puts a trailer on each side, and asserts only the topic-side trailer is in range. - fail-closed on an uncomputable range. With fragments a depth-1 checkout passes VACUOUSLY, every fragment reading as brand-new. With trailers the range cannot be computed at all, and returning an empty set would silently disarm the gate, so it must throw. The fixture builds a genuine shallow clone rather than simulating one. Also covers the self-inflicted case: this change's own documentation quotes the trailer syntax, so an example landing at the end of a commit message would arm a live acknowledgment keyed on the literal placeholder text. Keys carrying angle brackets or whitespace are rejected. Authored per the phase artifacts 40-design.md and 50-test-matrix.md. Not yet run on the remote runner — this commit exists to be tested. Refs #3942 * chore(#3942): move the emitted-drift ack to a commit trailer Implements ADR-3942, superseding ADR-2719 section 3 and its #2789 amendment. Sections 1, 2 and 4-7 are retained: the conservation law is unchanged, only the storage of its escape hatch moved off the working tree. An acknowledgment explains one PR's ripple, and the moment that PR merges the ripple is in the base, so it can never clear anything again. It was stored in permanent shared state anyway, and every consequence of that mismatch had to be built and then maintained. The chain is #2789 -> #2914 -> #3078 -> #3842 -> #3823 -> #3875, each fix generating the next defect, ending in a scheduled sweeper whose own first PR could not merge itself. Added parseAckTrailers + renderAckTrailer (pure) and readAckTrailers (IO shell), reading Emitted-Drift-Ack-Hash: / Emitted-Drift-Ack-Growth: trailers over the merge-base range. tests/emitted-ack-trailer.test.cjs, 37 cases, written failing-first and confirmed red before any of this existed. Changed diffEmitted takes two structurally distinct key-space maps instead of one shared paths map. That closes a latent defect: the spaces were separated by convention only, so a growth key satisfied a hash lookup by naming coincidence. staleAcks now reports which space a key was declared in. REMEDIATION teaches the trailer, per space, with its example rendered through renderAckTrailer so the taught grammar cannot drift from what the parser accepts. Removed the sweep workflow, the guard-no-ack-on-next job, the standalone linter and its lint:ci entry, the fragment directory and its three spent fragments, the legacy single-file union, and the baseAck/spentAcks mechanism -- spentness is now structural, not computed. Two range properties carry the design and are pinned by tests rather than asserted: the range is merge-base scoped, matching git diff base...HEAD, so an already-merged trailer is out of range by construction; and an uncomputable range throws instead of reading as zero acknowledgments, which is the inverse of the fragment guard's vacuous pass. Three deliberate observable changes, each disclosed in the changeset: the unread runtime field is gone, the legacy file is no longer read, and cross-space excusal no longer works. Ten open PRs carry fragments and will meet a modify/delete conflict. Measured before landing and accepted deliberately; the one-line migration is in the PR body. Verified: lint:ci exit 0. Remote runner to follow on this exact sha. Refs #3942 * fix(#3942): silent trailer collapse, lost coverage, and an unbounded cap Six findings from the orthogonal review round, all fixed in place. BLOCKER -- two trailers of the same name on one commit collapsed silently. readAckTrailers built `separator=1d` where git needs `separator=%x1d`: the `separator=` value inside a %(trailers:...) placeholder is itself a pretty-format string, so the bare hex was emitted as two literal characters and the split on \x1d never matched. Two same-name trailers therefore joined into one value with errors empty -- the first reason absorbing the second entry's key. Silent truncation, the exact class MAX_ACK_TRAILERS throws to prevent. Confirmed with od -c against real git output before and after. The failing-first matrix did not catch it because its "both spaces coexist" row uses Hash plus Growth -- different trailer NAMES -- so the value separator was never exercised. Two regression tests now cover same-name trailers directly. Coverage recovered: normalizeAckReason and INVISIBLE stayed on the live path via parseAckTrailers but lost every test when the old suite was pruned. Back under test against the current surface -- all six invisible codepoints individually, whitespace collapse, trim, CRLF, and two seeded fast-check properties. Dropping any single codepoint now fails. MAX_ACK_TRAILERS counted raw trailers before de-duplication, so one trailer carried forward across rebased commits counted once per commit and could throw on a legitimate branch. Now counts distinct entries; 100 identical repeats dedupe to one. diffEmitted validated baseline, current and changedPaths but not the new ackHash/ackGrowth, so a bad shape raised an unhandled TypeError instead of an error verdict -- the same defect shape this file documents for #2778. Docs: CONTRIBUTING and TESTING-SUITES were rewritten only in their first sections; the later passages still taught fragments, git rm and the deleted guard, contradicting the new text directly above them. Finished. Also extends lint-removed-but-needed to exempt docs/adr and docs/research. That gate fails on any docs mention of a file deleted in the same diff, which makes it impossible to document a deletion in the PR performing it -- an ADR's whole job is naming what it retired. Exemption is narrow and comes with a test proving the gate still fires for a live consumer elsewhere under docs/. A guard that cannot fail is worse than no guard. Maintainer-approved. CONTEXT.md names the retired machinery by role rather than by filename: its generated projection lands in docs/, which that gate does scan. Adds docs/how-to/acknowledge-emitted-drift.md. The required docs set is Reference and Explanation, so the task quadrant can be empty with every gate green -- and this change has a real multi-step journey, including the fragment migration ten open PRs now need. lint:ci exit 0. Refs #3942 * docs(#3942): correct the duplicate-trailer rule in CONTRIBUTING Both axes of the code review independently flagged the same passage, without seeing each other's output. It claimed two declarations of the same key are always "a hard, loudly-reported error, not a silent last-wins". That is only half true, and the missing half is the one contributors hit: identical declarations -- same key, same reason -- dedupe silently, because a trailer legitimately survives a rebase and reappears on every rebased commit. Failing there would red a branch for doing nothing wrong, which is exactly why the dedup exists. Only a same-key/different-reason pair errors, and that one is a genuine ambiguity about which explanation holds. As written, the paragraph told a contributor that a rebase-carried trailer breaks the gate -- the opposite of the behavior. CONTEXT.md's parallel entry already stated it correctly; this brings CONTRIBUTING into line. Doc-only, root-level markdown. Refs #3942 * chore(#3942): backfill changeset PR number to 3954 --------- Co-authored-by: sim <sim@local>
This commit is contained in:
Tom Boucher
File diff suppressed because one or more lines are too long
@@ -25,6 +25,7 @@ Language versions: [English](README.md) · [Português (pt-BR)](pt-BR/README.md)
|
||||
- [Probe edges in a non-English project](how-to/probe-edges-in-a-non-english-project.md) — get real edge coverage on a spec written in another language, and tell "no edges here" apart from "the probe could not read it"
|
||||
- [Resolve prohibition findings](how-to/resolve-prohibition-findings.md) — turn the spec phase's surfaced must-NOT constraints into resolved, dismissed, or deferred spec decisions
|
||||
- [Resolve an unreachable-workflow finding](how-to/resolve-unreachable-workflow-findings.md) — wire or fully sweep a shipped workflow that no command, agent, or skill references
|
||||
- [Acknowledge emitted-artifact drift](how-to/acknowledge-emitted-drift.md) — declare a deliberate emitted-byte ripple or workflow/agent growth in a commit trailer, and migrate an older ack fragment
|
||||
- [Change the STATE.md schema](how-to/change-the-state-md-schema.md) — add, change or remove a STATE.md frontmatter key and keep the template and all five reference documents in step
|
||||
- [Resolve verify-command path findings](how-to/resolve-verify-command-path-findings.md) — fix an `<automated>` verify command whose target directory does not resolve from the executor's cwd
|
||||
- [State a failing direction](how-to/state-a-failing-direction.md) — say what output constitutes failure for an `<automated>` verify command, and migrate a phase planned before the rule
|
||||
|
||||
@@ -137,32 +137,30 @@ The differential attribution check reports the file and the byte delta. To resol
|
||||
1. **Justify the growth in your PR** (a sentence in the description is enough) —
|
||||
the acknowledgment entry (below) is the review record that the larger size
|
||||
was a deliberate, seen decision, not silent drift.
|
||||
2. **Add an acknowledgment fragment** under `tests/emitted-drift-acks/` naming
|
||||
the file and the reason, per `CONTRIBUTING.md`'s "Editing shipped content"
|
||||
section and `CONTEXT.md`'s `### Emitted Artifact Provenance` entry. Name the
|
||||
fragment for your issue or PR (something nobody else is using) — the failure
|
||||
output prints a minimal valid document you can paste. This is deliberately a
|
||||
per-PR fragment, not one shared file: two fragments can never *merge-conflict*
|
||||
with each other, and a fragment appearing in your diff *is* the visible signal.
|
||||
They do, however, share a path key space. If the failure instead names a path a
|
||||
merged PR already acknowledged (a **spent** entry sitting in an existing
|
||||
fragment), you have two routes and the error text names both: `git rm` that
|
||||
fragment if every entry in it is spent — it gates nothing and only holds the
|
||||
keys — or, if it is still live, reword/extend its `reason` in place to explain
|
||||
the new ripple. Either way, do not add a duplicate entry for the same path; two
|
||||
ack sources naming the same path is a hard, loudly-reported error.
|
||||
The legacy single `tests/emitted-drift-ack.json` is still read and unioned
|
||||
in for branches that carry it, but new acknowledgments never go there.
|
||||
3. **Your fragment is deleted once it has merged (#3078).** A fragment on `next`
|
||||
is spent by definition — its prose is already at the base, so it can no longer
|
||||
clear anything — while still owning its path keys, which walls off the next PR
|
||||
that grows one of them. The `guard-no-ack-on-next` job reds `next` and prints
|
||||
the exact `git rm` for every fully-spent fragment. A *partially* spent fragment
|
||||
is deliberately left alone. Since #3875 you do not have to run that `git rm`:
|
||||
the `ack-fragment-sweep` workflow (`.github/workflows/ack-fragment-sweep.yml`)
|
||||
asks the guard for its own sweep list every six hours and opens a PR deleting
|
||||
exactly what it named, holding back any fragment an open PR still touches
|
||||
(#3842).
|
||||
2. **Add an acknowledgment trailer** to one of your own commits (ADR-3942),
|
||||
naming the file and the reason, per `CONTRIBUTING.md`'s "Editing shipped
|
||||
content" section and `CONTEXT.md`'s `### Emitted Artifact Provenance` entry:
|
||||
|
||||
```
|
||||
Emitted-Drift-Ack-Growth: explore.md — new dispatch section, reasoning ships with the block
|
||||
```
|
||||
|
||||
Growth keys on the **bare filename** as it appears under `gsd-core/workflows/`
|
||||
or `agents/`; an unattributable **hash** ripple uses
|
||||
`Emitted-Drift-Ack-Hash:` and keys on the emitted path (which always contains
|
||||
a `/`). The two are separate namespaces — a growth trailer will not excuse a
|
||||
hash ripple, and the failure output says which one applies. The trailer is the
|
||||
review record that the larger size was a deliberate, seen decision.
|
||||
|
||||
If you need to change an acknowledgment, amend the commit carrying it. That is
|
||||
deliberate: the trailer cannot drift out of sync with the diff it explains,
|
||||
because changing either changes the sha and re-runs the gate.
|
||||
3. **There is nothing to clean up afterwards.** The trailer is read from
|
||||
`git log $(git merge-base <base> HEAD)..HEAD` — your commits and no others —
|
||||
so once your PR merges it is out of range by construction. It never becomes
|
||||
"spent", it owns no shared key space, it cannot conflict with anyone else's,
|
||||
and no sweeper has to delete it. That is the whole reason ADR-3942 moved the
|
||||
acknowledgment off the working tree.
|
||||
4. **Or shrink it instead of acknowledging.** Prefer extraction when the growth
|
||||
is incidental: for a workflow, move per-mode bodies to
|
||||
`workflows/<name>/modes/`, templates to `workflows/<name>/templates/`, and
|
||||
@@ -182,8 +180,7 @@ help — that is the signal to extract, per step 3.
|
||||
|---|---|
|
||||
| `scripts/workflow-size.cjs` | Single source of truth — LF-normalized byte counter (`lfByteCount`) + generic `measureMdFiles(dir, predicate)` (backs both workflows and agents) + workflow enumeration (`listWorkflowStems`, `measureWorkflows`). Imported by both guards and by `tests/helpers/emitted-runtime.cjs`'s `currentSizes()` so they can never measure differently. |
|
||||
| `tests/emitted-attribution.test.cjs` + `tests/helpers/emitted-diff.cjs` | The differential attribution check and its size ratchet (ADR-2719). The sole mechanism for both emitted-content propagation AND per-file size growth as of #2724. |
|
||||
| `tests/emitted-drift-acks/` | Per-PR acknowledgment fragments (primary, #2914) for unattributable emitted-content ripples and for size growth. A fragment appearing in your diff *is* the alarm; absence is the healthy steady state. |
|
||||
| `tests/emitted-drift-ack.json` | Legacy single acknowledgment file, superseded by the per-PR fragments above. Still read and unioned in for branches that carry it; must never gain new entries and must never persist on `next` (enforced by `guard-no-ack-on-next` via `scripts/lint-emitted-drift-ack.cjs --guard-next`). |
|
||||
| `Emitted-Drift-Ack-Hash:` / `Emitted-Drift-Ack-Growth:` commit trailers (ADR-3942) | The acknowledgment mechanism for unattributable emitted-content ripples and for size growth. Read from `git log $(git merge-base <base> HEAD)..HEAD` — no committed file, nothing to sweep; a merged trailer is out of range by construction. |
|
||||
| `npm run regen:derived` | Runs every remaining generator in dependency order (build → registry → ADR index → capability matrix → inventory manifest → manifest versions → `tests/fixtures/install-tree/*.json`). |
|
||||
| `tests/workflow-size-budget.test.cjs` | The workflow tier hard-cap guards, plus the `discuss-phase` progressive-disclosure checks. |
|
||||
| `tests/agent-size-budget.test.cjs` | The agent tier hard-cap guards (the agent analog). |
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# ADR-2719: Emitted-artifact attribution — replace the committed parity fixtures with a computed conservation law
|
||||
|
||||
- **Status:** Accepted
|
||||
- **Status:** Accepted; **Decision §3 superseded** by [ADR-3942](3942-emitted-drift-ack-commit-trailer.md) (The emitted-drift acknowledgment is PR-lifetime data — it belongs in a commit trailer) (2026-08-27), which replaces §3 and its #2789 Amendment. **§1, §2 and §4–§7 are retained and depended upon** — the conservation law itself is unchanged; only the storage of its escape hatch moved off the working tree.
|
||||
- **Date:** 2026-07-27
|
||||
- **Issue:** [#2719](https://github.com/open-gsd/gsd-core/issues/2719) (epic); Phase 0 tracked by [#2720](https://github.com/open-gsd/gsd-core/issues/2720)
|
||||
- **Supersedes:** [ADR-2264](2264-golden-parity-redesign.md) (Redesign golden-install-parity) — replaces its Decision §2–§4 and its 2026-07-14 Amendment. ADR-2264 **Phase 1 is retained and depended upon**: the single-source `buildParityManifest` and the four exclusion constants in `tests/helpers/install-shared.cjs` are the foundation this design builds on, not something being reverted.
|
||||
|
||||
@@ -113,7 +113,7 @@ Sequencing inside Phase 1 that the platform forces:
|
||||
1. Author the contiguous protocol section and its extracted step file — this is what satisfies admission gate (1).
|
||||
2. Only then admit the atom across grammar, predicate, fact and router, and regenerate the section manifest.
|
||||
3. Update the tests that assert on `debug.md`'s literal text (`tests/debug-session-management.test.cjs`, `tests/debug-session-manager-commit.test.cjs`, `tests/claude-skills-migration.test.cjs`) in the same PR; regenerate `tests/fixtures/install-tree/*.json` via `npm run regen:derived`.
|
||||
4. Add a per-PR `tests/emitted-drift-acks/` fragment for `debug.md`'s growth, keyed on the bare filename.
|
||||
4. Add an `Emitted-Drift-Ack-Growth:` commit trailer for `debug.md`'s growth, keyed on the bare filename (ADR-3942; was a `tests/emitted-drift-acks/` fragment before that).
|
||||
|
||||
## Consequences
|
||||
|
||||
|
||||
@@ -57,7 +57,16 @@ The two key spaces are convention-only. A hash ripple keys on the emitted path (
|
||||
Emitted-Drift-Ack-Hash: <emitted/path> — <reason>
|
||||
Emitted-Drift-Ack-Growth: <filename> — <reason>
|
||||
|
||||
Read from `git log <base>..<head>` — the PR's own commits and no others.
|
||||
Read from `git log $(git merge-base <base> HEAD)..HEAD` — the PR's own commits and no others.
|
||||
|
||||
> **Amendment (#3942 implementation, 2026-08-27).** This section originally said `git log
|
||||
> <base>..<head>`, leaving the range semantics unstated. **Two-dot would be a defect.**
|
||||
> `changedPaths` comes from `git diff base...HEAD` — *three*-dot, i.e. merge-base — so a two-dot
|
||||
> ack range would let the acknowledgment set and the change set disagree about which commits
|
||||
> belong to this PR, and a trailer could excuse a delta that is not in the diff. §2's claim that
|
||||
> spentness becomes *structural* also rests entirely on merge-base: it is what puts an
|
||||
> already-merged trailer out of range by construction. Stated, and pinned by a test that forks a
|
||||
> topic branch, places a trailer on each side, and asserts only the topic-side trailer is read.
|
||||
|
||||
This preserves what ADR-2719 §3 actually cared about. Its stated design property is *"the acknowledgment file appears in the changed-files list **only when something rippled unexpectedly** … touching the acknowledgment *is* the alarm."* A trailer is still a conspicuous, reviewable, prose-carrying declaration that appears in the PR's diff — it is not the `UPDATE_GOLDEN=1` flag §3 rejected. What changes is that the declaration stops outliving the thing it declares.
|
||||
|
||||
@@ -81,7 +90,28 @@ There is in-repo precedent for the mechanism: `gsd-core/workflows/ship.md:312` a
|
||||
|
||||
### 5. The PR test lane must fetch the commit range
|
||||
|
||||
`.github/workflows/test.yml:107-110` — the `test` job — has no `fetch-depth` key and therefore checks out at depth 1. A depth-1 checkout cannot see the PR's commit range, and the failure mode is a **vacuous pass**, not an error. `test.yml:882-885` already documents this exact hazard for the `guard-no-ack-on-next` job.
|
||||
The gate must be able to see the PR's commit range, and must fail closed when it cannot.
|
||||
|
||||
> **Amendment 1 — the premise was wrong (#3942 implementation, 2026-08-27).** This section
|
||||
> originally asserted that "`.github/workflows/test.yml:107-110` — the `test` job — has no
|
||||
> `fetch-depth` key and therefore checks out at depth 1," and made `fetch-depth: 0` a required
|
||||
> change. **That is false, and no workflow change is needed.** Line 107 sits inside the
|
||||
> `lint-tests` job; the matrix `test` job — the one that actually runs
|
||||
> `tests/emitted-attribution.test.cjs` — begins at `test.yml:130` and already sets
|
||||
> `fetch-depth: 0` on *both* its Windows (v5.0.1) and Linux/macOS (v6.0.2) checkout steps. The
|
||||
> claim entered this ADR from a line citation that was not verified against the job boundaries
|
||||
> before it was written down. The requirement stands as a **property to preserve**, not a change
|
||||
> to make: if that `fetch-depth: 0` is ever removed, the reader must still fail closed.
|
||||
|
||||
> **Amendment 2 — the failure mode was mischaracterized (#3942 implementation, 2026-08-27).** This section originally called the depth-1
|
||||
> failure mode a **vacuous pass**. That is true of the *fragment* guard and **false of the trailer
|
||||
> reader**, and the phrase was carried over uncritically. With fragments, depth-1 makes every
|
||||
> fragment read as brand-new — therefore live — so the guard passes: a false **green**. With
|
||||
> trailers, an uncomputable range yields *zero* acknowledgments, so a PR that needs one fails: a
|
||||
> false **red**. Provided the reader throws rather than returning an empty set, the depth-1 failure
|
||||
> is loud in both directions, which is a real improvement this ADR undersold. `fetch-depth: 0` is
|
||||
> still required; forgetting it is now merely obstructive instead of dangerous. The throw is pinned
|
||||
> by a test that builds a genuine shallow clone rather than simulating one.
|
||||
|
||||
`fetch-depth: 0` is required on that job, and the gate must fail closed when the range is unavailable — never `return` on a missing base, per ADR-2719 §6 ("A baseline-unavailable path must never be a bare `return`. In `node:test` that is a **pass**").
|
||||
|
||||
|
||||
69
docs/how-to/acknowledge-emitted-drift.md
Normal file
69
docs/how-to/acknowledge-emitted-drift.md
Normal file
@@ -0,0 +1,69 @@
|
||||
# How to acknowledge emitted-artifact drift
|
||||
|
||||
**Goal:** Get a red differential-attribution check to green when the ripple it found is deliberate — by declaring it in a commit trailer on your own branch, so nothing is left behind in the tree once your PR merges.
|
||||
|
||||
**Prerequisites:** A branch whose CI failed with an unattributable emitted-artifact delta, or with growth in a `gsd-core/workflows/*.md` or `agents/gsd-*.md` file. The failure output names the key and the space; you do not need to work either out yourself.
|
||||
|
||||
For why the acknowledgment lives in a commit rather than a file, see [ADR-3942](../adr/3942-emitted-drift-ack-commit-trailer.md). For the conservation law it is an escape hatch from, see [ADR-2719](../adr/2719-emitted-artifact-attribution.md). This guide covers only how to *declare* one.
|
||||
|
||||
---
|
||||
|
||||
## Pick the right key space
|
||||
|
||||
There are two, and they are separate namespaces. A trailer in the wrong one will not excuse anything — it will fail as an unused declaration instead.
|
||||
|
||||
| Your failure says | Trailer | Key |
|
||||
|---|---|---|
|
||||
| an emitted path's hash moved and your diff cannot explain it | `Emitted-Drift-Ack-Hash:` | the emitted path exactly as printed — always contains a `/` |
|
||||
| a workflow or agent file grew | `Emitted-Drift-Ack-Growth:` | the **bare filename** as it appears under `gsd-core/workflows/` or `agents/` |
|
||||
|
||||
The failure output tells you which applies. If you are guessing, you have the wrong one.
|
||||
|
||||
## Declare it
|
||||
|
||||
The grammar is `<key> — <reason>`, split on the **first** ` — ` (space, em dash, space), so your reason may contain further em dashes.
|
||||
|
||||
On your next commit:
|
||||
|
||||
```bash
|
||||
git commit --trailer "Emitted-Drift-Ack-Growth: explore.md — new dispatch section; the reasoning ships with the block"
|
||||
```
|
||||
|
||||
On a commit you already made:
|
||||
|
||||
```bash
|
||||
git commit --amend --trailer "Emitted-Drift-Ack-Hash: skills/gsd-add-tests/SKILL.md — converter rewrote every skill header"
|
||||
```
|
||||
|
||||
Amending is the intended route, not a workaround. The trailer cannot drift out of sync with the diff it explains, because changing either changes the sha and re-runs the gate.
|
||||
|
||||
Write a real reason. "fix" or "expected" is not one — the reason is the whole artifact a reviewer reads, and an empty one is rejected.
|
||||
|
||||
## What happens next
|
||||
|
||||
Nothing, and that is the point. The trailer is read from `git log $(git merge-base <base> HEAD)..HEAD` — your commits and no others. Once your PR merges it is out of range by construction. There is no file to delete, no "spent" state to clean up, no shared key namespace to collide with, and no sweeper to wait for.
|
||||
|
||||
---
|
||||
|
||||
## Migrating from an ack fragment
|
||||
|
||||
If your branch predates ADR-3942 it may carry a `tests/emitted-drift-acks/*.json` fragment. That directory no longer exists on `next`, so you will meet a `modify/delete` conflict. Resolve it by moving the reason you already wrote into a trailer:
|
||||
|
||||
```bash
|
||||
git rm tests/emitted-drift-acks/<yours>.json
|
||||
git commit --amend --trailer "Emitted-Drift-Ack-Growth: <filename> — <the reason from your fragment>"
|
||||
```
|
||||
|
||||
Use `Emitted-Drift-Ack-Hash:` instead if the fragment's key contained a `/`. A fragment that declared several keys becomes several trailers — one per key, and they may sit on the same commit.
|
||||
|
||||
---
|
||||
|
||||
## When it still fails
|
||||
|
||||
| The failure says | What it means | What to do |
|
||||
|---|---|---|
|
||||
| an acknowledgment nothing consumed | you declared a key, but no delta matched it | remove the trailer, or correct the key to name the ripple you actually made — the message names which space it was declared in |
|
||||
| a key was declared twice with different reasons | two commits in your range declare the same key and disagree | keep one. Identical repeats are deduplicated silently; conflicting ones are ambiguous and refused |
|
||||
| an invalid key | your key contains whitespace, `<`, or `>` | you probably pasted a placeholder from documentation. Use the real path or filename |
|
||||
| the range is structurally uncomputable | the checkout has no common ancestor — typically a shallow clone | this is a CI configuration problem, not something a trailer fixes. The gate fails loudly here rather than reading your branch as having no acknowledgments |
|
||||
| a new file over the size cap | `NEW_FILE_CAP` is deliberately **not** acknowledgeable | extract content instead — lazily, via `gsd-core/references/`. An eager `@`-import shrinks the file without shrinking loaded context, which games the guard while making the real cost worse |
|
||||
Reference in New Issue
Block a user