The Field Manual

The False Green

Part I: The World, Misreported

You are here if

Something just told you it succeeded, and you are reading this because you do not quite believe it. The typecheck is green. The export finished. The publish returned zero. The pipeline shows a check mark. The message says merged. And you cannot point to the thing the success was supposed to produce.

You are here if it says done and you don't believe it. If the build passed but the artifact behaves as though the change never landed. If you shipped, and a user is telling you the installer will not open, the capability is missing, the package is not on the index. If it worked is a line in a log and not a state you have touched. You are also here, less obviously, if a signal says failed and you suspect the failure itself: an index reporting not shipped about a publish that landed belongs to this chapter too, because a false red and a false green come out of the same gap.

You are in the wrong chapter if the signal was true once and time broke it: that is chapter 2. If the claim came from a worker you dispatched, that is chapter 6. If what you distrust is the checking tool itself, that is chapter 4. This chapter is for the signal that was never true. The green light is real. It is wired to the wrong sensor.

The mechanism

A success signal answers a narrower question than the one you asked. Exit code zero means the process ended without an error it considered fatal. A green typecheck means the checker found a type for every reference it resolved. Notarized means the notary service accepted an upload. None of these is your question, which is: is the world now in the state I intend? The false green lives in the gap between those two questions, and the gap is structural rather than a defect in any one tool. A tool can only report on its own operation, and its own operation is never the whole of what you meant by done. Most of the time the two coincide, which is precisely what trains you to stop checking.

The type specimen. An ad-hoc shell install dropped a dependency into the home directory instead of the target repo. The repo's own typecheck went green anyway: failing to find the types where they belonged, the checker walked up the directory tree and resolved them from a parent that happened to hold a copy. Every component told the truth. The installer did install. The checker did resolve every reference. The green was honestly earned by the check as configured. It just was not a fact about the repo. It was a fact about a world nobody intended, and on the surface it was indistinguishable from the green you wanted. Nothing errored, because nothing was wrong anywhere except the one place you cared about.

The decoupling arrives in a few recurring shapes, and the ledger below holds all of them. The signal can measure a neighboring world, as the wrong-directory typecheck did. The operation can succeed at a narrower job than the one you assumed: an export that completes while quietly dropping the entitlements it could not provision, a notarization that succeeds without the ticket ever being attached to the file it certifies. The signal can be read from a lagging copy instead of from the thing itself, like a package index trailing the real publish by minutes. Or done was defined too small from the start: one fixed call site out of four, one repaired layer of a pipeline that is red several layers deep, a page edited without the generated shadow that must move with it.

Book One spends its full arc earning the rule that a system's self-report is a claim rather than a fact, and building the verification loop that answers it. This chapter inherits that argument whole and aims it at one moment, the moment a green light asks to be believed. Every other chapter in this manual assumes you already distrust the green. This is the chapter where the distrust gets installed.

The discipline

Done is a physical state, not a signal: define, per operation, the bytes that constitute done, and read them from the least-cached authoritative source.

The ritual:

  1. Define done in bytes before you run anything. Name the artifacts that will exist if and only if the operation succeeded: the entry in this repo's lockfile, the ref on the remote, the entitlement inside the exported binary, the ticket attached to the file a user downloads. Pass: every item in the definition is something you can read, and none of it is a message, an exit code, or a check mark.
  1. Enumerate the whole set. Done is usually plural: every call site, every generated shadow artifact, every index script that must agree, every stage of the pipeline. Enumerate by listing (grep the file, list the scripts, read the stage graph), never from memory. Pass: you can say how the set was enumerated, and the answer is a command rather than recall.
  1. Rank the sources by cache distance and take the far end. For a branch, the remote and never your local ref. For a package, the registry's canonical record or a real install, in preference to the convenience metadata endpoint. For an installer, the downloaded live asset, in preference to the local build. Pass: for each byte, you can name the nearer, more convenient source you are deliberately declining to use.
  1. Run the operation and file its self-report as a claim. Keep the log. Act on none of it yet. Pass: nothing downstream has moved on the strength of the report alone: no merge, no announcement, no done relayed upward.
  1. Read the bytes. Fetch and inspect the remote ref. Dump the exported binary's entitlements. Verify the staple on the file a user would actually download. Install the package you just published. Compare what you read against the step 1 definition. Pass: the bytes match, and the match is something you observed rather than inferred from an absence of complaints.
  1. On staged pipelines, verify per layer and budget for the stack. A long-red pipeline heals one buried failure at a time, and each green uncovers the next layer. Treat a stage's green as permission to check the next stage. Pass: the thing you verified is the terminal artifact of the final stage, not the most recent stage's exit code.

The case ledger

[E007] Ad-hoc install lands outside the target repo (undated) Receipt: an operator-run shell install landed a dependency in the home directory instead of the target repo, and the repo's typecheck falsely passed by resolving types from the wrong parent directory. Rule: scope every ad-hoc install to the explicit project directory, and verify the dependency landed in that repo's own manifest and lockfile; a green typecheck alone says nothing about where the types came from.

[E032] Auto-provisioning silently drops capability entitlements (2026-06-27) Receipt: headless automatic code-signing succeeded and exported a mobile app, but silently stripped several capability entitlements it could not auto-provision, with no error raised. Rule: for capability-dependent builds, sign with a real installed distribution profile or enable the capability on the developer portal first, then inspect the exported binary's actual entitlements; a successful export is not an entitlement check.

[E046] Partial conflict-marker removal ships broken files (undated) Receipt: a scripted regex conflict resolution removed one conflict marker but left the ancestor and closing markers in a committed file, which the hosting platform correctly flagged as unresolved. Rule: after any automated conflict resolution, grep for zero remaining conflict markers before staging, or prefer a clean ours/theirs checkout over a regex-based resolution.

[E057] Local-only branches need an explicit push before merge (2026-07-04) Receipt: an operator-facing merge instruction assumed a locally created branch was already pushed, but it never had been, producing a false done until checked against the remote. Rule: any merge instruction for a locally created branch pushes it first, and any merge claim is verified against the remote, not against the fact that the command ran.

[E090] Fixing one CI layer surfaces the next hidden failure (2026-05-17) Receipt: fixing one broken CI step on a long-red pipeline surfaced a new failure hidden behind it, repeating for several cycles before the pipeline actually went green. Rule: never promise green after one fix on a stale pipeline; budget for several fix-and-rerun cycles, and peek ahead at the next step to predict what it will fail on.

[E105] One fixed call site, three more unfixed in the same file (undated) Receipt: fixing one code path to expand a home-directory shortcut left three other call sites in the same file with the identical unfixed bug. Rule: after any home-directory-expansion fix, grep the whole file for every remaining unwrapped call site before considering the fix complete.

[E126] A hand-edited page has a generated shadow artifact (2026-07-03 / 2026-06-28) Receipt: a small hand-edit to a site page blocked a push because it left a generated data shadow of that page out of sync, even though the edit itself needed no rebuild. Rule: in a project with generated shadow artifacts, a page edit is done when the regenerated shadows are committed alongside it in the same commit.

[E127] Adding a page can force re-signing a manifest (2026-06-28) Receipt: adding a new served page normally requires re-signing a cryptographically signed site manifest, which was not possible for a purely functional asset page. Rule: to add a page without touching the signed manifest, exclude it explicitly from every index-building script as an unlisted, noindex asset, consistently across all of them.

[E128] Notarized is not the same as stapled (undated) Receipt: a shipped installer was notarized but never had its notarization ticket physically stapled to the file, so it failed to verify for any user without live network access to the notary service. Rule: notarized is not stapled; run the staple step, then verify against the actual downloaded live asset, not the local build or the upload's exit code.

[E132] A package-index endpoint can lag the real publish (2026-05-31 / 2026-06-19) Receipt: the standard package-metadata endpoint used to confirm a publish lagged the actual state by several minutes, risking a false not shipped read. Rule: verify an outward-facing package publish via the least-cached authoritative source, not the convenience metadata endpoint.

Adjacent doors

If the signal was true when it was recorded and the world has moved since, a handoff checklist reflecting authoring time, a work order asserting premises a later session already invalidated, you are holding a stale record, not a false green. That is chapter 2. The dividing question is whether it was ever a fact: never true is this chapter, true once is time's problem.

If the done claim came from a worker you dispatched, and what you distrust is the reporter rather than the reading, that is chapter 6. The check looks the same, the diff instead of the summary, but the failure has a principal-agent shape this chapter does not cover, and it gets worse with the delegate's fluency.

If you ran this chapter's ritual and the surprise survived it, so that the tool you used to read the bytes is now the thing you suspect, the entitlement dumper, the staple verifier, the fetch itself, that is chapter 4. It takes the distrust you just practiced and aims it one level up, at the instruments.