@cosyte/script-utils 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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

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,16 +244,16 @@ 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.
@@ -398,26 +384,32 @@ release, because config's check against npm picks the change up once the library
 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
+### The agent-notes checker, deprecated
 
-`@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:
+`@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.
 
-```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
-```
+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.
+
+```ts runnable
+import { checkAgentNotes, NOTES_PATH } from "@cosyte/script-utils/agent-notes";
+
+// The file it checks, which no repository keeps any more.
+NOTES_PATH; // => "documentation/agent-notes.md"
 
-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.
+// A card with no notes and nothing pointing at them has no findings.
+checkAgentNotes({ claude: "# demo\n\nOur demo.\n", notes: null, files: [] }); // => []
+```
 
 ## Overrides
 

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,5 +1,7 @@
 #!/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, or 2 under CI.
@@ -7,13 +9,20 @@
 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);

package/bin/script-utils.js

@@ -19,7 +19,7 @@ const COMMANDS = {
   ],
   readme: ["cosyte-readme", "the README gate, for the library here"],
   "claude-card": ["cosyte-claude-card", "the CLAUDE.md card checker"],
-  "agent-notes": ["cosyte-agent-notes", "the agent-notes checker"],
+  "agent-notes": ["cosyte-agent-notes", "the agent-notes checker, deprecated by D62"],
   catalog: ["cosyte-catalog", "the catalog check, for the library here"],
 };
 

package/claude-card.js

@@ -49,6 +49,14 @@ export const CARD_SECTIONS = Object.freeze(["Gate", "Hazard", "Rules"]);
 /** The line that imports AGENTS.md into the card. */
 export const AGENTS_IMPORT = "@AGENTS.md";
 
+/**
+ * Where what does not fit on the card goes, from the spec's "Where the detail goes". The card stands
+ * on its own: there is no notes file beside it to send detail to (D62).
+ */
+const DETAIL_GOES =
+  "where it is used: a test, a comment at the code it guards, an ADR, the README or docs, or a " +
+  "runbook";
+
 /** Every rule id a finding can carry, with what it requires. */
 export const CARD_RULES = Object.freeze({
   title: "The card opens with `# <name>`, after a YAML front matter block if it has one.",
@@ -140,7 +148,8 @@ export function checkClaudeCard(text, context = {}) {
       "bytes",
       0,
       `the card is ${bytes.toLocaleString("en-US")} bytes; the limit is ` +
-        `${CARD_MAX_BYTES.toLocaleString("en-US")}. Move detail to documentation/agent-notes.md.`,
+        `${CARD_MAX_BYTES.toLocaleString("en-US")}. Move detail to ${DETAIL_GOES}; git and the ` +
+        `PRs keep the history.`,
     );
   }
   lines.forEach((line, index) => {
@@ -185,7 +194,7 @@ export function checkClaudeCard(text, context = {}) {
         "section-extra",
         heading.line + 1,
         `"## ${heading.text}" is not one of the card's sections (${CARD_SECTIONS.join(", ")}); ` +
-          `make it a ### inside one of them, or move it to the agent notes.`,
+          `make it a ### inside one of them, or move it to ${DETAIL_GOES}.`,
       );
     } else if (!found.has(word)) {
       found.set(word, heading);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosyte/script-utils",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Zero-dependency helpers for the repo-local gate scripts in @cosyte/* repos.",
   "keywords": [
     "cli",