@descent-vtt/spec-brief 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -11,6 +11,28 @@ release that can turn a run red. This is the family's policy, recorded in
 releases up to 0.2.7 came before it, and several of their patches changed
 what a run reports.
 
+## 0.5.1
+
+The README's commands gave `npx` the command's bare name, which on npm is
+not this project's package. spec-brief 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-brief ...`.
+  `spec-brief` 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`, a CI job with no install step.
+  The CI examples install first, and [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 a CI job or a script gives `npx` the command's name
+  alone, write `npx --no-install @descent-vtt/spec-brief`. `--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.
+
 ## 0.5.0
 
 Five defects a reading of every surviving mutant found, none of which a test

package/README.md

@@ -8,11 +8,23 @@ spec-brief is one of the [spec-\* tools](https://github.com/DescentVTT/spec-core
 
 ```bash
 npm install --save-dev @descent-vtt/spec-brief
-npx spec-brief init
-npx spec-brief new "Rotate session tokens on privilege change" --wave 1
-npx spec-brief lint
+npx --no-install @descent-vtt/spec-brief init
+npx --no-install @descent-vtt/spec-brief new "Rotate session tokens on privilege change" --wave 1
+npx --no-install @descent-vtt/spec-brief lint
 ```
 
+## Names
+
+The package is `@descent-vtt/spec-brief`, and the command it installs is `spec-brief`. The name without the scope is not this project: on npm, `spec-brief` 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-brief` 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-brief`, 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-brief`, and not `npx --no-install spec-brief` 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. A `package.json` script names the command alone, as in `"briefs": "spec-brief lint"`, because npm fetches nothing for a script. 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.
+
 ## Why
 
 Repositories that run agents on briefs end up doing the same ceremony by hand, and getting it wrong in the same places:
@@ -357,12 +369,16 @@ How a heading fills a section, and what counts as a heading, a task or a link, i
 
 ## In CI
 
+After the job has installed the project, with `npm ci`:
+
 ```yaml
-- run: npx spec-brief lint --format github
-- run: npx spec-brief matrix --format github
-- run: npx spec-brief schedule --format github
+- run: npx --no-install @descent-vtt/spec-brief lint --format github
+- run: npx --no-install @descent-vtt/spec-brief matrix --format github
+- run: npx --no-install @descent-vtt/spec-brief schedule --format github
 ```
 
+Each gives `npx` the package's [full name](#names) and `--no-install`: a job that lost its install step then stops, where the command's name alone would fetch whatever package has that name.
+
 | Format | What it writes |
 | --- | --- |
 | `github` | Workflow commands, which annotate the pull request with no upload and no permission. |
@@ -372,7 +388,9 @@ How a heading fills a section, and what counts as a heading, a task or a link, i
 
 ```yaml
 spec-brief:
-  script: npx spec-brief lint --format gitlab > gl-code-quality.json
+  script:
+    - npm ci
+    - npx --no-install @descent-vtt/spec-brief lint --format gitlab > gl-code-quality.json
   artifacts:
     reports:
       codequality: gl-code-quality.json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@descent-vtt/spec-brief",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Lifecycle management for task briefs: lint the contract, map parallel collisions, and archive a round in one atomic command.",
   "keywords": [
     "agents",