[NSchatz]

Replaces the 317-line CLAUDE.md with a 58-line card (wc -l < CLAUDE.md prints 58). In order, the card has: what the library is, the gate in CI order, the patient-data hazard in our own words, and ten rules. Each rule points at the PR or recorded failure behind it. Only CLAUDE.md changes.

What was kept, and why

A rule stays only if a past failure proved it. Each one cites the fix PR, plus the documentation/agent-notes.md section where that failure is written up:

Rule	Failure behind it
A message without a new segment produces the same bundle and issues	ungated PV1-20 declaration during #46
A v2-required field with no source stays absent and raises a diagnostic, never a default	first cut of the reverse path returned no issue (#38)
Never hand-write a version or publish state; derive it	VERSION shipped as "0.0.0" (#22); README called a published package unpublished (#17)
Never hand-edit CHANGELOG.md	hand-kept [Unreleased] heading shipped published code as unreleased (#28)
pnpm attw is the wrapper, never the bare CLI	bare CLI exits 0 on a tarball with no types (#19)
The PHI scanner refuses when it did not read every file	never-existing root (#35), symlinks (#21), honored --allow-fixture (#44)
No bookkeeping on consumer surfaces	sweep and gate in #11
Keep the card and the agent notes in contract	#29, and the file once rewritten to name another package
Siblings come from the registry, never vendor/	vendored parser nine releases behind (#39)
Count dashes in Python or with the gate, never grep	grep read 0 during the sweep (#33)

Dropped: what the shared agent guide every session reads first already says (brand, no real PHI, what waits for the owner), plus status, phase history, architecture, and rationale with no recorded failure behind it. Git history keeps the old text.

The contract gate still holds. scripts/check-agent-notes.ts (R5) requires a pointer from CLAUDE.md to every ## section of documentation/agent-notes.md. The card points at all ten, from the rules and from the gate paragraph (branch protection), so the archive needs no change. No tracked file links to a CLAUDE.md# anchor, so no link elsewhere needed repair.

Every command and path the card names, and how it was checked (checked, not run)

package.json scripts, checked with jq -r '.scripts | keys[]' package.json: typecheck, lint, format:check, phi-scan, test, test:coverage, build, attw, typecheck:examples, lint:examples, examples, phi-scan:examples, check:no-emdash, ci:no-internal-refs, check:no-internal-refs, check:agent-notes. All 16 are present.

Built-in commands and binaries, checked with command -v:

• pnpm install --frozen-lockfile: a pnpm built-in. pnpm is on PATH, and CI installs the pinned 10.34.5 from packageManager through pnpm/action-setup.
• corepack enable --install-directory <dir> pnpm: corepack is on PATH. This is the card's fix for when the pnpm on PATH is another major. Scripts and tests call a bare pnpm, so corepack pnpm <script> alone is not enough. This is how the local gate below was run.
• npm view @cosyte/transform version: npm is on PATH.
• Python: python3 is on PATH.
• grep: on PATH. The card names it as the tool not to use.
• The bare attw CLI: node_modules/.bin/attw, installed by pnpm install from devDependencies. The card names it as the thing not to swap in.

CI-only, with no local script, and said as such on the card: the dual ESM/CJS import step and actionlint (from the shared ci.yml), CodeQL (.github/workflows/codeql.yml), and the shared pre-publish pack-and-install job.

Files, checked with git ls-files <path>: .github/workflows/ci.yml, .github/workflows/no-emdash.yml, .github/workflows/no-internal-refs.yml, .github/workflows/codeql.yml, package.json, test/messages/to-fhir.test.ts, scripts/attw.mjs, scripts/phi-scan.ts, CHANGELOG.md, README.md, documentation/agent-notes.md. Directories, checked the same way: .changeset/ (2 files), docs-content/ (7), vendor/ (3). dist/ is build output from pnpm build.

Gate run

All from the repo root with pnpm 10.34.5:

• Green: typecheck, lint, format:check, phi-scan, test (952 of 952), build, attw, the four examples scripts, check:no-emdash, ci:no-internal-refs, and the dual ESM/CJS import.
• test:coverage: 3 conformance tests hit the 10 s per-test timeout on this shared machine (load average 25 to 47). The same three files pass alone under coverage (34 of 34). With --testTimeout=60000, all 952 tests pass and coverage clears its thresholds. Main CI is green on the same base commit. This change touches no test input except the contract gate, which passes.

Follow-up, not in scope

The documentation/agent-notes.md preamble still says CLAUDE.md keeps "every trap" as a one-line imperative. That is no longer true. The task scope is CLAUDE.md only, so that sentence is left for a separate change.

Harness-Task: 71

🤖 Generated with Claude Code