@descent-vtt/spec-brief 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -2,6 +2,307 @@
 
 Notable changes, newest first. Versions follow [semver](https://semver.org).
 
+## 0.2.1
+
+`spec-brief init` points `$schema` at the schema of the installed version, and
+the README's links to files the package does not ship resolve on npmjs.com and
+in `node_modules`. spec-core's scanner now reads an image inside a link's text
+itself; archival rewrites and restores such a badge as 0.2.0 did, each
+destination once. Nothing needs to change in a repository that upgrades.
+
+### Changed
+
+- `npm publish` in a checkout refuses to run outside GitHub Actions, so a
+  version cannot reach npm from a workstation by mistake, without provenance;
+  spec-harness 0.1.0 did. The release never runs it: it stages a tarball it
+  packed.
+- spec-core at 8840d36. Its Markdown scanner reads an image inside a link's
+  text, as CommonMark renders it, and lists it after the link it lies in:
+  `[![build](badge.svg)](actions)` gives both. spec-brief read the link's
+  text itself, and still does for what the scanner leaves there - a link in
+  a link's text, which CommonMark takes as the link - so a destination found
+  both ways is kept once, and archival rewrites the badge inside a link once,
+  as before, and restores it on reopening.
+- The scanner makes a document's links, list items and directives mask the
+  first time they are read, and keeps them. The answers are the same.
+
+### Fixed
+
+- `spec-brief init` points `$schema` at
+  `./node_modules/@descent-vtt/spec-brief/schema.json`, the schema of the
+  version installed, as the README recommends. It wrote a URL on GitHub that
+  follows main, so an editor judged the configuration by a schema the
+  installed version might not share. A configuration `init` already wrote
+  keeps its URL until it is edited; either loads.
+- The README's links to `docs/adr/` and `src/config.ts` are GitHub URLs. The
+  package ships neither, so the relative links were dead on npmjs.com and in
+  `node_modules`. A test holds every link in a document the package ships to
+  a file it ships, or to one the repository holds by URL.
+
+## 0.2.0
+
+Scopes are read by spec-core's glob automaton, so a collision is proved with a
+file both briefs would write and protected paths are subtracted from a scope
+exactly. `spec-brief schedule` places briefs in waves from their dependencies
+and provable collisions. Deferred work waits on an observable trigger. A plugin
+may waive a `protected-file` or `out-of-scope` refusal, which is how
+spec-harness applies a signed ruling. Briefs are read with spec-core's
+CommonMark scanner, and the review of 0.1.0 is fixed throughout.
+
+### Upgrading from 0.1.0
+
+- **A configuration that already uses the word "deferred" no longer loads.**
+  Deferred work is a new status, and its word is `"deferred"` unless the
+  configuration says otherwise, so `"status": { "draft": "deferred" }` now
+  names two statuses with one word and stops the run with exit 2: "the
+  status words must differ: "deferred" is the word for draft and deferred".
+  Set `"status": { "deferred": null }` where the repository defers no work,
+  or give the new status a word of its own, `"deferred": "parked"`.
+- **JSON documents are `schemaVersion: 2`**, every command's: the version
+  is one number for all of them, and `matrix`'s document changed meaning. A
+  collision is a pair of briefs and carries `overlaps`, a list of
+  `{ patterns, witness }`, in place of `patterns` and `witness`, and a
+  witness is always a file, never a directory; a `sharedDirectories` entry
+  carries `directories` in place of `directory`; and deferred briefs, and
+  the briefs waiting on them, left `waves[].briefs` for `deferred` and
+  `waiting`. `list`, `lint` and `archive` changed only by adding: `trigger`
+  and `sections`, a `"deferred"` status, and `path` and `paths` on a
+  finding. A reader of those documents reads version 2 as it read 1.
+- **`**` inside a name is an error**, where it was read as `*`: a scope
+  written `docs/**.md` is a `glob` error in `lint`, and a `files` or
+  `exclude` pattern written so stops the run with exit 2. Parentheses are
+  literal unless a group holds a `|`. Both are under "Globs" below.
+- **A note that continues its box's paragraph no longer closes the box**:
+  `- [ ] Add a cache` over `  **Rejected** by 012` refuses an archival as
+  `open-task` until the note is a bullet or has a blank line above it. See
+  the entry on open boxes below.
+
+### Breaking (library API)
+
+- `Config['status']['deferred']` is required, `null` where a repository
+  has no such word. A configuration from `resolveConfig` or
+  `DEFAULT_CONFIG` has it; one built by hand must set it.
+- `Status` gains `'deferred'`, and `Format` and `FORMATS` gain
+  `'gitlab'`: an exhaustive `switch` over either needs the new case.
+- `CollisionReport` gains the required `deferred` and `waiting`, and
+  `WaveMatrix` the required `undecided`; a report built by hand carries
+  them. A wave's `briefs` no longer holds a deferred brief or one waiting on
+  deferred work.
+- `Collision` carries `overlaps` in place of `patterns` and `witness`, and
+  `SharedDirectory` carries `directories` in place of `directory`, as the
+  JSON does.
+- `parseGlob`'s `isFile` option is replaced by `literal` (`'file'`,
+  `'directory'`, `'either'` or a function, such as `readingIn(files)`), a
+  `Glob` carries `compiled` and `literals` in place of `alternatives`, and
+  `intersectGlobs` throws where the search is undecided.
+
+### Changes
+
+- Markdown is read by spec-core's scanner and front matter by its reader,
+  copied into `src/vendor/spec-core/` beside the glob engine and verified by
+  hash (ADR-0001, amended). What a brief's structure is stays as it was: a
+  section, and the title, is an ATX heading, `## Name`, outside a block
+  quote, so prose over a `---` line is still prose and a rule, not a section,
+  and a heading quoted from another document is not one of the brief's; a task
+  is a list item outside a block quote with `[ ]`, `[x]` or `[X]`. What counts
+  as code, a comment or a link is now what CommonMark says it is:
+  - **Indented code and raw-text HTML are code.** Four spaces at the top
+    level after a blank line, and a `<pre>`, `<script>`, `<style>` or
+    `<textarea>` block, hold no heading, task or link: a box in an indented
+    example no longer refuses an archival, and a fence indented four spaces
+    there no longer hides the rest of the brief. Inside a list item, code
+    starts four columns past the item's text: a box written that deep after a
+    blank line is code, and a fence that deep opens nothing.
+  - **A `<!--` in the middle of a line with no `-->` after it is text.** It
+    hid everything after it, so every later section was missing. One that
+    opens a line still runs to the end.
+  - **A heading's text leaves out a comment on its line**:
+    `## Intent <!-- required -->` fills `Intent`, where it was reported
+    missing.
+  - **A code span may close on a later line of its paragraph**, and a link
+    inside one is not rewritten.
+  - **A thematic break ends a task**, so a note after `***` no longer closes
+    the box above it; and **a tab indents to the next multiple of four
+    columns**, so a tab-indented note under a box indented by two spaces is
+    part of the item.
+  - **A link is one CommonMark reads.** `a](b.md)` and `[a](b.md c)` are text
+    and are no longer rewritten on archival; a definition in a block quote
+    is, and so is a destination after link text that runs over lines.
+  - **TOML front matter** between `+++` lines is recognised. `front-matter`
+    reports it, where it was read as body text and only the missing status
+    was reported.
+  - **An inline list on the line under its key** - `affectedFiles:` and then
+    `  [src/**]` - is reported as "an inline list starts on the line after
+    its key; write it after the colon", where the advice was to quote it,
+    which would have made the list a string.
+- Nothing is written into front matter that cannot hold it: TOML, or a block
+  never closed. `schedule --write` and `unarchive` refuse such a brief as
+  `front-matter`, and so does `archive` where lint's own `front-matter` error
+  does not refuse it already. `unarchive` stopped with an unexpected error on
+  a block never closed, as `archive` did with an empty banner template, and
+  `archive` otherwise prepended a second block above the banner.
+- Reopening a brief that had no front matter, in a repository with no status
+  field, gives it back with none. Archival wrote a block to hold the
+  integrity hash, and `unarchive` took the hash out and left `---` over
+  `---` behind; a block the reopening empties now goes with it.
+- A carriage return that ends no line, as a `\r\r\n` ending leaves one, is
+  read as a space; line numbers are unchanged. A front-matter line ending in
+  one now reads, where it was "not a key: value line".
+- Library API: `Brief.frontMatter` is spec-core's `FrontMatter`. It gains
+  `kind` (`'yaml'` or `'toml'`), and each entry gains `parent`, `keyStart`,
+  `valueStart` and `valueEnd`, offsets into the brief's `lines` joined by
+  `\n`. `Brief.scan` gains `links`, the destinations archival rewrites.
+- Globs are spec-core's `path` dialect, matched and intersected by its
+  automaton, which is copied into `src/vendor/spec-core/` and verified by
+  hash. The syntax is unchanged but for two refusals; what it means changes
+  in four places.
+  - **`**` inside a name is an error**: `docs/**.md`, `**.ts`, `a**b`. It
+    was read as `*`, one level, and dropped every nested file from a scope
+    that tools elsewhere read as recursive. The message says to write
+    `docs/**/*.md` for any depth, or `*.md` for one level. A scope pattern
+    written so is a `glob` error in `lint`, and a `files` or `exclude`
+    pattern stops the run with exit 2.
+  - **Parentheses are literal unless a group holds a `|`**:
+    `C++(notes).md`, `*(2017).md` and `@(a)` are names, where every
+    `?(`, `*(`, `+(`, `@(` or `!(` was refused as an extended glob.
+    `+(a|b)` is still refused, and the message now says to write `{a,b}`,
+    and a literal parenthesis as `[(]`.
+  - **A literal path is read from the tree.** A file the tree holds is that
+    file, a directory it holds is everything beneath it, and a path it does
+    not hold is a file unless written with a trailing `/`. The extension
+    guess is gone: it read `Dockerfile` as a directory, so `Dockerfile` and
+    `**/x.ts` collided through `Dockerfile/x.ts`, and read `docs/v1.2` as a
+    file, missing every collision inside it. Without a tree - the library
+    called with no files - every literal is a file.
+  - **A trailing `/**` or `/` is a directory's contents**, at least one name
+    below it: `src/**` no longer matches `src`, and a collision witness is
+    always a file, `docs/adr/x` where it was `docs/adr`.
+  - **`./` alone, and a `..` segment, are refused in the core's words**
+    ("the pattern names the root itself", "a pattern cannot climb out of its
+    root"), and a lone `}` is a literal rather than an error. A leading `/`
+    and a leading `!` are refused as before.
+  - **Protection wins.** What a brief may write is `affectedFiles` less
+    `protectedFiles`, so `affectedFiles: [src/**]` with
+    `protectedFiles: [src/db/schema.ts]` is valid. `scope-contradiction` now
+    fires only for affected patterns the protections cover entirely, as one
+    finding per brief naming each; it used to fire for any file in both.
+    `matrix` leaves out a file either brief of a pair protects.
+- `literal-read-as-file`, a note: a path with no glob syntax that the tree
+  does not hold and whose name has no extension, such as `src/newmod`, is
+  read as a file, and the hint says to write `src/newmod/` for a directory.
+  `glob-matches-nothing` leaves such a pattern to it.
+- `collision-undecided`, a warning: a pair of briefs whose collision the
+  witness search could not decide within its budget. It is never reported
+  as a collision and never as clean. `matrix` marks the pair `?`, and its
+  JSON gains an `undecided` list per wave (`{ a, b, patterns }`).
+- Deferred work has a status: `status.deferred` in configuration, `"deferred"`
+  by default and `null` for a repository without one. A deferred brief lives
+  in the briefs directory, is never ready, is listed and left out by
+  `matrix`, and is refused by `archive` as `archive-deferred`. It names the
+  event that brings it back in `trigger`, a new built-in field that `list`
+  reports. A brief that depends on deferred work, directly or through another
+  brief, runs in no wave either: `matrix` lists it under `waits`, and in JSON
+  under `waiting` with the brief it waits on, and compares it with nothing,
+  as `schedule` places it nowhere.
+- `deferral-trigger`, an error: a deferred brief with no `trigger`, or one
+  that is only a date or a time - `2026-10`, `Q3`, `next month`, `October`,
+  `in two weeks` - or a placeholder. "when the second tenant signs" and
+  "when p95 > 200 ms" pass.
+- `spec-brief schedule` computes the waves the live briefs can run in
+  (ADR-0011): dependency order, ties by id, each brief in the lowest wave
+  after its live dependencies that holds nothing it collides with, a brief
+  with no scope in a wave of its own. Each brief's proposed wave is shown
+  beside its declared one with the reason for a move - the dependency, or the
+  brief and the file that kept it out of a wave - and deferred briefs, the
+  briefs waiting on them, and dependency cycles are listed. `--write` sets
+  `wave` in the front matter of each brief that moves, every other line
+  untouched and a comment after the old wave kept, as one transaction, and
+  writes nothing over a cycle. A declared
+  wave that differs from the computed one is judged as `lint` and `matrix`
+  judge it: no collision in it, dependencies before it, dependents after it.
+  One that holds is a person's choice to keep, and its move is a note.
+  Exit 0 when every declared wave holds, 1 when a brief declares no wave or
+  one that does not hold, or on a cycle. Pretty, JSON, SARIF, GitHub and
+  GitLab output; `wave-schedule`, an error by default, is the finding per
+  move, and a note for a move whose declared wave holds.
+- A plugin may export a `waive` hook beside its rules (ADR-0007, amended).
+  After an archival is planned, and only when it has a refusal a plugin may
+  lift, each hook is given `{ root, brief: { id, file, text }, findings,
+  base, commit }`, a frozen copy, and answers `[{ rule, path, reason }]`. A
+  `protected-file` or `out-of-scope` refusal of the plan's own that it names
+  by rule and path becomes a `waived` note; a waiver for any other rule is
+  ignored with a `waiver-ignored` warning, and one that matches no refusal
+  changes nothing. A hook that returns nothing waives nothing; one that
+  throws - a write to the copy included - or answers in another shape stops
+  the run with exit 2. This is how spec-harness's plugin lets a signed ruling
+  allow a protected file, without spec-brief reading signatures.
+- A `protected-file` refusal names its file in a new `path` field, one
+  finding per file as before, and an `out-of-scope` finding lists its files
+  in `paths`. Both appear in the JSON of `archive`; a plugin reads them.
+- `--format gitlab` wherever `sarif` is offered - `lint`, `matrix`,
+  `schedule` - writes a GitLab Code Quality report: an array of
+  `{ description, check_name, fingerprint, severity, location }`, errors as
+  `major`, warnings as `minor`, notes as `info`, and a fingerprint that
+  hashes the rule, the file and the message but not the line.
+- 24 lint rules and 5 collision rules.
+- The library's `parseGlob`, `matchGlob`, `intersectGlobs` and `globBase`
+  keep their signatures over the new engine, with the options and shapes
+  under "Breaking (library API)" above. `globWitness`, `globCovers`,
+  `globBases`, `readingIn`, `meet`, `scopeOf`, `contradictions` and
+  `waitingOnDeferred` are new. `intersectTokens` is gone.
+- A `shared-directory` finding has a hint, and a `glob` finding says what a
+  scope pattern looks like.
+- Versions are staged by CI through npm's trusted publishing, with
+  provenance that names the commit and the run, and a maintainer releases
+  each with a second factor (ADR-0010).
+- `archive` no longer passes a scope it never measured. With no `--commit`,
+  `--base` or `archiving.base`, without git, or with a commit already in the
+  base branch - where the diff from the merge base is empty - a brief that
+  declares `affectedFiles` or `protectedFiles` gets `scope-unmeasured`, a
+  warning that names the next step, and a refusal under `--strict`. It is the
+  first archive rule, and configuration sets its severity like any other.
+- An open box is closed only by a note under it that starts with a
+  disposition marker, and a note starts a bullet, a paragraph after a blank
+  line, or a line after one that ends a sentence (`.`, `?` or `!`, then
+  only closing marks). A marker anywhere in the item used to count, the
+  box's own text included, so `- [ ] Explain why the **Rejected** designs
+  failed` archived as dispositioned, and so did the same sentence wrapped
+  after "the", indented or not. A line that continues a sentence no longer
+  closes the box, whatever it starts with; `- [ ] Add a cache.` over
+  `  **Rejected** by 012` still does. A note under a box whose text ends
+  without a stop, `- [ ] Add a cache` over `  **Rejected** by 012`, now
+  refuses the archival as `open-task`, and the hint says to make it a bullet
+  or put a blank line above it.
+- `archiving.rewriteLinks: false` now holds for the links other briefs hold
+  to a moving brief, which were rewritten regardless. Those left pointing at
+  the old path are reported as `stale-link`, a warning naming each file and
+  line, on `archive` and `unarchive` alike; `unarchive --strict` refuses on
+  it, as `archive --strict` does.
+- `matrix` reports two briefs whose scopes meet as one collision, however
+  many pairs of their patterns meet, and the finding lists every pair with a
+  path both cover. A pair writing into several shared directories is likewise
+  one `shared-directory` finding.
+- A plugin package whose `exports` offer only the `import` condition loads.
+  Packages were resolved with `require.resolve`, which reads `exports` under
+  the require conditions, so an ESM-only plugin could not be found.
+  A subpath is held to `exports` as Node holds it: a target, or what a
+  `*` matched, with a `.`, `..` or `node_modules` segment is refused,
+  split on `/` and on a backslash alike, so `pkg/..\..\outside` cannot
+  climb out of `node_modules` on Windows.
+- A brace group is split on its own commas only: `{[,]x,y}` has the two
+  alternatives `[,]x` and `y`, where a comma or brace inside a class used to
+  split the group or unbalance it.
+- A section rule takes a `hint`: what the section must answer. A new brief
+  carries it as a comment under the heading, `missing-section`,
+  `empty-section` and `placeholder` findings give it as their hint, and the
+  JSON of `list` and `lint` gains `sections`, every section the configuration
+  asks for with its type, switches and hint. The default sections carry one,
+  and `init` writes them out. `empty-section` and `placeholder` findings have
+  a hint even without one.
+- A `--base` or `archiving.base` that names no commit stops `archive` with a
+  message that says so, where git's failure to diff from it surfaced as an
+  unexpected error with a stack trace.
+
 ## 0.1.0
 
 The first release.

package/README.md

@@ -48,7 +48,11 @@ Every privilege change issues a new session token and invalidates the old one.
 - [ ] a rotated token is rejected by every endpoint
 ```
 
-The id comes from the file name (`012_rotate-session-tokens.md`) or from an `id` field. `affectedFiles` is the scope the round may write; `protectedFiles` is what it is not empowered to change, and archival refuses a round that changed it.
+Work put off for later is a brief too, with `status: deferred` and a `trigger` naming the event that brings it back - "when the second tenant signs", "when p95 exceeds 200 ms", never a date. A deferred brief stays in the briefs directory, is never ready, and runs in no wave until someone sets it `active`.
+
+The id comes from the file name (`012_rotate-session-tokens.md`) or from an `id` field. `affectedFiles` is the scope the round may write; `protectedFiles` is what it is not empowered to change, and archival refuses a round that changed it. Protection wins: what a round may write is `affectedFiles` less `protectedFiles`, so "all of `src/` but the schema" is `affectedFiles: [src/**]` with `protectedFiles: [src/db/schema.ts]`.
+
+Scopes are globs in spec-core's `path` dialect, the one every spec-\* tool reads: `*`, `?`, `[a-z]` and `{a,b}` within a name, `**` for any number of directories, compared case-sensitively on every host. `**` is a whole segment: `docs/**.md` is refused, since tools read it three ways - write `docs/**/*.md` for any depth, or `docs/*.md` for one level. Parentheses are literal, `C++(notes).md`, unless a group holds a `|`: an extended glob such as `+(a|b)` is refused, and written `{a,b}`. A trailing `/**` or `/` is a directory's contents - at least one name below it, never the directory itself. A path with no glob syntax is read from the tree: a file the tree holds is that file, a directory it holds is everything beneath it, and a path it does not hold yet is a file unless it ends in `/`. Write `src/newmod/` for a directory the round creates; `lint` notes a bare `src/newmod` it cannot place.
 
 ## Commands
 
@@ -58,7 +62,7 @@ Writes `.spec-brief.json` with every default spelled out, and creates the brief
 
 ### `spec-brief new <title>`
 
-Scaffolds a brief with the next free number - one more than the highest id, live or archived, since ids are never reused - and every required section, each holding a hint in a comment. A comment is not content, so a fresh brief reads as unwritten until someone writes it. `--id`, `--type`, `--wave`, `--depends-on 7,8` and `--date` fill the front matter.
+Scaffolds a brief with the next free number - one more than the highest id, live or archived, since ids are never reused - and every required section, each holding its `hint` in a comment. A comment is not content, so a fresh brief reads as unwritten until someone writes it. `--id`, `--type`, `--wave`, `--depends-on 7,8` and `--date` fill the front matter.
 
 ### `spec-brief lint [brief...]`
 
@@ -76,11 +80,11 @@ briefs/035_the-background-side.md
 
 ### `spec-brief list`
 
-Live briefs with their status, wave, task count and readiness. A brief is *ready* when every brief it depends on is archived. `--ready` shows only those, which is the question an orchestrator asks; `--archived` includes the archive; `--format json` gives an orchestrator the whole table.
+Live briefs with their status, wave, task count and readiness. A brief is *ready* when every brief it depends on is archived, and it is neither a draft nor deferred. `--ready` shows only those, which is the question an orchestrator asks; `--archived` includes the archive; `--format json` gives an orchestrator the whole table, and the sections the configuration asks for, each with its `hint`.
 
 ### `spec-brief matrix`
 
-Compares the `affectedFiles` of every pair of live briefs in the same wave, `--all-waves` for every pair.
+Compares the `affectedFiles` of every pair of live briefs in the same wave, `--all-waves` for every pair. Deferred briefs, and briefs that wait on one directly or through another, are listed and left out: they run in no wave until the deferred work comes back, as `schedule` places them nowhere, so the two agree on which briefs run side by side.
 
 ```text
 wave 1 · 3 briefs
@@ -92,28 +96,52 @@ wave 1 · 3 briefs
   ? 003 declares no affectedFiles and cannot be checked
 ```
 
-Scopes are intersected as globs, not compared as strings: the two above share no prefix and still meet, and the file named is one both patterns match. A brief with no scope is reported as unscoped rather than counted as safe. Exit 1 on a collision.
+Scopes are intersected as globs, not compared as strings: the two above share no prefix and still meet, and the file named is one both patterns match and neither brief protects - always a file, never a directory. Two briefs whose scopes meet in several places are one collision, listing every pair of patterns that meets. A brief with no scope is reported as unscoped rather than counted as safe. The search for a shared file has a budget; a pair it cannot decide within it is marked `?` and reported as `collision-undecided`, a warning, never as a collision and never as clean. Exit 1 on a collision.
+
+### `spec-brief schedule`
+
+Computes the waves the live briefs can run in, drafts included, and sets each beside the wave it declares. A brief runs after every dependency that is still live - an archived one is done - and shares a wave with no brief whose writable scope meets its own. Briefs are taken in dependency order, ties broken by id, and each goes into the lowest wave that is after its dependencies and holds nothing it collides with. A brief with no `affectedFiles` cannot be proved apart from anything, so it runs in a wave of its own and is reported as `unscoped`. The first wave is the lowest any brief declares, or 1.
+
+```text
+wave 1 · 2 briefs
+  001  Rotate session tokens
+  003  Audit log            moves from wave 2
+         wave 2 also holds
+         nothing holds it later
+wave 2 · 1 brief
+  002  Store sessions       moves from wave 1
+         wave 1 does not hold: 001 there also writes src/auth/session.ts
+         not wave 1, where 001 also writes src/auth/session.ts ("src/**/session.ts" and "src/auth/**")
+
+waits: 007 on 006, which is deferred
+deferred: 006
+2 briefs would move; "spec-brief schedule --write" writes the waves
+```
+
+Each move says why: the dependency that sets the earliest wave, and for every wave passed over, the brief there and the file both would write. It says first whether the declared wave holds - whether `lint` and `matrix` would pass it: no brief there that it collides with, its dependencies in earlier waves, and the briefs that depend on it in later ones. A deferred brief, and one that waits on it, is placed nowhere; a dependency cycle is an error, and nothing in or after it is placed. `--write` sets `wave` in the front matter of each brief whose wave changes - every other line as it was, in one transaction - and writes nothing over a cycle. A comment after the old wave, `wave: 2  # after the review`, stays after the new one. A brief whose lines end in both LF and CRLF is written with the ending of its first line throughout, as `archive` writes one. `--format json` gives an orchestrator the waves, each brief's declared and proposed wave with the reasons and whether the declared one holds, and what waits on what; `sarif`, `github` and `gitlab` carry a `wave-schedule` finding per move.
+
+The result is the same every time for the same briefs. It is a valid schedule, not always the shortest: no fast method promises the fewest waves, and a person can always move a brief later by hand, which `lint` and `matrix` then check. So a move is an error only when the declared wave does not hold, or there is none: a declared wave that holds is the person's to keep, and its move is a note. Exit 0 when every declared wave holds, 1 when a brief declares no wave or one that does not hold, or the dependencies form a cycle, 2 when the run cannot be trusted.
 
 ### `spec-brief archive <brief>`
 
 Closes a round. Refused, with every reason, when:
 
 - the brief has lint errors, is a draft, or depends on a brief that is still live;
-- a task item is neither ticked nor dispositioned - an open box counts as closed when a note under it starts with one of the `dispositions` (`**Delegated`, `**Accepted debt`, `**Rejected` by default);
+- a task item is neither ticked nor dispositioned - an open box counts as closed when a note under it starts with one of the `dispositions` (`**Delegated`, `**Accepted debt`, `**Rejected` by default), a note being a line under the box, above any box nested in it, that starts a bullet, a paragraph after a blank line, or a line after one that ends a sentence. A line that continues a sentence is the box's text wrapping, not a note, so `- [ ] Explain why the` over `  **Rejected** designs failed` is open, and `- [ ] Add a cache.` over `  **Rejected** by 012` is closed;
 - the working tree holds uncommitted work outside the brief directories (`--allow-dirty` to proceed);
-- the round's commit changed a file in `protectedFiles`.
+- the round's commit changed a file in `protectedFiles` - one refusal per file, naming it, unless a plugin that verifies rulings [waives it](#waiving-a-refusal).
 
-Changes outside `affectedFiles` are a warning, and an error under `--strict`. Otherwise it writes the archived brief with its status set, a frozen banner under the front matter, every relative link rewritten for the archive directory, and an `integrity` hash; rewrites the links other live briefs hold to it; and removes the original. `--commit <rev>` records the commit and the files it changed; `--base <rev>` measures from the merge base instead, for a branch of several commits; `--pr <n>` links the pull request; `--summary <text>` is what the round did, in the banner. `--dry-run` prints the plan and the banner and writes nothing. Archiving an archived brief does nothing and exits 0.
+Changes outside `affectedFiles` are a warning, and an error under `--strict`. A scope is never passed by checks that measured nothing: when the files the round changed are unknown - no `--commit`, `--base` or `archiving.base`, `--no-git`, or a commit already in the base branch, as on `main` after the merge - a brief that declares one gets `scope-unmeasured`, a warning, and a refusal under `--strict`. Otherwise it writes the archived brief with its status set, a frozen banner under the front matter, every relative link rewritten for the archive directory, and an `integrity` hash; rewrites the links other live briefs hold to it; and removes the original. With `archiving.rewriteLinks` off, no link is rewritten, and the links other live briefs are left holding are reported as `stale-link`. `--commit <rev>` records the commit and the files it changed; `--base <rev>` measures from the merge base instead, for a branch of several commits; `--pr <n>` links the pull request; `--summary <text>` is what the round did, in the banner. `--dry-run` prints the plan and the banner and writes nothing. Archiving an archived brief does nothing and exits 0.
 
 spec-brief reads git and never writes it. Review the change and commit it with the round.
 
 ### `spec-brief unarchive <brief>`
 
-Reopens an archived brief: the banner and the hash come off, the status goes back to the live word, and the links are rewritten again. A brief archived and reopened is the brief it was, blank lines and final newline included, with two exceptions: the status line is written in its plain spelling, and a relative link that had to be rewritten comes back in its shortest form (`./b.md` returns as `b.md`).
+Reopens an archived brief: the banner and the hash come off, the status goes back to the live word, and the links are rewritten again. A brief archived and reopened is the brief it was, blank lines and final newline included, with four exceptions: the status line is written in its plain spelling; a relative link that had to be rewritten comes back in its shortest form (`./b.md` returns as `b.md`); an empty front matter block, `---` over `---`, comes back as none, since archival gives a brief with no front matter a block for its hash and reopening takes away a block it leaves empty; and a brief whose lines end in both LF and CRLF comes back with the ending of its first line throughout.
 
 ### Every command
 
-`--root <dir>` runs from another directory. `--config <file>` names the configuration; `--no-config` uses the defaults. `--format` is `pretty`, `json`, `sarif` or `github` where the command reports findings. `--strict` makes warnings fail the run. `--no-git` leaves git out even inside a repository: the tree is read from disk, and `archive` records no commit. `--color` and `--no-color` override `NO_COLOR`, `FORCE_COLOR` and the terminal check. `--help` and `--version` do what they say.
+`--root <dir>` runs from another directory. `--config <file>` names the configuration; `--no-config` uses the defaults. `--format` is `pretty`, `json`, `sarif`, `github` or `gitlab` where the command reports findings. `--strict` makes warnings fail the run. `--no-git` leaves git out even inside a repository: the tree is read from disk, and `archive` records no commit. `--color` and `--no-color` override `NO_COLOR`, `FORCE_COLOR` and the terminal check. `--help` and `--version` do what they say.
 
 **Exit codes:** `0` clean, `1` findings, a collision, or a refused action, `2` the run could not be trusted - a bad flag, a configuration that does not load, a brief that does not exist. A run over a briefs directory that does not exist exits 2, because a check over nothing looks exactly like a clean one.
 
@@ -129,16 +157,16 @@ Reopens an archived brief: the banner and the hash come off, the status goes bac
 | `exclude` | `[]` | File-name globs that are never briefs, such as an index. |
 | `template` | `null` | A template file for `new`, with `{id}`, `{title}`, `{date}`, `{type}`, `{wave}`, `{status}`. |
 | `id` | `{ "source": "filename", "separator": "_", "digits": 3 }` | Where an id comes from, and how a new one is written. |
-| `status` | `{ "field": "status", "draft": "draft", "active": "active", "archived": "archived" }` | The words a repository uses. `field: null` reads status from location alone. |
-| `sections` | Intent, Negative Scope, Not Empowered (optional), Invariants (checklist) | Sections every live brief carries: a name, or `{ name, aliases, mustContain, checklist, optional }`. |
+| `status` | `{ "field": "status", "draft": "draft", "active": "active", "deferred": "deferred", "archived": "archived" }` | The words a repository uses. `field: null` reads status from location alone; `draft` and `deferred` may be `null` where a repository has no such word. |
+| `sections` | Intent, Negative Scope, Not Empowered (optional), Invariants (checklist) | Sections every live brief carries: a name, or `{ name, aliases, mustContain, checklist, optional, hint }`. `hint` says what the section must answer: a new brief carries it as a comment under the heading, a finding that the section is missing or unwritten gives it as the next step, and the JSON of `list` and `lint` reports it, so a tool helping to write a brief can ask for each section by what it is for. |
 | `sectionOrder` | `false` | Sections must appear in the listed order. |
 | `types` | `feature`, `defect`, `refactor`, `chore` | Brief types and the sections each adds. |
 | `placeholders` | `TBD`, `TODO`, `FIXME`, ... | Words that mark a section as unwritten. |
 | `fields` | `[]` | Front-matter keys the repository uses beyond the built-in ones. |
 | `archiving.tasks` | `"all"` | `"all"`, or the sections whose boxes must be closed. |
-| `archiving.dispositions` | `**Delegated`, `**Accepted debt`, `**Rejected` | Text under an open box that closes it. |
-| `archiving.banner` | see [`src/config.ts`](src/config.ts) | Banner lines, with `{date}`, `{summary}`, `{pr}`, `{commit}`, `{diffstat}`, `{links}`, `{id}`, `{title}`, `{author}`. A line with an empty placeholder is left out. |
-| `archiving.rewriteLinks` | `true` | Rewrite relative links when a brief moves. |
+| `archiving.dispositions` | `**Delegated`, `**Accepted debt`, `**Rejected` | What a note under an open box starts with to close it. |
+| `archiving.banner` | see [`src/config.ts`](https://github.com/DescentVTT/spec-brief/blob/main/src/config.ts) | Banner lines, with `{date}`, `{summary}`, `{pr}`, `{commit}`, `{diffstat}`, `{links}`, `{id}`, `{title}`, `{author}`. A line with an empty placeholder is left out. |
+| `archiving.rewriteLinks` | `true` | Rewrite relative links when a brief moves: its own, and the ones other live briefs hold to it. Off, neither is edited, and the links other briefs are left holding are reported as `stale-link`. |
 | `archiving.freeze` | `true` | Write an integrity hash, so a later edit is caught. |
 | `archiving.base` | `null` | Branch the diff is measured from, such as `"main"`. |
 | `rules` | `{}` | Severity per rule: `off`, `note`, `warning` or `error`. |
@@ -172,12 +200,14 @@ A repository whose briefs have eight ordered sections, `proposed` and `archived`
 
 Section names compare without case, typographic quotes, emphasis, a leading number or a trailing colon, and a heading may add a qualifier after a separator: `## 2. Commander’s Intent:` fills `Commander's Intent`, and `## Invariants (must hold)` fills `Invariants`.
 
+A brief is read as CommonMark reads it wherever that decides what is code or a comment - fenced and indented code, `<pre>`, `<script>`, `<style>` and `<textarea>` blocks, code spans, HTML comments - and nothing inside those is structure. A section, and the title, is an ATX heading, `## Name`, outside a block quote: prose over a `---` line is prose and a rule, and a heading quoted from another document is not one of the brief's sections. A task is a list item outside a block quote with `[ ]`, `[x]` or `[X]`. The links archival rewrites are the ones that write a destination: `[text](dest)`, `![alt](dest)` - one inside a link's text too - and a definition, `[label]: dest`, through which a reference is rewritten once.
+
 ## Rules
 
 <!-- rules:start -->
 | Rule | Default | Reports |
 | --- | --- | --- |
-| `front-matter` | error | Front matter that does not parse, a duplicate key, YAML beyond the flat subset. |
+| `front-matter` | error | Front matter that does not parse, a duplicate key, YAML beyond the flat subset, TOML. |
 | `field` | error | A field spec-brief reads with a value of the wrong shape: a wave that is not a whole number, a list where one value belongs. |
 | `unknown-field` | warning | A front-matter key nobody declared, with the one probably meant. |
 | `status` | error | No status, a word the configuration does not use, or a status that disagrees with the directory. |
@@ -195,25 +225,42 @@ Section names compare without case, typographic quotes, emphasis, a leading numb
 | `dependency` | error | A dependency on itself, or on a brief that does not exist. |
 | `dependency-cycle` | error | Live briefs that depend on each other in a cycle, reported once, as a path. |
 | `wave-order` | error | A live dependency that does not run in an earlier wave. |
+| `deferral-trigger` | error | A deferred brief with no `trigger`, or one that is only a date or a time - `2026-10`, `Q3`, `next month`, `October` - or a placeholder, rather than an event such as "when the second tenant signs". |
 | `glob` | error | A scope pattern spec-brief cannot read. |
-| `scope-contradiction` | error | A file that is both in `affectedFiles` and in `protectedFiles`. |
+| `scope-contradiction` | error | Patterns in `affectedFiles` that `protectedFiles` cover entirely, so nothing of them is writable - one finding per brief, naming each. A pattern the search cannot decide is a warning. |
 | `glob-matches-nothing` | note | A scope pattern that matches no file git sees, tracked or untracked - expected when the round creates it. |
+| `literal-read-as-file` | note | A path with no glob syntax that the tree does not hold and whose name has no extension, such as `src/newmod`: read as a file, and `src/newmod/` if a directory was meant. |
 | `archive-freeze` | error | An archived brief that changed after it was archived. |
 | `collision` | error | Two briefs in one wave whose scopes can name the same file (`matrix`). |
-| `unscoped` | note | A brief sharing a wave that declares no scope (`matrix`). |
+| `collision-undecided` | warning | Two briefs in one wave whose collision the search could not decide within its budget (`matrix`), or a wave `schedule` passed over for it. |
+| `unscoped` | note | A brief sharing a wave that declares no scope (`matrix`), or one `schedule` runs alone. |
 | `shared-directory` | off | Two briefs in one wave writing into the same directory (`matrix`). |
+| `wave-schedule` | error | A brief with no wave, or a declared wave that does not hold - a collision in it, a dependency out of order - with the wave `schedule` computes and why (`schedule`). A declared wave that holds and is not the computed one is a note. |
+| `scope-unmeasured` | warning | A brief with a scope archived without the files its round changed, so nothing checked the scope (`archive`). |
+| `stale-link` | warning | Links in live briefs left pointing where a brief used to be, when `archiving.rewriteLinks` is off (`archive`, `unarchive`). |
 <!-- rules:end -->
 
-`archive` refuses with its own reasons - `open-task`, `archive-draft`, `dependency-open`, `dirty-tree`, `protected-file`, `out-of-scope`, `archive-exists` - which are not lint rules: they are about whether this round is done, not whether the brief is well written.
+`archive` refuses with its own reasons - `open-task`, `archive-draft`, `archive-deferred`, `dependency-open`, `dirty-tree`, `protected-file`, `out-of-scope`, `archive-exists` - and says `waived` and `waiver-ignored` of what [plugins](#waiving-a-refusal) lift; none of these are lint rules: they are about whether this round is done, not whether the brief is well written. The rules marked `archive` above are raised by archival too, and configuration sets their severity like any other.
 
 ## In CI
 
 ```yaml
 - run: npx spec-brief lint --format github
 - run: npx spec-brief matrix --format github
+- run: npx spec-brief schedule --format github
 ```
 
-`github` writes workflow commands, which annotate the pull request with no upload and no permission. `sarif` writes SARIF 2.1.0 for code-scanning upload. `json` is a versioned document (`schemaVersion`) for anything else.
+`github` writes workflow commands, which annotate the pull request with no upload and no permission. `sarif` writes SARIF 2.1.0 for code-scanning upload. `gitlab` writes a GitLab Code Quality report - an array of `{ description, check_name, fingerprint, severity, location: { path, lines: { begin } } }` - for a merge request to show:
+
+```yaml
+spec-brief:
+  script: npx spec-brief lint --format gitlab > gl-code-quality.json
+  artifacts:
+    reports:
+      codequality: gl-code-quality.json
+```
+
+An error is `major`, a warning `minor` and a note `info`; GitLab's `critical` and `blocker` are for security holes and crashes, which no finding here is. The fingerprint is a SHA-256 of the rule, the file and the message, and not the line, so a finding that moves is the same issue. `json` is a versioned document for anything else: `schemaVersion` changes when a field changes meaning, and is 2 since a collision became a pair of briefs rather than a pair of patterns.
 
 ## As a library
 
@@ -224,11 +271,14 @@ const engine = await BriefEngine.open({ cwd: process.cwd() });
 const findings = await engine.lint();
 const ready = engine.ready();                        // what can run now
 const { report } = await engine.collisions();        // who collides with whom
+const { schedule } = await engine.schedule();        // the waves, computed
 const plan = await engine.planArchive('012', { commit: 'HEAD', pr: 41 });
 if (plan.blocking.length === 0) await engine.apply(plan);
 ```
 
-Everything below the engine is a pure function of text: `parseBrief`, `lint`, `collisions`, `intersectGlobs`, `planArchive`. `MemoryFileSystem` runs an engine over files that were never written, which is how a harness can ask what archiving a brief would do.
+Everything below the engine is a pure function of text: `parseBrief`, `lint`, `collisions`, `meet`, `globWitness`, `planArchive`. `MemoryFileSystem` runs an engine over files that were never written, which is how a harness can ask what archiving a brief would do.
+
+`parseGlob`, `matchGlob`, `intersectGlobs` and `globBase` keep their 0.1 signatures as a compatibility layer over the spec-core engine. They follow its dialect: a literal is read as a file unless `parseGlob` is told otherwise (`{ literal: 'directory' | 'either' | (path) => ... }`, where `readingIn(files)` reads it from a tree), and `intersectGlobs` throws where `globWitness` would answer `undecided`.
 
 ## Plugins
 
@@ -253,6 +303,26 @@ export default (options) => ({
 
 This is where integrations belong. A tool that defines a format - signed departures, recorded reproducers, a code graph's blast radius - is the one that can check it, and spec-brief carries no copy of formats it does not own. Loading a plugin runs its code, exactly as loading a linter configuration does.
 
+A path is relative to the root. A package is found from the root as an `import` there would find it, its `exports` read under the import conditions, so a plugin published as ESM only loads, and so does a subpath such as `@descent-vtt/spec-harness/spec-brief-plugin`.
+
+### Waiving a refusal
+
+A plugin may also export `waive`, which lets the archive accept a change its own check allows - spec-harness's plugin verifies a signed ruling for a protected path, which spec-brief does not know how to read.
+
+```js
+export default () => ({
+  name: 'rulings',
+  rules: [],
+  // context: { root, brief: { id, file, text }, findings, base, commit }
+  waive: async ({ findings }) =>
+    findings
+      .filter((f) => f.rule === 'protected-file' && verifiedRulingCovers(f.path))
+      .map((f) => ({ rule: f.rule, path: f.path, reason: 'ruling R3, signed by alice, allows it' })),
+});
+```
+
+`findings` are the archive's refusals, as a frozen copy: a hook reads them and cannot change them, and a write to them throws. A `protected-file` refusal is one per file and names its `path`; an `out-of-scope` refusal, which refuses only under `--strict`, lists its `paths`. Those two are the only ones a plugin can waive: a waiver matches one of the plan's own refusals by rule and path and turns it into a `waived` note naming the plugin, the rule, the path and the reason; a waiver for any other rule is ignored with a `waiver-ignored` warning. The hook is asked only when the plan has a refusal it could lift. A hook that returns nothing waives nothing. One that throws - a write to `findings` included - or answers in another shape stops the run with exit 2, as a plugin that fails to load does.
+
 ## What it does not do
 
 - **No status file.** There is no `manifest.json` to keep in step. A brief and the directory it sits in are the record; `list --format json` is the index, computed when asked. A committed index is also the one file every round merging in parallel edits.
@@ -262,7 +332,7 @@ This is where integrations belong. A tool that defines a format - signed departu
 
 ## Design
 
-The decisions and what they cost are in [`docs/adr/`](docs/adr/README.md).
+The decisions and what they cost are in [`docs/adr/`](https://github.com/DescentVTT/spec-brief/blob/main/docs/adr/README.md).
 
 ## License
 

package/dist/archive.d.ts

@@ -15,14 +15,36 @@ export interface PullRequest {
     readonly number: number;
     readonly url: string | null;
 }
+/**
+ * Why the files a round changed are unknown. `git`: there was no git to ask.
+ * `revision`: no commit was named and no base configured, so no diff was
+ * read. `merged`: the commit is already in the base branch, so the diff from
+ * their merge base is empty whatever the round changed - archiving on the base
+ * branch after the merge.
+ */
+export type Unmeasured = {
+    readonly reason: 'git';
+} | {
+    readonly reason: 'revision';
+} | {
+    readonly reason: 'merged';
+    readonly base: string;
+    readonly commit: string;
+};
 export interface ArchiveRequest {
     /** `YYYY-MM-DD`. */
     readonly date: string;
     readonly summary?: string | undefined;
     readonly pr?: PullRequest | undefined;
     readonly commit?: CommitInfo | undefined;
-    /** The files the round changed, when a commit is known. */
+    /** The files the round changed, when they were read. */
     readonly changes?: readonly FileChange[] | undefined;
+    /**
+     * Why `changes` is missing, when the caller knows. Without changes the
+     * scope checks have nothing to check, and a plan that said nothing would
+     * read as a round that stayed in scope.
+     */
+    readonly unmeasured?: Unmeasured | undefined;
     /** Uncommitted paths, when the working tree was read. */
     readonly dirty?: readonly string[] | undefined;
     readonly allowDirty?: boolean | undefined;
@@ -73,9 +95,37 @@ export declare function openTasks(brief: Brief, corpus: Corpus): Brief['tasks'];
  */
 export declare function renderBanner(template: readonly string[], values: Readonly<Record<string, string>>): string[];
 export declare function planArchive(corpus: Corpus, brief: Brief, request: ArchiveRequest): Plan;
+/** A plugin's answer to a refusal it may lift: which rule, for which path, and why. */
+export interface Waiver {
+    readonly rule: string;
+    readonly path: string;
+    readonly reason: string;
+}
+/**
+ * The refusals a plugin may lift. A tool that verifies a ruling can say a
+ * protected file was allowed to change, or that a file outside the scope was;
+ * whether a round is done is spec-brief's to say.
+ */
+export declare const WAIVABLE: readonly string[];
+/**
+ * The plan with the refusals plugins waived turned into notes. A waiver
+ * matches a blocking finding by rule and path: a protected-file finding is
+ * replaced by the note, and an out-of-scope finding loses the path and goes
+ * when none is left. A waiver that matches nothing changes nothing, and one
+ * for any other rule is ignored with a warning, which refuses under --strict
+ * as any warning does.
+ */
+export declare function applyWaivers(plan: Plan, waivers: readonly {
+    readonly plugin: string;
+    readonly waiver: Waiver;
+}[], strict?: boolean): Plan;
+export interface UnarchiveRequest {
+    /** Warnings refuse the reopening, as they fail lint. */
+    readonly strict?: boolean | undefined;
+}
 /**
  * Reopens an archived brief: the banner and the freeze come off, the status
  * goes back to the live word, and the links are rewritten for the directory
  * it returns to. What the round wrote stays in history, where it belongs.
  */
-export declare function planUnarchive(corpus: Corpus, brief: Brief): Plan;
+export declare function planUnarchive(corpus: Corpus, brief: Brief, request?: UnarchiveRequest): Plan;