@cosyte/cli 0.0.5 → 0.1.0

package/CHANGELOG.md

@@ -15,8 +15,424 @@ still do. Each entry was assigned to the release whose tag first contains it, re
 
 ## [Unreleased]
 
+**What 0.1 means for you.** This is the first release whose commands, output and exit codes we treat
+as settled: command names, flags, the JSON output shapes, the exit-code contract (`0`, `1`, `2`,
+`65`, `66`, `69`, `70`, `74`) and the diagnostic codes are the surface we keep stable. It covers the
+`cosyte` command over all eight cosyte formats (`parse`, `validate`, `inspect`, `fmt`, `convert`,
+`map-codes`, `redact` / `deid`, `completion`), value-free diagnostics with `--unsafe-show-values` as
+the one opt-in, the `cosyte-mcp` stdio server and the programmatic `core` API. While the package is
+below 1.0, a breaking change bumps the minor version and is called out here; a fix that changes no
+output ships as a patch. Not covered yet: DICOM `parse` and `fmt`, C-CDA `parse`, and MLLP `fmt` and
+`validate` (`CLI_FORMAT_UNSUPPORTED`), `validate --profile` (`CLI_NOT_IMPLEMENTED`), `redact` for
+`astm`, `dicom`, `mllp` and `ncpdp`, a remote MCP transport and MCP tools for `redact` and
+`map-codes`. The FHIR commands and `convert` use `@cosyte/fhir` as the peer of the optional
+`@cosyte/transform`, and report `CLI_PARSER_UNAVAILABLE` (exit `69`) when a package manager leaves
+it out.
+
+### Added
+
+- **A downstream consumer that closes the CLI's stdout now ends the run quietly, under a documented
+  code of its own: `74` (`IOERR`, the value `sysexits.h` assigns `EX_IOERR`).** A pipeline into
+  `head`, a pager you quit, or any early-exiting reader gets the stable value-free
+  `CLI_OUTPUT_WRITE_FAILED` diagnostic and that exit code: no stack trace, no platform error text,
+  and no byte of the input on stderr. The contract is additive; no existing code is renamed,
+  repurposed or removed, and no existing code's meaning changes.
+  - **The code was chosen on a measurement, not a citation.** A write to a closed stdout is a Node
+    `EPIPE` on the stream, which is fatal when nothing is listening: measured here, the unguarded
+    shape prints a ten-frame stack trace and exits `1`. It is a handled condition the consumer owns,
+    so reporting it as `70` told an operator their pipeline had hit a bug in the CLI. The one
+    condition that moves onto the new code is that write failure itself, which previously reported
+    `70` on the record-stream path.
+  - **Neither write path reports a success over output that reached nobody.** The whole-result write
+    in the `cosyte` bin bypassed the guarded output sink altogether, and the record stream's sink
+    only consulted a flag the platform sets asynchronously, so a short enough run could have every
+    line enqueued before the closed consumer was reported. Either way a parse piped into a reader
+    that stopped early could print a summary and exit `0` over output that was never delivered.
+    Every chunk bound for stdout now waits for the platform's acknowledgement before the run may
+    resolve, so an undelivered result resolves to `74` whatever the command had computed, and the
+    summary describing that computed outcome is withdrawn with it.
+  - **`cosyte-mcp` terminates quietly when its client goes away.** A closed stdout used to reach the
+    process as an unhandled stream error, printing a Node stack trace naming this machine's install
+    paths. It is now a value-free diagnostic and the same exit code, and the server ends rather than
+    serving a channel nobody is reading.
+  - **A closed stderr cannot turn either termination into an unhandled error.** Both bins hear the
+    diagnostic channel's own error and fall back to the exit code as the whole signal.
+  - `test/pipe-close.test.ts` spawns real processes and closes their real streams, which nothing in
+    this suite did before: the existing coverage drove an injected sink inside the test process and
+    could say nothing about the process adapters. Its record-stream cases run at one and two records
+    on purpose, because a long stream fails on a later write and so is caught however the earlier
+    ones were handled, and `scripts/smoke.mjs` asks the same question of the PACKAGED bin under
+    plain `node`, where a faster start widens the window further.
+
+- **The release pipeline now installs the packed tarball from outside this repository, and runs both
+  bins from that installed copy, before anything can publish.** `0.0.1` and `0.0.2` are on npm
+  permanently uninstallable, and the check that catches that shape was a sentence in a human
+  checklist: a `--dry-run` packs a tarball but never resolves its dependencies from a registry. It is
+  now the `install-gate` job in the release workflow, which the publishing job `needs:`, so a red
+  gate stops the publish rather than reporting on one that already happened.
+  - **It refuses a local-path dependency specifier before it packs anything.** A `file:`, `link:` or
+    bare filesystem path in `dependencies`, `optionalDependencies` or `peerDependencies` is what made
+    those two versions uninstallable, and it is now a refusal naming the field and the specifier.
+    `devDependencies` is deliberately exempt and reported rather than skipped silently: a consumer
+    never installs them, which is why this package can carry one on purpose.
+  - **Both bins are executed, not stat-ed.** `cosyte` must exit `0` from the installed copy, and
+    `cosyte-mcp`, a stdio server that never exits on its own, must not exit non-zero inside a bounded
+    window. A bin whose file is missing from the tarball is reported as a packaging defect, in words
+    that do not read like an install failure.
+  - **It fails closed.** An install that exceeds its time bound, a registry that does not answer and
+    a throw inside the gate each refuse with their own reason rather than warning and continuing. The
+    accepted cost is that a transient fault delays a correct release until the run is repeated.
+  - No dependency was added, no manifest field moved, and nothing a consumer receives changed.
+
+- **Every MCP tool now publishes an `outputSchema`, and every tool result conforms to it.** An agent
+  calling a cosyte tool used to receive `structuredContent: { exit, ok }` with no schema to check it
+  against, so deciding whether a result held data or a diagnostic meant pattern-matching a text blob.
+  Each of the four tools now advertises an output schema and a `title` on `tools/list`, and every
+  dispatch path (success, negative verdict, hard failure, usage error, internal error) returns
+  structured content conforming to the schema its own tool declared.
+  - **The result carries `ok`, `status`, `exit`, `code` and `data`.** `status` is `success`,
+    `verdict` or `failed`, and it is the property that separates a negative verdict about the message
+    (the tool ran, the payload is present, the call is not an error) from a call that produced
+    nothing: the distinction no text blob could make reliably. `code` is the stable diagnostic code on
+    a failed call. `data` is the tool's own payload: the parsed model and warnings (or a record stream
+    for a multi-record input), the validation verdict and findings, the value-free structural summary,
+    or the converted `Bundle`.
+  - **On a failed call the structured result is value-free by construction**, not by review: every
+    property is drawn from a fixed set (the outcome vocabulary, the exit-code contract, the diagnostic
+    code registry), so no part of the caller's input can appear in it. One consequence is deliberate:
+    an unknown tool name is no longer echoed back, because a tool name is caller-supplied text like
+    any other argument.
+  - Tool names, tool count, `tools/list` ordering, input schemas, the exit-code contract, and the rule
+    that a parsed-but-invalid `validate` is a successful call are all unchanged, and no dependency was
+    added. The suite validates each emitted result against its own tool's declared schema with a
+    dependency-free checker that refuses any schema keyword it does not implement.
+
+- **`redact` / `deid` produces a real de-identified copy, delegated whole to `@cosyte/deid`.** The
+  command that shipped as an honest `CLI_NOT_IMPLEMENTED` is wired. For `ccda`, `fhir`, `hl7` and
+  `x12` stdout carries the de-identified document (serialized exactly as `cosyte fmt` serializes that
+  format) and stderr carries the library's own value-free manifest, one line per locus with its
+  category, transform, structural path, count, disposition and stable code, plus the library's own
+  published output label and version. The CLI adds no policy, no locus map, no transform and no
+  fallback scrub, and asserts no de-identification standard of its own.
+  - **Every other outcome emits nothing at all**, because a partial pass offered as a de-identified
+    copy is the hazard the command exists to prevent. `astm`, `mllp` and `ncpdp` have no adapter in
+    that library: `CLI_NOT_IMPLEMENTED` (`69`). `dicom` is covered there, but its de-identified form
+    is a Part 10 byte stream this text stdout cannot carry: `CLI_FORMAT_UNSUPPORTED` (`65`), the
+    CLI's own limit, deliberately not blamed on the library. Any locus the library reports it could
+    not handle is the new `CLI_DEID_INCOMPLETE` diagnostic and exit `1`, with the blocked paths and
+    their codes named on stderr.
+  - **`@cosyte/deid` is an `optionalDependency`.** An install without it degrades to a value-free
+    `CLI_PARSER_UNAVAILABLE` (`69`), decided **before the input is read**, so a copy that cannot
+    de-identify never touches the bytes it cannot strip. No other command loads it: the boundary is
+    gated statically and observed at runtime in `test/deid-isolation.test.ts`.
+  - **Identifier surrogates are keyed with a per-invocation ephemeral key.** The library's default
+    policy pseudonymizes MRN / account / beneficiary numbers, and a keyed transform with no key is a
+    fatal there, never an unkeyed fallback. The CLI holds no key material and adds no key surface, so
+    it keys each run with a fresh random value: surrogates are consistent within one output and
+    deliberately not stable across runs. Stated on stderr and in the docs rather than discovered.
+  - **`redact` does not honour `--unsafe-show-values`.** The opt-in excerpt exists for debugging a
+    rejected parse; on this command an excerpt of the un-stripped input is precisely the leak it
+    exists to prevent, so its diagnostics stay value-free under every flag. The PHI-leak sentinel
+    matrix now carries a redact row per mode (covered, refused, blocked, library absent, `--format`
+    given and omitted, file and stdin).
+  - No published exit value moved and no existing `CLI_*` code was renamed. `redact` is still
+    deliberately absent from the MCP tool surface.
+
+- **The two-file agent-guidance contract is now gated (`pnpm check:agent-notes`).** `CLAUDE.md` was
+  split from `documentation/agent-notes.md` on 2026-08-04, which made every anchor between them
+  load-bearing, and nothing checked them. `scripts/check-agent-notes.ts` now verifies that the
+  narrative file is tracked, that no section is emptied down to its heading (a container whose body is
+  its subsections is exempt and counted), and that every pointer at it resolves. It runs from
+  `test/scripts/agent-notes.test.ts`, so it rides the required `ci / verify` contexts and
+  `prepublishOnly` rather than adding a fourth workflow.
+  - **The matcher was derived by counting this tree, not by porting a sibling's.** Two pointer
+    spellings are live across these repositories, and porting without re-counting has produced a false
+    green twice: a qualified-only matcher would have covered 3 of `ncpdp`'s 38 pointers, and would
+    have matched nothing at all in `terminology` (42 bare, zero qualified) while still exiting 0.
+    **Measured here: every pointer is the qualified `documentation/agent-notes.md#<anchor>` form and no
+    bare pointer exists**, so the gate matches that form only. No count is written into the gate's
+    prose as a promise; the OK line prints all of them on every run, because it measures rather than
+    remembers.
+  - **A bare-form census keeps that scope honest.** Matching one spelling is safe only while the other
+    stays absent, so in **every opened file** each backticked `#<anchor>` span is enumerated: a
+    digits-only one is a pull-request reference and is counted and reported, and **any other one
+    refuses the run at exit 2** with an instruction to re-derive the matcher. Refusal rather than a
+    finding, because the tree has not necessarily broken but the evidence the scope rested on has.
+    A first draft scoped the census to the pair and justified that with tree files it claimed a
+    widening would red; **running it tree-wide proved none of them can, and that the only files that
+    could were the gate's own source and test**, which wrote bare spans out literally. That made the
+    narrow scope a self-exemption for the very files where a broken pointer would hide, so the samples
+    are now assembled from parts and the census covers the corpus. It closes the hole a pair-scoped
+    census leaves: a bare pointer in a third file was covered by neither the matcher nor the census.
+  - **Three claims were withdrawn after review rather than shipped.** The opening promise said the
+    gate catches "a rename"; it does not, because both halves match on **basename** and the directory
+    is never compared, so moving the file while pointers keep their prefix exits 0 with every rendered
+    link broken. That is now a narrowed promise and a disclosed miss rather than a bigger guard. A
+    **heading inside an HTML comment** mints a phantom anchor, which the list had omitted; it is now
+    disclosed and pinned. And a written-down count of sibling repos lacking the file was already
+    wrong, so **the number was dropped in favour of the class**.
+  - **Two further claims were withdrawn on later review passes, each arriving inside the fix for the
+    one before it.** The first fix asserted the HTML-comment miss is disclosed in "every sibling
+    copy"; that phrasing came from a review rather than from the tree, and it is false. `ncpdp`,
+    `terminology` and `astm` disclose it; `mllp`, `ccda`, `transform` and `docs` do not, and `mllp`
+    is the copy this gate's disclosed-miss block is transcribed from, so the shared ancestor never
+    carried the entry. The second fix then said the four that lack it are all owed it. Also false:
+    `mllp`, `ccda` and `transform` derive anchors by **slugging headings** and are owed it, while
+    `docs` resolves explicit `<a id>` anchors and cannot have the miss at all. **A claim about
+    another repository is not checkable from inside this one**, so it is measured against that
+    repository's source or not made.
+  - **It refuses rather than reporting green over a corpus it never opened.** There is no declared
+    scan root to be wrong about: the corpus is `git ls-files`, reconciled as **sets of paths**, and
+    zero pointers, zero tracked files, an unmerged path, a symlink, a non-regular file or two files
+    carrying the contract basename each refuse at exit 2. This repository has already shipped the
+    opposite defect once, in `phi-scan`, which printed `OK, no hits` over a root it never walked.
+  - **Every claim was watched to fail on a clone of the real tree** before the gate was believed: a
+    misspelled real anchor, an emptied real section, the narrative file deleted, a bare pointer that
+    resolves, a neutered matcher, and a tree with every pointer rewritten out of range. The last two
+    are the `terminology` scenario, and both refuse instead of going green.
+  - **Exit codes and corpus handling were re-derived from this repository, not inherited.** `0`, `1`
+    for a finding and `2` for a refusal come from `scripts/phi-scan.ts`. An unmerged path **refuses**
+    here even though `phi-scan` leaves that status unenumerated, because its reasoning (`git commit`
+    refuses an unmerged index) covers a staged route this gate does not have.
+  - **The NUL skip is a disclosed miss, not a pass**, and is required rather than tidy: the tree
+    tracks vendored `@cosyte/*` tarballs and a synthetic DICOM fixture, none readable as markdown or
+    editable to clear a red. The tell is the skipped count on the OK line. A draft claimed this
+    partition differs from `check-no-emdash.sh`'s; **that was false and was corrected by reading that
+    gate's own OK line.** Both key on an actual NUL byte; the wider set is git's own binary
+    classification, which is why neither gate may be reduced to `grep -I`.
+
+- **`parse` has a documented input-size limit: 67108864 bytes (64 MiB) per invocation, refused as a
+  data error.** Node has two hard allocation ceilings (`buffer.constants.MAX_LENGTH` and
+  `buffer.constants.MAX_STRING_LENGTH`), and a legitimately large input that crossed one of them threw
+  past every handler and was reported as `CLI_INTERNAL` / exit `70`, which says "this is a bug in the
+  tool" about an input that is merely big. The CLI now declares its own limit far below both, checks it
+  against the **running byte count as the input arrives**, and refuses with a value-free
+  `CLI_INPUT_TOO_LARGE` naming the limit and exit `65`. The number is rendered from one constant into
+  `cosyte --help` and the command reference, and a test reds if the two ever disagree.
+  - The refusal fires before anything allocates memory proportional to the oversized input, which is
+    what makes it a refusal rather than a slower way to reach the same crash. The regression suite
+    proves it with sources that would run past `MAX_STRING_LENGTH` if anything drained them.
+  - The MLLP frame reader's own smaller default ceiling is raised to the CLI's limit on this path, so
+    the documented number is the binding one rather than an undocumented number underneath it.
+
+### Changed
+
+- **The CLI now runs on the 0.1 releases of every `@cosyte` library it uses except `@cosyte/deid`.**
+  The two required dependencies, `@cosyte/hl7` and `@cosyte/terminology`, and the optional
+  `@cosyte/astm`, `@cosyte/ccda`, `@cosyte/dicom`, `@cosyte/mllp`, `@cosyte/ncpdp`,
+  `@cosyte/transform` and `@cosyte/x12` move from their `0.0.x` releases to `^0.1.0`, so an install
+  takes their `0.1.x` patch releases and stops before `0.2.0`. `@cosyte/deid` follows in the next
+  entry, because it changes what `redact` does. The CLI's commands, flags, exit codes and diagnostic
+  codes are unchanged.
+- **`redact` now delegates to the 0.1 releases of `@cosyte/deid`, and refuses more HL7 messages.**
+  The optional `@cosyte/deid` moves from `^0.0.9` (which pinned exactly `0.0.9`) to `^0.1.0`. The
+  library's default policy is the one `redact` applies, unmodified, and under it:
+  - **An HL7 visit number or order number refuses the run.** `PV1-19`, and a placer or filler order
+    number (`ORC-2`/`ORC-3`, `OBR-2`/`OBR-3`), fall to the catch-all identifier category, which the
+    default policy blocks (`DEID_LOCUS_BLOCKED`). `redact` answers with its existing refusal:
+    `CLI_DEID_INCOMPLETE`, exit `1`, nothing on stdout, and each blocked locus named on stderr with
+    the policy still attributed to the library. An ADT message that carries a visit number, which
+    `redact` used to de-identify, is now refused. The CLI passes no policy of its own to turn the
+    block into a removal: the library's own profile API rejects that weakening.
+  - **Medical record, account and member numbers are removed** (`DEID_CATEGORY_REMOVED`) rather than
+    replaced by a keyed surrogate. The per-invocation ephemeral key and its stderr disclosure stay,
+    so any keyed transform the library applies is never unkeyed.
+  - **HL7 `MSH-7` and `EVN-2` timestamps are now generalized.** The `0.0.9` policy left them
+    unchanged; a guard in the suite reds if a delegate that does so is ever resolved again.
+  - No exit code, diagnostic code or flag changed. The README and the command reference, limitations
+    and troubleshooting pages say which inputs produce output and which are refused.
+- **The `js-yaml` dependency override now covers the advisory's extended range.** The pin moves from
+  `4.2.0` on `>=4.0.0 <4.2.0` to `4.3.0` on `>=4.0.0 <4.3.0`, so a transitive resolution landing
+  inside the newly covered window is remediated instead of being admitted silently. The `esbuild`
+  override is untouched, and the lockfile records the new pin.
+- **`pnpm-workspace.yaml` declares the install hardening this package relies on**: a
+  `minimumReleaseAge` of 1440 minutes, which is the cooling-off window that blunts a compromised
+  release, and a `trustPolicy` of `no-downgrade`.
+  - **The `packageManager` pin moves to a pnpm release that honours both keys.** The previous pin
+    predates them, so it would have ignored the settings file entirely: a file that decorates rather
+    than defends is worse than an absent one, because it reads as a control that is in place.
+  - **Nothing an install resolves changed beyond the override above.** The full pre-publish ladder
+    (clean, typecheck, lint, test, build and the types check) runs green on the new pin.
+- **The always-read agent guide is inside its declared line budget, and nothing it said was lost.**
+  Every rule and every trap stays there as a one-line imperative carrying a resolving pointer, and
+  the sentences that explained each one moved into the narrative document verbatim. The two-file
+  contract gate checks on every run that each pointer still lands on a section with a body, so the
+  compression cannot quietly become a deletion.
+- **The declared Node range now matches the release lines this package is tested on.**
+  `engines.node` narrows from `>=22.0.0` to `>=22.0.0 <26.0.0`. Node 26 is supported upstream and
+  was admitted by the old open-ended range while the test matrix exercises 22 and 24 only, so an
+  install on Node 26 was a combination nobody here had run and the manifest said nothing about it.
+  The claim narrows to the tested set rather than the tested set widening to the claim: every matrix
+  cell is a required status check whose name is fixed by a repository setting no commit can edit, so
+  adding a line is a change that has to start outside this repository.
+  - **The tested set is stated here now.** The CI caller passes the Node majors explicitly rather
+    than inheriting them from the shared pipeline's input default. The same two versions run and
+    every status-check name is byte-identical; what changed is that the set is readable and diffable
+    in this repository instead of resolved somewhere else.
+  - **A guard reds when the two drift apart again.** It derives the lines upstream still supports
+    from a release schedule committed beside it, evaluated at the run date rather than pinned to a
+    number typed into a test, and reports a supported line the range admits but the matrix skips, a
+    matrix cell the range refuses, a range admitting a line the schedule does not carry, and any
+    prose surface restating the range or the matrix differently. It refuses to report agreement over
+    an absent, empty or provenance-less schedule.
+  - **The installation prerequisite states the upper bound too**, so the published documentation and
+    the published manifest cannot disagree about which runtimes are supported.
+- **The MCP text content block is now the serialized JSON of the structured result**, replacing the
+  command's raw stdout (on a success) or its stderr diagnostic (on a failure). A client that reads
+  only text now sees exactly the value a schema-aware client validates: there is one value, serialized
+  once, so the two channels cannot disagree. A client that read the text block expecting the bare
+  command output will find the same payload one level down, under `data`.
+- **Multi-record `parse` output (`--ndjson` and MLLP) is now emitted record by record, as each record
+  is parsed**, instead of being accumulated and written once at the end. The first line reaches stdout
+  before the rest of the input has been read, so a bulk batch pipes into the next process instead of
+  waiting on the whole file. Per-record isolation and the exit-code contract are unchanged: a record
+  that fails to parse is still a value-free `{ record, error }` line, the stream still continues, and
+  any failed record still resolves the invocation to exit `65`.
+  - **A fatal condition part way through keeps the lines already written and still exits non-zero.**
+    A truncated MLLP stream is the visible case: the frames that completed have already been emitted
+    when the unterminated one is detected at end of stream, so `stdout` is no longer empty for that
+    input. It was never a success and still is not: the exit code carries the failure, and a partial
+    record stream is never reported as a complete one.
+  - **A downstream consumer that closes the pipe part way through is now a value-free
+    `CLI_OUTPUT_WRITE_FAILED`** rather than an unhandled write error. One write per record is a
+    failure surface a single write did not have.
+
+- **`CLAUDE.md` narrative was relocated into `documentation/agent-notes.md` to make room for the gate's
+  rules.** The branch-protection, PHI-scanner-residual and em-dash blocks were compressed to their
+  imperatives; every trap keeps a one-line rule and a pointer, and the reasoning each one compresses
+  was already in the narrative file. No trap was deleted and no ceiling was raised.
+
 ### Fixed
 
+- **The PHI scanner reported on a run that had enumerated a target and never read it.** A logged
+  `--allow-fixture` bypass withdraws a file after the scan has already named it on the command line,
+  and the run then reported on whatever was left as though the corpus were whole. Over a corpus whose
+  only violator was withdrawn, that reads as a clean verdict about a file nobody opened.
+  - **The run now refuses, with a status distinct from both the clean status and the hits status.**
+    The refusal names every enumerated path that went unread and points at the token-level allow-list
+    as the remedy, because declaring an identifier keeps the file inside the scan while withdrawing it
+    removes the only evidence the run could have had about it.
+  - **Hits are reported FIRST, always.** A refusal raised before the findings were written would
+    discard every hit the run did find, which turns a stricter gate into a quieter one. The report
+    runs first and the refusal changes only the exit status.
+  - **The question is answered as a set difference, never as a count.** A count counts the targets
+    that DID get read, so it reads healthy at the exact moment a withdrawal empties the corpus, and it
+    cannot say which paths were missed.
+  - **An honest run is untouched.** With nothing withdrawn, the read set is the enumerated set, so the
+    pre-commit hook, the whole-tree sweep and a plain scan of named paths keep the exit codes they
+    already had.
+- **The exit-code contract labelled exit `2` as `EX_USAGE`, and `sysexits.h` assigns `EX_USAGE` the
+  value `64` (EXIT-CODE-SYSEXITS-LABEL).** The label sat in two places in `src/core/exit-codes.ts`,
+  the module's contract table and the `USAGE` member's JSDoc, so it compiled into `dist/*.d.ts` and
+  rendered on a consumer's hover. `README.md` and the concepts page grounded their whole table in
+  that header while listing `1` and `2`, which it does not define at all. A developer aligning their
+  own tooling to `sysexits.h` therefore learned a false fact about it from our documentation.
+  - **Exit `2` now carries no sysexits constant, and `1` and `2` are both stated as this CLI's own
+    values.** The four labels that were already correct (`EX_DATAERR` 65, `EX_NOINPUT` 66,
+    `EX_UNAVAILABLE` 69, `EX_SOFTWARE` 70) are untouched.
+  - **No published number moved, and no member of the exported `EXIT` map was added, removed or
+    renamed.** This is a documentation correction and nothing else: `2` is still `2`, every command
+    still exits with the status it exited with before, and the golden exit-code matrix is unchanged.
+    A consumer who hard-coded `EX_USAGE = 2` against this CLI keeps working.
+  - **`test/exit-code-docs.test.ts` reds if a sysexits constant is ever again attached to a number
+    that header does not assign it**, across every source file, the README and every published docs
+    page, naming the offending surface, line and code. It carries the header's own table, reports a
+    constant that table does not define rather than passing it through, and is proved against the
+    exact text that shipped before this correction.
+- **`pnpm phi-scan`'s all-mode walk was rooted at `test/__fixtures__` and `src` only, so 89 of this
+  repository's 123 tracked files were scanned by NEITHER of its two routes
+  (PHI-SCAN-WALK-ROOT-SCOPE).** The walk now roots at **`src`, `test` and `scripts`**, which opens 72
+  tracked files instead of 34.
+  - **Measured back to back on the base commit, and re-derived for this repository rather than ported
+    from a sibling.** A dashed SSN and an off-domain address written into `test/planted.test.ts`, in
+    this repository's own inline-message shape (a whole HL7 message as one `.ts` string literal with
+    `\r` escapes between its segments), exited **0** with `OK, no hits` in all mode, while naming the
+    same file in paths mode reported both at **exit 1** over the same bytes. A file written under
+    `scripts/` behaved identically. Both routes now report both.
+  - **All 38 newly opened files were hand-read.** Every message literal is a placeholder and the only
+    SSN/email shapes anywhere are the scanner's own declared synthetic payload, so the gap was one of
+    **enumeration**, not a live exposure: the defect was that the gate could not see those files, so
+    nothing would have caught a real value if one appeared.
+  - **`test` REPLACES `test/__fixtures__` rather than joining it.** Roots must stay disjoint: each is
+    walked independently and the results concatenated, so a nested root would enumerate every file
+    beneath it twice and report each hit twice. The fixture directory is still watched, through the
+    observation rule's other condition, **wherever git tracks files under it** (here, seven); only the
+    root a refusal is filed under changed.
+  - **One cover was LOST, and it is stated rather than implied away:** where git tracks NOTHING under
+    `test/__fixtures__`, an empty one no longer refuses. As a declared root it refused by the
+    opened-nothing floor whatever git carried; as an ordinary directory it contributes no entry and the
+    reconciliation has no expected path to miss. A test pins it.
+  - **`scripts/` is a root because the scanner, its allow-list and its override log live there**, so
+    the one directory guaranteed to hold PHI-shaped text was the one nothing enumerated. All nine
+    files there were measured against the detector before the root was declared: no hits.
+  - **The cost of that root nobody would guess: the allow-list's own bytes.** The allow-list documents
+    `ID <value>` as a synthetic id "matching an SSN / MRN / member-id shape", and the dashed-SSN check
+    consults no allow-list, so an `ID` entry written in that dashed shape now reds the gate on the
+    allow-list itself. Latent today (the shipped file declares its only id in the `MRN-` form, and a
+    test pins that). **The remedy is to spell the id in a shape the check does not match**, never to
+    make that check consult the allow-list (which would delete a detection) and never to exempt the
+    file (which would leave the likeliest place for a real value unswept).
+  - **A narrowing that came with it:** `test/__fixtures__` is no longer a declared root, so a live or
+    dangling symbolic link at that path is now an enumerated entry and is refused outright, whatever
+    it points at. Only the three top-level roots can still be followed.
+  - **`test/scripts/phi-scan.test.ts` is exempt from the sweep, and is the only exempt path.** It
+    carries violator literals on purpose, as the positive half of the scanner's own tests. The
+    exemption is applied **after the read**, so the file still counts as observed and an unreadable
+    one still refuses; it is **scoped to the sweep**, so naming the file explicitly still reports
+    every hit; and it is **per path, never a pattern**.
+  - **What this does NOT buy, stated because a wider reading would be false:** the detector is still
+    the cross-cutting SSN + email floor, over 38 more files. Structured, field-level detection remains
+    unimplemented, and a test now pins that limit rather than leaving it as prose.
+  - **`--staged` is deliberately unchanged**, because widening it changes what a commit is blocked on.
+    The two routes therefore differ widely, and the scanner's own documentation says by how much.
+  - **Four claims about which directories are deliberately NOT scan roots are now checks rather than
+    prose**, after two of them were measured false: `docs-content/` and `.changeset/` each carry one
+    tracked non-markdown file, and the repository root is not clean under the detector (the `author`
+    field carries a real off-domain contact address). `documentation/` and `.github/` were correct.
+
+- **`pnpm phi-scan` printed `OK, no hits` and exited 0 over a corpus it never opened
+  (PHI-SCAN-OBSERVED-NOTHING-IS-GLOBAL).** A declared scan root that the walk never observed is now
+  a refusal at **exit 2**, in the all-mode sweep CI runs. Each root's walk is reconciled against
+  `git ls-files`, and two independent conditions refuse: the root contributed **nothing**, or git
+  tracks an in-scope file under the root that the walk did not open.
+  - **Six states measured on this repository, every one of them previously exiting 0 with
+    `OK, no hits`:** the root missing; the root emptied; the root a **dangling** symbolic link; the
+    root a **live** symbolic link to a directory outside the repository; a single tracked fixture
+    removed from the working tree with the rest of the root still opened; and `src` moved away.
+  - **The dangling case is why a kind check cannot stand in for this rule.** `existsSync` follows
+    the link and answers false, so `walk()` returns before `readdirSync` and the existing
+    not-a-regular-file refusal never fires. Nothing about the entry is ever inspected, so no check
+    on its kind can reach it. Refusing on what was **observed** needs no opinion about the entry.
+  - **A denominator is deliberately not what this is.** A count counts the roots and the files that
+    did exist, so a healthy-looking total is exactly what a starved root produces. This scanner
+    prints no file count and one was not added.
+  - **Existence is not observation, which is why both conditions ship.** Refusing only a missing
+    root leaves the emptied one open; refusing only an empty result leaves the swapped one open,
+    because a root pointed at another directory opens plenty. Neither subsumes the other.
+  - **Exit 2 was derived from this scanner's own contract, not ported from a sibling.** `1` means
+    "hits found" here; `walk()` already raises an unreadable root as an invocation failure, and a
+    root replaced by a regular file already exits 2 through `readdirSync`. Sibling scanners disagree
+    on this code, and carrying one across would have been the defect.
+  - **`git ls-files` failing refuses rather than answering the empty set**, because an empty answer
+    is indistinguishable from "this root tracks nothing" and would switch the rule off in silence.
+  - **The rule is one-directional on purpose.** A tracked in-scope file the walk missed refuses; an
+    untracked working-tree file the walk found does not, because scanning more than git carries is
+    the safe direction.
+  - **Scope, stated rather than left to be inferred:** all-mode only. `--staged` is a diff and not a
+    corpus, and widening it would change what a **commit** is blocked on, which is a separate
+    decision. Naming paths explicitly is unchanged.
+  - **Narrowed, not closed, and still disclosed in the module header:** a scan root that is itself a
+    live link is still followed. It is now refused whenever git tracks an in-scope file under the
+    root that the link's target does not also carry **at the same relative path**, so a link to an
+    unrelated directory refuses; the reconciliation compares path **sets** rather than the bytes git
+    carries at those paths, so a target mirroring the tracked names still passes at exit 0, and a
+    root git tracks nothing under is the degenerate case of that rather than the whole of it. An
+    **ancestor** of a scan root remains out of the staged route's scope, and paths mode still follows
+    a link a caller names.
+- **A present-but-unreadable `phi-scan-overrides.md` exited 1, the code reserved for "hits found".**
+  `loadOverrideLog` threw a raw filesystem error past every handler while its sibling reader,
+  `loadAllowList`, had already been wrapped. It now exits 2 with a diagnostic. A caller branching on
+  the exit code read a broken invocation as a PHI finding.
 - **A red pre-publish gate showed a red X and merged anyway, because `ci / prepublish` was a
   required check nowhere (CI-REQUIRED-CHECKS).** The shared pipeline this repo calls grew a
   `prepublish` job on 2026-08-05 (`cosyte/.github#35`, `6142ac4`; its second layer defaulted on in