@cosyte/script-utils 0.1.5 → 0.1.7

package/bin/cosyte-phi-scan.js

@@ -2,9 +2,10 @@
 // cosyte-phi-scan: the PHI commit-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-phi-scan`. 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 { runPhiScanCli } from "../phi-scan.js";
+import { answerHelp } from "./help.js";
 
 const HELP = `cosyte-phi-scan: run the PHI commit-gate over the repository in the working directory.
 
@@ -20,7 +21,7 @@ values, and scripts/phi-scan.exclude names literal tracked paths to leave out. E
 
 const args = process.argv.slice(2);
 if (args.includes("--help") || args.includes("-h")) {
-  process.stdout.write(HELP);
+  process.exitCode = answerHelp("cosyte-phi-scan", HELP);
 } else {
   process.exitCode = runPhiScanCli(args);
 }

package/bin/cosyte-readme.js

@@ -2,9 +2,10 @@
 // cosyte-readme: the README gate 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-readme`. 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 { runReadmeGate } from "../readme.js";
+import { answerHelp } from "./help.js";
 
 const HELP = `cosyte-readme: check a library README against the house skeleton and npm's size limit.
 
@@ -16,7 +17,7 @@ names its line and rule), 2 the package could not be read.
 
 const args = process.argv.slice(2);
 if (args.includes("--help") || args.includes("-h")) {
-  process.stdout.write(HELP);
+  process.exitCode = answerHelp("cosyte-readme", HELP);
 } else {
   process.exitCode = runReadmeGate({ argv: args });
 }

package/bin/help.js

@@ -0,0 +1,41 @@
+// Not a bin: the one answer every gate bin gives to `--help` and `-h`, written once beside them.
+//
+// A gate asked for its help checks nothing. At a terminal that is what was asked for, so the help
+// goes to stdout and the exit is 0. Under CI it is a trap: a package script that ends in `--help`
+// passes a required check having checked nothing (`"attw": "cosyte-attw --help"` did exactly that).
+// So when `CI` is set to anything but an empty string, `false` or `0`, which is how GitHub Actions
+// and the other common runners announce themselves, the help goes to stderr, a refusal follows it,
+// and the bin exits 2, the code every gate here uses for "did not run".
+
+/**
+ * Whether this process runs under CI, read the way the common runners set it.
+ *
+ * @param {Record<string, string | undefined>} [env] The environment to read.
+ * @returns {boolean} True when `CI` is set to anything but an empty string, `false` or `0`.
+ */
+export function underCi(env = process.env) {
+  const value = env.CI;
+  return value !== undefined && value !== "" && value !== "false" && value !== "0";
+}
+
+/**
+ * Answer `--help`: print the help and return 0, or under CI print it to stderr with a refusal and
+ * return 2.
+ *
+ * @param {string} name The bin's name, for the refusal line.
+ * @param {string} help The help text.
+ * @param {Record<string, string | undefined>} [env] The environment to read.
+ * @returns {number} The exit code.
+ */
+export function answerHelp(name, help, env = process.env) {
+  if (!underCi(env)) {
+    process.stdout.write(help);
+    return 0;
+  }
+  process.stderr.write(help);
+  process.stderr.write(
+    `${name}: refusing --help under CI (CI=${env.CI}). It prints this text and checks nothing, ` +
+      "so a CI step that runs it must not pass. Run the gate without --help.\n",
+  );
+  return 2;
+}

package/bin/script-utils.js

@@ -1,11 +1,14 @@
 #!/usr/bin/env node
 // script-utils: one entry for every gate in @cosyte/script-utils (D56). npx runs the bin named
 // after the package, so `npx -y @cosyte/script-utils@<version> <command> [args]` reaches each gate
-// from a repository with no package.json. `<command> --help` is the gate's own help.
+// from a repository with no package.json. `<command> --help` is the gate's own help; under CI
+// every `--help` exits 2, because it checks nothing.
 
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
+import { answerHelp } from "./help.js";
+
 const COMMANDS = {
   "no-emdash": ["cosyte-no-emdash", "the em and en dash gate, over tracked files and their names"],
   attw: ["cosyte-attw", "the attw publish gate, for the package here"],
@@ -16,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"],
 };
 
@@ -31,9 +34,11 @@ ${Object.entries(COMMANDS)
 `;
 
 const [command, ...rest] = process.argv.slice(2);
-if (command === undefined || command === "--help" || command === "-h") {
+if (command === undefined) {
   process.stdout.write(HELP);
-  process.exitCode = command === undefined ? 2 : 0;
+  process.exitCode = 2;
+} else if (command === "--help" || command === "-h") {
+  process.exitCode = answerHelp("script-utils", HELP);
 } else if (!(command in COMMANDS)) {
   process.stderr.write(`script-utils: ${JSON.stringify(command)} is not a command.\n\n${HELP}`);
   process.exitCode = 2;

package/catalog.d.ts

@@ -99,12 +99,19 @@ export declare function compareWithCatalog(
 export interface CatalogCheckOptions {
   /** The package directory holding package.json. Default: the working directory. */
   dir?: string;
-  /** CLI arguments; only `--dir <path>` is accepted. */
+  /** CLI arguments; `--dir <path>` and `--strict` are accepted. */
   argv?: string[];
+  /**
+   * Fail on a disagreement (1) or an unlisted package (2) instead of printing a note and exiting
+   * 0. Default: false, because keeping the catalog fresh is cosyte/config's job.
+   */
+  strict?: boolean;
 }
 
 /**
- * Run the check over one package directory and return the exit code: 0 the description is the
- * catalog's, 1 it is not, 2 the check could not run. It never exits the process.
+ * Run the check over one package directory and return the exit code. Advisory by default: 0 when
+ * the description is the catalog's, and 0 with a note when it is not or the package is unlisted.
+ * With `strict`, 1 for a disagreement and 2 for an unlisted package. 2 whenever the check could not
+ * run. It never exits the process.
  */
 export declare function runCatalogCheck(options?: CatalogCheckOptions): 0 | 1 | 2;

package/catalog.js

@@ -8,16 +8,20 @@
 // A site, the org profile, a deck or a knowledgebase page reads that one list instead of keeping
 // its own roster.
 //
-// IT ALSO CARRIES THE CHECK EVERY LIBRARY RUNS. Each package.json description is that library's one
-// canonical line (ST14), so the description in a library's package.json must be the catalog's.
-// When a library changes its description, its check fails until the catalog is regenerated and a
-// script-utils release carries it: the catalog and the package cannot quietly disagree.
+// IT ALSO CARRIES THE CHECK A LIBRARY CAN RUN, AND THAT CHECK IS ADVISORY. Each package.json
+// description is that library's one canonical line (ST14). Keeping the catalog fresh is cosyte/config's
+// job: `scripts/catalog.mjs check --npm` compares the catalog with every library's latest npm release,
+// nightly and before each config release. So a library that changes its description is not held red
+// until the next script-utils release: this check prints both values as a note and exits 0. `--strict`
+// makes a disagreement exit 1 and an unlisted package exit 2, for a caller that wants the old gate.
 //
 //   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 CODES, the contract every gate here keeps: 0 the description agrees, 1 it does not, 2 the
-// check could not run (no package.json, or a package the catalog does not list).
+// EXIT CODES: 0 the description agrees, or (advisory) it does not and a note says so; 1 it does not,
+// with --strict; 2 the check could not run (no package.json, a bad argument, or, with --strict, a
+// package the catalog does not list).
 //
 // ZERO DEPENDENCIES AND NO BUILD STEP, like the rest of this package.
 
@@ -192,21 +196,29 @@ export function compareWithCatalog(manifest, catalog = CATALOG) {
 /**
  * Run the check over one package directory and return the exit code. It never exits the process.
  *
- * @param {{ dir?: string, argv?: string[] }} [options] `dir` is the package directory (default:
- *   the working directory). `argv` is the CLI arguments, read only for `--dir <path>`.
- * @returns {0 | 1 | 2} 0 agree, 1 disagree, 2 the check could not run.
+ * ADVISORY BY DEFAULT: a disagreement or an unlisted package is printed as a note and exits 0,
+ * because keeping the catalog fresh is cosyte/config's job (`scripts/catalog.mjs check --npm`).
+ * `strict` (or `--strict`) restores the gate: 1 for a disagreement, 2 for an unlisted package.
+ *
+ * @param {{ dir?: string, argv?: string[], strict?: boolean }} [options] `dir` is the package
+ *   directory (default: the working directory). `argv` is the CLI arguments, read for
+ *   `--dir <path>` and `--strict`.
+ * @returns {0 | 1 | 2} 0 agree (or advisory), 1 disagree under strict, 2 the check could not run.
  */
 export function runCatalogCheck(options = {}) {
   let dir = options.dir ?? process.cwd();
+  let strict = options.strict === true;
   const argv = options.argv ?? [];
   for (let i = 0; i < argv.length; i += 1) {
     if (argv[i] === "--dir" && typeof argv[i + 1] === "string") {
       dir = argv[i + 1];
       i += 1;
+    } else if (argv[i] === "--strict") {
+      strict = true;
     } else if (argv[i] !== "--") {
       process.stderr.write(
         `catalog check: ${JSON.stringify(argv[i])} is not an argument this check accepts (only ` +
-          `--dir <package directory>). Nothing was checked.\n`,
+          `--dir <package directory> and --strict). Nothing was checked.\n`,
       );
       return 2;
     }
@@ -223,8 +235,15 @@ export function runCatalogCheck(options = {}) {
   try {
     differences = compareWithCatalog(manifest);
   } catch (err) {
-    process.stderr.write(`catalog check: ${err.message} Nothing was checked.\n`);
-    return 2;
+    if (strict) {
+      process.stderr.write(`catalog check: ${err.message} Nothing was checked.\n`);
+      return 2;
+    }
+    process.stderr.write(
+      `catalog check: note: ${err.message} The catalog is cosyte/config's to keep fresh; this ` +
+        `check is advisory, so it exits 0.\n`,
+    );
+    return 0;
   }
   if (differences.length === 0) {
     process.stdout.write(`catalog check: ${manifest.name}'s description is the catalog's.\n`);
@@ -237,11 +256,21 @@ export function runCatalogCheck(options = {}) {
         `    catalog:      ${JSON.stringify(d.catalog)}`,
     )
     .join("\n");
+  if (!strict) {
+    process.stderr.write(
+      `catalog check: note: ${manifest.name}'s package.json and the catalog this release of ` +
+        `@cosyte/script-utils carries disagree.\n${report}\n` +
+        `This is advisory and exits 0. Once this package is released with the new description, ` +
+        `cosyte/config's nightly check against npm (scripts/catalog.mjs check --npm) flags the ` +
+        `catalog, and the next script-utils release carries it.\n`,
+    );
+    return 0;
+  }
   process.stderr.write(
     `catalog check: ${manifest.name}'s package.json and the catalog disagree.\n${report}\n` +
-      `The catalog is generated from package.json in cosyte/config (scripts/catalog.mjs) and ` +
-      `ships in @cosyte/script-utils. Change both together: regenerate the catalog, release ` +
-      `script-utils, then move this package to that release.\n`,
+      `The catalog is generated in cosyte/config (scripts/catalog.mjs) and ships in ` +
+      `@cosyte/script-utils. Regenerate it there, release script-utils, then move this package to ` +
+      `that release.\n`,
   );
   return 1;
 }

package/check-no-emdash.sh

@@ -118,6 +118,22 @@
 #   * A repo with no such file declares no exclusions.
 #   * The declaration file is itself tracked and is SCANNED LIKE ANY OTHER TRACKED
 #     FILE. It is not self-excluding.
+#   * A BOUNDARY is the one entry that names part of a file rather than a whole one:
+#
+#       CHANGELOG.md em-only below ## Released before this file was generated
+#       CHANGELOG.md unread below ## Released before this file was generated
+#
+#     It is for a changelog whose dated archive predates the generated part and is kept
+#     verbatim. The path is ONE EXACT TRACKED PATH (no `/` prefix entry, no spaces), and
+#     the text after `below ` is a WHOLE LINE of that file, matched exactly. From the
+#     first line equal to 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 reds; `unread` does not read the archive at all. Everything
+#     above the boundary line is read for both dashes like any other file, and the file's
+#     NAME is scanned as always. A boundary line the file does not contain is a stale
+#     entry and the run exits 1, so a lost heading fails closed instead of widening what
+#     is left out. A path may carry one boundary, and a path the declaration also leaves
+#     out whole is refused, since it cannot be both.
 #
 # AN ENTRY IS THE LINE VERBATIM: nothing is trimmed off either end, because a path is
 # bytes and trimming would invent a second spelling for one entry. A line carrying
@@ -255,6 +271,14 @@ PATTERN='(?i)\x{2014}|\x{2013}|&[mn]dash(?![a-z])|&#0*821[12](?![0-9])|&#x0*201[
 PATTERN+='|%E2%80%9[34]|\\u(?:0000)?201[34]|\\u\{0*201[34]\}|\\x\{0*201[34]\}'
 PATTERN+='|\\0{0,2}201[34](?![0-9a-f])|\\N\{E[MN] DASH\}'
 
+# The em dash's half of PATTERN, form for form, for the archive a declared `em-only`
+# boundary reads. The self-test below holds it to matching the em dash and NOT the en
+# dash, and test/check-no-emdash.test.ts holds every em form to it, so it cannot drift
+# from PATTERN without a red.
+EM_PATTERN='(?i)\x{2014}|&mdash(?![a-z])|&#0*8212(?![0-9])|&#x0*2014(?![0-9a-f])'
+EM_PATTERN+='|%E2%80%94|\\u(?:0000)?2014|\\u\{0*2014\}|\\x\{0*2014\}'
+EM_PATTERN+='|\\0{0,2}2014(?![0-9a-f])|\\N\{EM DASH\}'
+
 # The declaration's path, relative to the top level of the repo under scan. Deliberately
 # NOT relative to this file: in a consuming repo this file lives under `node_modules/`
 # and the declaration is the consumer's own tracked file.
@@ -314,6 +338,25 @@ if [ "$#" -gt 0 ] && [ "$1" = '--' ]; then
   shift
 fi
 
+usage() {
+  cat << 'USAGE'
+check-no-emdash: refuse the em dash (U+2014) and the en dash (U+2013), as the characters and
+in every encoded form, in the tracked files of the repository it runs in and in their names.
+
+  check-no-emdash.sh                 scan every tracked file and every tracked file name
+  check-no-emdash.sh --stdin LABEL   scan the text on stdin (a PR title, body, commit message)
+  check-no-emdash.sh --list-scanned  write the NUL-separated paths the default scan reads
+  check-no-emdash.sh --self-id       write the sha256 of the implementation that is executing
+
+A repository leaves paths out in scripts/check-no-emdash.exclude: one per line, an entry ending
+in / covers everything beneath it, # starts a comment. A changelog archive is named by a boundary,
+`PATH em-only below LINE` or `PATH unread below LINE`: from the first line of PATH equal to LINE to
+the end, em-only reads for the em dash alone and unread reads nothing; above it, both dashes as
+usual. Exit 0 means the mode completed and found nothing banned; exit 1 means anything else. Under
+CI, --help exits 1: it checks nothing.
+USAGE
+}
+
 case "${1:-}" in
   '')
     MODE=files
@@ -339,19 +382,17 @@ case "${1:-}" in
     fi
     ;;
   --help | -h)
-    cat << 'USAGE'
-check-no-emdash: refuse the em dash (U+2014) and the en dash (U+2013), as the characters and
-in every encoded form, in the tracked files of the repository it runs in and in their names.
-
-  check-no-emdash.sh                 scan every tracked file and every tracked file name
-  check-no-emdash.sh --stdin LABEL   scan the text on stdin (a PR title, body, commit message)
-  check-no-emdash.sh --list-scanned  write the NUL-separated paths the default scan reads
-  check-no-emdash.sh --self-id       write the sha256 of the implementation that is executing
-
-A repository leaves paths out in scripts/check-no-emdash.exclude: one per line, an entry ending
-in / covers everything beneath it, # starts a comment. Exit 0 means the mode completed and found
-nothing banned; exit 1 means anything else.
-USAGE
+    # Under CI the help is a refusal: it prints this text and checks nothing, so a CI step that
+    # runs it must not pass. `CI` set to anything but empty, `false` or `0` is how GitHub Actions
+    # and the other common runners announce themselves.
+    if [ -n "${CI:-}" ] && [ "${CI}" != false ] && [ "${CI}" != 0 ]; then
+      usage >&2
+      echo "ERROR: check-no-emdash - refusing --help under CI (CI=${CI}). It prints this text and" >&2
+      echo "       checks nothing, so a CI step that runs it must not pass. Run the gate without" >&2
+      echo "       --help." >&2
+      exit 1
+    fi
+    usage
     exit 0
     ;;
   *)
@@ -557,6 +598,13 @@ entry_matches_a_tracked_path() {
 
 # ---- the exclusion declaration ---------------------------------------------------
 EXCLUDES=()
+# A declared boundary, one index per entry: the path, `em-only` or `unread`, the boundary
+# line as written, and the number of the first line of the file equal to it.
+BOUND_PATH=()
+BOUND_MODE=()
+BOUND_TEXT=()
+BOUND_LINE=()
+BOUNDARY_SHAPE='^([^ ]+) (em-only|unread) below (.+)$'
 refuse_declaration() {
   local line="$1" entry="$2" what="$3"
   echo "ERROR: check-no-emdash - unusable entry in ${DECLARATION}, line ${line}: ${entry}" >&2
@@ -589,6 +637,45 @@ if is_tracked "$DECLARATION"; then
     # The entry is the line VERBATIM. See the header: nothing is trimmed, because a path
     # is bytes. The anchor rules are the whole of what makes an entry usable on its face.
     entry=$line
+
+    # A BOUNDARY names part of one file. It is recognised by its shape and validated on its
+    # own terms, so nothing below it can mistake it for a path with spaces in it.
+    if [[ $entry =~ $BOUNDARY_SHAPE ]]; then
+      b_path=${BASH_REMATCH[1]}
+      b_mode=${BASH_REMATCH[2]}
+      b_text=${BASH_REMATCH[3]}
+      case $b_path in
+        /* | ./* | *..* | */)
+          refuse_declaration "$lineno" "$entry" \
+            "A boundary names ONE tracked file, anchored at the repository root: not absolute, not ./, no .., and not a directory."
+          ;;
+      esac
+      if ! is_tracked "$b_path"; then
+        refuse_declaration "$lineno" "$entry" \
+          "No tracked file is spelled ${b_path}. A boundary that has outlived its file is a hole nobody is looking at."
+      fi
+      for i in "${!BOUND_PATH[@]}"; do
+        if [ "${BOUND_PATH[$i]}" = "$b_path" ]; then
+          refuse_declaration "$lineno" "$entry" \
+            "${b_path} already carries a boundary. A file has one archive, so it has one boundary."
+        fi
+      done
+      if [ ! -f "$b_path" ] || [ ! -r "$b_path" ]; then
+        refuse_declaration "$lineno" "$entry" \
+          "${b_path} is not a readable regular file, so its boundary line cannot be looked for."
+      fi
+      b_line=$(grep -n -m1 -xF -e "$b_text" -- "$b_path" 2> /dev/null || true)
+      b_line=${b_line%%:*}
+      if [ -z "$b_line" ]; then
+        refuse_declaration "$lineno" "$entry" \
+          "${b_path} has no line that is exactly: ${b_text}. A lost boundary fails closed rather than leaving out more than was declared: restore the line, or correct or delete the entry."
+      fi
+      BOUND_PATH+=("$b_path")
+      BOUND_MODE+=("$b_mode")
+      BOUND_TEXT+=("$b_text")
+      BOUND_LINE+=("$b_line")
+      continue
+    fi
     case $entry in
       /*)
         refuse_declaration "$lineno" "$entry" \
@@ -648,6 +735,30 @@ is_excluded() {
   return 1
 }
 
+# A path is either left out whole or read up to its boundary. Both at once would leave the
+# reader unable to say which one the gate honoured, so it is refused, whichever line came
+# first.
+for i in "${!BOUND_PATH[@]}"; do
+  if is_excluded "${BOUND_PATH[$i]}"; then
+    echo "ERROR: check-no-emdash - ${DECLARATION} both leaves out ${BOUND_PATH[$i]} and" >&2
+    echo "       declares a boundary in it. A file is either left out whole or read up to its" >&2
+    echo "       boundary; delete one of the two entries." >&2
+    exit 1
+  fi
+done
+
+# The index of the boundary declared for a path, or nothing.
+boundary_index() {
+  local p="$1" i
+  for i in "${!BOUND_PATH[@]}"; do
+    if [ "${BOUND_PATH[$i]}" = "$p" ]; then
+      printf '%s' "$i"
+      return 0
+    fi
+  done
+  return 1
+}
+
 # ---- --self-id: which bytes am I ------------------------------------------------
 #
 # Answered before the scanner assertions, because this mode reads no scanned content and
@@ -736,6 +847,20 @@ if [ "$MODE" = files ] || [ "$MODE" = stdin ]; then
     echo "       Refusing to report findings from a scanner that flags what the rule allows." >&2
     exit 1
   fi
+  # The archive reading a declared `em-only` boundary uses: it must still see the em dash,
+  # and it must NOT see the en dash, or `em-only` would mean something other than it says.
+  if [ "${#BOUND_PATH[@]}" -gt 0 ]; then
+    if ! printf 'a\xe2\x80\x94b\n' | grep -qP "$EM_PATTERN"; then
+      echo "ERROR: check-no-emdash - the archive scanner cannot match a known em dash." >&2
+      echo "       Refusing to read a declared boundary's archive with a scanner that cannot see." >&2
+      exit 1
+    fi
+    if printf 'a\xe2\x80\x93b\n' | grep -qP "$EM_PATTERN"; then
+      echo "ERROR: check-no-emdash - the archive scanner matched an en dash, so it is not reading" >&2
+      echo "       for the em dash alone. Refusing to report what an em-only boundary allows." >&2
+      exit 1
+    fi
+  fi
 
   # SCANNER VISIBILITY PROBE: prove the scanner can still READ a file before believing a
   # word it says about one. The self-test above asserts what the tool MATCHES; this
@@ -901,12 +1026,20 @@ for i in "${!TRACKED[@]}"; do
     exit 1
   fi
 
+  # A file with a declared boundary is read on its own below, in two halves. It is still
+  # READ, so it is listed for --list-scanned and counted as scanned.
+  if boundary_index "$f" > /dev/null; then
+    printf '%s\0' "$f" >> "$PLAINLIST"
+    scanned=$((scanned + 1))
+    continue
+  fi
+
   printf './%s\0' "$f" >> "$SCANLIST"
   printf '%s\0' "$f" >> "$PLAINLIST"
   scanned=$((scanned + 1))
 done
 
-if [ ! -s "$SCANLIST" ]; then
+if [ ! -s "$SCANLIST" ] && [ "${#BOUND_PATH[@]}" -eq 0 ]; then
   echo "ERROR: check-no-emdash - no tracked files left to scan. Refusing to report" >&2
   echo "       green from a scan that read nothing." >&2
   exit 1
@@ -932,6 +1065,38 @@ HITS=$(xargs -0 -r grep -H -nP -e "$PATTERN" -- < "$SCANLIST" 2>> "$ERRLOG" || t
 
 refuse_if_incomplete
 
+# The files with a declared boundary. Every hit is found with the full pattern first, so
+# the line numbers are the file's own; a hit above the boundary line stands, and a hit at
+# or below it stands only for `em-only` and only when the line holds an em dash.
+bounded_note=''
+for i in "${!BOUND_PATH[@]}"; do
+  b_path=${BOUND_PATH[$i]}
+  b_line=${BOUND_LINE[$i]}
+  b_mode=${BOUND_MODE[$i]}
+  b_hits=$(grep -H -nP -e "$PATTERN" -- "./${b_path}" 2>> "$ERRLOG" || true)
+  refuse_if_incomplete
+  while IFS= read -r hit; do
+    [ -n "$hit" ] || continue
+    n=${hit#"./${b_path}:"}
+    n=${n%%:*}
+    keep=0
+    if [ "$n" -lt "$b_line" ]; then
+      keep=1
+    elif [ "$b_mode" = em-only ] && printf '%s\n' "${hit#"./${b_path}:${n}:"}" | grep -qP -e "$EM_PATTERN"; then
+      keep=1
+    fi
+    if [ "$keep" -eq 1 ]; then
+      HITS="${HITS:+${HITS}
+}${hit}"
+    fi
+  done <<< "$b_hits"
+  if [ "$b_mode" = em-only ]; then
+    bounded_note="${bounded_note}, ${b_path} from line ${b_line} read for the em dash only"
+  else
+    bounded_note="${bounded_note}, ${b_path} from line ${b_line} not read"
+  fi
+done
+
 if [ -n "$NAME_HITS" ] && [ -n "$HITS" ]; then
   fail_with_hits "the tracked file names and the tracked files listed above" \
     "$NAME_HITS"$'\n'"$HITS"
@@ -941,4 +1106,4 @@ fi
 
 echo "check-no-emdash: OK (no em or en dashes in ${scanned} of ${#TRACKED[@]} tracked file(s)" \
   "or their names; ${gitlinks} gitlink(s) skipped, ${self_excluded} excluded as the" \
-  "implementation under scan, ${declared_excluded} excluded by ${DECLARATION})"
+  "implementation under scan, ${declared_excluded} excluded by ${DECLARATION}${bounded_note})"

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/internal-refs.d.ts

@@ -68,6 +68,16 @@ export interface SourceDocCommentsAxis {
   extraRules?: ExtraRule[];
 }
 
+/** Whether the source string-literal pass runs, over what, and with which extra rules. */
+export interface SourceStringLiteralsAxis {
+  /** @default false */
+  enabled: boolean;
+  /** Tracked pathspecs holding the source whose string literals reach a consumer as messages. */
+  paths?: string[];
+  /** Detection that applies to string literals only. */
+  extraRules?: ExtraRule[];
+}
+
 export interface InternalRefsConfig {
   /**
    * AXIS 1, REQUIRED. The project and programme prefixes an identifier is keyed on, and an empty
@@ -113,6 +123,15 @@ export interface InternalRefsConfig {
    */
   sourceDocComments?: SourceDocCommentsAxis;
 
+  /**
+   * DEFAULTED OFF. The source string-literal pass: double-quoted, single-quoted and template
+   * literals, decoded, with every comment skipped, because a string literal reaches a consumer as
+   * error and warning text and a comment does not. A NUL byte in source reads as a space.
+   *
+   * @default { enabled: false }
+   */
+  sourceStringLiterals?: SourceStringLiteralsAxis;
+
   /**
    * AXIS 6, DEFAULTED. `clean` must be 0 and the other two must not be, which is checked: a mapping
    * that put `hits` on 0 would turn every finding into a green run.
@@ -207,6 +226,18 @@ export declare function runSelfTests(rules: CompiledRule[]): string[];
 /** Join a document the way markdown renders it, so a violation that straddles a wrap is visible. */
 export declare function reflowParagraphs(text: string): string[];
 
+/**
+ * Extract the string literals of one JavaScript or TypeScript source file, decoded, with every
+ * comment skipped: one entry per literal, and one per source line holding two or more of them.
+ */
+export declare function extractStringLiterals(
+  text: string,
+  file: string,
+): {
+  literals: { text: string; where: string }[];
+  lines: { text: string; where: string }[];
+};
+
 /** Extract doc-comment text from one source file, with each line's location beside it. */
 export declare function extractDocComments(
   text: string,