@descent-vtt/spec-guard 0.19.0 → 0.19.1

package/CHANGELOG.md

@@ -10,6 +10,40 @@ what to do when upgrading; the family's policy, including how a flag or field
 is deprecated before it goes, is spec-core's
 [ADR-0009](https://github.com/DescentVTT/spec-core/blob/main/docs/adr/0009-versions-before-1-0.md).
 
+## 0.19.1
+
+The README's commands gave `npx` the command's bare name, which on npm is
+not this project's package. spec-guard itself is unchanged.
+
+### Security
+
+- Every command in the README gives `npx` the package's full name behind
+  `--no-install`, as in `npx --no-install @descent-vtt/spec-guard ...`.
+  `spec-guard` without the scope belongs to nobody on npm (2026-10-07), so
+  anyone can register it.
+  `npx` given a name the project has not installed fetches the package of
+  that name and runs it, unasked when no terminal is attached: a fresh
+  clone, a worktree before `npm ci`, and the `mcpServers` entry the README
+  showed, which an MCP client starts with no terminal, wherever it stands.
+  [Names](README.md#names) says whose the names are; what was measured is in
+  the family's
+  [adopting guide](https://github.com/DescentVTT/spec-core/blob/main/docs/adopting.md#names).
+  Upgrading: where an `.mcp.json`, a hook, a CI job or a script gives `npx`
+  the command's name alone, write `npx --no-install @descent-vtt/spec-guard`;
+  in an MCP entry that is
+  `"args": ["--no-install", "@descent-vtt/spec-guard", "mcp", ...]`.
+  `--no-install` before the bare name is not enough: npm still runs a copy
+  of that name's package an earlier fetch left in its cache.
+
+### Documentation
+
+- The CI examples install the project and then run
+  `npx --no-install @descent-vtt/spec-guard`, as the family's adopting guide
+  has them. They ran `npx @descent-vtt/spec-guard` with no install, which
+  fetched whatever release was latest when the job ran; the lockfile now
+  pins it, as the same examples pin their actions to commits. A job written
+  the old way keeps working.
+
 ## 0.19.0
 
 An engine named `constructor` or `__proto__` is refused as any unknown

package/README.md

@@ -51,23 +51,11 @@ build with a line number, not a landmine.
 
 ```bash
 npm install --save-dev @descent-vtt/spec-guard
-npx spec-guard "docs/**/*.md"
+npx --no-install @descent-vtt/spec-guard "docs/**/*.md"
 ```
 
-**The package is scoped; the command is not.** Once installed, the binary is
-plain `spec-guard`, so `npx spec-guard`, `npm scripts` and a global install all
-use that name:
-
-```bash
-npm install -g @descent-vtt/spec-guard   # then: spec-guard "docs/**/*.md"
-```
-
-Without a local install, `npx` needs the full package name - `npx spec-guard`
-on its own would resolve to a different package on the registry:
-
-```bash
-npx @descent-vtt/spec-guard "docs/**/*.md"
-```
+`npx` is given the package's full name, here and in every command below:
+[Names](#names) says why the command's name alone is not written.
 
 Add a directive to any Markdown file, directly under the sentence it makes
 executable:
@@ -83,7 +71,7 @@ Session state has exactly one owner.
 Run it:
 
 ```bash
-npx spec-guard "docs/**/*.md" --verbose
+npx --no-install @descent-vtt/spec-guard "docs/**/*.md" --verbose
 ```
 
 ```text
@@ -110,6 +98,38 @@ And when it drifts:
 
 Exit code 1. The ADR is now a test.
 
+## Names
+
+The package is `@descent-vtt/spec-guard`, and the command it installs is
+`spec-guard`. The name without the scope is not this project: on npm,
+`spec-guard` belonged to nobody on 2026-10-07, and whoever registers it decides
+what it runs.
+
+`npx` fetches and runs the package of whatever name it is given when the
+project has none installed - a fresh clone, a worktree before `npm ci`, a CI job
+without the install step - and without a terminal it does not ask first. So
+give `npx` the full name:
+
+- `npx --no-install @descent-vtt/spec-guard` in a project that installed it: it
+  runs that install, the version the lockfile pins, and where there is none it
+  stops with an error that names this package.
+- `npx @descent-vtt/spec-guard`, without `--no-install`, where nothing is
+  installed: it fetches this package and runs it.
+
+<!-- bare-name: the two forms in the next sentence are shown as what not to write -->
+Never `npx spec-guard`, and not `npx --no-install spec-guard` either:
+`--no-install` stops a download, and npm still runs a copy of the bare name's
+package that an earlier fetch left in its cache. The family's
+[adopting guide](https://github.com/DescentVTT/spec-core/blob/main/docs/adopting.md#names)
+has what was measured, under npm 10, 11 and 12.
+
+The command alone, `spec-guard`, is what a `package.json` script holds - npm
+fetches nothing for a script - and what a global install puts on the path:
+
+```bash
+npm install -g @descent-vtt/spec-guard   # then: spec-guard "docs/**/*.md"
+```
+
 ## Directives
 
 Every directive is an HTML comment. It may span multiple lines. Attribute values
@@ -1015,12 +1035,16 @@ usual `mcpServers` entry is:
   "mcpServers": {
     "spec-guard": {
       "command": "npx",
-      "args": ["spec-guard", "mcp", "--spec", "docs/**/*.md"]
+      "args": ["--no-install", "@descent-vtt/spec-guard", "mcp", "--spec", "docs/**/*.md"]
     }
   }
 }
 ```
 
+A client starts a server with no terminal, wherever it stands, so the entry
+gives `npx` the package's [full name](#names) behind `--no-install`: in a tree
+without the install the server fails to start, and nothing is fetched.
+
 The root defaults to the directory the client starts the server in; pass
 `--root` if yours starts servers somewhere else. On Windows, `npx` is a `.cmd`
 script that a client spawning without a shell cannot launch; point `command` at
@@ -1432,13 +1456,21 @@ jobs:
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: '22'
-      - run: npx @descent-vtt/spec-guard "docs/**/*.md" "README.md" --verbose
+      - run: npm ci
+      - run: npx --no-install @descent-vtt/spec-guard "docs/**/*.md" "README.md" --verbose
 ```
 
 The actions are pinned to commits, with the version beside each, because a tag
 can be moved and a commit cannot; Dependabot's `github-actions` updates keep
 pins like these current.
 
+spec-guard is pinned the same way, by the lockfile: `npm ci` installs the
+version it names, and `--no-install` behind the package's [full name](#names)
+stops the job where that install is missing, rather than fetching another. A
+repository with no JavaScript of its own keeps a `package.json` with
+`"private": true` and spec-guard as its only `devDependencies` entry, and
+commits the lockfile.
+
 That job needs nothing else installed. GitHub-hosted runners do **not** ship
 ripgrep on `PATH` - spec-guard's own CI reports `engine: javascript` there - so
 the fallback is what actually runs, and it produces identical results. If your
@@ -1464,10 +1496,10 @@ default `--engine auto`, a binary that cannot be run leaves the built-in
 scanner to do the work, and the report's engine says `javascript`; under
 `--engine rg` it is exit 2.
 
-As a pre-commit hook (assuming a local install, so the bare command resolves):
+As a pre-commit hook, in a project that installed it:
 
 ```bash
-npx spec-guard "docs/**/*.md" --fail-fast
+npx --no-install @descent-vtt/spec-guard "docs/**/*.md" --fail-fast
 ```
 
 ### Annotations on the pull request
@@ -1481,8 +1513,8 @@ comment on the offending line:
       security-events: write
       actions: read # only in a private repository
     steps:
-      # ...checkout and setup-node as above
-      - run: npx @descent-vtt/spec-guard "docs/**/*.md" --format sarif > spec-guard.sarif || true
+      # ...checkout, setup-node and npm ci as above
+      - run: npx --no-install @descent-vtt/spec-guard "docs/**/*.md" --format sarif > spec-guard.sarif || true
       - uses: github/codeql-action/upload-sarif@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
         with:
           sarif_file: spec-guard.sarif
@@ -1518,7 +1550,8 @@ which a merge request shows beside its changes:
 ```yaml
 spec-guard:
   script:
-    - npx @descent-vtt/spec-guard --format gitlab > gl-code-quality-report.json || true
+    - npm ci
+    - npx --no-install @descent-vtt/spec-guard --format gitlab > gl-code-quality-report.json || true
   artifacts:
     reports:
       codequality: gl-code-quality-report.json
@@ -1808,7 +1841,7 @@ fail, and `spec-guard cites` holds every ADR a comment in the code cites to
 existing and being in force.
 
 Line coverage is 100%, CI's full mutation sweep kills 99.14% of 12,333 mutants
-(0.19.0), and every survivor a release adds is replayed before it ships
+(0.19.1), and every survivor a release adds is replayed before it ships
 ([ADR-0003](https://github.com/DescentVTT/spec-guard/blob/main/docs/adr/0003-mutation-testing.md));
 [CONTRIBUTING.md](https://github.com/DescentVTT/spec-guard/blob/main/CONTRIBUTING.md)
 has how to build, test and release, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@descent-vtt/spec-guard",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "description": "Executable architecture assertions for Markdown specs & ADRs.",
   "keywords": [
     "adr",