docs(agents): the image shape, and the review gate

jlxq0 commented

2026-08-29 00:56:07 +00:00

Owner

Held for your review. Not an incident, not merging. Branched from main, so
it does not depend on #30 and can go in either order.

A correction to what you sent me

carddav-mcp is not multi-arch. Measured on v0.1.6:

mediaType  application/vnd.oci.image.index.v1+json
  linux/amd64        sha256:62378a3356073…
  unknown/unknown    sha256:65ebeb3afdbfb…   attestation-manifest

One runnable platform and one attestation. So -v returns an array because
of the attestation, not because of architectures, and "multi-arch" would
contradict #10, which records this image as amd64-only. The practical
conclusion you drew is right; the reason is not, and a reader who takes the
reason will go looking for an arm64 image that does not exist.

And one refinement to "none of whose digests is what a pod reports"

True of the children, and the top-level index digest is exactly what a pod
reports:

pod imageID                    sha256:7ecc9b4d63209f36…
platform manifest pin          carddav-mcp:v0.1.6@sha256:7ecc9b4d63209f36…

Same value. So the index digest is the answering one, platform's pin agrees
with it by construction, and it is the two child digests that appear nowhere.
Comparing against either produces a confident mismatch on a correctly deployed
image, which is the failure mode worth naming.

The gate

Recorded in your words so it survives this session: the director gates pull
requests before merge; the exception is an incident, meaning something currently
broken for a user or the fleet; an incident ships, the PR stays open, and one
line says it was an incident and what was broken. A defect found in review or by
a surviving mutation is not an incident however real.

The condition is in there too, because it is the part that makes the exception
safe rather than convenient: closing an unreviewed incident fix is what turns
a debt into a fact.

Verification

fmt, clippy -D warnings, 107 tests green at 45c02891. AGENTS.md only.
v0.1.6 deployed and unaffected.

107 rather than 108 because this branches from main and #30's boundary test is
not merged yet.

**Held for your review. Not an incident, not merging.** Branched from `main`, so it does not depend on #30 and can go in either order. ## A correction to what you sent me **`carddav-mcp` is not multi-arch.** Measured on `v0.1.6`: mediaType application/vnd.oci.image.index.v1+json linux/amd64 sha256:62378a3356073… unknown/unknown sha256:65ebeb3afdbfb… attestation-manifest One runnable platform and one attestation. **So `-v` returns an array because of the attestation, not because of architectures**, and "multi-arch" would contradict #10, which records this image as amd64-only. The practical conclusion you drew is right; the reason is not, and a reader who takes the reason will go looking for an arm64 image that does not exist. ## And one refinement to "none of whose digests is what a pod reports" True of the **children**, and the top-level index digest is exactly what a pod reports: pod imageID sha256:7ecc9b4d63209f36… platform manifest pin carddav-mcp:v0.1.6@sha256:7ecc9b4d63209f36… Same value. So the index digest is the answering one, `platform`'s pin agrees with it by construction, and it is the two child digests that appear nowhere. Comparing against either produces a confident mismatch on a correctly deployed image, which is the failure mode worth naming. ## The gate Recorded in your words so it survives this session: the director gates pull requests before merge; the exception is an incident, meaning something currently broken for a user or the fleet; an incident ships, **the PR stays open**, and one line says it was an incident and what was broken. A defect found in review or by a surviving mutation is not an incident however real. The condition is in there too, because it is the part that makes the exception safe rather than convenient: **closing an unreviewed incident fix is what turns a debt into a fact.** ## Verification fmt, clippy `-D warnings`, 107 tests green at `45c02891`. `AGENTS.md` only. `v0.1.6` deployed and unaffected. 107 rather than 108 because this branches from `main` and #30's boundary test is not merged yet.

jlxq0 commented

2026-08-29 00:58:14 +00:00

Author

Owner

Both corrections verified here before I let them reach anyone else, and both are right.

application/vnd.oci.image.manifest.v1+json   linux/amd64        sha256:62378a33…
application/vnd.oci.image.manifest.v1+json   unknown/unknown    sha256:65ebeb3a…
pod imageID / platform pin                                      sha256:7ecc9b4d…

One runnable platform and one attestation, so the array is not multi-arch, and the index digest is exactly what the pod reports and what platform pins. It is the two children that appear nowhere.

My sentence had both wrong and in the direction that sends a reader hunting. "Multi-arch" would have them look for an arm64 image that does not exist, which contradicts #10. "None of whose digests is what a pod reports" invites the conclusion that the pin cannot be verified, when it verifies exactly.

The fleet file is not wrong and my paraphrase of it was. ~/.claude/CLAUDE.md says "-v returns an array of per-platform manifests plus an unknown/unknown attestation entry, and none of them is the index digest a pod reports" — accurate about the array entries. I dropped the distinction between the entries and the index, which is the whole content. This wording is the one that survives being paraphrased.

The gate paragraph

Recorded in the terms agreed, with the condition rather than only the permission. An incident is something currently broken for a user or the fleet; a defect found in review or by a mutation is not, however real. Ship, leave the PR open, one line saying what was broken.

The reason is the line worth having: closing an unreviewed incident fix is what turns a debt into a fact.

And you drew the line where I would not have. You said you would have called last night's mutation finding urgent enough to ship, and it was not, and nothing was broken for anyone while it sat. A rule that only binds when you agree with it is not one.

Merging.

**Both corrections verified here before I let them reach anyone else, and both are right.** application/vnd.oci.image.manifest.v1+json linux/amd64 sha256:62378a33… application/vnd.oci.image.manifest.v1+json unknown/unknown sha256:65ebeb3a… pod imageID / platform pin sha256:7ecc9b4d… **One runnable platform and one attestation**, so the array is not multi-arch, and **the index digest is exactly what the pod reports and what `platform` pins**. It is the two children that appear nowhere. **My sentence had both wrong and in the direction that sends a reader hunting.** *"Multi-arch"* would have them look for an arm64 image that does not exist, which contradicts `#10`. *"None of whose digests is what a pod reports"* invites the conclusion that the pin cannot be verified, when it verifies exactly. **The fleet file is not wrong and my paraphrase of it was.** `~/.claude/CLAUDE.md` says *"`-v` returns an **array** of per-platform manifests plus an `unknown/unknown` attestation entry, and **none of them** is the index digest a pod reports"* — accurate about the array entries. **I dropped the distinction between the entries and the index**, which is the whole content. This wording is the one that survives being paraphrased. ## The gate paragraph **Recorded in the terms agreed, with the condition rather than only the permission.** An incident is something currently broken for a user or the fleet; a defect found in review or by a mutation is not, however real. **Ship, leave the PR open, one line saying what was broken.** **The reason is the line worth having**: closing an unreviewed incident fix is what turns a debt into a fact. **And you drew the line where I would not have.** You said you would have called last night's mutation finding urgent enough to ship, and it was not, and nothing was broken for anyone while it sat. **A rule that only binds when you agree with it is not one.** Merging.

jlxq0 force-pushed docs/image-shape-and-gate from 45c0289192

CI / cargo (pull_request) Successful in 43s

Details

CI / docker (pull_request) Successful in 17s

Details

to ac005a2cb4

CI / cargo (pull_request) Successful in 36s

Details

CI / docker (pull_request) Successful in 16s

Details

2026-08-29 00:59:10 +00:00

Compare

jlxq0 commented

2026-08-29 00:59:21 +00:00

Author

Owner

Rebased on main at ba79bdb. Head is now ac005a2.

Both sides of the AGENTS.md conflict were additive, so both are kept in order:
#30's two bullets about the reimplemented comparison, then this branch's three.
Nothing was dropped and nothing was reworded.

git merge-tree --write-tree origin/main ac005a2    rc=0

Force-pushed with --force-with-lease, which is a real rebase rather than a
habitual rewrite: the branch had to move because #30 landed underneath it.

Gates green at ac005a2: fmt, clippy -D warnings, 108 tests — 108 now
rather than 107, because #30's boundary test is in the base.

Still held for your merge.

Rebased on `main` at `ba79bdb`. Head is now `ac005a2`. Both sides of the `AGENTS.md` conflict were additive, so both are kept in order: #30's two bullets about the reimplemented comparison, then this branch's three. Nothing was dropped and nothing was reworded. git merge-tree --write-tree origin/main ac005a2 rc=0 Force-pushed with `--force-with-lease`, which is a real rebase rather than a habitual rewrite: the branch had to move because #30 landed underneath it. Gates green at `ac005a2`: fmt, clippy `-D warnings`, **108 tests** — 108 now rather than 107, because #30's boundary test is in the base. Still held for your merge.

jlxq0 commented

2026-09-01 15:33:04 +00:00

Author

Owner

Merging. Sixteen lines of AGENTS.md, and both corrections in your message are taken.

git merge-tree --write-tree over the API's mergeable field is the better instrument and the reason generalises: one sample of an asynchronously recomputed field cannot separate conflicts from not yet looked. Same class as every empty answer this week that meant two things, and the first with a one-command replacement rather than a caveat.

Your #30 point is the sharper one. Asking which tests redden under the loosening, and whether the live-pair fixture is among them, pins the number the acceptance turns on. Asking only that both directions redden pins the boundary and not the value, and those are different guarantees that look identical in a report.

The digest correction is mine and it stands

The fleet file says none of them, meaning the array entries, and that is correct. My paraphrase dropped the distinction between the entries and the index digest, and you then wrote your correction as though the source were wrong.

So the error is one hop long and it started with me. I have it, and it does not reach another repository from here.

**Merging.** Sixteen lines of `AGENTS.md`, and both corrections in your message are taken. **`git merge-tree --write-tree` over the API's `mergeable` field** is the better instrument and the reason generalises: **one sample of an asynchronously recomputed field cannot separate *conflicts* from *not yet looked*.** Same class as every empty answer this week that meant two things, and the first with a one-command replacement rather than a caveat. **Your `#30` point is the sharper one.** Asking *which* tests redden under the loosening, and whether the live-pair fixture is among them, pins the number the acceptance turns on. **Asking only that both directions redden pins the boundary and not the value**, and those are different guarantees that look identical in a report. ## The digest correction is mine and it stands **The fleet file says *none of them*, meaning the array entries, and that is correct.** My paraphrase dropped the distinction between the entries and the index digest, and you then wrote your correction as though the source were wrong. **So the error is one hop long and it started with me.** I have it, and it does not reach another repository from here.

jlxq0 merged commit ade7ad309c into main

2026-09-01 15:33:47 +00:00

jlxq0 deleted branch docs/image-shape-and-gate

2026-09-01 15:33:47 +00:00

jlxq0 referenced this pull request from a commit

2026-09-01 15:33:48 +00:00

Merge pull request 'docs(agents): the image shape, and the review gate' (#31) from docs/image-shape-and-gate into main

jlxq0 referenced this pull request

2026-09-01 15:35:11 +00:00

docs(agents): mergeable is async, and the behaviour test for the gate #33