@descent-vtt/spec-brief 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -11,6 +11,92 @@ 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.11.0
+
+A template, a plugin, or what stands where `archive` or `unarchive`
+would write a brief is read only where it is a file, or a link to one:
+a named pipe there had a run wait without end, and a directory or a
+socket ended it on a stack. Each is now refused, exit 2, before it is
+opened.
+
+### Changed
+
+- **A template, a plugin, or what stands where a brief would move, is read
+  only where it is a file.** A named pipe as the `template`, where
+  `archive` or `unarchive` would write the brief, or as a plugin's module or
+  the `package.json` its package is found by, had the run wait without end;
+  a link to `/dev/null` as the template wrote a brief of no bytes; a
+  directory or a socket ended the run on Node's error and a stack. Each is
+  now exit 2 with one line before it is opened, nothing written, as a
+  configuration has been since 0.10.0. A link is read as what it names
+  ([An input that names nothing](README.md#an-input-that-names-nothing);
+  ADR-0003, amended 2026-10-24). Upgrading: nothing to change where each is
+  a file, or a link to one; a template that is a link to `/dev/null` now
+  refuses, so point `template` at a file, or set it to `null`.
+
+## 0.10.0
+
+One value written two ways is taken once in three more cases, each of
+which was refused as two values: a drive letter in either case on
+Windows, two revisions git says name one commit, and two lists that name
+the same briefs. Nothing that ran is refused.
+
+`list --format json` names what its answer was read from, so that another
+tool can give the answer again without starting spec-brief. A
+configuration that is not a file is refused, exit 2, where a named pipe
+under its name was read without end.
+
+### Fixed
+
+- **A drive letter names its volume in either case.** On Windows
+  `--root C:\x` beside `--root c:\x`, and two `--config` values the same
+  way, were refused as two directories; each is taken once. The rest of a
+  path is compared as it resolves, so `C:\x` beside `C:\X` is still two
+  ([An option given two values](README.md#an-option-given-two-values);
+  [the family contract](https://github.com/DescentVTT/spec-core/blob/main/docs/adr/0005-the-family-contract.md),
+  amended 2026-10-19).
+- **A revision written two ways is asked of git.** `--commit HEAD` beside
+  the hash it names, or `--base main` beside the commit `main` is at, was
+  refused as two values. `archive` now asks git once what commit each
+  names, and takes two that name one as one. Two that name two commits,
+  one git cannot name, and any line with `--no-git`, `--help` or
+  `--version`, none of which asks git, are refused as they were
+  (ADR-0001, amended 2026-10-19).
+- **`--depends-on` is read as the set of ids it names**, each as a brief's
+  id is matched: `7,8` beside `8,7`, `7` beside `007` and `7,8` beside
+  `7,8,7` are taken once, and the brief is written with the later as
+  given. A list that names another brief, or one fewer, is still two
+  values.
+
+### Added
+
+- **`list --format json` names its inputs**, in a field `inputs`: each
+  file the answer was read from, with the SHA-256 of its bytes; each name a
+  configuration was looked for under and was not there, with `null`; each
+  directory the briefs were listed from, with the files in it, or `null`
+  where there was none, as an archive not yet made; and the version that
+  read them. `keep` is `false`, and nothing is listed, wherever that
+  cannot be named whole: a run that starts below its configuration's
+  directory, and one with no configuration file
+  ([`spec-brief list`](README.md#spec-brief-list); ADR-0002, amended
+  2026-10-19). `schemaVersion` stays 2, since a field is added and none
+  changes. `list` asks git nothing where a configuration file names the
+  root, which is a process fewer.
+
+### Changed
+
+- **A configuration that is not a file is refused.** A named pipe at
+  `.spec-brief.json` or `spec-brief.json`, or named by `--config`, was read
+  without end by every command; a socket ended the run on `ENXIO` and a
+  stack, and `--config /dev/zero` on `RangeError`. Each is now exit 2 with
+  one line, `is neither a file nor a directory, not a configuration file`,
+  before it is opened, as a directory was already. A link is read as what
+  it names ([An input that names nothing](README.md#an-input-that-names-nothing);
+  ADR-0003, amended 2026-10-19). Upgrading: nothing to change for a
+  configuration that is a file; `--config <(...)`, which a shell hands as a
+  pipe, ran in `/dev/fd` and found no briefs, and now says what it was
+  handed.
+
 ## 0.9.0
 
 An option that takes one value and is given two is refused, exit 2, where

package/README.md

@@ -126,7 +126,32 @@ Live briefs with their status, in the word the brief writes (`封存` where the
 | --- | --- |
 | `--ready` | Only the ready briefs, which is the question an orchestrator asks. |
 | `--archived` | The archive as well. |
-| `--format json` | The whole table, for an orchestrator, and the sections the configuration asks for, each with its `hint`. |
+| `--format json` | The whole table, for an orchestrator, the sections the configuration asks for, each with its `hint`, and what the answer was read from. |
+
+**What the answer was read from.** `--format json` names, under `inputs`, every input of its answer, so that a tool that asks for the same answer again, as spec-harness does before each write it checks, can give the one it kept while every input reads as listed, without starting spec-brief ([the family contract](https://github.com/DescentVTT/spec-core/blob/main/docs/adr/0005-the-family-contract.md), amended 2026-10-19):
+
+```json
+"inputs": {
+  "keep": true,
+  "tool": "0.10.0",
+  "files": [
+    { "path": ".spec-brief.json", "sha256": "ca3d163b..." },
+    { "path": "briefs/001_a.md", "sha256": "5ee9361a..." },
+    { "path": "spec-brief.json", "sha256": null }
+  ],
+  "directories": [
+    { "path": "briefs", "entries": ["001_a.md", "README.md"] },
+    { "path": "briefs/archive", "entries": null }
+  ],
+  "git": null
+}
+```
+
+- **`files`**: each file read, with the SHA-256 of its bytes in hex, and each name a configuration was looked for under and was not there, with `null`: it must still not be there.
+- **`directories`**: each directory the briefs were listed from, with the names of the regular files directly in it, sorted as JavaScript sorts strings. A link and a directory are no file here, and a file that is no brief is named though it is not read, since one renamed would be. A directory looked for and not found, as an archive not yet made, has `null`: there must still be no directory there.
+- **`tool`**: the version that read them. **`git`**: `null`, since `list` reads nothing of git, and asks it nothing where a configuration file names the root.
+- **Paths** are POSIX, from the root, which wherever `keep` is `true` is the directory the run started in.
+- **`keep` is `false`**, and the lists are empty, wherever spec-brief cannot name every input: a run that starts below its configuration's directory, or names a configuration in another, and one with no configuration file, where git or the search above the root finds the root.
 
 ### `spec-brief matrix`
 
@@ -280,7 +305,8 @@ An option, an argument or a path that is given and names nothing is refused: exi
 - **A list that names nothing.** `--depends-on ,` names no brief, and a brief that depends on nothing is one scaffolded without the option. A place in a list that names no brief, the comma too many in `7,8,` or the gap in `7,,8`, is refused as well: it is a brief left out, as `"$A,$B"` is with one of the two unset.
 - **An argument a command does not take.** `init`, `list`, `matrix` and `schedule` take none and refuse one by name, with their usage. `init mydir` set up the current directory; `init --root mydir` is what sets up another.
 - **A `--root` that is no directory.** A file, or a path that does not exist, is refused: the search for a configuration would go on from its parent, and the run would report on, or `new` write into, the tree above. A directory below the configuration's is a place to start from, as the current directory is.
-- **A configuration that is a directory**, named by `--config` or found under the configuration's name, does not load, and is said so in a line, as one that is not JSON is.
+- **A configuration that is not a file**, named by `--config` or found under the configuration's name, does not load, and is said so in a line before it is opened, as one that is not JSON is: a directory, a named pipe, which was read without end, a socket or a device. A link is read as what it names.
+- **A template, a plugin or what stands where a brief would move that is not a file** is refused in a line before it is opened, and nothing is written: the `template` a configuration names, a plugin's module and each `package.json` spec-brief reads to find one, and what stands where `archive` or `unarchive` would write the brief, which a plan made from the files a listing names cannot have seen. A named pipe there had the run wait without end, a link to `/dev/null` as the template wrote a brief of no bytes, and a directory or a socket ended the run on a stack. A link is read as what it names.
 
 ### An option a command does not read
 
@@ -309,8 +335,8 @@ An option that takes one value is given one. Given two that read as two, the run
 spec-brief: --root is given "nowhere" and ".", and takes one value; give one of the two
 ```
 
-- **One value given twice is taken once, however it is written.** Two values are compared as each is read: `--root` and `--config` as the paths they resolve to, so `--root .` beside `--root ./`; `--briefs` and `--archive` as directories of the repository, so `specs` beside `./specs/`; `--wave` and `--pr` by the number their digits write, so `1` beside `01`; `--depends-on` by its ids in their order, so `7,8` beside `7, 8`; `--summary` with the spaces around it taken off. Any other value is read as it is written, in its own case.
-- **A revision written two ways is two values**: `--commit HEAD` beside the hash it names, since only git can say they are one, and the line is checked before git is asked anything.
+- **One value given twice is taken once, however it is written.** Two values are compared as each is read: `--root` and `--config` as the paths they resolve to, so `--root .` beside `--root ./`, and on Windows with the drive letter in either case, so `C:\x` beside `c:\x`, where `C:\x` beside `C:\X` is two; `--briefs` and `--archive` as directories of the repository, so `specs` beside `./specs/`; `--wave` and `--pr` by the number their digits write, so `1` beside `01`; `--depends-on` by the set of ids it names, each as an id is matched to a brief, so `7,8` beside `8,7` or `7, 8`, and `7` beside `007`, and the brief is written with the later; `--summary` with the spaces around it taken off. Any other value is read as it is written, in its own case.
+- **A revision written two ways is asked of git**: `archive` asks git once what commit each value of `--commit`, or of `--base`, names, and takes `HEAD` beside the hash it names as one value. Two that name two commits, or one git cannot name, are two values; so are any two beside `--no-git`, `--help` or `--version`, none of which asks git.
 - **Every option that takes a value takes one.** `--depends-on` is a list written in one value, and no option adds to a list each time it is given. A flag given twice is that flag once.
 - A shell alias or a script that gives an option, and a line that gives it again to override it, is refused: give the option once.
 
@@ -336,7 +362,7 @@ spec-brief: --help is given beside --version, and one of the two answers would g
 
 ## Configuration
 
-`.spec-brief.json` (or `spec-brief.json`) at the root; the nearest one above the working directory is used, and its directory is the root. It is JSON, validated against [`schema.json`](schema.json): an unknown key, a misspelt rule or a value of the wrong type stops the run with exit 2 rather than falling back to defaults and reporting on the wrong rules.
+`.spec-brief.json` (or `spec-brief.json`) at the root; the nearest one above the working directory is used, and its directory is the root. It is a file, and JSON, validated against [`schema.json`](schema.json): an unknown key, a misspelt rule or a value of the wrong type stops the run with exit 2 rather than falling back to defaults and reporting on the wrong rules.
 
 | Key | Default | What it says |
 | --- | --- | --- |

package/dist/apply.d.ts

@@ -12,10 +12,11 @@
  * which `lint` reports by name.
  */
 import type { FileOp } from './archive.js';
-import type { FileSystem } from './fs.js';
+import { type FileSystem, type NotAFile } from './fs.js';
 export declare class ConflictError extends Error {
     readonly path: string;
-    constructor(path: string);
+    /** `found` is what stands at the path where it is not a file, which is not read. */
+    constructor(path: string, found?: NotAFile);
 }
 export declare class TransactionError extends Error {
     /** Whether every completed operation was undone. */

package/dist/apply.js

@@ -11,10 +11,14 @@
  * operation and the last, and a crash inside it leaves two briefs with one id,
  * which `lint` reports by name.
  */
+import { NotAFileError } from './fs.js';
 export class ConflictError extends Error {
     path;
-    constructor(path) {
-        super(`${path} changed after the plan was made; nothing was written. Run the command again.`);
+    /** `found` is what stands at the path where it is not a file, which is not read. */
+    constructor(path, found) {
+        super(found === undefined
+            ? `${path} changed after the plan was made; nothing was written. Run the command again.`
+            : `${path} is ${found}; nothing was written. Move it out of the way, then run the command again.`);
         this.name = 'ConflictError';
         this.path = path;
     }
@@ -35,7 +39,12 @@ export class TransactionError extends Error {
 }
 export async function applyPlan(fs, ops) {
     for (const op of ops) {
-        const current = await fs.read(op.path);
+        const current = await fs.read(op.path).catch((error) => {
+            // A plan is made from the files a listing names, so what stands where
+            // it would write a new one can be a named pipe, read without end, or a
+            // directory. Nothing is written yet, and the refusal can say so.
+            throw error instanceof NotAFileError ? new ConflictError(op.path, error.what) : error;
+        });
         if (current !== op.before)
             throw new ConflictError(op.path);
     }

package/dist/apply.js.map

@@ -1 +1 @@
-{"version":3,"file":"apply.js","sourceRoot":"","sources":["../src/apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,MAAM,OAAO,aAAc,SAAQ,KAAK;IAC7B,IAAI,CAAS;IAEtB,YAAY,IAAY;QACtB,KAAK,CAAC,GAAG,IAAI,+EAA+E,CAAC,CAAC;QAC9F,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACzC,oDAAoD;IAC3C,UAAU,CAAU;IACpB,QAAQ,CAAoB;IAErC,YAAY,KAAc,EAAE,UAAmB,EAAE,QAA2B;QAC1E,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtE,KAAK,CACH,UAAU;YACR,CAAC,CAAC,GAAG,MAAM,gCAAgC;YAC3C,CAAC,CAAC,GAAG,MAAM,+BAA+B,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,iCAAiC,CACjG,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAED,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,EAAc,EAAE,GAAsB;IACpE,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;QACrB,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,OAAO,KAAK,EAAE,CAAC,MAAM;YAAE,MAAM,IAAI,aAAa,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;IAC9D,CAAC;IAED,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,IAAI,CAAC;QACH,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;YACrB,IAAI,EAAE,CAAC,IAAI,KAAK,OAAO;gBAAE,MAAM,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC;;gBACxD,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;YAC9B,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAChB,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,KAAK,MAAM,EAAE,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;YACrC,oEAAoE;YACpE,mEAAmE;YACnE,iBAAiB;YACjB,IAAI,CAAC;gBACH,IAAI,EAAE,CAAC,MAAM,KAAK,IAAI;oBAAE,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;;oBAC5C,MAAM,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC;YAC1C,CAAC;YAAC,OAAO,IAAI,EAAE,CAAC;gBACd,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,KAAK,IAAI,YAAY,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACtF,CAAC;QACH,CAAC;QACD,MAAM,IAAI,gBAAgB,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,QAAQ,CAAC,CAAC;IACrE,CAAC;AACH,CAAC","sourcesContent":["/**\n * Executing a plan as a transaction over files.\n *\n * Three phases. First every file is read back and compared with what the plan\n * saw, so a file somebody edited in the meantime stops the transaction before\n * anything changes. Then the operations run in order - the new file first, the\n * old one removed last - and each one that completes is recorded. If any\n * fails, the recorded ones are undone in reverse from the contents the plan\n * already holds. Each write is itself atomic (a rename over the target), so\n * the only window in which the tree shows both copies is between the first\n * operation and the last, and a crash inside it leaves two briefs with one id,\n * which `lint` reports by name.\n */\n\nimport type { FileOp } from './archive.js';\nimport type { FileSystem } from './fs.js';\n\nexport class ConflictError extends Error {\n  readonly path: string;\n\n  constructor(path: string) {\n    super(`${path} changed after the plan was made; nothing was written. Run the command again.`);\n    this.name = 'ConflictError';\n    this.path = path;\n  }\n}\n\nexport class TransactionError extends Error {\n  /** Whether every completed operation was undone. */\n  readonly rolledBack: boolean;\n  readonly failures: readonly string[];\n\n  constructor(cause: unknown, rolledBack: boolean, failures: readonly string[]) {\n    const reason = cause instanceof Error ? cause.message : String(cause);\n    super(\n      rolledBack\n        ? `${reason}; every change was rolled back`\n        : `${reason}; the rollback also failed (${failures.join('; ')}), so check these files by hand`,\n    );\n    this.name = 'TransactionError';\n    this.rolledBack = rolledBack;\n    this.failures = failures;\n  }\n}\n\nexport async function applyPlan(fs: FileSystem, ops: readonly FileOp[]): Promise<void> {\n  for (const op of ops) {\n    const current = await fs.read(op.path);\n    if (current !== op.before) throw new ConflictError(op.path);\n  }\n\n  const done: FileOp[] = [];\n  try {\n    for (const op of ops) {\n      if (op.kind === 'write') await fs.write(op.path, op.content);\n      else await fs.remove(op.path);\n      done.push(op);\n    }\n  } catch (error) {\n    const failures: string[] = [];\n    for (const op of [...done].reverse()) {\n      // Undoing is putting back what was there: a file that was absent is\n      // removed, and one that was present - written over or removed - is\n      // written again.\n      try {\n        if (op.before === null) await fs.remove(op.path);\n        else await fs.write(op.path, op.before);\n      } catch (undo) {\n        failures.push(`${op.path}: ${undo instanceof Error ? undo.message : String(undo)}`);\n      }\n    }\n    throw new TransactionError(error, failures.length === 0, failures);\n  }\n}\n"]}
+{"version":3,"file":"apply.js","sourceRoot":"","sources":["../src/apply.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Executing a plan as a transaction over files.\n *\n * Three phases. First every file is read back and compared with what the plan\n * saw, so a file somebody edited in the meantime stops the transaction before\n * anything changes. Then the operations run in order - the new file first, the\n * old one removed last - and each one that completes is recorded. If any\n * fails, the recorded ones are undone in reverse from the contents the plan\n * already holds. Each write is itself atomic (a rename over the target), so\n * the only window in which the tree shows both copies is between the first\n * operation and the last, and a crash inside it leaves two briefs with one id,\n * which `lint` reports by name.\n */\n\nimport type { FileOp } from './archive.js';\nimport { type FileSystem, type NotAFile, NotAFileError } from './fs.js';\n\nexport class ConflictError extends Error {\n  readonly path: string;\n\n  /** `found` is what stands at the path where it is not a file, which is not read. */\n  constructor(path: string, found?: NotAFile) {\n    super(\n      found === undefined\n        ? `${path} changed after the plan was made; nothing was written. Run the command again.`\n        : `${path} is ${found}; nothing was written. Move it out of the way, then run the command again.`,\n    );\n    this.name = 'ConflictError';\n    this.path = path;\n  }\n}\n\nexport class TransactionError extends Error {\n  /** Whether every completed operation was undone. */\n  readonly rolledBack: boolean;\n  readonly failures: readonly string[];\n\n  constructor(cause: unknown, rolledBack: boolean, failures: readonly string[]) {\n    const reason = cause instanceof Error ? cause.message : String(cause);\n    super(\n      rolledBack\n        ? `${reason}; every change was rolled back`\n        : `${reason}; the rollback also failed (${failures.join('; ')}), so check these files by hand`,\n    );\n    this.name = 'TransactionError';\n    this.rolledBack = rolledBack;\n    this.failures = failures;\n  }\n}\n\nexport async function applyPlan(fs: FileSystem, ops: readonly FileOp[]): Promise<void> {\n  for (const op of ops) {\n    const current = await fs.read(op.path).catch((error: unknown) => {\n      // A plan is made from the files a listing names, so what stands where\n      // it would write a new one can be a named pipe, read without end, or a\n      // directory. Nothing is written yet, and the refusal can say so.\n      throw error instanceof NotAFileError ? new ConflictError(op.path, error.what) : error;\n    });\n    if (current !== op.before) throw new ConflictError(op.path);\n  }\n\n  const done: FileOp[] = [];\n  try {\n    for (const op of ops) {\n      if (op.kind === 'write') await fs.write(op.path, op.content);\n      else await fs.remove(op.path);\n      done.push(op);\n    }\n  } catch (error) {\n    const failures: string[] = [];\n    for (const op of [...done].reverse()) {\n      // Undoing is putting back what was there: a file that was absent is\n      // removed, and one that was present - written over or removed - is\n      // written again.\n      try {\n        if (op.before === null) await fs.remove(op.path);\n        else await fs.write(op.path, op.before);\n      } catch (undo) {\n        failures.push(`${op.path}: ${undo instanceof Error ? undo.message : String(undo)}`);\n      }\n    }\n    throw new TransactionError(error, failures.length === 0, failures);\n  }\n}\n"]}

package/dist/cli.d.ts

@@ -24,11 +24,21 @@ export interface CliIO {
     readonly env?: Readonly<Record<string, string | undefined>>;
 }
 type Values = Record<string, string | boolean | undefined>;
+/**
+ * A resolved path as two values of one option compare. On Windows a drive
+ * letter names its volume in either case, and a path resolved there starts
+ * with its drive letter or a backslash, so its first character is folded;
+ * the rest is compared as resolved (spec-core ADR-0005, amended 2026-10-19).
+ * A path written `\\?\c:\x` keeps its letter as written.
+ */
+export declare function onVolume(path: string, platform?: string): string;
 export declare const HELP: string;
 interface Parsed {
     readonly command: string | undefined;
     readonly values: Values;
     readonly positionals: readonly string[];
+    /** Each option's revisions as they were written, where two are written two ways, for git to read. */
+    readonly revisions: ReadonlyMap<string, readonly string[]>;
 }
 /**
  * The line, read and checked. Everything the line alone decides is refused

package/dist/cli.js

@@ -12,6 +12,7 @@ import { parseArgs } from 'node:util';
 import { TransactionError, ConflictError } from './apply.js';
 import { reported } from './collisions.js';
 import { CONFIG_FILES, ConfigError, initialConfig } from './config.js';
+import { idKey } from './corpus.js';
 import { BriefEngine, EngineError, isDate, today } from './engine.js';
 import { NodeFileSystem } from './fs.js';
 import { GitError } from './git.js';
@@ -157,25 +158,38 @@ function unread(command, spec, values) {
     }
     return null;
 }
+/**
+ * A resolved path as two values of one option compare. On Windows a drive
+ * letter names its volume in either case, and a path resolved there starts
+ * with its drive letter or a backslash, so its first character is folded;
+ * the rest is compared as resolved (spec-core ADR-0005, amended 2026-10-19).
+ * A path written `\\?\c:\x` keeps its letter as written.
+ */
+export function onVolume(path, platform = process.platform) {
+    // Folded to either case, two letters compare the same, and the folded path is never shown.
+    return platform === 'win32' ? `${path.charAt(0).toUpperCase()}${path.slice(1)}` : path;
+}
 /**
  * An option's value as the command reads it, so that one thing written two
- * ways is asked for once: a directory as the run resolves it, a number by
- * what its digits count, a list by its ids, a summary as it is trimmed. Any
- * other value is read as it is written, in its own case, which is how each
- * of those options reads it. A revision is read by git, which a line is not
- * checked against, so `HEAD` and the commit it names are two values here.
+ * ways is asked for once: a directory as the run resolves it, its drive
+ * letter in either case, a number by what its digits count, a list by the
+ * set of ids it names, each as a brief's id is matched, a summary as it is
+ * trimmed. Any other value is read as it is written, in its own case, which
+ * is how each of those options reads it. A revision is read by git, which
+ * the run asks once there are two (`sameCommits`).
  */
 function asRead(option, value, root) {
     switch (option) {
         case 'root':
-            return resolve(value);
+            return onVolume(resolve(value));
         case 'config':
-            return resolve(root, value);
+            return onVolume(resolve(root, value));
         case 'wave':
         case 'pr':
             return String(digits(value) ?? value);
         case 'depends-on':
-            return JSON.stringify(idsOf(value));
+            // `7` and `007` name one brief, and `8,7` the briefs `7,8` does.
+            return JSON.stringify([...new Set(idsOf(value).map(idKey))].sort());
         case 'summary':
             return value.trim();
         case 'briefs':
@@ -192,12 +206,18 @@ function asRead(option, value, root) {
     // After the switch, for the reason `untrue` has.
     return value;
 }
+/** The refusal of an option given two values, each shown as JSON, as an empty value is, where what cannot be seen can be. */
+function twoValues(option, first, second) {
+    return `--${option} is given ${JSON.stringify(first)} and ${JSON.stringify(second)}, and takes one value; give one of the two`;
+}
 /**
  * Why a line that gives one option two values is not one to run: the later
  * was read, and the earlier went unread with no word of it, so `--root
  * nowhere --root .` ran in `.` (spec-core ADR-0005, amended 2026-10-18).
+ * Two revisions written two ways are kept in `revisions`, where it is
+ * given, for git to say whether they name one commit.
  */
-function twice(options, values, cwd) {
+function twice(options, values, cwd, revisions) {
     // A configuration is found from the root, as the engine finds it.
     const root = resolve(text(values, 'root') ?? cwd);
     const first = new Map();
@@ -212,8 +232,9 @@ function twice(options, values, cwd) {
         if (earlier === undefined)
             first.set(token.name, { written: token.value, read });
         else if (earlier.read !== read) {
-            // Shown as JSON, as an empty value is, where what cannot be seen can be.
-            return `--${token.name} is given ${JSON.stringify(earlier.written)} and ${JSON.stringify(token.value)}, and takes one value; give one of the two`;
+            if (revisions === null || (token.name !== 'commit' && token.name !== 'base'))
+                return twoValues(token.name, earlier.written, token.value);
+            revisions.set(token.name, [...(revisions.get(token.name) ?? [earlier.written]), token.value]);
         }
     }
     return null;
@@ -421,13 +442,40 @@ export function parse(argv, cwd = process.cwd()) {
         throw new UsageError(`${command} takes no argument, not ${extra}: spec-brief ${command}${spec.noArgument}`);
     }
     const options = parsed.tokens.filter((token) => token.kind === 'option');
-    const refusal = twice(options, parsed.values, cwd) ??
+    // Two revisions written two ways are git's to read, by the run: `--help`
+    // and `--version` start none, and `--no-git` asks git nothing, so with
+    // any of the three they are two values, as the line reads them.
+    const revisions = flag(parsed.values, 'help') || flag(parsed.values, 'version') || flag(parsed.values, 'no-git') ? null : new Map();
+    const refusal = twice(options, parsed.values, cwd, revisions) ??
         answers(options) ??
         (spec === undefined ? null : (unread(command, spec, parsed.values) ?? unwritten(command, spec, parsed.values)));
     if (refusal !== null)
         throw new UsageError(refusal);
     checkValues(command, parsed.values, positionals);
-    return { command, values: parsed.values, positionals };
+    return { command, values: parsed.values, positionals, revisions: revisions ?? new Map() };
+}
+/**
+ * Two revisions of one option are one value where the run's git says both
+ * name one commit, and two where it names two, or cannot say of one: with
+ * no repository, outside one, or for a revision that names none. It is asked
+ * once, for every revision of both options.
+ */
+async function sameCommits(engine, revisions) {
+    // Asked nothing, a git process answers nothing: the mutant that starts one is equivalent.
+    if (revisions.size === 0)
+        return;
+    const asked = [...revisions.values()].flat();
+    // A git a caller of the library hands the engine may have no `commits`;
+    // the command line's is always NodeGit's, which has, so the mutant that
+    // calls it without asking is equivalent here.
+    const named = await engine.git?.commits?.(asked);
+    const commitOf = new Map(asked.map((revision, index) => [revision, named?.[index] ?? null]));
+    for (const [option, [first, ...later]] of revisions) {
+        const commit = commitOf.get(first) ?? null;
+        const other = later.find((revision) => commit === null || commitOf.get(revision) !== commit);
+        if (other !== undefined)
+            throw new UsageError(twoValues(option, first, other));
+    }
 }
 /** A `--format` the command does not write, which the help lists by command. */
 function unwritten(command, spec, values) {
@@ -524,12 +572,14 @@ function useColor(values, io) {
         return false;
     return (io.stdout ?? process.stdout).isTTY === true;
 }
-async function openEngine(run) {
+/** The engine for a run, which asks git nothing where `needsGit` is false and a configuration file names the root. */
+async function openEngine(run, needsGit = true) {
     return BriefEngine.open({
         cwd: text(run.values, 'root') ?? run.cwd,
         config: text(run.values, 'config'),
         ...(flag(run.values, 'no-git') ? { git: null } : {}),
         noConfig: flag(run.values, 'no-config'),
+        needsGit,
     });
 }
 function emitFindings(run, command, findings, checked, extra = {}) {
@@ -607,7 +657,9 @@ async function runLint(run) {
     return emitFindings(run, 'lint', findings, checked, { sections: sectionsJson(engine.config) });
 }
 async function runList(run) {
-    const engine = await openEngine(run);
+    // Nothing `list` answers is read from git, so git is asked nothing where
+    // the root is a configuration file's, and the answer can say so.
+    const engine = await openEngine(run, false);
     engine.requireBriefs();
     const briefs = flag(run.values, 'archived') ? engine.corpus.briefs : engine.corpus.live;
     const ready = new Set(engine.ready());
@@ -615,10 +667,14 @@ async function runList(run) {
         .map((brief) => ({ brief, ready: ready.has(brief), waitingOn: engine.waitingOn(brief) }))
         .filter((row) => !flag(run.values, 'ready') || row.ready);
     if (run.format === 'json') {
+        const { keep, ...read } = engine.inputs();
         run.out(jsonDocument('list', run.version, {
             ok: true,
             briefs: rows.map((r) => briefJson(r.brief, { ready: r.ready, waitingOn: r.waitingOn })),
             sections: sectionsJson(engine.config),
+            // What the answer was read from, for a tool that would give it again
+            // without starting this one, and the version that read it.
+            inputs: { keep, tool: run.version, ...read },
         }));
     }
     else {
@@ -671,6 +727,7 @@ async function runTransition(run, action) {
     if (reference === undefined)
         throw new UsageError(`${action} takes one brief: spec-brief ${action} <brief>`);
     const engine = await openEngine(run);
+    await sameCommits(engine, run.revisions);
     const dryRun = flag(run.values, 'dry-run');
     const plan = action === 'archive'
         ? await engine.planArchive(reference, {
@@ -708,7 +765,7 @@ export async function main(argv = process.argv.slice(2), io = {}) {
         err(error.message);
         return EXIT_ERROR;
     }
-    const { command, values, positionals } = parsed;
+    const { command, values, positionals, revisions } = parsed;
     // From here on, so that what comes before a command is covered as the
     // command is: --version and --help, the package's own manifest, the colour.
     // An error there left main as a rejection, which the launcher ended as
@@ -751,6 +808,7 @@ export async function main(argv = process.argv.slice(2), io = {}) {
             version: await version(),
             values,
             positionals,
+            revisions,
             cwd: io.cwd ?? process.cwd(),
         };
         switch (command) {