@descent-vtt/spec-brief 0.2.7 → 0.3.0

package/CHANGELOG.md

@@ -1,6 +1,72 @@
 # Changelog
 
-Notable changes, newest first. Versions follow [semver](https://semver.org).
+Notable changes, newest first. Before 1.0, a minor release (0.2 to 0.3)
+carries anything that can turn a passing run red or change what a script
+reads - a finding not reported before, a changed exit code, input refused
+that was accepted, a flag, key or JSON field removed or renamed after a
+release of warning - and new features; a patch release carries only fixes
+that report less, crashes, speed and documentation, so `^0.3.0` takes no
+release that can turn a run red. This is the family's policy, recorded in
+[spec-core ADR-0009](https://github.com/DescentVTT/spec-core/blob/main/docs/adr/0009-versions-before-1-0.md);
+releases up to 0.2.7 came before it, and several of their patches changed
+what a run reports.
+
+## 0.3.0
+
+Deferral triggers and placeholders written in Chinese are read, the GitLab
+fingerprint no longer changes with a message's wording, `matrix` names a file
+the tree holds, and Chinese columns line up. spec-core is at 5666c96.
+
+### Changed
+
+- spec-core at 5666c96: `.//docs`, `./{/docs,src}` and `{.//docs,src}` read
+  as relative patterns, where they were refused as rooted (ADR-0005).
+  Upgrading: a scope refused before is read now; run `spec-brief matrix`.
+- A front-matter key may be written in any script: `狀態: 已接受` is an
+  `unknown-field` warning where it was a `front-matter` error, and
+  `status.field` may name `狀態` or `状态`. Upgrading: write `status:`, or
+  set `status.field`.
+- `archive`, `unarchive` and `new` write a status word such as `封存`
+  unquoted. Upgrading: a script matching the written line sees
+  `status: 封存`.
+- A deferral trigger that names only a time in Chinese (`下個月`,
+  `2026年10月`, `第三季`, full-width `Ｑ３`) is refused by `deferral-trigger`
+  (ADR-0003). Upgrading: name the event that brings the work back.
+- The default `placeholders` gain `待定`, `未定`, `待補`, `待確認` and their
+  Simplified forms, and a full-width colon ends a placeholder as a colon
+  does. Upgrading: fill the section, or list the old `placeholders`.
+- The GitLab fingerprint is built from the rule, the file, the brief and
+  the finding's subject, never its message. Upgrading: the first merge
+  request after upgrading shows each issue resolved and found again once.
+- `matrix` and `schedule` name a file the tree holds where both patterns
+  match one outside the protections, or say the file named is an example
+  (ADR-0005).
+- A pair the search could not decide is a `collision` (an error) when the
+  tree holds a file both patterns match and neither brief protects.
+  Upgrading: run the two briefs in different waves, or narrow a scope.
+
+### Added
+
+- `inTree` on each pair of patterns in `matrix` and `schedule` JSON
+  (`schemaVersion` stays 2); `meet` takes the tree's files.
+- A rule's result, a plugin's included, may carry a `subject`, which the
+  GitLab fingerprint is built from.
+
+### Fixed
+
+- `list`, `schedule` and `matrix` line up columns holding Chinese.
+- `unknown-field` no longer suggests a key that shares nothing with the one
+  written (`狀態` was asked about `id`).
+- `list` shows the status word the brief writes, such as `封存`, not its
+  English equivalent.
+- `list` and `schedule` show a title without the id it repeats.
+- `--help` lists the formats each command writes.
+
+### Documentation
+
+- The README is reorganised into lists and tables, with a "Scope patterns"
+  list of one rule per item; SECURITY.md says how to report a vulnerability
+  privately.
 
 ## 0.2.7
 

package/README.md

@@ -4,6 +4,8 @@
 
 A *brief* is the input to one round of work - for a coding agent or a person: what done looks like, what the round must not touch, and the checks that prove it finished. spec-brief manages briefs as files in your repository. It has no runtime dependencies, reads and writes nothing but Markdown in two directories, and never writes to git.
 
+spec-brief is one of the [spec-\* tools](https://github.com/DescentVTT/spec-core#the-family). The family's words - brief, round, wave, scope, the two kinds of plugin - are defined in [concepts](https://github.com/DescentVTT/spec-core/blob/main/docs/concepts.md), and the [tutorial](https://github.com/DescentVTT/spec-core/blob/main/docs/tutorial.md) takes one round from the brief to the archive in ten steps.
+
 ```bash
 npm install --save-dev @descent-vtt/spec-brief
 npx spec-brief init
@@ -48,11 +50,34 @@ Every privilege change issues a new session token and invalidates the old one.
 - [ ] a rotated token is rejected by every endpoint
 ```
 
-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`.
+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: not `Q3`, not `下個月` (next month), not `2026年10月`. 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]`.
+
+### Scope patterns
+
+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. The rules:
 
-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]`.
+- `**` 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 - on a brace alternative as on the whole pattern: `{src/,lib}` is `src/` or `lib`.
+- Each alternative names a path under the root, as a whole pattern does: `./` is refused, and so is `{./,src}`.
+- A pattern is relative to the repository root, so a leading `/` is refused, on an alternative as on the whole pattern: `/docs` and `{/docs,src}` alike. A leading `./` takes the slashes after it along, as POSIX reads them: `.//docs` is `docs`, and `./{/docs,src}` is `docs` or `src`.
+- After a name, a `/` inside braces names nothing: `docs/{/a,b}` is `docs/a` or `docs/b`.
+- 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.
 
-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 - on a brace alternative as on the whole pattern: `{src/,lib}` is `src/` or `lib`. Each alternative names a path under the root, as a whole pattern does: `./` is refused, and so is `{./,src}`. A pattern is relative to the repository root, so a leading `/` is refused, on an alternative as on the whole pattern: `/docs`, `.//docs` and `{/docs,src}` alike. After a name, a `/` inside braces names nothing: `docs/{/a,b}` is `docs/a` or `docs/b`. 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.
+### How a brief is read
+
+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.
+- **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 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. A definition is one where CommonMark reads it, opening a paragraph or under another: the shape of one under a paragraph's text, or in alt text, is text and stays as written.
 
 ## Commands
 
@@ -80,7 +105,16 @@ 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, 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`.
+Live briefs with their status, in the word the brief writes (`封存` where the configuration names it for archived), wave, task count, readiness and title.
+
+- **The title** is shown without the id it repeats: `new` writes `# 012 — Rotate tokens`, and the table has an id column, so the title shown is `Rotate tokens`. Only the brief's own id comes off, and only before a dash, a colon or a spaced hyphen, so `Fix - the login bug` is shown whole. `schedule` shows titles the same way, and `--format json` gives the title as written.
+- **A brief is *ready*** when every brief it depends on is archived, and it is neither a draft nor deferred.
+
+| Option | Shows |
+| --- | --- |
+| `--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`. |
 
 ### `spec-brief matrix`
 
@@ -96,11 +130,21 @@ 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 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.
+Scopes are intersected as globs, not compared as strings: the two above share no prefix and still meet. Exit 1 on a collision.
+
+- **The file named** is one both patterns match and neither brief protects - always a file, never a directory. It is a file the tree holds where there is one, the first in git's order; where the tree holds none, it is the shortest path the search built, said to be an example: `both cover src/newmod/a.ts, an example not in the tree`. `--format json` says which, as `inTree` on each pair of patterns: `true`, `false`, or `null` when the tree could not be read.
+- **One collision per pair of briefs**: two briefs whose scopes meet in several places are one collision, listing every pair of patterns that meets.
+- **Unscoped**: a brief with no scope is reported as unscoped rather than counted as safe.
+- **Undecided**: 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 - unless the tree holds a file both patterns match and neither brief protects, which proves the 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.
+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
@@ -118,32 +162,96 @@ 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.
+Each move says why:
+
+- 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;
+- the dependency that sets the earliest wave;
+- for every wave passed over, the brief there and the file both would write.
+
+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, in one transaction, and writes nothing over a cycle:
+
+- every other line stays as it was;
+- 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.
+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 | When |
+| --- | --- |
+| `0` | Every declared wave holds. |
+| `1` | A brief declares no wave or one that does not hold, or the dependencies form a cycle. |
+| `2` | 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 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;
+- 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 is 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` - one refusal per file, naming it, unless a plugin that verifies rulings [waives it](#waiving-a-refusal).
+- the round's commit changed a file in `protectedFiles` - one refusal per file, naming it, unless a spec-brief plugin that verifies rulings [waives it](#waiving-a-refusal).
+
+Two warnings, which `--strict` turns into refusals:
+
+- 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, in one transaction, it:
 
-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.
+- 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;
+- 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`. Archiving an archived brief does nothing and exits 0.
+
+| Option | What it does |
+| --- | --- |
+| `--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>` | What the round did, in the banner. |
+| `--dry-run` | Prints the plan and the banner, and writes nothing. |
 
 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 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.
+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:
+
+1. The status line is written in its plain spelling.
+2. A relative link that had to be rewritten comes back in its shortest form (`./b.md` returns as `b.md`).
+3. 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.
+4. 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`, `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.
+| Flag | What it does |
+| --- | --- |
+| `--root <dir>` | Runs from another directory. |
+| `--config <file>` | Names the configuration. |
+| `--no-config` | Uses the defaults. |
+| `--format <format>` | `pretty` by default, or `json`; `lint`, `matrix` and `schedule`, which report findings, also write `sarif`, `github` and `gitlab`, and `--help` lists each command's formats. |
+| `--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`, `--no-color` | Override `NO_COLOR`, `FORCE_COLOR` and the terminal check. |
+| `--help`, `--version` | Do what they say. |
+
+**Exit codes:**
 
-**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.
+| Code | Means |
+| --- | --- |
+| `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.
 
 ## Configuration
 
@@ -157,11 +265,11 @@ 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", "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. |
+| `status` | `{ "field": "status", "draft": "draft", "active": "active", "deferred": "deferred", "archived": "archived" }` | The words a repository uses. `field` may be a key of any script, `狀態` as well as `status`, followed by an ASCII colon in the brief; `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` is below. |
 | `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. |
+| `placeholders` | `TBD`, `TODO`, `FIXME`, ..., `待定`, `未定`, `待補`, `待確認` and their Simplified forms | Words that mark a section as unwritten: alone, or followed by a space, a colon (`：` too), a period or a dash. |
 | `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` | What a note under an open box starts with to close it. |
@@ -172,6 +280,12 @@ Reopens an archived brief: the banner and the hash come off, the status goes bac
 | `rules` | `{}` | Severity per rule: `off`, `note`, `warning` or `error`. |
 | `plugins` | `[]` | Modules that contribute rules: a path or package, or `{ module, options }`. |
 
+A section's `hint` says what the section must answer, so a tool helping to write a brief can ask for each section by what it is for:
+
+- 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;
+- the JSON of `list` and `lint` reports it.
+
 A repository whose briefs have eight ordered sections, `proposed` and `archived` for words, and a banner of its own:
 
 ```json
@@ -198,9 +312,7 @@ 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. A definition is one where CommonMark reads it, opening a paragraph or under another: the shape of one under a paragraph's text, or in alt text, is text and stays as written.
+How a heading fills a section, and what counts as a heading, a task or a link, is under [How a brief is read](#how-a-brief-is-read).
 
 ## Rules
 
@@ -218,21 +330,21 @@ A brief is read as CommonMark reads it wherever that decides what is code or a c
 | `missing-section` | error | A required section that is absent. |
 | `duplicate-section` | warning | A section that appears twice. |
 | `empty-section` | error | A section with no content; a comment is not content. A warning in a draft. |
-| `placeholder` | error | A section holding only `TBD`, `TODO` or an empty box. A warning in a draft. |
+| `placeholder` | error | A section holding only `TBD`, `TODO`, `待定` or an empty box. A warning in a draft. |
 | `missing-checklist` | error | A checklist section with no task item. A warning in a draft. |
 | `must-contain` | error | A section without the text the configuration requires of it. |
 | `section-order` | error | Sections out of the configured order, when one is configured. |
 | `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". |
+| `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`, `下個月`, `2026年10月`, `第三季` - or a placeholder, rather than an event such as "when the second tenant signs". Full-width `Ｑ３` reads as `Q3`. |
 | `glob` | error | A scope pattern spec-brief cannot read. |
 | `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. Inside braces the advice is the pattern written with the `/` added, `lib/{util,new/}`, or the alternative in an entry of its own, `lib/new/`. |
 | `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`). |
-| `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. |
+| `collision-undecided` | warning | Two briefs in one wave whose collision the search could not decide within its budget and no file of the tree proves (`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. |
@@ -250,7 +362,12 @@ A brief is read as CommonMark reads it wherever that decides what is code or a c
 - 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. `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:
+| Format | What it writes |
+| --- | --- |
+| `github` | Workflow commands, which annotate the pull request with no upload and no permission. |
+| `sarif` | SARIF 2.1.0, for code-scanning upload. |
+| `gitlab` | A GitLab Code Quality report - an array of `{ description, check_name, fingerprint, severity, location: { path, lines: { begin } } }` - for a merge request to show. |
+| `json` | 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. |
 
 ```yaml
 spec-brief:
@@ -260,7 +377,11 @@ spec-brief:
       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.
+In the GitLab report:
+
+- 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 `description` is the message and the next action.
+- The fingerprint is a SHA-256 of what the finding is: its rule, its file, its brief, and what it is about there - a section, a pattern, a dependency, the other brief of a pair - never the message, the hint or the line. So a finding that moves, or is worded another way, or a collision that names another file both briefs write, is the same issue; two findings alike in all four, such as two problems in one front matter, are told apart by their order.
 
 ## As a library
 
@@ -282,7 +403,7 @@ Everything below the engine is a pure function of text: `parseBrief`, `lint`, `c
 
 ## Plugins
 
-A plugin is a module that exports `{ name, rules }`, or a function of its configured options that returns one. Its rules run beside the built-in ones as `<name>/<rule>`, and configuration sets their severity like any other.
+A plugin here is a spec-brief plugin, a module this tool loads, not a Claude Code plugin. It exports `{ name, rules }`, or a function of its configured options that returns one. Its rules run beside the built-in ones as `<name>/<rule>`, and configuration sets their severity like any other.
 
 ```js
 // tools/departures.mjs
@@ -301,13 +422,21 @@ export default (options) => ({
 { "plugins": [{ "module": "./tools/departures.mjs", "options": { "marker": "Signed-off-by" } }] }
 ```
 
+A result is `{ line, message }`, with optional fields:
+
+| Field | What it is |
+| --- | --- |
+| `hint` | The next action. |
+| `severity` | Lower than the rule's, for this one finding. |
+| `subject` | What the finding is about, where the rule can report several in one brief; GitLab's fingerprint is built from it. |
+
 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.
+A plugin may also export `waive`, which lets the archive accept a change its own check allows - spec-harness's spec-brief plugin verifies a signed ruling for a protected path, which spec-brief does not know how to read.
 
 ```js
 export default () => ({
@@ -321,7 +450,11 @@ export default () => ({
 });
 ```
 
-`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.
+- `findings` are the archive's refusals, as a frozen copy: a hook reads them and cannot change them, and a write to them throws.
+- Two refusals can be waived, and no others: `protected-file`, one per file, which names its `path`; and `out-of-scope`, which refuses only under `--strict` and lists its `paths`.
+- 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
 
@@ -332,7 +465,7 @@ export default () => ({
 
 ## Design
 
-The decisions and what they cost are in [`docs/adr/`](https://github.com/DescentVTT/spec-brief/blob/main/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). Working on spec-brief itself: [CONTRIBUTING.md](https://github.com/DescentVTT/spec-brief/blob/main/CONTRIBUTING.md); reporting a vulnerability: [SECURITY.md](https://github.com/DescentVTT/spec-brief/blob/main/SECURITY.md).
 
 ## License
 

package/dist/cli.d.ts

@@ -23,8 +23,8 @@ export interface CliIO {
     readonly cwd?: string;
     readonly env?: Readonly<Record<string, string | undefined>>;
 }
-export declare const HELP = "spec-brief - lint, schedule and archive task briefs\n\nUsage:\n  spec-brief <command> [options]\n\nCommands:\n  init                  write .spec-brief.json and the brief directories\n  new <title>           scaffold a brief with the next free id\n  lint [brief...]       check briefs against the configuration\n  list                  briefs with their status, wave and readiness\n  matrix                scope collisions between briefs in the same wave\n  schedule              the waves the live briefs can run in, computed\n  archive <brief>       close a round: check it, stamp it, freeze it, move it\n  unarchive <brief>     reopen an archived brief\n\nOptions for every command:\n  --root <dir>          run from this directory instead of the current one\n  --config <file>       use this configuration file\n  --no-config           use the defaults, ignoring any configuration file\n  --format <format>     pretty (default), json, sarif, github or gitlab\n  --strict              treat warnings as errors\n  --no-git              leave git out; read the files on disk instead\n  --color, --no-color   force colour on or off\n  -h, --help            show this help\n  -v, --version         show the version\n\ninit:\n  --briefs <dir>        the directory of live briefs; default briefs\n  --archive <dir>       the directory of archived briefs; default <briefs>/archive\n\nnew:\n  --id <id>             use this id instead of the next free one\n  --type <type>         a brief type from the configuration\n  --wave <n>            the wave it runs in\n  --depends-on <ids>    comma-separated ids it runs after\n  --date <YYYY-MM-DD>   the date in its front matter; default today\n\nlist:\n  --ready               only briefs that can run now: dependencies archived, not drafts or deferred\n  --archived            include archived briefs\n\nmatrix:\n  --all-waves           compare every live brief, whatever its wave\n\nschedule:\n  --write               write each proposed wave into its brief's front matter\n\narchive:\n  --pr <number>         the pull request the round merged in\n  --commit <rev>        the commit the round landed as\n  --base <rev>          the branch it started from; the diff runs from the merge base\n  --summary <text>      what the round did, for the banner\n  --date <YYYY-MM-DD>   the archival date; default today\n  --allow-dirty         archive although the tree has uncommitted work\n  --dry-run             print the plan and change nothing\n\nunarchive:\n  --dry-run             print the plan and change nothing\n\nExit codes: 0 clean, 1 findings or refused, 2 the run could not be trusted.\n";
 type Values = Record<string, string | boolean | undefined>;
+export declare const HELP: string;
 interface Parsed {
     readonly command: string | undefined;
     readonly values: Values;

package/dist/cli.js

@@ -24,6 +24,63 @@ export class UsageError extends Error {
         this.name = 'UsageError';
     }
 }
+const GLOBAL = {
+    root: { type: 'string' },
+    config: { type: 'string' },
+    'no-config': { type: 'boolean' },
+    format: { type: 'string' },
+    strict: { type: 'boolean' },
+    'no-git': { type: 'boolean' },
+    color: { type: 'boolean' },
+    'no-color': { type: 'boolean' },
+    help: { type: 'boolean', short: 'h' },
+    version: { type: 'boolean', short: 'v' },
+};
+const COMMANDS = {
+    init: { options: { briefs: { type: 'string' }, archive: { type: 'string' } }, formats: ['pretty', 'json'] },
+    new: {
+        options: {
+            id: { type: 'string' },
+            type: { type: 'string' },
+            wave: { type: 'string' },
+            'depends-on': { type: 'string' },
+            date: { type: 'string' },
+        },
+        formats: ['pretty', 'json'],
+    },
+    lint: { options: {}, formats: FORMATS },
+    list: { options: { ready: { type: 'boolean' }, archived: { type: 'boolean' } }, formats: ['pretty', 'json'] },
+    matrix: { options: { 'all-waves': { type: 'boolean' } }, formats: FORMATS },
+    schedule: { options: { write: { type: 'boolean' } }, formats: FORMATS },
+    archive: {
+        options: {
+            pr: { type: 'string' },
+            commit: { type: 'string' },
+            base: { type: 'string' },
+            summary: { type: 'string' },
+            date: { type: 'string' },
+            'allow-dirty': { type: 'boolean' },
+            'dry-run': { type: 'boolean' },
+        },
+        formats: ['pretty', 'json'],
+    },
+    unarchive: { options: { 'dry-run': { type: 'boolean' } }, formats: ['pretty', 'json'] },
+};
+/**
+ * The formats each command writes, read from the table `main` checks a
+ * `--format` against, so the help names no format a command refuses: the
+ * finding formats are `lint`'s, `matrix`'s and `schedule`'s alone.
+ */
+function formatsHelp() {
+    const groups = new Map();
+    for (const [command, spec] of Object.entries(COMMANDS)) {
+        const formats = spec.formats.join(', ');
+        groups.set(formats, [...(groups.get(formats) ?? []), command]);
+    }
+    const rows = [...groups].map(([formats, commands]) => [commands.join(', '), formats]);
+    const width = Math.max(...rows.map(([commands]) => commands.length));
+    return rows.map(([commands, formats]) => `  ${commands.padEnd(width)}  ${formats}`).join('\n');
+}
 export const HELP = `spec-brief - lint, schedule and archive task briefs
 
 Usage:
@@ -43,13 +100,16 @@ Options for every command:
   --root <dir>          run from this directory instead of the current one
   --config <file>       use this configuration file
   --no-config           use the defaults, ignoring any configuration file
-  --format <format>     pretty (default), json, sarif, github or gitlab
+  --format <format>     the output format, pretty by default; each command's are below
   --strict              treat warnings as errors
   --no-git              leave git out; read the files on disk instead
   --color, --no-color   force colour on or off
   -h, --help            show this help
   -v, --version         show the version
 
+Formats:
+${formatsHelp()}
+
 init:
   --briefs <dir>        the directory of live briefs; default briefs
   --archive <dir>       the directory of archived briefs; default <briefs>/archive
@@ -85,48 +145,6 @@ unarchive:
 
 Exit codes: 0 clean, 1 findings or refused, 2 the run could not be trusted.
 `;
-const GLOBAL = {
-    root: { type: 'string' },
-    config: { type: 'string' },
-    'no-config': { type: 'boolean' },
-    format: { type: 'string' },
-    strict: { type: 'boolean' },
-    'no-git': { type: 'boolean' },
-    color: { type: 'boolean' },
-    'no-color': { type: 'boolean' },
-    help: { type: 'boolean', short: 'h' },
-    version: { type: 'boolean', short: 'v' },
-};
-const COMMANDS = {
-    init: { options: { briefs: { type: 'string' }, archive: { type: 'string' } }, formats: ['pretty', 'json'] },
-    new: {
-        options: {
-            id: { type: 'string' },
-            type: { type: 'string' },
-            wave: { type: 'string' },
-            'depends-on': { type: 'string' },
-            date: { type: 'string' },
-        },
-        formats: ['pretty', 'json'],
-    },
-    lint: { options: {}, formats: FORMATS },
-    list: { options: { ready: { type: 'boolean' }, archived: { type: 'boolean' } }, formats: ['pretty', 'json'] },
-    matrix: { options: { 'all-waves': { type: 'boolean' } }, formats: FORMATS },
-    schedule: { options: { write: { type: 'boolean' } }, formats: FORMATS },
-    archive: {
-        options: {
-            pr: { type: 'string' },
-            commit: { type: 'string' },
-            base: { type: 'string' },
-            summary: { type: 'string' },
-            date: { type: 'string' },
-            'allow-dirty': { type: 'boolean' },
-            'dry-run': { type: 'boolean' },
-        },
-        formats: ['pretty', 'json'],
-    },
-    unarchive: { options: { 'dry-run': { type: 'boolean' } }, formats: ['pretty', 'json'] },
-};
 /** Global options that take a value, so the value is not mistaken for the command. */
 const VALUED = new Set(['--root', '--config', '--format']);
 function commandOf(argv) {