@cosyte/script-utils 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.1.7
+
+### Patch Changes
+
+- 9d0d69f: Deprecated: the agent-notes checker, `@cosyte/script-utils/agent-notes` and its bin `cosyte-agent-notes`. The agent notes, `documentation/agent-notes.md`, were removed from every Cosyte repository (D62), so remove the package script or CI step that runs it. Until a minor release removes the entry point and the bin, a repository with no notes file (not tracked, or deleted from the working tree) passes: the checker exits 0 with one line, `agent notes: OK, no agent notes (retired, D62)`, where it used to fail on a pointer left in the card, a source comment or a changelog. A repository that still has the file is checked as before, and a failing run ends with a line saying the notes are retired. `--help`, the `script-utils` command list, the declarations and the README say it is deprecated.
+- 9d0d69f: The CLAUDE.md card checker no longer sends detail to `documentation/agent-notes.md`, which was removed from every repository (D62). A card over 5,120 bytes, or with a level-2 heading other than Gate, Hazard and Rules, is told to move the detail to where it is used: a test, a comment at the code it guards, an ADR, the README or docs, or a runbook. What the checker checks, and its exit codes, are unchanged.
+
+## 0.1.6
+
+### Patch Changes
+
+- 239ac9a: The catalog check a library runs is now advisory. `cosyte-catalog` (and `catalog.js`) still compares the package.json description with the catalog this release carries, but a disagreement, or a package the catalog does not list, prints both values as a note and exits 0: a library that changes its description is no longer held red until the next script-utils release. `--strict` (or `{ strict: true }`) restores the gate, 1 for a disagreement and 2 for an unlisted package; 2 still means the check could not run. Keeping the catalog fresh moves to cosyte/config, which compares it with every library's latest release on npm (its description, release line and engines range) nightly and before each config release, and regenerates it from there.
+- 4e30735: The dash gate reads a changelog's dated archive the way the repositories that keep one already do. A line in `scripts/check-no-emdash.exclude` of the form `CHANGELOG.md em-only below ## Released before this file was generated` reads the file from that exact line to its end for the em dash alone, in every form, so an en dash in an old range passes while an em dash still reds; `CHANGELOG.md unread below <line>` does not read the archive at all. Everything above the line is read for both dashes as before, the file's name is still scanned, and a boundary line the file no longer carries is refused rather than ignored. The test suite now spells out every encoded form terminology's own scanner carried (the braced escape, lower-case URL encoding, entities with no semicolon or with leading zeros, and the upper-case X), all of which 0.1.4 already refused. The internal-refs slice rule no longer counts `the` or `each` as a determiner: a fixed-width reader's field slice (`the field slices`, `the slice holding the concept code`) is the reader's vocabulary. `this`, `that`, `another`, `previous`, `next`, `final` and `current` still red, so `the final slice` and `the next slice` are still hits, but a bare `the slice` and `each slice` no longer are.
+- 409ef6c: Under CI, every gate's `--help` and `-h` now exit non-zero instead of 0: the bins exit 2 and the dash gate exits 1, after printing the help to stderr with a line saying why. Help checks nothing, so a package script such as `"attw": "cosyte-attw --help"` used to pass a required check having run no gate. CI is read the way the common runners set it: `CI` set to anything but an empty string, `false` or `0`. At a terminal `--help` prints to stdout and exits 0 as before.
+- 91f8d76: The internal-refs canonical rules take what generalizes from dicom's own gate. An umbrella spec id (`S0228-github-profile-ci-drift`, never a HCPCS code such as `S9083`) is an identifier. The phase rule also catches the adjective forms (`in subsequent phases`, `a later wave`, `waves 2 and 3`) while letting the clinical senses through (`a later phase of the disease`), and a citation of the roadmap (`tracked by the roadmap`). The ADR rule reads the plural, `#` and two-digit forms (`ADRs 0015`, `ADR #0018`, `ADR 23`). The jargon rule catches process commentary (`a later PR`, `this changeset`, `out of scope for this change`) but not `this spec`, `this session` or `this port`, which are reader words in a parser, and lets an image slice in its volume through. The repo-path rule catches the planning files a session writes (`CONTEXT.md`, `REQUIREMENTS.md`, `PITFALLS.md`), the meta-repo or umbrella repo named as a place, and its `work/` and `cards/` directories, and a `decisions/NNNN-` path wherever it sits. Measured on the pinned libraries, this adds 12 hits, all of them real (in hl7, x12 and ncpdp), and removes none. dicom's decision-number, issue-number, `WORD-N` and bare section rules stay dicom's: each collides with reference material another library publishes.
+- d75579c: The internal-refs gate gains a source string-literal pass, `sourceStringLiterals: { enabled, paths, extraRules }`, off by default like the doc-comment pass. It reads the double-quoted, single-quoted and template literals in the tracked source under `paths`, decoded, plus the literals on each line joined, because a string literal reaches a consumer as error and warning text. It never reads a comment, so an item identifier in a `//` note or a `/* */` block stays allowed, and it skips regular-expression literals. In both source passes a NUL byte now reads as a space instead of refusing the file: a raw separator inside a literal is legitimate source, and a space keeps the word boundary beside it. The public-surface pass still refuses a NUL-bearing target.
+- d30eca0: The PHI engine reads a JavaScript or TypeScript source as the document its string literals spell, as well as its bytes. A literal can spell a dashed identifier's separators as `-`, `\u{2D}` or `\x2D`, and the raw floor read straight past it. Each `.ts`, `.js`, `.mts`, `.cts`, `.mjs`, `.cjs`, `.tsx` and `.jsx` target is now also decoded (an escaped backslash first, so a doubled backslash stays text), and the floor and the caller's `detect` run over that view too, so a field-level detector can parse a record whose separators are escapes. The decoded view adds only what the raw view did not report, and says `escape-encoded in a source literal` on the hit. It is a view, not a parser, so it also decodes a `String.raw` template or a comment quoting an escape; an `ID <value>` declaration in the allow-list clears such a hit. `decodeSourceLiterals` and `isSourceLiteralContainer` are exported.
+
 ## 0.1.5
 
 ### Patch Changes

package/README.md

@@ -188,20 +188,6 @@ 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                                                                                   |
@@ -213,7 +199,7 @@ checkAgentNotes({ claude, notes: notes.replace("Setup", "Install"), files: [] })
 | `@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          |
+| `@cosyte/script-utils/agent-notes`   | deprecated (D62): `runAgentNotesCheck(options)` and `checkAgentNotes(input)`                 |
 
 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
@@ -258,19 +244,22 @@ npx -y @cosyte/script-utils@0.1 no-emdash          # the dispatcher: script-util
 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                             |
+| 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`          | deprecated (D62): the retired 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.
+Under CI (`CI` set to anything but empty, `false` or `0`, as GitHub Actions sets it) `--help` and
+`-h` print to stderr and exit non-zero (2, or 1 for the dash gate, whose only codes are 0 and 1): help
+checks nothing, so a package script that ends in `--help` must not pass a required check.
 
 ### The em-dash gate, which is a file rather than a subpath
 
@@ -308,6 +297,16 @@ its backslash-u escape (plain, braced and eight-digit), its braced backslash-x e
 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.
 
+A changelog whose dated archive predates the generated part names that archive with a boundary line
+in the same file, `CHANGELOG.md em-only below ## Released before this file was generated` or
+`CHANGELOG.md unread below ## Released before this file was generated`. The text after `below` is a
+whole line of that file, matched exactly; from it to the end of the file is the archive. `em-only`
+reads the archive for the em dash alone, in every form, so an en dash in an old range passes and an em
+dash still fails; `unread` does not read the archive. Above the line the file is read for both dashes
+like any other, and its name is scanned as always. A boundary line the file no longer carries is
+refused, so a lost heading fails closed, and a file cannot be both left out whole and given a
+boundary.
+
 ### The README gate
 
 `@cosyte/script-utils/readme` checks a library's README against the house skeleton, and against a
@@ -362,40 +361,56 @@ record is generated from the package's own `package.json` (name, description, re
 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:
+Each package.json description is that library's one canonical line (ST14). Two sides check it, and
+each checks one thing:
+
+- **cosyte/config keeps the catalog fresh.** `node scripts/catalog.mjs check --npm` compares the
+  committed catalog with every library's latest release on npm. It runs nightly and before each
+  config release, and fails when a library has released a description, release line or engines
+  range the catalog does not carry; `write --npm` regenerates it. npm keeps 255 characters of a
+  description, so a longer one is fresh when npm holds its first 255, and the run notes it.
+- **A library can check its own line, advisory.** 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
+node node_modules/@cosyte/script-utils/catalog.js --strict     # a disagreement fails
 ```
 
-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.
+It compares the package.json description with the catalog this release of `@cosyte/script-utils`
+carries. A disagreement, or a package the catalog does not list, prints both values as a note and
+exits 0: a library that changes its description is not held red until the next script-utils
+release, because config's check against npm picks the change up once the library is released. Exit
+2 means the check could not run (no package.json, or an argument it does not accept). `--strict`
+restores the gate: 1 for a disagreement, 2 for an unlisted package.
+
+### The agent-notes checker, deprecated
+
+`@cosyte/script-utils/agent-notes` and its bin, `cosyte-agent-notes`, are deprecated. They check a
+repository's agent notes, `documentation/agent-notes.md`, and every
+`documentation/agent-notes.md#<anchor>` pointer into them. On 2026-11-08 the notes were removed from
+every Cosyte repository (D62): a CLAUDE.md card stands on its own, and what does not fit on it goes
+where it is used, in a test, a comment at the code it guards, an ADR, the README or docs, or a
+runbook (`documentation/claude-card.md` in cosyte/config). Remove the package script or CI step that
+runs the checker.
+
+Until a minor release removes them, the entry point and the bin keep a repository that still runs
+the checker green while its notes are removed. With no `documentation/agent-notes.md` (not tracked,
+or deleted from the working tree) the checker exits 0 with one line,
+`agent notes: OK, no agent notes (retired, D62)`, whatever still points at the file. A repository
+that still has the file is checked as before: exit 0 clean, 1 a finding (file, line and rule from
+`AGENT_NOTES_RULES`, then a line saying the notes are retired), and 2 that the check could not run.
 
-### The agent-notes checker
+```ts runnable
+import { checkAgentNotes, NOTES_PATH } from "@cosyte/script-utils/agent-notes";
 
-`@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:
+// The file it checks, which no repository keeps any more.
+NOTES_PATH; // => "documentation/agent-notes.md"
 
-```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
+// A card with no notes and nothing pointing at them has no findings.
+checkAgentNotes({ claude: "# demo\n\nOur demo.\n", notes: null, files: [] }); // => []
 ```
 
-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
 
 `isCliEntrypoint` has no options and cannot be overridden. It answers one question and its
@@ -528,6 +543,13 @@ every `scanRoots` entry yielded a file the WALK read, naming the starved roots);
 cross-cutting detection floor that finds a dashed SSN shape and an email at an undeclared domain over
 every file, always.
 
+**A JavaScript or TypeScript source is read twice**: as its bytes, and as the document its string
+literals spell, with `\uXXXX`, `\u{...}`, `\xHH` and the single-character escapes decoded (an
+escaped backslash first, so a doubled backslash before `u002D` stays text). The floor and your
+`detect` run over both views, and the decoded view adds only what the raw view did not report, with
+`, escape-encoded in a source literal` on its reason. It is a view, not a parser, so it also decodes a
+`String.raw` template or a comment quoting an escape; an `ID <value>` declaration clears such a hit.
+
 **The RULES, local to your repo, never moved and never shipped in this package.**
 `scripts/phi-allow-list.txt` (the positive declaration that a token is synthetic, tagged `NAME`,
 `DOB`, `ADDR`, `ID`, `EMAILDOMAIN`); `phi-scan-overrides.md` (the `--allow-fixture` audit log, and
@@ -593,7 +615,7 @@ still refuses such an entry on both of its routes.
 `@cosyte/script-utils/internal-refs` keeps our own bookkeeping off every surface a consumer reads:
 item identifiers, phase and wave language, ADR numbers, internal repository paths and traceability
 markers, on the pages, the npm metadata and, optionally, the doc comments that compile into shipped
-type declarations.
+type declarations and the string literals a consumer reads as error and warning text.
 
 ```ts
 import { runInternalRefsScan } from "@cosyte/script-utils/internal-refs";
@@ -605,6 +627,7 @@ process.exit(
     surfacePaths: ["README.md", "TRADEMARKS.md", "LICENSE", "docs-content"],
     accountedTarballFiles: ["CHANGELOG.md", "dist"],
     sourceDocComments: { enabled: true, paths: ["src/*.ts", "src/**/*.ts"] },
+    sourceStringLiterals: { enabled: true, paths: ["src/*.ts", "src/**/*.ts"] },
   }),
 );
 ```
@@ -632,14 +655,23 @@ gets wrong, and a default would be one repository's answer imposed on every othe
 | 3 Public surface           | `surfacePaths`          | **Required**, empty refused, every entry must be tracked.             |
 | 4 Tarball accounting       | `accountedTarballFiles` | **Required.** The `files` entries already accounted for.              |
 | 5 Source doc comments      | `sourceDocComments`     | Defaulted OFF. Enable where the build copies doc text verbatim.       |
-| 6 Exit codes               | `exitCodes`             | Defaulted `{ clean: 0, hits: 1, refuse: 1 }`. `clean` must stay 0.    |
-| 7 Added detection          | `extraRules`            | Defaulted `[]`. Each added rule brings its own samples.               |
-| 8 Added self-test material | `extraSamples`          | Defaulted `{}`. Additive only.                                        |
-| 9 Repository under test    | `repoRoot`              | Defaulted to the working directory, anchored at its git top level.    |
-| 10 Report destination      | `write`                 | Defaulted to the process streams.                                     |
+| 6 Source string literals   | `sourceStringLiterals`  | Defaulted OFF. Enable where messages reach a consumer. No comments.   |
+| 7 Exit codes               | `exitCodes`             | Defaulted `{ clean: 0, hits: 1, refuse: 1 }`. `clean` must stay 0.    |
+| 8 Added detection          | `extraRules`            | Defaulted `[]`. Each added rule brings its own samples.               |
+| 9 Added self-test material | `extraSamples`          | Defaulted `{}`. Additive only.                                        |
+| 10 Repository under test   | `repoRoot`              | Defaulted to the working directory, anchored at its git top level.    |
+| 11 Report destination      | `write`                 | Defaulted to the process streams.                                     |
 
 `CONFIG_AXES` is the same table as data, so a consumer can enumerate it rather than transcribe it.
 
+The string-literal pass reads double-quoted, single-quoted and template literals (a multi-line
+template whole, a `${...}` as a space), decodes their escapes, and also reads the literals on one
+source line joined, so a phrase split across `"a " + "b"` is seen. It never reads a comment: a `//`
+line, a trailing `//` and a `/* */` block are skipped, so an item identifier in a maintainer's note
+stays allowed. A regular-expression literal is skipped too. In both source passes a NUL byte reads as
+a space instead of refusing the file, since a raw separator inside a literal is legitimate source;
+the clean line counts them.
+
 #### Two things worth knowing before you adopt this one
 
 **The prefix set has to be extended by hand, and that is the cheaper mistake.** A new programme

package/agent-notes.d.ts

@@ -2,12 +2,24 @@
  * 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).
+ *
+ * Deprecated (D62): the agent notes were removed from every Cosyte repository. A repository with no
+ * notes file passes `runAgentNotesCheck` with one line, and one that still has the file is checked
+ * as before. This entry point stays until a minor release removes it.
  */
 
-/** The one place the notes live. */
+/**
+ * The one place the notes live.
+ *
+ * @deprecated Retired with the agent notes (D62).
+ */
 export declare const NOTES_PATH: "documentation/agent-notes.md";
 
-/** A rule id a finding can carry. */
+/**
+ * A rule id a finding can carry.
+ *
+ * @deprecated Retired with the agent notes (D62).
+ */
 export type AgentNotesRule =
   | "layout"
   | "pointer-form"
@@ -18,19 +30,39 @@ export type AgentNotesRule =
   | "empty-section"
   | "stale-citation";
 
-/** Every rule id, with what it requires. */
+/**
+ * Every rule id, with what it requires.
+ *
+ * @deprecated Retired with the agent notes (D62).
+ */
 export declare const AGENT_NOTES_RULES: Readonly<Record<AgentNotesRule, string>>;
 
-/** Raised when the check cannot run; the CLI turns it into exit 2. */
+/**
+ * Raised when the check cannot run; the CLI turns it into exit 2.
+ *
+ * @deprecated Retired with the agent notes (D62).
+ */
 export declare class AgentNotesRefusal extends Error {}
 
-/** GitHub's heading slug, as github-slugger writes it. */
+/**
+ * GitHub's heading slug, as github-slugger writes it.
+ *
+ * @deprecated Retired with the agent notes (D62).
+ */
 export declare function slugify(text: string): string;
 
-/** A slugger that suffixes repeats as GitHub does: the second `Setup` is `setup-1`. */
+/**
+ * A slugger that suffixes repeats as GitHub does: the second `Setup` is `setup-1`.
+ *
+ * @deprecated Retired with the agent notes (D62).
+ */
 export declare function makeSlugger(): (text: string) => string;
 
-/** One heading of the notes. */
+/**
+ * One heading of the notes.
+ *
+ * @deprecated Retired with the agent notes (D62).
+ */
 export interface NotesHeading {
   level: number;
   text: string;
@@ -46,10 +78,15 @@ export interface NotesHeading {
  * its headings.
  *
  * @throws {AgentNotesRefusal} On an HTML comment that never closes.
+ * @deprecated Retired with the agent notes (D62).
  */
 export declare function readNotes(text: string): { targets: Set<string>; headings: NotesHeading[] };
 
-/** One place the notes or a pointer depart from RD4. */
+/**
+ * One place the notes or a pointer depart from RD4.
+ *
+ * @deprecated Retired with the agent notes (D62).
+ */
 export interface AgentNotesFinding {
   rule: AgentNotesRule;
   file: string;
@@ -58,6 +95,11 @@ export interface AgentNotesFinding {
   message: string;
 }
 
+/**
+ * What `checkAgentNotes` reads.
+ *
+ * @deprecated Retired with the agent notes (D62).
+ */
 export interface AgentNotesInput {
   /** CLAUDE.md's contents, or `null` when the repository has none. */
   claude: string | null;
@@ -75,9 +117,15 @@ export interface AgentNotesInput {
  * Check the notes and every pointer into them.
  *
  * @throws {AgentNotesRefusal} When the notes cannot be read to the end.
+ * @deprecated Retired with the agent notes (D62).
  */
 export declare function checkAgentNotes(input: AgentNotesInput): AgentNotesFinding[];
 
+/**
+ * What `runAgentNotesCheck` takes.
+ *
+ * @deprecated Retired with the agent notes (D62).
+ */
 export interface AgentNotesCheckOptions {
   /** The repository root. Default: the working directory. */
   dir?: string;
@@ -87,6 +135,9 @@ export interface AgentNotesCheckOptions {
 
 /**
  * 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.
+ * least one finding, 2 the check could not run. A repository with no notes file is clean: it gets
+ * one line, `agent notes: OK, no agent notes (retired, D62)`. It never exits the process.
+ *
+ * @deprecated Retired with the agent notes (D62).
  */
 export declare function runAgentNotesCheck(options?: AgentNotesCheckOptions): 0 | 1 | 2;

package/agent-notes.js

@@ -1,10 +1,22 @@
 // @cosyte/script-utils/agent-notes
 //
-// THE AGENT-NOTES CHECKER (RD4). A repository's CLAUDE.md card stays short, and what does not fit in
-// it lives in ONE file, `documentation/agent-notes.md`, which the card points into with ONE form:
-// `documentation/agent-notes.md#<anchor>`. This checker replaces the eight per-repository checkers
-// (mllp, ccda, ncpdp, astm, terminology, transform, deid and cli), keeping every rule they shared and
-// resolving the ones they disagreed on; the README section "The agent-notes checker" lists both.
+// DEPRECATED (D62, 2026-11-08). The agent notes were removed from every Cosyte repository, and the
+// card spec (documentation/claude-card.md in cosyte/config) has no pointer form any more: a card
+// stands on its own. This checker stays only so that a repository still running it keeps passing
+// while its notes are removed:
+//
+//   - with no notes file (not tracked, or deleted from the working tree) it exits 0 with one line,
+//     `agent notes: OK, no agent notes (retired, D62)`, whatever still points at the file;
+//   - with one, it checks the notes and every pointer into them as it always has (below).
+//
+// Removing it (this file, its declarations, the `./agent-notes` export and the `cosyte-agent-notes`
+// bin) is a breaking change, so it waits for a minor release, which the operator approves (D56).
+//
+// THE AGENT-NOTES CHECKER (RD4, as it stood before D62). A repository's CLAUDE.md card stays short,
+// and what does not fit in it lives in ONE file, `documentation/agent-notes.md`, which the card
+// points into with ONE form: `documentation/agent-notes.md#<anchor>`. This checker replaced the eight
+// per-repository checkers (mllp, ccda, ncpdp, astm, terminology, transform, deid and cli), keeping
+// every rule they shared and resolving the ones they disagreed on.
 //
 // THE RULES, each one id a finding names:
 //
@@ -40,6 +52,9 @@ import { isCliEntrypoint } from "./index.js";
 /** The one place the notes live. */
 export const NOTES_PATH = "documentation/agent-notes.md";
 
+/** What a repository with no notes file is told, and passes on (D62). */
+const RETIRED = "no agent notes (retired, D62)";
+
 /** The directory layout the one-file rule retires. */
 const NOTES_DIRECTORY = "documentation/agent-notes/";
 
@@ -406,8 +421,8 @@ export function checkAgentNotes(input) {
   return findings;
 }
 
-/** The tracked files of a repository: regular files read, everything else counted. */
-function trackedFiles(dir) {
+/** The tracked paths of a repository, each with whether git records it as a regular file. */
+function listTracked(dir) {
   let listing;
   try {
     listing = execFileSync("git", ["ls-files", "-z", "-s"], {
@@ -419,14 +434,24 @@ function trackedFiles(dir) {
   } catch (err) {
     throw new AgentNotesRefusal(`could not list the tracked files of ${dir}: ${err.message}`);
   }
-  const files = [];
-  const skipped = [];
+  const entries = [];
   for (const record of listing.split("\0")) {
     if (record === "") continue;
-    const tab = record.indexOf("\t");
     const mode = record.slice(0, 6);
-    const path = record.slice(tab + 1);
-    if (mode !== "100644" && mode !== "100755") {
+    entries.push({
+      path: record.slice(record.indexOf("\t") + 1),
+      regular: mode === "100644" || mode === "100755",
+    });
+  }
+  return entries;
+}
+
+/** The tracked files of a repository: regular files read, everything else counted. */
+function readTracked(dir, entries) {
+  const files = [];
+  const skipped = [];
+  for (const { path, regular } of entries) {
+    if (!regular) {
       skipped.push(path);
       continue;
     }
@@ -469,10 +494,20 @@ export function runAgentNotesCheck(options = {}) {
   }
   dir = resolve(dir);
   try {
-    const { files, skipped } = trackedFiles(dir);
+    const entries = listTracked(dir);
+    // Retired (D62): with no notes file there is nothing to check, so nothing else is read, and a
+    // pointer left in the card, a source comment or a changelog is not a finding.
+    const hasNotes =
+      entries.some((entry) => entry.path === NOTES_PATH && entry.regular) &&
+      existsSync(join(dir, NOTES_PATH));
+    const { files, skipped } = hasNotes ? readTracked(dir, entries) : { files: [], skipped: [] };
     const byPath = new Map(files.map((file) => [file.path, file.text]));
     const claude = byPath.get("CLAUDE.md") ?? null;
     const notes = byPath.get(NOTES_PATH) ?? null;
+    if (notes === null) {
+      process.stdout.write(`agent notes: OK, ${RETIRED}\n`);
+      return 0;
+    }
     const others = files.filter((f) => f.path !== "CLAUDE.md" && f.path !== NOTES_PATH);
     const decisions = join(dir, "documentation", "decisions");
     const findings = checkAgentNotes({
@@ -495,7 +530,9 @@ export function runAgentNotesCheck(options = {}) {
         findings
           .map((f) => `  ${f.file}${f.line > 0 ? `:${f.line}` : ""} [${f.rule}] ${f.message}`)
           .join("\n") +
-        "\n",
+        `\nagent notes: the notes are retired (D62). Rather than fix these, delete ${NOTES_PATH}, ` +
+        `which passes this check, and move what still binds to where it is used ` +
+        `(documentation/claude-card.md in cosyte/config).\n`,
     );
     return 1;
   } catch (err) {

package/bin/cosyte-agent-notes.js

@@ -1,23 +1,33 @@
 #!/usr/bin/env node
 // cosyte-agent-notes: the agent-notes checker for the repository in the working directory.
+// Deprecated (D62): the agent notes were removed from every repository, so it passes a repository
+// with no notes file, and stays only until a minor release removes it.
 // A bin of @cosyte/script-utils (D56), so a repository with no package.json can run it with
 // `npx -y -p @cosyte/script-utils cosyte-agent-notes`. It forwards every argument to the gate and exits with
-// the gate's own code; `--help` prints what it does and exits 0.
+// the gate's own code; `--help` prints what it does and exits 0, or 2 under CI.
 
 import { runAgentNotesCheck } from "../agent-notes.js";
+import { answerHelp } from "./help.js";
 
-const HELP = `cosyte-agent-notes: check a repository's agent notes and every pointer into them.
+const HELP = `cosyte-agent-notes: deprecated (D62). Remove the step that runs it.
 
   cosyte-agent-notes [--dir <repository root>]
 
-The notes are one file, documentation/agent-notes.md, and CLAUDE.md points into it as
-documentation/agent-notes.md#<anchor>. Every pointer in a tracked file must name a heading or an
-explicit anchor. Exit 0 clean, 1 a finding, 2 the check could not run.
+The agent notes, documentation/agent-notes.md, were removed from every Cosyte repository on
+2026-11-08 (D62). A CLAUDE.md card stands on its own, and what does not fit on it goes where it is
+used: a test, a comment at the code it guards, an ADR, the README or docs, or a runbook
+(documentation/claude-card.md in cosyte/config).
+
+Until a minor release removes this bin, a repository with no documentation/agent-notes.md passes
+with one line, "no agent notes (retired, D62)", whatever still points at the file. One that still
+has the file is checked as before: every documentation/agent-notes.md#<anchor> pointer in a tracked
+file must name a heading or an explicit anchor. Exit 0 clean, 1 a finding, 2 the check could not
+run.
 `;
 
 const args = process.argv.slice(2);
 if (args.includes("--help") || args.includes("-h")) {
-  process.stdout.write(HELP);
+  process.exitCode = answerHelp("cosyte-agent-notes", HELP);
 } else {
   process.exitCode = runAgentNotesCheck({ argv: args });
 }

package/bin/cosyte-attw.js

@@ -2,9 +2,10 @@
 // cosyte-attw: the attw publish gate for the package in the working directory.
 // A bin of @cosyte/script-utils (D56), so a repository with no package.json can run it with
 // `npx -y -p @cosyte/script-utils cosyte-attw`. It forwards every argument to the gate and exits with
-// the gate's own code; `--help` prints what it does and exits 0.
+// the gate's own code; `--help` prints what it does and exits 0, or 2 under CI.
 
 import { runAttwCli } from "../attw.js";
+import { answerHelp } from "./help.js";
 
 const HELP = `cosyte-attw: run the attw publish gate for the package in the working directory.
 
@@ -18,7 +19,7 @@ passed; attw's own status when attw judged the package; 1 a refusal.
 
 const args = process.argv.slice(2);
 if (args.includes("--help") || args.includes("-h")) {
-  process.stdout.write(HELP);
+  process.exitCode = answerHelp("cosyte-attw", HELP);
 } else {
   process.exitCode = runAttwCli(args);
 }

package/bin/cosyte-catalog.js

@@ -2,22 +2,24 @@
 // cosyte-catalog: the catalog check for the library in the working directory.
 // A bin of @cosyte/script-utils (D56), so a repository with no package.json can run it with
 // `npx -y -p @cosyte/script-utils cosyte-catalog`. It forwards every argument to the gate and exits with
-// the gate's own code; `--help` prints what it does and exits 0.
+// the gate's own code; `--help` prints what it does and exits 0, or 2 under CI.
 
 import { runCatalogCheck } from "../catalog.js";
+import { answerHelp } from "./help.js";
 
 const HELP = `cosyte-catalog: check that a library's package.json description is the catalog's.
 
-  cosyte-catalog [--dir <package directory>]
+  cosyte-catalog [--dir <package directory>] [--strict]
 
-The catalog is the one list of our libraries, generated in cosyte/config from each package.json.
-Exit 0 the description is the catalog's, 1 it is not (both values printed), 2 the package is not
-listed or package.json cannot be read.
+The catalog is the one list of our libraries, generated in cosyte/config, which keeps it fresh
+against npm. This check is advisory: exit 0 when the description is the catalog's, and 0 with both
+values printed when it is not or the package is unlisted; 2 when package.json cannot be read. With
+--strict a disagreement exits 1 and an unlisted package 2.
 `;
 
 const args = process.argv.slice(2);
 if (args.includes("--help") || args.includes("-h")) {
-  process.stdout.write(HELP);
+  process.exitCode = answerHelp("cosyte-catalog", HELP);
 } else {
   process.exitCode = runCatalogCheck({ argv: args });
 }

package/bin/cosyte-claude-card.js

@@ -2,9 +2,10 @@
 // cosyte-claude-card: the CLAUDE.md card checker for the repository in the working directory.
 // A bin of @cosyte/script-utils (D56), so a repository with no package.json can run it with
 // `npx -y -p @cosyte/script-utils cosyte-claude-card`. It forwards every argument to the gate and exits with
-// the gate's own code; `--help` prints what it does and exits 0.
+// the gate's own code; `--help` prints what it does and exits 0, or 2 under CI.
 
 import { runClaudeCardGate } from "../claude-card.js";
+import { answerHelp } from "./help.js";
 
 const HELP = `cosyte-claude-card: check a repository's CLAUDE.md against the card spec.
 
@@ -17,7 +18,7 @@ Gate, Hazard and Rules in order, at most 60 lines of at most 100 characters and
 
 const args = process.argv.slice(2);
 if (args.includes("--help") || args.includes("-h")) {
-  process.stdout.write(HELP);
+  process.exitCode = answerHelp("cosyte-claude-card", HELP);
 } else {
   process.exitCode = runClaudeCardGate({ argv: args });
 }

package/bin/cosyte-internal-refs.js

@@ -2,9 +2,10 @@
 // cosyte-internal-refs: the internal-reference gate over the repository in the working directory.
 // A bin of @cosyte/script-utils (D56), so a repository with no package.json can run it with
 // `npx -y -p @cosyte/script-utils cosyte-internal-refs`. It forwards every argument to the gate and exits with
-// the gate's own code; `--help` prints what it does and exits 0.
+// the gate's own code; `--help` prints what it does and exits 0, or 2 under CI.
 
 import { runInternalRefsCli } from "../internal-refs.js";
+import { answerHelp } from "./help.js";
 
 const HELP = `cosyte-internal-refs: run the internal-reference gate over the repository in the working directory.
 
@@ -17,7 +18,7 @@ clean, 1 hits, 2 the gate could not run.
 
 const args = process.argv.slice(2);
 if (args.includes("--help") || args.includes("-h")) {
-  process.stdout.write(HELP);
+  process.exitCode = answerHelp("cosyte-internal-refs", HELP);
 } else {
   process.exitCode = runInternalRefsCli(args);
 }