[NSchatz]

Harness-Task: 55

Replaces the 261-line CLAUDE.md with a 57-line card a session can read in seconds: what the repo is, the gate in the order CI runs it, the hazard, and the nine rules that a recorded failure proved. Each rule names its failure (a fix PR or a commit) and, where documentation/agent-notes.md has the reasoning, points at that section. Architecture, status, history and rationale are left out, and nothing was moved into another file: git history keeps the old text.

What the card keeps, and why

• The gate is taken from the CI the required checks come from: the shared ci / verify ladder that .github/workflows/ci.yml calls (install, typecheck, lint, format check, PHI scan, test, coverage, build, attw), this repo's examples and conformance jobs in the same file, and the two gate workflows no-emdash.yml and no-internal-refs.yml. The card says to put the pinned pnpm 10.34.5 first on PATH, and why: on this branch, pnpm 12.14.0 on PATH failed pnpm install --frozen-lockfile with ERR_PNPM_LOCKFILE_CONFIG_MISMATCH (it ignores pnpm.overrides), and prefixing each step with corepack was not enough, because test/docs-content.test.ts runs a bare pnpm build, which hit pnpm 12 and failed with ERR_PNPM_BAD_PM_VERSION. With corepack enable --install-directory <dir> pnpm and <dir> first on PATH, pnpm --version prints 10.34.5 and the gate below ran.
• Rules kept, one line each with its failure: no document text in messages or unbounded model fields (fix(phi): build every warning and fatal message from a frozen registry (PHI-WARNING-MESSAGE-LEAK) #77); refuse a narrative label instead of defaulting one (fix(builder): refuse a missing narrative label instead of rendering a positively-asserted allergy as "No known allergies" #100); transcribe terminology from the published source, never from memory (fix(ccda): wire up two dead diagnostics, and read the whole v3 NullFlavor code system (CCDA-DEAD-DIAGNOSTICS) #78); keep pnpm attw on its wrapper (fix(attw): make the publish gate report an untyped pack instead of passing it (ATTW-FALSE-GREEN-PORT) #82); check for em dashes with the repo script, because grep skips src/profiles/merge.ts as binary (Remove em dashes from source + config #52, ci: port the em-dash brand gate to ccda, and remove the one live character it found (EMDASH-CONFORMANCE) #60); no exemption in the PHI scanner (fix(phi-scan): scan the tracked corpus every route used to read past #103); a test that writes into the tree races the others (Run the working-tree snapshot test alone, after every other test file #146); never hand-edit CHANGELOG.md (fix(changelog): let the release write CHANGELOG.md, and stop shipping "will ship" #94); classify a changeset's bump from what it does (S0196-ccda-release-prep-1: audit the pending changesets against a 0.1.0 release #125).
• Dropped: everything the workspace rules already give every session (brand, synthetic data only, what waits for the owner), and every imperative from the old file that we could not tie to a recorded failure.

The agent-notes contract still holds

pnpm test runs scripts/check-agent-notes-contract.mjs, which fails if CLAUDE.md carries no pointer into documentation/agent-notes.md or if a pointer does not resolve. The card keeps seven pointers and all of them resolve. No other file linked to a section of CLAUDE.md (rg 'CLAUDE\.md#' finds nothing), so nothing else changed.

Not changed, and left for a later task because the scope here is CLAUDE.md only: the preamble of documentation/agent-notes.md still says every trap has a one-line imperative in CLAUDE.md, and a few code comments (scripts/check-no-internal-refs.sh, scripts/check-agent-notes-contract.mjs, test/edge-cases.test.ts) still describe what the old CLAUDE.md recorded. None of them is a link.

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

Command	How it was checked
pnpm --version, pnpm install --frozen-lockfile	pnpm built-ins, not scripts; pnpm itself is a binary on PATH (command -v pnpm), pinned by packageManager (pnpm@10.34.5)
corepack enable --install-directory <dir> pnpm	corepack is a binary on PATH: command -v corepack gives /usr/local/bin/corepack; enable --install-directory was run on this branch and wrote the pnpm shim
pnpm typecheck, lint, format:check, phi-scan, test, test:coverage, build, attw	each a key in jq -r '.scripts | keys[]' package.json
pnpm typecheck:examples, lint:examples, examples	each a script in package.json
pnpm check:no-emdash, check:no-internal-refs, check:agent-notes	each a script in package.json
pnpm conformance, pnpm changeset	each a script in package.json
grep	binary on PATH: type -P grep gives /usr/bin/grep
actionlint	CI installs it (reviewdog/action-actionlint in the shared workflow); also on PATH here
.github/workflows/ci.yml, test/docs-content.test.ts, documentation/agent-notes.md, src/profiles/merge.ts, scripts/phi-scan.ts, CHANGELOG.md, package.json	each listed by git ls-files <path>

wc -l < CLAUDE.md prints 57.

Gate run on this branch

Run from the repo root with pnpm 10.34.5 first on PATH, in the card's order. Every step passed: pnpm install --frozen-lockfile, typecheck, lint, format:check, phi-scan, test (43 files, 1375 passed, 1 skipped), test:coverage, build, attw, typecheck:examples, lint:examples, examples, check:no-emdash, check:no-internal-refs and conformance (15 built documents, 20 corpus round trips, report unchanged). node scripts/check-agent-notes-contract.mjs prints OK with 15 pointers, 7 of them in CLAUDE.md. rg -n '[\x{2013}\x{2014}]' CLAUDE.md finds nothing.

No changeset: nothing under src/ changed and nothing published moves.

🤖 Generated with Claude Code