[NSchatz]

What

Replaces the 299-line CLAUDE.md with a short card (59 lines): what the repo is, its gate in the order CI runs it, its hazard, and only the rules a past failure proved, each citing the cosyte/synth PR that fixed that failure. Nothing was moved into another file: the old text stays in git history, and documentation/agent-notes.md is untouched.

Two code comments cited CLAUDE.md sentences the card drops, so they were repointed (comments only, no behaviour change):

• scripts/determinism/engines.ts: the "nothing inside this repository can observe its own ruleset" sentence now cites documentation/agent-notes.md, where it still lives.
• scripts/check-no-internal-refs.sh: the JSDoc guardrail sentence no longer says it lives in CLAUDE.md; the JSDoc lint rule enforces it.

No src/ change, so no changeset.

Finish line

wc -l < CLAUDE.md prints 59 (limit 60).

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

package.json scripts (jq -r '.scripts | keys[]' package.json): typecheck, lint, format:check, phi-scan, test, test:coverage, build, attw, examples, smoke, check:install, check:test-selection, determinism:digest, check:determinism-window, acquire:oracle, oracle, check:no-emdash, check:no-internal-refs. All 18 present.

• pnpm phi-scan --staged: the pre-commit entry of simple-git-hooks in package.json.
• pnpm check:no-emdash --stdin pr: the --stdin LABEL mode in the usage header of scripts/check-no-emdash.sh.

Files (git ls-files <path>, each returns the path): CHANGELOG.md, README.md, package.json, vitest.config.ts, src/index.ts, src/select.ts, scripts/attw.mjs, scripts/sync-version.mjs, scripts/phi-scan.ts, scripts/phi-allow-list.txt, .github/workflows/ci.yml, smoke.yml, install.yml, test-selection.yml, no-emdash.yml, no-internal-refs.yml. Directories: vendor/ (7 tracked), docs-content/ (15), .changeset/ (2). .changeset/<slug>.md is a pattern for a new file.

Identifiers (grep): SynthError and SYNTH_FATAL_MESSAGES in src/codes.ts; resolveKind and resolveMix exported from src/select.ts; VERSION in src/index.ts; BINARY_EXEMPT_PATHS in scripts/phi-scan.ts; NAME, EMAIL and EMAILDOMAIN tags in scripts/phi-allow-list.txt.

Binaries (command -v): corepack, actionlint, java, git. pnpm must be pnpm 10 (packageManager is pnpm@10.0.0): the pnpm 12 on this box's PATH refuses the repo (ERR_PNPM_VERIFY_DEPS_BEFORE_RUN, then ERR_PNPM_BAD_PM_VERSION), and test/docs-content.test.ts shells out to pnpm build, so corepack pnpm test alone still fails. The card's fix, corepack enable --install-directory <dir> pnpm with <dir> first on PATH, was run here and gives pnpm --version = 10.0.0. attw, named only as the thing not to call, is node_modules/.bin/attw after install. CI-only, said as such in the card: the shared prepublish checks and CodeQL (and reviewdog for actionlint).

Where the gate comes from

ci.yml calls the shared cosyte/.github reusable ci.yml, whose verify job runs install, typecheck, lint, format:check, phi-scan (on, via run-phi-scan: true), test, test:coverage, build, attw and a dual ESM/CJS smoke; its prepublish job runs the shared manifest lint and packed-tarball install; actionlint runs through reviewdog. This repo's ci.yml adds oracle (acquire:oracle, oracle), the determinism jobs (determinism:digest on Node 22 and 24, determinism:verify, check:determinism-window) and examples (build, examples). smoke.yml, install.yml and test-selection.yml run smoke, check:install and check:test-selection. no-emdash.yml and no-internal-refs.yml call the shared gate workflows, which run check:no-emdash (tracked files, then --stdin over the PR title, body and commits) and check:no-internal-refs.

Rules kept, and the failure behind each

Rule	Failure
Fatals are SynthError(code) from SYNTH_FATAL_MESSAGES; selectors resolved first	#29: a caller string reached err.message through a peer builder; unresolved kinds mislabeled corpora
Changesets write CHANGELOG.md; no hand edits, no [Unreleased]	#45: 0.0.1 to 0.0.7 shipped a changelog with no version headings
Never hand-edit VERSION	#39: five releases exported "0.0.0"
pnpm attw is the wrapper; no bare attw, no extra flags	#36: bare attw exits 0 on a pack with no types
Never narrow vitest include or the test scripts; stage new tests	#25: a narrowed glob dropped every synthetic-safety suite with every required check green
Clear a flagged value with one exact allow-list entry; --allow-fixture exits 2	#49 (a domain-wide entry passed the suite where one address was meant), #61 (--allow-fixture reached exit 0 over a seeded violator)
A parser bump can move bytes; re-run tests and the digest after a vendor refresh	#67: swapping @cosyte/ccda moved four digests and six golden fixtures
No item ids or internal paths on what a consumer reads	#18: 416 doc-comment hits in src/, 562 lines in the built .d.ts
Measure before claiming coverage; re-measure ported claims	#25, #55, #67: each corrected a claim made by reasoning
Hazard: never make a synthetic identifier valid	#52: 900-range SSNs overlapped IRS ITIN groups

Dropped

Brand, no-PHI, em dashes and what waits for the owner (every session reads those first, before this file); architecture, per-format status, history and phase names; and rules with no recorded failure in this repo: the ruleset-handling notes (renaming or splitting a required job, requiring a context early), design notes (buildCcda's default effectiveTime, distinct ASTM patient ids, the deid sweep loci, quirk grounding), and porting rationales from sibling repos.

One left out on purpose: the old note to run Prettier over docs-content/ by hand. main already fails it (prettier --list-different "docs-content/**/*.md" lists docs-content/limitations.md), and fixing that is outside this task.

Gate run

Run locally on the head commit, from the repo root, with pnpm 10.0.0 on PATH (the card's corepack step), in the card's order. All exit 0:

pnpm typecheck, pnpm lint, pnpm format:check, pnpm phi-scan (262 files, no hits), pnpm test, pnpm test:coverage, pnpm build, pnpm attw, pnpm examples, pnpm smoke, pnpm check:install, pnpm check:test-selection, pnpm run determinism:digest, pnpm run check:determinism-window, pnpm run acquire:oracle, pnpm run oracle, pnpm check:no-emdash, pnpm check:no-internal-refs, actionlint.

Two things the first run hit, both from this box rather than the change: pnpm test failed under the pnpm 12 on PATH (test/docs-content.test.ts runs pnpm build), which is why the card now says how to get pnpm 10 on PATH; and pnpm run oracle failed until a JDK was selected (java here is a version manager shim with no default), then graded clean. Dash check on the changed files and this text: rg -n '[\x{2013}\x{2014}]' finds nothing.

Harness-Task: 75

🤖 Generated with Claude Code