xspec review: Staged Review Session Commands

Reference for xspec review subcommands: create, list, status, next, show, split, resolve, and export — strategies, resolve statuses, and scripting tips.

review manages staged review sessions — structured workflows for triaging requirement changes, auditing specs, or verifying coverage. Each session is a persistent file in your workspace that tracks which items have been reviewed and which are still pending.

Session name rules

Session names may contain A–Z, a–z, 0–9, ., _, and -. They must not start with .. Session files are stored at .xspec/reviews/<name>.json.

Comparisons against session names are byte-wise case-sensitive.

Subcommands

create

Create a new review session. You must specify exactly one strategy.

xspec review create --base <ref> --name <name>
xspec review create --strategy audit --name <name>
xspec review create --coverage <profile> --name <name>

--name · string · required

The name for the new session. Must follow the session name rules above.

--base · git-ref

Path-blocks strategy. Builds a review queue from requirements whose content changed since the given git ref, traced through the journal.

--strategy · string

Built-in strategy name. Currently only audit is supported, which queues every requirement node in the workspace for review.

--coverage · string

Coverage strategy. Builds the queue from uncovered required nodes in the named coverage profile.

---

list

List all review sessions in the workspace.

xspec review list

---

status

Show summary counts for a session: total items, resolved, pending, and resolution breakdown.

xspec review status <name>

---

next

Print the next unresolved item in the session queue.

xspec review next <name> [--json]

--json · flag

Emit the item as a JSON object instead of the human-readable format.

---

show

Print the full detail of a specific item by its item ID.

xspec review show <name> <item-id>

---

split

Split one review item into multiple finer-grained items. Useful when a single queue entry covers more ground than can be reviewed in one step.

xspec review split <name> <item-id>

Mutating — subject to the workspace concurrency lock.

---

resolve

Mark an item as reviewed with a resolution status and an optional note.

xspec review resolve <name> <item-id> --status <status> [--note <text>]

--status · string · required

Resolution status. Accepted values:

Value	Meaning
updated	The requirement was reviewed and changes were made
no-change	The requirement was reviewed and no changes are needed
skipped	The item is deferred — it remains in the queue as skipped

--note · string

Optional free-text note to attach to the resolution record.

Mutating — subject to the workspace concurrency lock.

---

export

Export the full session as a JSON document. JSON is always emitted for this subcommand — no --json flag is needed.

xspec review export <name>

The exported document contains the session metadata, strategy, all items with their IDs and source nodes, and all resolution records including statuses and notes.

Scripting with —json

Use review next --json in a loop to process items programmatically:

while true; do
  item=$(xspec review next my-session --json)
  [ $? -ne 0 ] && break          # no more items
  id=$(echo "$item" | jq -r '.id')
  # ... your review logic ...
  xspec review resolve my-session "$id" --status no-change
done

Concurrency

review create, review resolve, and review split are mutating commands and are mutually exclusive per workspace. A second mutating command attempted while one is running exits immediately with code 2. Non-mutating subcommands (list, status, next, show, export) can run concurrently.

Exit codes

Code	Condition
0	Success for all informational subcommands
1	Refused operation (e.g., resolving an already-resolved item); corrupt session (finding 21)
2	Unknown session or item ID; invalid flag value; concurrency lock held