@williamthorsen/nmr 0.39.0 → 0.41.0

package/.meta/changelog.json

@@ -1,4 +1,144 @@
 [
+  {
+    "version": "0.41.0",
+    "date": "2026-10-02",
+    "sections": [
+      {
+        "title": "🎉 Features",
+        "audience": "all",
+        "items": [
+          {
+            "description": "Adds a hint to `nmr` that, when a command fails, names any of nmr's own flags written after the command name and shows the corrected invocation, such as `nmr -q check`. (#956)",
+            "hash": "21e1759f8eb8257d81bc5bf1e533dbd496d99017",
+            "entry": 1
+          }
+        ]
+      }
+    ]
+  },
+  {
+    "version": "0.40.0",
+    "date": "2026-10-01",
+    "sections": [
+      {
+        "title": "🎉 Features",
+        "audience": "all",
+        "items": [
+          {
+            "description": "Makes `checkTestFileConventions` and the readyup kit's tier and placement checks skip untracked paths that git ignores, so that local build output such as a stale `.netlify/` directory no longer fails the check. (#898)",
+            "hash": "15132d5e797b734f1fc78bce7abc5d82c7e81974",
+            "entry": 1
+          },
+          {
+            "description": "Excludes untracked paths that git ignores from collection in `defineVitestConfig` and `defineRootVitestConfig`, so that Vitest does not run a test file that the conventions check skips. (#898)",
+            "hash": "15132d5e797b734f1fc78bce7abc5d82c7e81974",
+            "entry": 2
+          },
+          {
+            "description": "Rewords the `nmr --log` refusal for a run that the check-result cache does not cover to `the check-result cache does not apply here (NMR_DEBUG=1 reports why)`, and renames the matching `docs/check-cache.md` heading to \"When the cache does not apply\", which changes its anchor. (#923)",
+            "hash": "71d8c3dfb45aca872ca897ee589aae6351a1f516",
+            "entry": 1
+          }
+        ]
+      },
+      {
+        "title": "🐛 Bug fixes",
+        "audience": "all",
+        "items": [
+          {
+            "description": "Rewords the messages printed by `nmr`, its bin wrappers, and its readyup kit, which used figures such as \"sits under\" and \"holds\", em-dashes, and \"no\" as a determiner, so that a diagnosis such as \"-F/--filter did not match any workspace\" states its condition directly. (#932)",
+            "hash": "570f1103437d22b81b556f2d2b2e02f1fc32942c",
+            "entry": 1
+          },
+          {
+            "description": "Fixes the issue that the `nmr` rulebook recommended `-q` without stating that nmr reads its own flags only before the command name, which led agents to run `nmr ci -q` and fail when `nmr-fmt` rejected the flag. (#948)",
+            "hash": "b7cf3b3dfcd901db11546f153ec6de61580e6a69",
+            "entry": 1
+          }
+        ]
+      },
+      {
+        "title": "♻️ Refactoring",
+        "audience": "dev",
+        "items": [
+          {
+            "description": "Replaces every `.sort()` call that suppressed `unicorn/no-array-sort` with `toSorted()` and drops the spread copy wherever the source was already an array. (#925)",
+            "hash": "4680fb4e865ffce0bd135fac20d49b766b156992",
+            "entry": 1
+          }
+        ]
+      },
+      {
+        "title": "🧪 Tests",
+        "audience": "dev",
+        "items": [
+          {
+            "description": "Stubs `GIT_CEILING_DIRECTORIES` to the fixture's parent in every test that expects git to find no repository, so that a repository above the temp directory can no longer change the test's result. (#923)",
+            "hash": "71d8c3dfb45aca872ca897ee589aae6351a1f516",
+            "entry": 2
+          },
+          {
+            "description": "Moves the `everyBinTargetIsACommittedWrapper` tests from `kit-bin-checks.unit.test.ts` to `kit-bin-checks.tool.test.ts`, because they spawn git through readyup's `listTrackedFiles`. (#923)",
+            "hash": "71d8c3dfb45aca872ca897ee589aae6351a1f516",
+            "entry": 3
+          }
+        ]
+      },
+      {
+        "title": "⚙️ Tooling",
+        "audience": "dev",
+        "items": [
+          {
+            "description": "Adds a check to `bootstrap.tool.test.ts` that fails when a package's `prepare` runs the build bootstrap without either depending on nmr-core or passing `--conditions nmr-source`, which would make `pnpm install` fail on a fresh clone. (#903)",
+            "hash": "b00b17d277197c1b18133da2e5258cf52719946a",
+            "entry": 3
+          }
+        ]
+      },
+      {
+        "title": "📦 Dependencies",
+        "audience": "dev",
+        "items": [
+          {
+            "description": "Adds `esbuild` 0.28.2 to the pnpm catalog and declares it as a devDependency of `nmr`, `release-kit`, and `v11y-check`, because `readyup` declares it only as an optional peer and `rdy compile` failed in those packages once a regenerated lockfile stopped installing it. (#944)",
+            "hash": "6dffd5df5bc4209dc225d08390ef2b67fe381f1b",
+            "entry": 2
+          }
+        ]
+      },
+      {
+        "title": "📚 Documentation",
+        "audience": "dev",
+        "items": [
+          {
+            "description": "Revises the comments in `packages/nmr/src` and `packages/nmr/.readyup/kits/default.ts` against the comment-discipline rules, correcting comments that misstated the code, such as the Levenshtein distance quoted in `runCli.ts` and a `root-tests-config` kit check that does not exist. (#919)",
+            "hash": "84fe905d4142059425d82eb8d10821b687f522c2",
+            "entry": 1
+          },
+          {
+            "description": "Corrects the truncation example in `packages/nmr/docs/reporting.md`, replacing 90 seconds, which renders as `1m 30s` whether it is truncated or rounded, with 119.9 seconds, which truncates to `1m 59s`. (#919)",
+            "hash": "84fe905d4142059425d82eb8d10821b687f522c2",
+            "entry": 2
+          },
+          {
+            "description": "Rewrites the sentences in the README, the guides under `docs/`, the agent rulebook, and the code comments of `@williamthorsen/nmr` that broke the repository's writing rules on plain speech, em-dashes, second-person address, and relative clauses. (#932)",
+            "hash": "570f1103437d22b81b556f2d2b2e02f1fc32942c",
+            "entry": 2
+          },
+          {
+            "description": "Replaces \"where\" in two doc comments in `packages/nmr/src/check-cache.ts` and in the fixture comment in two tier-budget tests, because each use introduced a consequence rather than a place. (#945)",
+            "hash": "6f2c93ee0c73810ebd4cb4ab76618c00235edc42",
+            "entry": 1
+          },
+          {
+            "description": "Writes `-q` as `nmr -q <command>` in `docs/reporting.md` and in the README's verbosity paragraph. (#948)",
+            "hash": "b7cf3b3dfcd901db11546f153ec6de61580e6a69",
+            "entry": 2
+          }
+        ]
+      }
+    ]
+  },
   {
     "version": "0.39.0",
     "date": "2026-09-22",
@@ -229,7 +369,8 @@
         "items": [
           {
             "description": "Keep global git ignore rules and attributes out of test subprocesses (#773)",
-            "body": "Fixes an issue where a test that spawns `git` read ignore rules and attributes from outside the repository, so a suite could pass or fail on whatever a developer or their machine happened to have configured. The setup file that `defineVitestConfig` loads by default now isolates both, alongside the git configuration already covered.\r\n\r\nMigration: Where a test needs its own `core.excludesFile` or `core.attributesFile`, pass it on the invocation as `git -c core.excludesFile=<path>`. An environment-injected key now outranks repository-local config.",
+            "body": "Fixes an issue where a test that spawns `git` read ignore rules and attributes from outside the repository, so a suite could pass or fail on whatever a developer or their machine happened to have configured. The setup file that `defineVitestConfig` loads by default now isolates both, alongside the git configuration already covered.\n\nMigration: Where a test needs its own `core.excludesFile` or `core.attributesFile`, pass it on the invocation as `git -c core.excludesFile=<path>`. An environment-injected key now outranks repository-local config.",
+            "migration": "Where a test needs its own `core.excludesFile` or `core.attributesFile`, pass it on the invocation as `git -c core.excludesFile=<path>`. An environment-injected key now outranks repository-local config.",
             "hash": "59b454ff3344a7c00d766f041a5862faa1ee6f1f"
           }
         ]
@@ -466,7 +607,7 @@
         "items": [
           {
             "description": "Carry the test-tier convention in the ambient rulebook (#689)",
-            "body": "Adds the test-tier convention to `nmr.md`, the ambient rulebook `codeassembly sync` deploys to each consuming repo's agent guidance. The guidance describes the `<subject>[.<aspect>].<tier>.test.ts` grammar and the four tiers, and warns that tests outside a `__tests__` directory are ignored. Tests not explicitly attributed to a tier are flagged by the ReadyUp kit bundled with `nmr`.\r\n\r\nThe previous guidance is removed from `AGENTS.md`.",
+            "body": "Adds the test-tier convention to `nmr.md`, the ambient rulebook `codeassembly sync` deploys to each consuming repo's agent guidance. The guidance describes the `<subject>[.<aspect>].<tier>.test.ts` grammar and the four tiers, and warns that tests outside a `__tests__` directory are ignored. Tests not explicitly attributed to a tier are flagged by the ReadyUp kit bundled with `nmr`.\n\nThe previous guidance is removed from `AGENTS.md`.",
             "hash": "a1fa0e0eb19362f0506ce4f98cd527b205baf1e7"
           },
           {
@@ -503,7 +644,7 @@
           },
           {
             "description": "Adopt `isError` and consolidate errno narrowing on a shared helper (#697)",
-            "body": "Replaces every hand-rolled `instanceof Error` narrowing with `hasErrnoCode`, a new predicate exported from `@williamthorsen/nmr-core`, or with `isError` from `@williamthorsen/toolbelt.errors`. Previously the errno question was answered by inline copies alongside two private helpers of differing shape; both helpers are removed.\r\n\r\nSeparately, `eslint.config.ts` now bans `instanceof Error` in every position rather than in a ternary alone.",
+            "body": "Replaces every hand-rolled `instanceof Error` narrowing with `hasErrnoCode`, a new predicate exported from `@williamthorsen/nmr-core`, or with `isError` from `@williamthorsen/toolbelt.errors`. Previously the errno question was answered by inline copies alongside two private helpers of differing shape; both helpers are removed.\n\nSeparately, `eslint.config.ts` now bans `instanceof Error` in every position rather than in a ternary alone.",
             "hash": "c5e8e8a5e006b451e8c5aeea75d35772926d503c"
           }
         ]
@@ -581,7 +722,7 @@
         "items": [
           {
             "description": "Derive the shelled-nmr remedy from the declaration site and reject a malformed package.json (#658)",
-            "body": "Fixes a shelled-nmr warning that named `.config/nmr.config.ts` as the remedy for every step it reported, including the `package.json` entries that tier cannot resolve. The line now names the relevant declaration and remedy. Shelled nmr can now be detected not only in a step's first token but anywhere in the step.\r\n\r\nSeparately, a configuration mistake now reports as a plain message rather than a Node stack trace.",
+            "body": "Fixes a shelled-nmr warning that named `.config/nmr.config.ts` as the remedy for every step it reported, including the `package.json` entries that tier cannot resolve. The line now names the relevant declaration and remedy. Shelled nmr can now be detected not only in a step's first token but anywhere in the step.\n\nSeparately, a configuration mistake now reports as a plain message rather than a Node stack trace.",
             "hash": "74ea98c361cf13e213d257952c582a4ebd631d9a"
           }
         ]

package/.readyup/kits/default.js

@@ -64,7 +64,7 @@ var workspaceScripts = {
   "test:unit": "pnpm exec vitest --project unit",
   "test:watch": `pnpm exec vitest ${GATE_PROJECTS} --watch`,
   typecheck: "tsgo --noEmit",
-  // The command is a string because neither half names an nmr command: both are binaries.
+  // The command is a string because neither half names an nmr command: Both are binaries.
   upgrade: "nmr-report-catalog && nmr-taze",
   "view-coverage": "open coverage/index.html"
 };
@@ -75,8 +75,8 @@ var rootScripts = {
   build: ["-R build"],
   check: [TYPECHECK_STEP, "fmt:check", "lint:check", "test"],
   "check:strict": [TYPECHECK_STEP, "fmt:check", "lint:strict", "test"],
-  // Excludes the audit, which in CI has a workflow of its own. The build is what the narrowed check runs
-  // against, so it declines the arguments rather than being narrowed by them.
+  // Excludes the audit, which in CI has a workflow of its own. The narrowed check runs against the build, so
+  // the build declines the arguments rather than being narrowed by them.
   ci: [{ run: "build", shouldDeclineArguments: true }, "check:strict"],
   clean: "nmr-clean",
   fix: ["lint", "fmt"],
@@ -86,8 +86,8 @@ var rootScripts = {
   lint: "eslint --fix .",
   "lint:check": "eslint .",
   "lint:strict": "strict-lint",
-  // The audit costs seconds and `ci` costs minutes, so the cheap gate fails first. The audit reads the
-  // dependency tree, which no argument narrowing the code under test says anything about.
+  // The audit takes seconds and `ci` takes minutes, so the cheap gate fails first. The audit reads the
+  // dependency tree, and an argument narrowing the code under test does not say anything about that tree.
   prepush: [{ run: "audit", shouldDeclineArguments: true }, "ci"],
   "report-overrides": "nmr-report-overrides",
   "root:check": [ROOT_TYPECHECK_STEP, "fmt:check", "root:lint:check", "root:test"],
@@ -99,7 +99,7 @@ var rootScripts = {
   "root:test:tool": "vitest --config ./vitest.root.config.ts --project tool",
   "root:test:unit": "vitest --config ./vitest.root.config.ts --project unit",
   "root:typecheck": "tsgo --noEmit",
-  // Carries the override report for the same reason `upgrade` does: both end in the tool that rewrites a
+  // Includes the override report for the same reason `upgrade` does: Both end in the tool that rewrites a
   // `pnpm.overrides` block, so both need the reporter's rejection ahead of them.
   "root:upgrade": "nmr-report-overrides && nmr-taze",
   test: ["root:test", "-R test"],
@@ -109,9 +109,9 @@ var rootScripts = {
   "test:unit": ["root:test:unit", "-R test:unit"],
   "test:watch": `vitest ${GATE_PROJECTS} --watch`,
   // Neither step is narrowable, so `nmr typecheck <file>` is rejected rather than checking that file under
-  // default options at the root and hunting for it in every package.
+  // default options at the root and searching for it in every package.
   typecheck: [ROOT_TYPECHECK_STEP, { run: "-R typecheck", shouldDeclineArguments: true }],
-  // The command is a string because neither half names an nmr command: both are binaries, and a composite
+  // The command is a string because neither half names an nmr command: Both are binaries, and a composite
   // element can name only a command.
   upgrade: "nmr-report-overrides && nmr-taze --recursive"
 };
@@ -124,6 +124,20 @@ function getDefaultRootScripts() {
 // src/tiers.ts
 import { readdirSync } from "node:fs";
 import path from "node:path";
+
+// src/git-ignored-paths.ts
+import { spawnSync } from "node:child_process";
+function listGitIgnoredPaths(dir) {
+  const result = spawnSync(
+    "git",
+    ["ls-files", "-z", "--others", "--ignored", "--exclude-standard", "--directory", "--no-empty-directory"],
+    { cwd: dir, encoding: "utf8" }
+  );
+  if (result.error !== void 0 || result.status !== 0) return [];
+  return result.stdout.split("\0").filter((entry) => entry !== "").toSorted();
+}
+
+// src/tiers.ts
 var TEST_DIR = "__tests__";
 var TEST_EXTENSIONS = "{ts,tsx}";
 var TEST_GLOB_PREFIX = `**/${TEST_DIR}/**`;
@@ -149,9 +163,9 @@ function collectTestFiles(dir, relativeDir, isInTestDir, context) {
   for (const entry of entries) {
     const relativePath = relativeDir === "" ? entry.name : `${relativeDir}/${entry.name}`;
     if (entry.isDirectory()) {
-      if (context.pruned.has(entry.name)) continue;
+      if (context.pruned.has(entry.name) || context.ignoredPaths.has(`${relativePath}/`)) continue;
       collectTestFiles(path.join(dir, entry.name), relativePath, isInTestDir || entry.name === TEST_DIR, context);
-    } else if (isInTestDir !== context.misplaced && TEST_FILE_PATTERN.test(entry.name)) {
+    } else if (isInTestDir !== context.misplaced && TEST_FILE_PATTERN.test(entry.name) && !context.ignoredPaths.has(relativePath)) {
       context.foundPaths.push(relativePath);
     }
   }
@@ -159,6 +173,7 @@ function collectTestFiles(dir, relativeDir, isInTestDir, context) {
 function walkTestFiles(rootDir, { excludedBasenames = [] }, misplaced) {
   const context = {
     foundPaths: [],
+    ignoredPaths: new Set(listGitIgnoredPaths(rootDir)),
     misplaced,
     pruned: /* @__PURE__ */ new Set([...TEST_COLLECTION_EXCLUDE, ...excludedBasenames])
   };
@@ -210,21 +225,21 @@ var default_default = defineRdyKit({
           severity: "warn",
           quiet: true,
           check: toolVersionsHasNoPnpm,
-          fix: "Remove pnpm from .tool-versions \u2014 manage via the packageManager field"
+          fix: "Remove pnpm from .tool-versions, and manage it through the packageManager field"
         },
         {
           name: "no package.json declares a pnpm field",
           severity: "error",
           quiet: true,
           check: () => noPnpmFieldInPackageJson(),
-          fix: "Move these settings into pnpm-workspace.yaml, quoting each version under `overrides`, or run `pnpx codemod run pnpm-v10-to-v11`. pnpm 11 reads no key from the `pnpm` field, so an override left there pins nothing while an upgrade run with `--write` goes on rewriting it"
+          fix: "Move these settings into pnpm-workspace.yaml, quoting each version under `overrides`, or run `pnpx codemod run pnpm-v10-to-v11`. pnpm 11 does not read any key from the `pnpm` field, so an override left there pins nothing while an upgrade run with `--write` goes on rewriting it"
         },
         {
           name: ".config/nmr.config.ts uses defineConfig",
           severity: "recommend",
           skip: () => !fileExists(".config/nmr.config.ts") ? "no nmr config file" : false,
           check: () => fileContains(".config/nmr.config.ts", /defineConfig/),
-          fix: "Wrap your config export with defineConfig() from @williamthorsen/nmr/config for type safety"
+          fix: "Wrap the config export with defineConfig() from @williamthorsen/nmr/config for type safety"
         },
         // `error` because falling short produces wrong results rather than a failure. Names and fixes are
         // getters because their version constants are declared below the kit.
@@ -236,7 +251,7 @@ var default_default = defineRdyKit({
           skip: () => !hasDevDependency("eslint") ? "eslint not installed" : false,
           check: hasSupportedEslintVersion,
           get fix() {
-            return `pnpm add --save-dev eslint@^${MIN_ESLINT_VERSION} \u2014 earlier releases resolve config from the working directory, so nmr's root lint and lint:check would apply the root config to every package`;
+            return `pnpm add --save-dev eslint@^${MIN_ESLINT_VERSION}. Earlier releases resolve config from the working directory, so nmr's root lint and lint:check would apply the root config to every package`;
           }
         },
         {
@@ -247,7 +262,7 @@ var default_default = defineRdyKit({
           skip: () => !hasDevDependency("@williamthorsen/strict-lint") ? "strict-lint not installed" : false,
           check: hasSupportedStrictLintVersion,
           get fix() {
-            return `pnpm add --save-dev @williamthorsen/strict-lint@^${MIN_STRICT_LINT_VERSION} \u2014 earlier releases pin ESLint to one config and resolve ceilings from the working directory, so nmr's root lint:strict would report the wrong rules for every package`;
+            return `pnpm add --save-dev @williamthorsen/strict-lint@^${MIN_STRICT_LINT_VERSION}. Earlier releases pin ESLint to one config and resolve ceilings from the working directory, so nmr's root lint:strict would report the wrong rules for every package`;
           }
         },
         // -- Root script cleanup -------------------------------------------------
@@ -256,7 +271,7 @@ var default_default = defineRdyKit({
           severity: "warn",
           quiet: true,
           check: noRedundantRootScripts,
-          fix: "Remove scripts from root package.json that nmr provides as built-in root scripts \u2014 invoke via nmr directly"
+          fix: "Remove scripts from root package.json that nmr provides as built-in root scripts, and invoke them through nmr directly"
         },
         // -- Git hooks -----------------------------------------------------------
         {
@@ -278,13 +293,13 @@ var default_default = defineRdyKit({
           name: "every bin target is a committed wrapper",
           severity: "error",
           check: () => everyBinTargetIsACommittedWrapper(),
-          fix: `Point each listed entry at a committed wrapper under bin/ that loads the build output at runtime. pnpm links a workspace package's bins during the install's link phase, which runs before anything is built, so a target that is not committed does not exist when pnpm reaches for it \u2014 and pnpm never retries, leaving the link missing for the life of the node_modules tree`
+          fix: `Point each listed entry at a committed wrapper under bin/ that loads the build output at runtime. pnpm links a workspace package's bins during the install's link phase, which runs before anything is built, so a target that is not committed does not exist when pnpm tries to link it. pnpm never retries, which leaves the link missing for the life of the node_modules tree`
         },
         {
           name: "every bin wrapper's build-output target is covered by files",
           severity: "warn",
           check: () => everyBinWrapperTargetIsCoveredByFiles(),
-          fix: "Add the build output directory to `files` in each listed package. npm and pnpm publish the bin target itself whatever `files` says, so the wrapper ships pointing at build output missing from the tarball"
+          fix: "Add the build output directory to `files` in each listed package. npm and pnpm publish the bin target itself whatever `files` says, so the wrapper is published pointing at build output missing from the tarball"
         },
         // -- Vitest projects -----------------------------------------------------
         {
@@ -298,7 +313,7 @@ var default_default = defineRdyKit({
           name: "every vitest.config builds on @williamthorsen/nmr/vitest",
           severity: "error",
           check: () => vitestConfigBuildsOnSharedConfig(),
-          fix: "Replace each listed config with: import { defineVitestConfig } from '@williamthorsen/nmr/vitest'; export default defineVitestConfig(); -- a config that does not call the factory declares no projects, so every tier-selecting test command fails against it. Pass your own settings to the factory as layers to keep them"
+          fix: "Replace each listed config with: import { defineVitestConfig } from '@williamthorsen/nmr/vitest'; export default defineVitestConfig(); -- a config that does not call the factory does not declare any projects, so every tier-selecting test command fails against it. Pass the repo's own settings to the factory as layers to keep them"
         },
         {
           name: "vitest.root.config.ts builds on @williamthorsen/nmr/vitest",
@@ -310,27 +325,27 @@ var default_default = defineRdyKit({
           name: "every workspace with a Vite config has a Vitest config",
           severity: "error",
           check: () => everyViteConfigHasVitestConfig(),
-          fix: "Add a vitest.config.ts calling defineVitestConfig() from @williamthorsen/nmr/vitest beside each listed vite.config -- Vitest stops its config search at the first directory holding either name, so the Vite config otherwise wins and the projects model is never reached"
+          fix: "Add a vitest.config.ts calling defineVitestConfig() from @williamthorsen/nmr/vitest beside each listed vite.config -- Vitest stops its config search at the first directory containing either name, so the Vite config otherwise wins and the projects model is never reached"
         },
         {
           name: "the test suite gates the test-file conventions",
           severity: "warn",
           check: () => testSuiteGatesTestFileConventions(),
-          fix: "Add a test of the repo's own under a __tests__ directory that declares the check: import { checkTestFileConventions } from '@williamthorsen/nmr/tests'; checkTestFileConventions(); -- passing `excludedBasenames` the directory names that the repo passes to `testCollectionExclude`. Without it no test run reports an untiered or misplaced test file, and this kit reports them in its place against nmr's built-in exclusions alone"
+          fix: "Add a test of the repo's own under a __tests__ directory that declares the check: import { checkTestFileConventions } from '@williamthorsen/nmr/tests'; checkTestFileConventions(); -- passing `excludedBasenames` the directory names that the repo passes to `testCollectionExclude`. Without it, the repo's test run does not report an untiered or misplaced test file, and this kit reports them in its place against only nmr's built-in exclusions and the paths that git ignores"
         },
         {
           name: "every test file names its isolation tier",
           severity: "error",
           skip: () => describeConventionsGuardSkip(),
           check: () => everyTestFileNamesItsTier(),
-          fix: `Rename each to <subject>[.<aspect>].<tier>.test.ts, naming one of ${TIER_NAMES.join(", ")}. Use tool for a test that reaches a program the environment supplies, which is where a retired .int. or .integration. file belongs. Only the segment before .test. selects a project, so an untiered file runs under the residual unit project and reports success`
+          fix: `Rename each to <subject>[.<aspect>].<tier>.test.ts, naming one of ${TIER_NAMES.join(", ")}. Use tool for a test that reaches a program supplied by the environment, which is the tier for a retired .int. or .integration. file. Only the segment before .test. selects a project, so an untiered file runs under the residual unit project and reports success`
         },
         {
-          name: "every test file sits under a __tests__ directory",
+          name: "every test file is under a __tests__ directory",
           severity: "error",
           skip: () => describeConventionsGuardSkip(),
           check: () => everyTestFileSitsUnderTestsDir(),
-          fix: "Move each into a __tests__ directory, the only place from which the shared Vitest config collects. No project collects a file outside one, so it runs nowhere and reports nothing. For a file that is not a test, declare checkTestFileConventions with its directory in `excludedBasenames` instead, which this check then defers to"
+          fix: "Move each into a __tests__ directory, the only place from which the shared Vitest config collects. Vitest does not collect a file outside one, so it runs nowhere and reports nothing. For a file that is not a test, declare checkTestFileConventions with its directory in `excludedBasenames` instead, which this check then defers to"
         },
         {
           name: "no package re-exports the ancestor Vitest config",
@@ -351,14 +366,14 @@ var default_default = defineRdyKit({
           name: "taze.config.ts builds on @williamthorsen/nmr/taze",
           severity: "warn",
           check: () => tazeConfigBuildsOnSharedConfig(),
-          fix: "Replace the taze config with: import { defineConfig } from '@williamthorsen/nmr/taze'; export default defineConfig(); \u2014 nmr's upgrade policy reaches a repo only through this file, so without it `nmr upgrade` reports nothing where dependencies are pinned to exact versions"
+          fix: "Replace the taze config with: import { defineConfig } from '@williamthorsen/nmr/taze'; export default defineConfig(); -- nmr's upgrade policy applies to a repo only through this file, so without it `nmr upgrade` does not report a dependency pinned to an exact version"
         },
         {
           name: "taze config declares no option taze discards",
           severity: "warn",
           quiet: true,
           check: () => tazeConfigAvoidsClobberedOptions(),
-          fix: "Set these through the upgrade script instead, as rootScripts: { upgrade: 'nmr-report-overrides && nmr-taze --recursive --request-timeout 90000' } in .config/nmr.config.ts, keeping the rest of the default script \u2014 taze's CLI writes a default for each of them over whatever the config file declares, so the value there never reaches taze (antfu-collective/taze#317). nmr already forwards a 30-second request timeout"
+          fix: "Set these through the upgrade script instead, as rootScripts: { upgrade: 'nmr-report-overrides && nmr-taze --recursive --request-timeout 90000' } in .config/nmr.config.ts, keeping the rest of the default script. taze's CLI writes a default for each of them over whatever the config file declares, so taze never uses the file's value (antfu-collective/taze#317). nmr already forwards a 30-second request timeout"
         },
         // -- Audit dependency --------------------------------------------------------
         {
@@ -373,7 +388,7 @@ var default_default = defineRdyKit({
           severity: "error",
           quiet: true,
           check: () => !fileExists("scripts/run-workspace-script.ts"),
-          fix: "Delete scripts/run-workspace-script.ts \u2014 nmr replaces this custom script runner"
+          fix: "Delete scripts/run-workspace-script.ts, because nmr replaces this custom script runner"
         },
         {
           name: 'no workspace packages reference run-workspace-script or "pnpm run ws"',
@@ -481,9 +496,9 @@ function prettierConfigBuildsOnSharedConfig(cwd = process.cwd()) {
 }
 function describeMissingPrettierConfig(cwd) {
   const inertConfigs = findFiles(INERT_PRETTIER_CONFIGS, cwd);
-  if (inertConfigs.length > 0) return `holds no code to call the factory: ${inertConfigs.join(", ")}`;
+  if (inertConfigs.length > 0) return `does not contain code that calls the factory: ${inertConfigs.join(", ")}`;
   if (hasPrettierConfigKey(cwd)) {
-    return 'holds no code to call the factory: the "prettier" key in package.json';
+    return 'does not contain code that calls the factory: the "prettier" key in package.json';
   }
   return ".prettierrc.js is missing";
 }
@@ -602,7 +617,7 @@ function formatPaths(paths) {
 ${paths.map((path2) => `      ${path2}`).join("\n")}`;
 }
 function getMinVersion() {
-  const pickedFields = { "version": "0.39.0" };
+  const pickedFields = { "version": "0.41.0" };
   if (typeof pickedFields["version"] !== "string") {
     throw new TypeError("nmr/package.json: 'version' must be a string");
   }
@@ -754,14 +769,14 @@ function tazeConfigAvoidsClobberedOptions(cwd = process.cwd()) {
 }
 function describeMissingTazeConfig(cwd) {
   const inertConfigs = findFiles(INERT_TAZE_CONFIGS, cwd);
-  if (inertConfigs.length > 0) return `holds no code to call the factory: ${inertConfigs.join(", ")}`;
+  if (inertConfigs.length > 0) return `does not contain code that calls the factory: ${inertConfigs.join(", ")}`;
   return "taze.config.ts is missing";
 }
 function testSuiteGatesTestFileConventions(cwd = process.cwd()) {
   if (findConventionsGuard(cwd) !== void 0) return true;
   return {
     ok: false,
-    detail: `no test file under __tests__ imports checkTestFileConventions from ${SHARED_TESTS_MODULE}`
+    detail: `the test files under __tests__ do not import checkTestFileConventions from ${SHARED_TESTS_MODULE}`
   };
 }
 function describeConventionsGuardSkip() {

package/.readyup/manifest.json

@@ -11,12 +11,12 @@
       "esbuildVersion": "0.28.2",
       "inputs": [
         {
-          "hash": "0ae7745f",
+          "hash": "5f7bd316",
           "kind": "module",
           "path": "kits/default.ts"
         },
         {
-          "hash": "30230373",
+          "hash": "00e9a998",
           "kind": "inline",
           "path": "../package.json",
           "paths": [
@@ -24,17 +24,22 @@
           ]
         },
         {
-          "hash": "06bffeed",
+          "hash": "9336f4c0",
           "kind": "module",
           "path": "../src/default-scripts.ts"
         },
         {
-          "hash": "c53d0c51",
+          "hash": "d4828172",
+          "kind": "module",
+          "path": "../src/git-ignored-paths.ts"
+        },
+        {
+          "hash": "23646439",
           "kind": "module",
           "path": "../src/resolve-scripts.ts"
         },
         {
-          "hash": "beb92e94",
+          "hash": "19dec003",
           "kind": "module",
           "path": "../src/tiers.ts"
         }
@@ -43,8 +48,8 @@
       "path": "kits/default.js",
       "readyupVersion": "0.38.0",
       "source": "kits/default.ts",
-      "sourceHash": "0ae7745f",
-      "targetHash": "06f47835"
+      "sourceHash": "5f7bd316",
+      "targetHash": "69936c4f"
     }
   ]
 }

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.41.0 — 2026-10-02
+
+### 🎉 Features
+
+- Adds a hint to `nmr` that, when a command fails, names any of nmr's own flags written after the command name and shows the corrected invocation, such as `nmr -q check`. (#956)
+
+## 0.40.0 — 2026-10-01
+
+### 🎉 Features
+
+- Makes `checkTestFileConventions` and the readyup kit's tier and placement checks skip untracked paths that git ignores, so that local build output such as a stale `.netlify/` directory no longer fails the check. (#898)
+- Excludes untracked paths that git ignores from collection in `defineVitestConfig` and `defineRootVitestConfig`, so that Vitest does not run a test file that the conventions check skips. (#898)
+- Rewords the `nmr --log` refusal for a run that the check-result cache does not cover to `the check-result cache does not apply here (NMR_DEBUG=1 reports why)`, and renames the matching `docs/check-cache.md` heading to "When the cache does not apply", which changes its anchor. (#923)
+
+### 🐛 Bug fixes
+
+- Rewords the messages printed by `nmr`, its bin wrappers, and its readyup kit, which used figures such as "sits under" and "holds", em-dashes, and "no" as a determiner, so that a diagnosis such as "-F/--filter did not match any workspace" states its condition directly. (#932)
+- Fixes the issue that the `nmr` rulebook recommended `-q` without stating that nmr reads its own flags only before the command name, which led agents to run `nmr ci -q` and fail when `nmr-fmt` rejected the flag. (#948)
+
+### ♻️ Refactoring
+
+- Replaces every `.sort()` call that suppressed `unicorn/no-array-sort` with `toSorted()` and drops the spread copy wherever the source was already an array. (#925)
+
+### 🧪 Tests
+
+- Stubs `GIT_CEILING_DIRECTORIES` to the fixture's parent in every test that expects git to find no repository, so that a repository above the temp directory can no longer change the test's result. (#923)
+- Moves the `everyBinTargetIsACommittedWrapper` tests from `kit-bin-checks.unit.test.ts` to `kit-bin-checks.tool.test.ts`, because they spawn git through readyup's `listTrackedFiles`. (#923)
+
+### ⚙️ Tooling
+
+- Adds a check to `bootstrap.tool.test.ts` that fails when a package's `prepare` runs the build bootstrap without either depending on nmr-core or passing `--conditions nmr-source`, which would make `pnpm install` fail on a fresh clone. (#903)
+
+### 📦 Dependencies
+
+- Adds `esbuild` 0.28.2 to the pnpm catalog and declares it as a devDependency of `nmr`, `release-kit`, and `v11y-check`, because `readyup` declares it only as an optional peer and `rdy compile` failed in those packages once a regenerated lockfile stopped installing it. (#944)
+
+### 📚 Documentation
+
+- Revises the comments in `packages/nmr/src` and `packages/nmr/.readyup/kits/default.ts` against the comment-discipline rules, correcting comments that misstated the code, such as the Levenshtein distance quoted in `runCli.ts` and a `root-tests-config` kit check that does not exist. (#919)
+- Corrects the truncation example in `packages/nmr/docs/reporting.md`, replacing 90 seconds, which renders as `1m 30s` whether it is truncated or rounded, with 119.9 seconds, which truncates to `1m 59s`. (#919)
+- Rewrites the sentences in the README, the guides under `docs/`, the agent rulebook, and the code comments of `@williamthorsen/nmr` that broke the repository's writing rules on plain speech, em-dashes, second-person address, and relative clauses. (#932)
+- Replaces "where" in two doc comments in `packages/nmr/src/check-cache.ts` and in the fixture comment in two tier-budget tests, because each use introduced a consequence rather than a place. (#945)
+- Writes `-q` as `nmr -q <command>` in `docs/reporting.md` and in the README's verbosity paragraph. (#948)
+
 ## 0.39.0 — 2026-09-22
 
 ### 🎉 Features