# Changelog
All notable changes to this project are recorded here. Format follows
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the project
adheres to semantic versioning where `_format` schema bumps are major
version moves and CLI surface additions are minor.
## [Unreleased]
## [0.3.1] — 2026-05-18
Closes the four real frictions from the 0.3.0 agent sweep. No new
commands; the loop just actually closes now.
### Fixed — status-aware post-commit (REQ-0106)
- **`req review --summary`** now reads each cited REQ's current
status and prints the LEGAL next transition for that status, not
a one-size-fits-all `--promote` suggestion. Draft gets "advance
to proposed", Approved gets "mark implemented", Implemented gets
"verify --promote", Verified/Obsolete get a quiet "no action"
note.
- **Pre-commit hook's pass path is silent.** The 0.3.0 hook
duplicated the post-commit summary; users saw the same line
twice per commit. Single source of truth now lives in the
post-commit hook.
### Fixed — `req setup` is actually one-shot
- **Merge driver auto-registered.** Setup now runs the two `git
config merge.req-merge.*` commands inline after writing
`.gitattributes`. No more "next steps you must paste"; `req
doctor` reports the driver as active on a fresh bootstrap.
- **Next-steps example is copy-paste-runnable.** The 0.3.0 example
was `req add ... -k functional -p must` with no `-a`, which the
validator immediately rejects (functional reqs need acceptance).
Now includes a sample acceptance criterion.
### Fixed — strict mode sticky on reinstall
- `req hooks install` (no flag) now inherits the existing hook's
mode. A project that's strict stays strict on re-install. Pass
`--strict` explicitly to flip from default to strict.
### CI
- 0.3.0 `cargo fmt` failure in `src/mcp.rs` fixed in 5b41e9c
(trailing-comment alignment + vec macro collapse). Green across
ubuntu/macos/windows + lint.
## [0.3.0] — 2026-05-18
Reframes the tool around **spec-memory that survives between
conversations**, not enforcement that catches mistakes. Same
guarantees, surfaced through reminders an agent actually wants to
read. New command surface and new docs voice.
### Added — adoption surface
- **`req brief` (REQ-0104)** — session-start summary. Project name,
delivery percentage, what's queued (single highest-priority pick),
what's loose (Implemented but not Verified, Drafts). Default short
(5-10 lines, fits an agent context); `--full` for the dashboard;
`--json` for tooling. The first thing an agent should run in a new
conversation.
- **Post-commit hook (REQ-0103)** — calm one-line impact summary
after every commit that touched source files. Never gates. Names
the cited REQs and points at the natural next status change.
Installed alongside pre-commit; both removed by `req hooks
--uninstall`. `req hooks install --force` upgrades an existing
managed pre-commit hook.
- **`req setup` (REQ-0105)** — one-shot bootstrap: init + git hooks
(pre + post) + AGENTS.md managed block. Idempotent. `--strict`
for hunk-level pre-commit; `--no-hooks` / `--no-agents` to opt
out. `--name` overrides the inferred project name.
- **Pre-commit gate's pass path now prints a summary** instead of
staying silent: `req: N source file(s) staged · cites REQ-A,
REQ-B · reminder: ...`. Silent on pure-docs commits.
### Cross-surface parity
- New MCP tool **`req_brief`** with an explicit "run this FIRST"
framing in the tool description. `req_setup` is humans-only by
design (interactive bootstrap).
- New TUI menu entry **"Brief (where are we now?)"** as the first
item.
### Voice / framing — same content, friendlier register
- `req help agents` rewritten. Leads with "why this exists" and
names the vibecoding problem directly: conversations end, the
spec must survive. The trigger table becomes "WHEN THE USER ASKS
FOR SOMETHING NEW" / "WHILE YOU WORK" / "WHEN YOU FINISH
SOMETHING".
- AGENTS.md cardinal-rules block rewritten as "The handful of
things that matter" — same discipline, less lawyer.
- README adds two TL;DR sections (agents + humans) before the
Mission. Quick start now headlines `req setup`.
### Polish (rolled in from the 0.2.5 agent sweep)
- **REQ-V-0019** now names `req test record` / `req verify` as the
fix path, not just the symptom.
- **REQ-V-0022** quotes the actual hedge words that fired
(`perhaps`, `maybe`, `probably`) instead of just counting them.
- **REQ-V-0008** trimmed — points at `req help best-practice` for
the modal-verb gloss.
- **`req lint`** quality section de-dupes against the validator
(REQ-V-0013) so a single requirement is never named twice with
different thresholds.
- **`req help lint`** section added (was missing in 0.2.5).
- **`short_rationale` JSON shape** is now `{id, words}` objects,
consistent with the rest of the lint quality block.
- **Markerless check** excludes Draft status (consistent with the
no-test-record check). "Active" = Proposed-or-later everywhere.
- **`req validate` findings sort by REQ-ID** ascending. Stable
output across runs.
- **`req diff HEAD~1` on a fresh repo** returns a friendly hint
instead of leaking git's raw `fatal: invalid object name`.
### Project state
- 100 / 100 requirements Verified, 100% delivery.
- `req validate` clean.
## [0.2.5] — 2026-05-18
Quality pass. No breaking changes; the project now validates clean
against its own ruleset.
### Exemplar cleanup
- Seven requirement statements rewritten to be atomic:
REQ-0039, REQ-0066, REQ-0067, REQ-0084, REQ-0085, REQ-0090,
REQ-0098. Detail moved into acceptance criteria where it belongs.
`req validate` on `project.req` now reports
`OK — 95 requirement(s), no findings.`
### Validator wording (REQ-V-0001 .. REQ-V-0015, REQ-V-0022)
- Every message now names the rule and tells you the fix. The
rule codes are unchanged; only the message text is sharper.
Examples:
- REQ-V-0010 names *why* it tripped (`semicolon`, `repeated
modal`, or `multiple "and" joins`) and suggests `req split`.
- REQ-V-0009 spells out what "measurable criterion" means.
- REQ-V-0013 reports the actual word count.
- REQ-V-0015 quotes the criterion length and shows an example.
- REQ-V-0008 lists the four normative modals with their meanings.
### Added — `req lint` (REQ-0101)
- New `req lint` command produces a project-wide quality audit
beyond `req validate`: marker coverage, rationale length,
acceptance count, test-record presence, verification-kind mix.
- Output is markdown by default; `--json` for tooling. Exit code
reflects validator errors only — lint observations never gate.
- Available as `req_lint` MCP tool and `Lint (quality audit)` TUI
menu entry, preserving cross-surface parity.
## [0.2.4] — 2026-05-18
### Added — strict pre-commit mode (REQ-0100)
- **`req hooks install --strict`** writes a pre-commit hook that
invokes `req review --staged --gate --marker-near-hunks 50`, so
edits inside an already-marked file still need a marker near the
changed hunk. Closes the file-level loophole observed live during
0.2.3 implementation.
- Re-running `req hooks install` (with or without `--strict`)
swaps modes deterministically.
- **`req doctor`** surfaces the active gate mode (`[strict mode]`
or `[default mode]`) on the pre-commit-hook check.
- **`req help integration`** documents both modes and the tradeoff.
## [0.2.3] — 2026-05-18
Clears the six Draft requirements added in 0.2.1.
### Validator
- **REQ-0093 / REQ-V-0019 gated on status >= Implemented.** A
`verifies` link on a Draft/Proposed/Approved source no longer
triggers the "no test record" warning; it only fires once the
requirement actually reaches Implemented. Stops the validator
from crying wolf during the early lifecycle.
- **REQ-0095**: `req add` warns when the new title is highly
similar (Jaccard ≥ 0.65) to a requirement that became Obsolete
in the last 60 days, suggesting `req update` or `req split
--keep-original` instead of a fresh ID.
### CLI surface
- **REQ-0094**: every `value_enum` arg (`--status`, `--kind`,
`--priority`, `--by`, etc.) is now case-insensitive.
`Implemented`, `IMPLEMENTED`, and `implemented` all fold to the
canonical lowercase form.
### LLM hook
- **REQ-0096**: new `REQ_VALIDATE_LLM_SHELL` env var overrides the
shell used to invoke the hook. Set to `bash`, `pwsh`, or `sh` so
shell-script hooks work on Windows when Git Bash or PowerShell is
on PATH and `cmd.exe` is not finding the interpreter.
- **REQ-0097**: new `REQ_VALIDATE_LLM_CONCURRENCY` env var caps the
number of in-flight hook calls. Default 1 (sequential, matches
0.2.x). Findings are sorted by id afterwards so output is stable
regardless of completion order. 10s timeout remains per-call.
### Review gate
- **REQ-0098**: new `--marker-near-hunks N` flag on `req review`
requires a `// REQ-NNNN:` comment within N lines of each changed
hunk, not merely somewhere in the file. Default 0 keeps the
0.2.x file-level behaviour. Use a positive value (e.g. 50) for
strict hunk-level enforcement on real PRs.
### Test fixture update
- `req_0077_verifies_link_without_test_record_warns` walks the
fixture to Implemented before asserting the rule fires, matching
the new REQ-V-0019 gating semantics.
## [0.2.2] — 2026-05-18
### Added — pre-commit gate (REQ-0099)
- **`req hooks install` now wires the gate into the pre-commit
hook**, not just CI. An agent (or human) committing code without a
`// REQ-NNNN:` marker is blocked locally with the same educational
message the CI gate uses, listing the offending files and naming
the two fix paths (add a marker citing an existing REQ, or
`req add` a new one then mark the code).
- **`REQ_SKIP_GATE=1 git commit ...`** bypasses the gate for genuine
WIP / rebase / merge cases. The env var leaves a trace in shell
history rather than being silent.
- **`req review --staged`** is the new scope mode the hook uses:
reads `git diff --cached --name-only` instead of `git diff
<base>...HEAD`. Works on the first commit (HEAD doesn't have to
exist) — `--gate` does NOT fail-closed in staged mode.
- **CHANGELOG.md / README.md / AGENTS.md added to default `--ignore`**
so descriptive REQ-ID mentions in docs aren't read as ghosts.
### Upgrade path
- Existing managed pre-commit hooks are upgraded by re-running:
`req hooks install --force`. Hooks not managed by `req` are left
alone unless `--force` is passed.
## [0.2.1] — 2026-05-17
Closes every finding from the 0.2.0 adversarial agent sweep.
### Fixed — `req review --gate` hardening (P1)
- **Broader source-extension defaults** for the markerless check.
Now covers 50+ languages (Kotlin, Swift, Scala, C#, Ruby, PHP, Lua,
Haskell, OCaml, Elixir, Erlang, Clojure, Dart, Zig, Nim, V, Crystal,
F#, Groovy, Perl, shell, PowerShell, Objective-C, …). `--ext` to
override. Was: hardcoded 10-entry Rust-leaning list, silently
invisible to Kotlin/Swift/etc.
- **Fail-closed on missing base ref under --gate.** A CI YAML typo
(`origin/master` vs `origin/main`) previously disabled the gate
silently; now `req review --base bogus --gate` exits non-zero with
a clear error. Advisory mode (no `--gate`) still produces the
report.
- **Comment-context marker matching.** A `REQ-NNNN` token only
counts as a marker on lines that look like a comment (start with
`//`, `#`, `--`, `;`, `*`, or contain `//`/`#` before the token).
String literals, doc attributes, and incidental string matches no
longer satisfy the gate.
- **Default `--ignore` patterns** carve out test trees, build
helpers, generated code, and the .req project file itself. The
spec file's instructions block contains example REQ-NNNN tokens
that should never be treated as markers or ghosts. `--ignore
<glob>` to add more.
- **Ghosts deduplicated** to one finding per (id, file) pair, not
one per textual occurrence.
- **Path separators normalised** to `/` everywhere in markdown and
JSON output.
### Fixed — LLM hook usability (P1)
- **Stdin closed after payload write.** A naive
`sys.stdin.read()` hook used to hang until the 10s timeout because
the pipe stayed open. Now it returns immediately.
- **`REQ_VALIDATE_LLM_CMD` documented** in `req help env` with the
full stdin/stdout/exit-code/timeout contract, an example, and a
caching note.
### Fixed — split + ergonomics (P2)
- **`req split` inherits acceptance** from the parent. Functional
reqs could not be split pre-0.2.1 because empty acceptance on
part #1 tripped REQ-V-0014.
- **`req add` prints a follow-up nudge** pointing at the
`// REQ-NNNN:` marker convention and `req coverage --path src`.
Closes the discoverability gap between "REQ created" and "REQ
referenced from code".
### Notes
- Sequential per-requirement hook calls remain the model. For paid
LLM APIs cache by `sha256(statement)` in your hook; bounded
parallelism is a 0.3 design question.
## [0.2.0] — 2026-05-17
### Added — new commands and rules
- **`req split <id> --into "..."`** (REQ-0085): interactive (or
flag-driven) split of a compound requirement into N atomic ones.
Children inherit kind / priority / tags; the original is
soft-retired to Obsolete with history naming its replacements.
`--keep-original` for additive splits.
- **`req review --base <ref>`** (REQ-0086): single-shot PR-style
markdown report combining validate + coverage + stale + audit +
the changed-requirement diff. `--gate` makes it CI-friendly: exits
non-zero on validate errors, coverage ghosts, OR — critically —
changed source files that contain zero `REQ-NNNN` markers (the
"shipped new behaviour without a backing requirement" rule that
let three releases slip through).
- **`req status --tag`** (REQ-0092): milestone-scoped status report.
AND semantics across multiple `--tag` flags.
- **REQ-V-0023** (REQ-0087): opt-in external statement-quality
hook. When `REQ_VALIDATE_LLM_CMD` is set, the validator pipes a
small JSON stub on stdin and surfaces the hook's `{ok, message}`
verdict. 10s timeout per requirement; never aborts validation on
hook failure. Default validator stays deterministic and offline.
### Added — MCP surface
- `req_review` and `req_split` mirror the CLI commands for agents.
- `req_validate` output now includes `rule_code` on every finding so
agents can pattern-match REQ-V-0021 cycles deterministically.
### Added — CI gate
- `.github/workflows/ci.yml` runs `req review --gate` on every PR
against `origin/${{ base_ref }}`. New source files without a REQ
marker fail the build.
### Added — process discipline
- `AGENTS.md` cardinal rule 7: "New behaviour gets a REQ first, then
the code." Names `req review --gate` as the enforcement
mechanism.
### Backfilled requirements
Catches up the spec to ship-state. Nine new REQs cover the 0.1.2 /
0.1.3 / 0.2.0 surface that landed without a backing requirement:
REQ-0084 (state machine), REQ-0085 (split), REQ-0086 (review),
REQ-0087 (LLM hook), REQ-0088 (REQ-V-0021 cycle), REQ-0089
(REQ-V-0022 hedge stacking), REQ-0090 (ID normalisation),
REQ-0091 (repair --force), REQ-0092 (status --tag). Each cited from
source via a `// REQ-NNNN:` line.
## [0.1.3] — 2026-05-17
### Changed (lifecycle policy)
- **Full state-machine guard on `req update --status`** (was: only the
approach to Verified). The five-step ladder is now the discipline:
Draft -> Proposed -> Approved -> Implemented -> Verified. Natural
(free) transitions are forward-one-step, any-state -> Obsolete, and
a Draft carve-out that allows Draft -> Proposed or Draft -> Approved
directly (sketch-then-slot workflow). Everything else — skip-forward,
any backward move, resurrection from Obsolete, leaving Verified for
anything-but-Obsolete — requires `--force --reason "..."` so
irregular moves stay deliberate and traceable.
- Same policy applied to `req batch` `update` mutations via a
`"force": true` per-mutation flag.
This is a deliberate breaking change for anyone driving `req update`
non-naturally; the fix is to either walk the lifecycle one step at a
time or pass `--force` for the irregular step.
## [0.1.2] — 2026-05-17
### Fixed (P0 — closed bypasses around 0.1.1 guards)
- **`req batch` lifecycle guard**: `{kind: update, status: verified}`
no longer slides Draft straight to Verified. Pass
`"force": true` per-mutation to override. Same gate as direct
`req update --force`.
- **`req batch` cycle detection**: link mutations now cycle-check
every asymmetric kind (parent, depends-on, refines, verifies).
Batch can no longer install cycles that `req link` rejects.
### Fixed (P1 — second-line defences and trapped states)
- **`req validate` reports graph cycles** as REQ-V-0021. Each cycle
is reported once, attributed to its smallest-ID member. Catches
cycles introduced by old binaries, merges, or hand-edits.
- **`req repair --force`** re-signs even when validation errors
remain. Closes the deadlock where a hand-edit that broke both the
hash AND validation left every command stuck. With --force the
errors surface via `req validate` instead of the integrity check.
- **`req diff <REQ-ID>`** returns a friendly hint pointing at
`req show` instead of leaking git's
`fatal: invalid object name`.
### Improved (validator quality)
- **REQ-V-0010 compound-statement rebuilt**. "A and B and C" now
triggers with a single modal verb (was the headline false-
negative). "X, Y, and Z" Oxford-comma lists suppressed when there
are 2+ commas and a single " and " (was the headline false-
positive).
- **REQ-V-0022 hedge stacking**: 2+ of {perhaps, probably, maybe,
possibly, might, roughly, potentially} now warns.
- **`req update` quiet-by-default**: only re-emits field-scoped
warnings whose inputs the user actually edited. Status / priority
/ tag nudges no longer replay the same compound warnings each
time.
### Improved (CLI polish)
- **Case- and pad-insensitive ID lookup**: `req-1`, `REQ-1`,
`req-0001`, even bare `1` now resolve to `REQ-0001`. Misses on
near-IDs suggest "did you mean REQ-0042?".
- **`req add -t/-s/-r` marked required** in `--help` (via
`required_unless_present_any` on `--interactive`/`--from-json`).
- **`req retire` alias** for `req delete` matches the soft-retire
semantics (Obsolete with links preserved). `req delete` still
works for muscle memory.
- **`req doctor` signing is advisory**, not gating. Doctor's overall
exit code only flips red on load-bearing setup gaps. Signing
surfaces as `[WARN]`.
- **`req hooks install` writes `.gitattributes` once**, listing all
added lines under a single update message instead of three.
- **`req batch` malformed JSON** wraps the serde error with a hint
at `req schema batch`.
- **`req add` flushes stderr** before the stdout "Added" line so
validation WARN lines can't appear after the success message.
## [0.1.1] — 2026-05-17
### Fixed
- **Lifecycle guard on `req update --status verified`**: reject direct
jumps from any status other than Implemented. Pass `--force` to
override (e.g. when correcting history). Closes a path where a Draft
could be marked Verified in one command.
- **Lifecycle guard on `req verify --promote`**: only auto-promotes
from Implemented. Adds `--force` (CLI) / `force` (MCP) for history
fixes.
- **Link cycle detection** generalised across all asymmetric link
kinds: `parent`, `depends-on`, `refines`, `verifies`. Previously
only `parent` was checked.
- **`--json` errors** now write the structured envelope to stdout (the
parseable channel) and exit non-zero without propagating the anyhow
chain to stderr. Callers can `JSON.parse(stdout)` directly.
- **`req diff <ref>`** accepts a single ref as shorthand for
`<ref>..HEAD`, matching `git diff <ref>` muscle memory. Same in MCP
`req_diff`.
- **`req_import` MCP error envelope** no longer concatenates anyhow's
Display chain — first envelope-shaped line wins.
- **`req_export` MCP** csv/html now actually returns the rendered
output instead of an isError hint.
- **`req_help` MCP description** points at `section="_index"` as the
authoritative section list (was a hardcoded list that drifted).
- **`req_next` default** excludes Verified as well as Obsolete — the
"no filter" call no longer suggests already-shipped work.
### Internal
- New `first_envelope_line` helper for MCP subprocess error rendering;
scans stdout (the envelope channel) before stderr.
- Regression tests for every fix in `tests/coverage_boost.rs` and
`tests/mcp_tools.rs`.
## [0.1.0] — 2026-05-17
### Added
- `req batch` for transactional multi-mutation JSON input (REQ-0066).
- `req import` ingest from markdown or JSON, routed through the validator (REQ-0067).
- `req doctor` per-clone setup audit (pre-commit hook, merge driver, gitattributes pin, signing) (REQ-0064).
- `req diff <base>..<head>` per-requirement summary across git revs (REQ-0069).
- `req coverage --by-file` and `--unlinked-files` and `--remap` (REQ-0033/0032/0034).
- `req coverage --strict` exits non-zero on findings; CI/pre-commit gate (REQ-0065).
- `req add --from-json` and `req add` with JSON document input (REQ-0072).
- `req schema [add|batch|import]` publishes the JSON Schemas for structured input (REQ-0078).
- `req audit --gate --require-signer --require-good-signature` enforces a signature policy (REQ-0079).
- `req status` project-level implementation summary with `delivery_progress_pct` (REQ-0054).
- `req next` dependency-aware suggestion for the next requirement (REQ-0040).
- `req check <ref>` incremental validation and coverage scoped to changes (REQ-0041).
- `req version` and `req version --json` (REQ-0037).
- `req verify <id> --by composition|inspection` evidence record kinds (REQ-0056).
- `req test run` parses `cargo test` output and records evidence per REQ (REQ-0055).
- `req test record` attaches a manual test record with HEAD SHA (REQ-0049/REQ-0050).
- `req stale` two-level staleness (commit drift vs content drift) (REQ-0063).
- `req mcp` JSON-RPC stdio server with first-class agent guidance (REQ-0017/0047/0048).
- `req help <section> --install` writes managed blocks into AGENTS.md (REQ-0031).
- `req help <section> --json` structured agent crib (REQ-0042).
- Validator rule codes `REQ-V-NNNN` on every finding (REQ-0045).
- Structured JSON error envelope with stable `REQ-E-NNNN` codes (REQ-0039).
- `actor_kind` (human / agent / unknown) on every history entry (REQ-0043).
- Advisory file lock around mutation cycles (REQ-0062).
- `.gitattributes` line-ending pin to defend the integrity hash from autocrlf (REQ-0071).
- Test-vs-implementation marker classification in `req coverage` (REQ-0070).
- `req migrate` skeleton with backup, lock, and current-format no-op (REQ-0068).
- MIT license and crates.io metadata (`name=req-cli`, `[[bin]] name=req`) (REQ-0060/0061).
- Format-version policy section (REQ-0074).
- Hide `Obsolete` from default `req list` output; `--include-obsolete` to re-include (REQ-0073).
- Duplicate-intent warning when two non-obsolete requirements have semantically overlapping statements (REQ-0076).
- Validator warning for `verifies` links whose source has no test record (REQ-0077).
- GitHub Actions release workflow for tagged `v*` pushes (REQ-0059).
### Notes
- This release predates the first crates.io publish; the `0.1.0` tag will be the first.