0009: Mark records reviewed from the CLI

Context#

Review decisions on a schedule gives decided records a review date. Closing a review is a front matter edit: set reviewed to today, drop a reviewBy that has just been honoured, perhaps change the interval. Done by hand, the edit is easy to get wrong in the same ways a status change is, and a review that leaves reviewBy in the past is reported as overdue again on the next check. The other half of the loop, finding out what is due, needs the site or a jq query over decisions.json; a weekly job and a quick look before a team meeting want it from the terminal.

Decision#

Two commands, built like status and supersede:

• inkan reviewed <record> records a review: it sets reviewed (today unless --date says otherwise), sets reviewBy from --next, sets reviewEvery from --every, and, without --next, removes reviewBy once an interval takes over. It refuses records whose status is not a review status.
• inkan reviews lists the records whose review is overdue or due within a window, soonest first, with --all for every scheduled record and --json for scripts.

Both resolve records by the spellings every command accepts, rewrite only the keys they change, and refuse records from a repo source. --dry-run prints the diff.

How to use it#

Record a review#

1
npx inkan reviewed dbre/adr/0001

1
dbre/adr/0001-standardize-on-postgresql-16: reviewed 2026-10-17, next review 2027-10-17

What the command writes depends on what the record already has:

The record must be in a review status (reviews.statuses, by default accepted and implemented). A proposed RFC is not reviewed this way: its reviewBy is a decision deadline, and the command exits with code 1 and the list of review statuses. Decide on the record with inkan status first; see Change status and supersede from the CLI.

The front matter is edited key by key, the way status does it: comments, key order, quoting and line endings survive.

List what is due#

1
npx inkan reviews

1
2026-09-30  17 days late  DBRE-ADR-0001  Standardize on PostgreSQL 16
2
2026-11-15  in 29 days    PAYMENTS-ADR-0003  Use Stripe as the primary payment provider
3

4
1 overdue, 1 due within 30 days.

The list comes from the same rule as the site and check: reviewBy, or the interval after reviewed or date, for records in a review status. Records from sources are included. With nothing due the output is one line saying so. A job that should fail on overdue reviews runs inkan check --strict, where an overdue review is the review-due warning; see Check records in CI.

In scripts and agents#

1
npx inkan reviews --json > due-reviews.json

The same list is one MCP tool away for agents, due_reviews, see MCP server for agents. A weekly workflow that runs inkan reviews and posts the output is in Review decisions on a schedule.

Consequences#

• Closing a review is one command that leaves the record in a state check accepts: no reviewBy in the past, an interval or a next date in place.
• The command does not change status. A review that finds the decision no longer holds continues with status, supersede or a new record, which is a deliberate second step.
• Refusing a record without an interval and without --next or --every is stricter than status; it stops a review from silently taking the record off the schedule.
• reviews reads the files, so it sees uncommitted edits, and it reads the config, so a custom reviews.statuses is honoured. A published site offers the same through decisions.json and the MCP server’s --url mode.