@cosyte/script-utils 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,18 +1,36 @@
 # Changelog
 
-All notable changes to `@cosyte/script-utils` are documented here, following
-[Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versions are managed with Changesets;
-this file is hand-maintained (Changesets' own changelog generation is disabled). The package is on the
-**`0.1.x`** line: its surface is settled, and bump types follow ordinary semver rather than a
-pre-alpha rule. See
-[ADR 0002](../../documentation/decisions/0002-the-0-1-0-version-line.md).
+## 0.1.4
 
-> Because the generator is disabled, **`[Unreleased]` is promoted to a version heading BY HAND**, in
-> the pull request that adds the changeset. Nothing does it automatically.
+### Patch Changes
 
-## [Unreleased]
+- b9b2a7c: Every gate is now a bin, so a repository with no `package.json` can run it through npx: `cosyte-no-emdash`, `cosyte-attw`, `cosyte-phi-scan`, `cosyte-internal-refs`, `cosyte-readme`, `cosyte-claude-card`, `cosyte-agent-notes` and `cosyte-catalog`, each with `--help`, and `script-utils`, the dispatcher npx runs by the package's name (`npx -y @cosyte/script-utils@0.1 no-emdash`). The dash gate also matches every form the marketing and consulting scanner caught, in any case: the characters, URL encoding, the backslash-u escape (plain, braced and eight-digit), the braced backslash-x escape, the CSS escape, the Unicode name, and the named, decimal and hexadecimal HTML entities with or without the semicolon and with leading zeros. It now reads every tracked file's name as well as its content, and answers `--help`. A tracked file or name carrying one of the newly matched forms is refused where 0.1.3 printed OK.
 
-## [0.1.2] - Unreleased
+## 0.1.3
+
+### Patch Changes
+
+- f15075b: A new entry point, `@cosyte/script-utils/agent-notes`: the checker for a repository's agent notes, which replaces each library's own. What does not fit on the CLAUDE.md card lives in one file, `documentation/agent-notes.md`, and the card points into it in one form, `documentation/agent-notes.md#<anchor>`. The checker reads every tracked file and requires every pointer to name a heading of the notes (its GitHub slug) or an explicit `<a id>` or `<a name>` target; in CLAUDE.md it also refuses a bare backticked `#anchor` and `agent-notes.md#` without its directory. A notes directory, notes the card never points into, a blank notes file, an empty section and a citation of the umbrella's deleted ADR 0023 or its doc-budget hook are findings. Run it with `node node_modules/@cosyte/script-utils/agent-notes.js`; it exits 0 when clean, 1 with each finding's file, line and rule, and 2 when it cannot run.
+- 7a0f98c: The `attw` gate in `@cosyte/script-utils` reads `npm pack --dry-run --json` in both of npm's shapes: the array npm 10 and 11 print, and the object keyed by package name that npm 12 prints. Before this, npm 12's object read as no tarball at all, and the gate refused every package ("npm described 0 tarball(s)"). It still requires exactly one entry whose name is the package's own, and in the object shape the key must match too; any other document is refused as before. The docblock no longer says every repo's `prepare` is the same one-liner: the parser template's `prepare` printed on stdout, inside the JSON this net reads, and twelve sibling repos still carry that line.
+- 9d56322: A new entry point, `@cosyte/script-utils/catalog`: the one list of our libraries. It holds a record for each of the 14 libraries, the 8 standards (HL7 v2, MLLP, FHIR, C-CDA, X12, NCPDP, ASTM and DICOM) and the 6 built on them (terminology, transform, deid, synth, dates and cli), and one for Pathways, our integration engine, in development and not on npm. Each record is generated from the package's own package.json (name, description, release line, engines, repository, docs and npm URLs) and carries its tier. The data ships as `catalog.json` beside the module, and `CATALOG` is that file, frozen. Every library can run `node node_modules/@cosyte/script-utils/catalog.js` to check that its package.json description is the catalog's: it exits 0 when they agree, 1 with both values when they do not, and 2 when the package is not listed or package.json cannot be read.
+- d0a2576: A new entry point, `@cosyte/script-utils/claude-card`: the checker for the CLAUDE.md card every Cosyte repository keeps. A card opens with `# <name>` and a paragraph, then has exactly three level-2 sections in order, Gate, Hazard and Rules (a heading may go on after its word, as in `## Rules that bind here`), none empty. It is at most 60 lines, every line at most 100 characters with code included, and at most 5,120 bytes, and when an AGENTS.md sits beside it the card imports it on a line of its own (`@AGENTS.md`). Run it with `node node_modules/@cosyte/script-utils/claude-card.js`; it exits 0 when the card follows the spec, 1 with each finding's line and rule, and 2 when CLAUDE.md cannot be read. `checkClaudeCard`, `runClaudeCardGate` and the limits it checks against are exported.
+- a71747a: The attw, PHI-scan and internal-reference gates run from the command line, each with one per-repository file, as the dash gate already did. `node node_modules/@cosyte/script-utils/attw.js` runs the attw gate for the package in the working directory, and `scripts/attw.exclude` selects the profile (`node10` alone for `node16`, with `node16-cjs` for `esm-only`). `node node_modules/@cosyte/script-utils/phi-scan.js` runs the PHI engine over the whole repository with exit codes 0, 1 and 2, `--staged` reading everything but Markdown, and the literal tracked paths in `scripts/phi-scan.exclude` left out; it carries the cross-cutting floor only. `node node_modules/@cosyte/script-utils/internal-refs.js` reads the gate's axes from `scripts/internal-refs.json`, with exit codes 0, 1 and 2. The PHI engine's `--staged` route now passes `--ignore-submodules=none` to git, so a staged gitlink is refused even when the user's git config hides submodules from `git diff`. The internal-reference gate's ADR rule also matches an ADR path segment (`docs/adr/0001-scope.md`) and its phase rule the plural (`Phases 1 to 6`), as ten of the eleven per-repository copies did, and an extra rule's pattern may be a `{ source, flags }` object, so a rule read from JSON can be case-insensitive.
+- bcdb7ea: The README's license line names the legal owner: "MIT, copyright Cosyte LLC." The READMEs of `@cosyte/eslint-config`, `@cosyte/process` and `@cosyte/script-utils` also use US spelling where they did not (license, behavior, generalize, recognized, honored). No code, configuration or type changes.
+- e788688: A new entry point, `@cosyte/script-utils/readme`: the README gate for every `@cosyte/*` library. It checks the house skeleton (the shared lockup tile with the alt text assets declares for it, `# <package name>`, a one-line tagline, the badge row for npm version, CI, license and Node derived from `package.json`, the sections Why this exists, Status, Install, Usage, Support, Security, Contributing and License in that order with none empty, a link to the package's page on docs.cosyte.com between Usage and Support, and License last with an absolute link to the repository's LICENSE) and refuses a README over 60,000 characters, because npm keeps only the first 65,536. Run it with `node node_modules/@cosyte/script-utils/readme.js`; it exits 0 when the README follows the skeleton, 1 with each finding's line and rule, and 2 when it cannot read the package. `checkReadme`, `badgeRow`, `runReadmeGate` and the constants it checks against are exported.
+
+## Released before this file was generated
+
+Every release section above this heading is written by
+[Changesets](https://github.com/changesets/changesets) from the changesets in `.changeset/`, newest
+release first. A release writes its own version heading, so nothing above this line is maintained by
+hand: a change is recorded by adding a changeset rather than by editing this file.
+
+The sections below were kept by hand, in the
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format, until 2026-11-07. A version heading
+that still read "Unreleased" after its version reached npm now carries that date; no entry was
+reworded.
+
+## [0.1.2] - 2026-11-07
 
 ### Changed
 
@@ -25,7 +43,7 @@ pre-alpha rule. See
   now refuses where 0.1.1 printed OK**: write a range with "to", and rewrite a pause with a period,
   a colon, a comma or parentheses.
 
-## [0.1.1] - Unreleased
+## [0.1.1] - 2026-09-24
 
 ### Fixed
 
@@ -39,7 +57,7 @@ pre-alpha rule. See
   still read from the bytes git carries and a hit in them is printed before the refusal; the
   completeness rule still counts every read, and a root the walk reads is not refused.
 
-## [0.1.0] - Unreleased
+## [0.1.0] - 2026-09-21
 
 ### Changed
 

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Cosyte
+Copyright (c) 2026 Cosyte LLC
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -49,7 +49,7 @@ that a broken or hostile install cannot decide whether a release gate runs.
 
 ### If your gate runs before `pnpm install`, do not use the bare specifier
 
-Read this before adopting the package, because it is the one thing that does not generalise.
+Read this before adopting the package, because it is the one thing that does not generalize.
 
 A bare `import ... from "@cosyte/script-utils"` resolves through `node_modules`, so it only works
 once the install has happened. `config`'s own gates run before their install and therefore import
@@ -65,8 +65,9 @@ So check when your gate runs, and pick accordingly:
 Installing the package does not, on its own, give a pre-install gate the property described above.
 
 Every entry point is published as source with no build step, so the relative-path route works for
-all three: the files are `index.js`, `phi-scan.js` and `internal-refs.js`, each beside its own
-hand-written `.d.ts`. A vendored copy is one of those files and nothing else.
+each: the files are `index.js` and one `<entry>.js` per subpath, each beside its own hand-written
+`.d.ts`. A vendored copy of a gate is that one file: its command-line form loads nothing beside it
+unless node was pointed at a file of the same name.
 
 ## Usage
 
@@ -142,19 +143,135 @@ import { runAttwGate } from "@cosyte/script-utils/attw";
 typeof runAttwGate; // => "function"
 ```
 
+The README gate is the fifth. It checks a library README against the house skeleton and npm's
+size limit, and it reads everything package-specific from `package.json`:
+
+```ts runnable
+import { checkReadme, README_CHARACTER_LIMIT } from "@cosyte/script-utils/readme";
+
+const manifest = {
+  name: "@cosyte/demo",
+  repository: "https://github.com/cosyte/demo",
+  engines: { node: ">=22.14" },
+};
+
+// A README that is only a title: each finding names the rule it breaks and the line.
+const findings = checkReadme("# @cosyte/demo\n", manifest);
+findings.some((finding) => finding.rule === "tile"); // => true
+README_CHARACTER_LIMIT; // => 60000
+```
+
+The card checker is the sixth. It checks a repository's CLAUDE.md against the card spec: a title,
+a paragraph, then `## Gate`, `## Hazard` and `## Rules`, in at most 60 lines of at most 100
+characters and 5,120 bytes:
+
+```ts runnable
+import { checkClaudeCard, CARD_MAX_LINES } from "@cosyte/script-utils/claude-card";
+
+const card =
+  "# cosyte/demo\n\nOur demo.\n\n## Gate\n\npnpm test\n\n## Hazard\n\nNone.\n\n## Rules\n\n- One.\n";
+checkClaudeCard(card); // => []
+checkClaudeCard(card.replace("## Hazard", "## Notes")).length > 0; // => true
+CARD_MAX_LINES; // => 60
+```
+
+The catalog is the seventh: one record per library, generated from its package.json, with its
+tier, and one for Pathways. A site reads the list from it, and a library checks its description
+against it:
+
+```ts runnable
+import { CATALOG, catalogEntry } from "@cosyte/script-utils/catalog";
+
+CATALOG.libraries.length; // => 14
+CATALOG.libraries.filter((library) => library.tier === "standard").length; // => 8
+catalogEntry("@cosyte/hl7")?.docs; // => "https://docs.cosyte.com/hl7"
+CATALOG.engine.displayName; // => "Pathways"
+```
+
+The agent-notes checker is the eighth. It resolves every pointer into a repository's one notes
+file against that file's headings, slugged the way GitHub slugs them:
+
+```ts runnable
+import { checkAgentNotes, slugify } from "@cosyte/script-utils/agent-notes";
+
+slugify("Why `attw` exits 0"); // => "why-attw-exits-0"
+
+const claude = "# demo\n\nSee documentation/agent-notes.md#setup.\n";
+const notes = "# Notes\n\n## Setup\n\nRun it.\n";
+checkAgentNotes({ claude, notes, files: [] }); // => []
+checkAgentNotes({ claude, notes: notes.replace("Setup", "Install"), files: [] })[0]?.rule; // => "dangling"
+```
+
 ## Entry points
 
-| entry point                          | what it is                                                               |
-| ------------------------------------ | ------------------------------------------------------------------------ |
-| `@cosyte/script-utils`               | `isCliEntrypoint(moduleUrl)`, the entry-point guard                      |
-| `@cosyte/script-utils/phi-scan`      | `runPhiScan(config)` and `exemptsMarkdown(relPath)`, the shared PHI gate |
-| `@cosyte/script-utils/internal-refs` | `runInternalRefsScan(config)`, the shared internal-reference gate        |
-| `@cosyte/script-utils/attw`          | `runAttwGate(options)`, the shared `attw` publish gate                   |
+| entry point                          | what it is                                                                                   |
+| ------------------------------------ | -------------------------------------------------------------------------------------------- |
+| `@cosyte/script-utils`               | `isCliEntrypoint(moduleUrl)`, the entry-point guard                                          |
+| `@cosyte/script-utils/phi-scan`      | `runPhiScan(config)` and `exemptsMarkdown(relPath)`, the shared PHI gate                     |
+| `@cosyte/script-utils/internal-refs` | `runInternalRefsScan(config)`, the shared internal-reference gate                            |
+| `@cosyte/script-utils/attw`          | `runAttwGate(options)`, the shared `attw` publish gate                                       |
+| `@cosyte/script-utils/readme`        | `runReadmeGate(options)` and `checkReadme(text, manifest)`, the README gate                  |
+| `@cosyte/script-utils/claude-card`   | `runClaudeCardGate(options)` and `checkClaudeCard(text)`, the CLAUDE.md card checker         |
+| `@cosyte/script-utils/catalog`       | `CATALOG`, `catalogEntry(name)` and `runCatalogCheck(options)`, the catalog of our libraries |
+| `@cosyte/script-utils/agent-notes`   | `runAgentNotesCheck(options)` and `checkAgentNotes(input)`, the agent-notes checker          |
 
 They are separate subpaths because they are separately adoptable: a repo can take the entry-point
 guard without taking a position on PHI scanning, a repo can take the internal-reference gate without
 taking either, and importing one never loads another.
 
+### The four gates from the command line
+
+Each shared gate runs from a repository's package script with no file of its own but one input
+(ST34). The dash gate already did; the other three now do too:
+
+| gate           | command                                                     | the one per-repository file       |
+| -------------- | ----------------------------------------------------------- | --------------------------------- |
+| em and en dash | `bash node_modules/@cosyte/script-utils/check-no-emdash.sh` | `scripts/check-no-emdash.exclude` |
+| attw           | `node node_modules/@cosyte/script-utils/attw.js`            | `scripts/attw.exclude`            |
+| PHI scan       | `node node_modules/@cosyte/script-utils/phi-scan.js`        | `scripts/phi-scan.exclude`        |
+| internal refs  | `node node_modules/@cosyte/script-utils/internal-refs.js`   | `scripts/internal-refs.json`      |
+
+- **attw** runs for the package in the working directory, as the one-line `scripts/attw.mjs`
+  caller does. `scripts/attw.exclude` names the resolutions the package leaves out, one per line:
+  `node10` alone selects attw's `node16` profile, and `node10` with `node16-cjs` selects `esm-only`.
+  It selects a profile and nothing else; any other entry, a repeat, `node16-cjs` alone, or a
+  `--profile` argument beside the file is refused at exit 1.
+- **PHI scan** runs the engine with the house settings: exit codes 0 clean, 1 hits, 2 refuse; the
+  whole repository as the scan root; `--staged` reading everything but Markdown; the allow-list at
+  `scripts/phi-allow-list.txt` and the override log at `phi-scan-overrides.md`. Each line of
+  `scripts/phi-scan.exclude` is one literal tracked path (`#` lines are comments); a directory, a
+  pattern, a repeat or a path git does not track is refused at exit 2. It carries the
+  cross-cutting floor only, so a repository whose standard needs field-level detectors keeps a
+  caller passing `detect` until the per-standard detectors ship here.
+- **Internal refs** reads its axes from `scripts/internal-refs.json` (keys starting with `$` are
+  notes), with exit codes 0 clean, 1 hits, 2 the gate could not run. The file may not set
+  `exitCodes`, `repoRoot` or `write`, which the command-line form owns.
+
+### The bins, for a repository with no package.json
+
+Every gate is also a bin (D56), so a repository with no `package.json`, or none that depends on this
+package, runs it through npx. `script-utils` is named after the package, so npx runs it by the
+package's name and it dispatches to the gate named first:
+
+```sh
+npx -y @cosyte/script-utils@0.1 no-emdash          # the dispatcher: script-utils <command>
+npx -y -p @cosyte/script-utils@0.1 cosyte-readme   # or one gate's own bin
+```
+
+| bin                    | `script-utils` command | the gate                                      |
+| ---------------------- | ---------------------- | --------------------------------------------- |
+| `cosyte-no-emdash`     | `no-emdash`            | the em and en dash gate, over files and names |
+| `cosyte-attw`          | `attw`                 | the attw publish gate, for the package here   |
+| `cosyte-phi-scan`      | `phi-scan`             | the PHI commit-gate                           |
+| `cosyte-internal-refs` | `internal-refs`        | the internal-reference gate                   |
+| `cosyte-readme`        | `readme`               | the README gate                               |
+| `cosyte-claude-card`   | `claude-card`          | the CLAUDE.md card checker                    |
+| `cosyte-agent-notes`   | `agent-notes`          | the agent-notes checker                       |
+| `cosyte-catalog`       | `catalog`              | the catalog check                             |
+
+Each runs over the working directory, takes the arguments its gate takes, exits with the gate's own
+code, and prints what it does with `--help`. `script-utils` with no command prints the list and exits 2.
+
 ### The em-dash gate, which is a file rather than a subpath
 
 This package also ships `check-no-emdash.sh`, the one implementation of the em-dash gate for every
@@ -172,7 +289,7 @@ bash node_modules/@cosyte/script-utils/check-no-emdash.sh --self-id
 
 Exit 0 means the mode completed and found nothing banned. Exit 1 means anything else: a banned form
 was found, an input could not be read, an input was not scanned, a declaration was unusable, or an
-argument was not recognised. There is no third code. Hits and diagnostics go to stderr in every mode.
+argument was not recognized. There is no third code. Hits and diagnostics go to stderr in every mode.
 
 `--self-id` prints the sha256 of the copy that is executing, so a repository can prove it is running
 these bytes rather than a fork of them. `--list-scanned` prints the NUL-separated, repo-root-relative
@@ -183,9 +300,101 @@ A repository narrows WHAT IS SCANNED, and only that, through a tracked file at i
 `scripts/check-no-emdash.exclude`: one entry per line, `#` comments and blank lines ignored, an entry
 ending in `/` covering every tracked path beneath it, and every entry anchored at the repository
 root. An entry that matches no tracked path is refused rather than ignored, because an exclusion that
-has outlived its subject is a hole nobody is looking at. Nothing narrows WHAT IS MATCHED: the twelve
-banned forms are fixed in the gate. They are the em dash (U+2014) and the en dash (U+2013), each as
-the literal character, its URL encoding, its JS escape and three HTML entity spellings.
+has outlived its subject is a hole nobody is looking at; an excluded path's name is left out with its
+content. Nothing narrows WHAT IS MATCHED: the banned forms are fixed in the gate. They are the em
+dash (U+2014) and the en dash (U+2013), in any case, each as the literal character, its URL encoding,
+its backslash-u escape (plain, braced and eight-digit), its braced backslash-x escape, its CSS escape
+(plain and zero-padded), its Unicode name escape (a backslash, `N` and the character's name in braces), and its named, decimal and hexadecimal
+HTML entities, with or without the semicolon and with leading zeros. The default scan also reads
+every tracked file's NAME, because a name is copy too.
+
+### The README gate
+
+`@cosyte/script-utils/readme` checks a library's README against the house skeleton, and against a
+size limit under npm's: the registry keeps only the first 65,536 characters of a README, and the
+gate refuses one over 60,000. A library runs it from its package script, with no file of its own:
+
+```sh
+# "readme:check": "node node_modules/@cosyte/script-utils/readme.js"
+node node_modules/@cosyte/script-utils/readme.js              # the package in this directory
+node node_modules/@cosyte/script-utils/readme.js --dir <path> # another package directory
+```
+
+The skeleton, in order: the shared lockup tile in a `<picture>` element with the alt text assets
+declares for it; `# <package name>`; a one-line `>` tagline of at most 120 characters; the badge row
+(npm version, CI, license and Node, one per line, derived from `package.json`); then the sections
+`Why this exists`, `Status`, `Install`, `Usage`, `Support`, `Security`, `Contributing` and
+`License`, in that order, none empty, with `License` last and linking the repository's `LICENSE` by
+its absolute URL. A link to the package's page on docs.cosyte.com sits after `## Usage` begins and
+before `## Support`. Other sections may sit between the required ones.
+
+Exit 0 means the README follows the skeleton, 1 that it does not (each finding names its line and
+its rule, from `README_RULES`), and 2 that the gate could not read the package: no README, no
+`package.json`, or a manifest without the `@cosyte/*` name, the github.com/cosyte repository URL or
+the `engines.node` the skeleton is derived from. Nothing is configurable, so no setting switches a
+rule off.
+
+### The CLAUDE.md card checker
+
+`@cosyte/script-utils/claude-card` checks the CLAUDE.md card every Cosyte repository keeps: what
+must pass before a push, what a change can break that a gate would not show, and the rules that bind
+there. The spec is `documentation/claude-card.md` in cosyte/config. A repository runs it with no file
+of its own:
+
+```sh
+node node_modules/@cosyte/script-utils/claude-card.js              # CLAUDE.md in this directory
+node node_modules/@cosyte/script-utils/claude-card.js --dir <path> # another repository
+```
+
+The card opens with `# <name>` and a paragraph, then has exactly three level-2 sections in order,
+`## Gate`, `## Hazard` and `## Rules` (a heading may go on after its word, as in
+`## Rules that bind here`), none empty. It is at most 60 lines, every line at most 100 characters
+with code included, and at most 5,120 bytes. When an AGENTS.md sits beside it, the card imports it on
+a line of its own, `@AGENTS.md`. Exit 0 means the card follows the spec, 1 that it does not (each
+finding names its line and rule, from `CARD_RULES`), and 2 that CLAUDE.md could not be read.
+
+### The catalog
+
+`@cosyte/script-utils/catalog` is the one list of our libraries (ST13): the 8 standards (HL7 v2,
+MLLP, FHIR, C-CDA, X12, NCPDP, ASTM and DICOM), the 6 built on them (terminology, transform, deid,
+synth, dates and cli), and Pathways, our integration engine, in development and not on npm. Each
+record is generated from the package's own `package.json` (name, description, release line,
+engines, repository, docs and npm URLs) and carries its tier; the data ships as `catalog.json`
+beside the module, and `CATALOG` is that file, frozen.
+
+Each package.json description is that library's one canonical line (ST14), so every library runs
+the check that its description is the catalog's, with no file of its own:
+
+```sh
+node node_modules/@cosyte/script-utils/catalog.js              # the package in this directory
+node node_modules/@cosyte/script-utils/catalog.js --dir <path> # another package directory
+```
+
+Exit 0 means the description is the catalog's, 1 that it is not (both values are printed), and 2
+that the check could not run (no package.json, or a package the catalog does not list). A changed
+description therefore goes through the catalog: regenerate it in cosyte/config
+(`node scripts/catalog.mjs write`), release this package, then move the library to that release.
+
+### The agent-notes checker
+
+`@cosyte/script-utils/agent-notes` checks a repository's agent notes (RD4): what does not fit on the
+CLAUDE.md card lives in one file, `documentation/agent-notes.md`, and the card points into it in one
+form, `documentation/agent-notes.md#<anchor>`. A repository runs it with no file of its own:
+
+```sh
+node node_modules/@cosyte/script-utils/agent-notes.js              # this repository
+node node_modules/@cosyte/script-utils/agent-notes.js --dir <path> # another repository
+```
+
+It reads every file `git ls-files` lists, skipping and counting a binary file or anything that is not
+a regular file. Every pointer in any of them must name a heading of the notes (its GitHub slug) or an
+explicit `<a id>` or `<a name>` target. In CLAUDE.md the pointer must take the one form, not a bare
+backticked `#anchor` or `agent-notes.md#` without its directory. A `documentation/agent-notes/`
+directory is a finding, and so is a notes file CLAUDE.md never points into, a blank one, an empty
+section (a heading followed by a deeper one is a container, not empty), and a citation of the
+umbrella's deleted ADR 0023 or its doc-budget hook. A repository with no notes and no pointers
+passes. Exit 0 means clean, 1 a finding (file, line and rule from `AGENT_NOTES_RULES`), and 2 that
+the check could not run.
 
 ## Overrides
 
@@ -207,7 +416,7 @@ four required, six defaulted, and every per-repository difference supplied by th
 will not accept is a configuration that SUBTRACTS. The canonical rule set, the self-test floor and
 every completeness refusal are not caller inputs, and an option that reaches for one of them is
 refused by name rather than ignored. So is an option the gate has never heard of: an ignored setting
-reads, from the caller's side, exactly like an honoured one.
+reads, from the caller's side, exactly like an honored one.
 
 `runAttwGate` takes the narrowest bargain of the four, and deliberately. A caller supplies where it
 lives (`callerUrl`, required, no default) and may supply the arguments to forward; everything else
@@ -491,4 +700,4 @@ something. Never open an issue containing a real PHI value; describe the shape i
 
 ## License
 
-MIT, copyright Cosyte. See [LICENSE](https://github.com/cosyte/config/blob/main/LICENSE).
+MIT, copyright Cosyte LLC. See [LICENSE](https://github.com/cosyte/config/blob/main/LICENSE).

package/agent-notes.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Types for `@cosyte/script-utils/agent-notes`: the checker for a repository's agent notes, one
+ * file at `documentation/agent-notes.md` that CLAUDE.md points into as
+ * `documentation/agent-notes.md#<anchor>` (RD4).
+ */
+
+/** The one place the notes live. */
+export declare const NOTES_PATH: "documentation/agent-notes.md";
+
+/** A rule id a finding can carry. */
+export type AgentNotesRule =
+  | "layout"
+  | "pointer-form"
+  | "dangling"
+  | "notes-missing"
+  | "no-pointer"
+  | "blank"
+  | "empty-section"
+  | "stale-citation";
+
+/** Every rule id, with what it requires. */
+export declare const AGENT_NOTES_RULES: Readonly<Record<AgentNotesRule, string>>;
+
+/** Raised when the check cannot run; the CLI turns it into exit 2. */
+export declare class AgentNotesRefusal extends Error {}
+
+/** GitHub's heading slug, as github-slugger writes it. */
+export declare function slugify(text: string): string;
+
+/** A slugger that suffixes repeats as GitHub does: the second `Setup` is `setup-1`. */
+export declare function makeSlugger(): (text: string) => string;
+
+/** One heading of the notes. */
+export interface NotesHeading {
+  level: number;
+  text: string;
+  /** 0-based line. */
+  line: number;
+  slug: string;
+  /** Nothing under it, and not a container followed by a deeper heading. */
+  empty: boolean;
+}
+
+/**
+ * The anchors a notes file offers (heading slugs and explicit `<a id>` or `<a name>` targets) and
+ * its headings.
+ *
+ * @throws {AgentNotesRefusal} On an HTML comment that never closes.
+ */
+export declare function readNotes(text: string): { targets: Set<string>; headings: NotesHeading[] };
+
+/** One place the notes or a pointer depart from RD4. */
+export interface AgentNotesFinding {
+  rule: AgentNotesRule;
+  file: string;
+  /** 1-based line, or 0 for the whole file. */
+  line: number;
+  message: string;
+}
+
+export interface AgentNotesInput {
+  /** CLAUDE.md's contents, or `null` when the repository has none. */
+  claude: string | null;
+  /** The notes' contents, or `null` when the repository has none. */
+  notes: string | null;
+  /** Every other tracked text file, scanned for pointers. */
+  files: { path: string; text: string }[];
+  /** Whether a `documentation/agent-notes/` directory is tracked. */
+  notesDirectory?: boolean;
+  /** Whether the repository has its own `documentation/decisions/0023-*`. */
+  localDecision0023?: boolean;
+}
+
+/**
+ * Check the notes and every pointer into them.
+ *
+ * @throws {AgentNotesRefusal} When the notes cannot be read to the end.
+ */
+export declare function checkAgentNotes(input: AgentNotesInput): AgentNotesFinding[];
+
+export interface AgentNotesCheckOptions {
+  /** The repository root. Default: the working directory. */
+  dir?: string;
+  /** CLI arguments; only `--dir <path>` is accepted. */
+  argv?: string[];
+}
+
+/**
+ * Run the checker over one repository's tracked files and return the exit code: 0 clean, 1 at
+ * least one finding, 2 the check could not run. It never exits the process.
+ */
+export declare function runAgentNotesCheck(options?: AgentNotesCheckOptions): 0 | 1 | 2;