document-review-loop

@xenonbyte/document-review-loop installs four document review routes that run a structured review-fix loop for SPEC, PLAN, DESIGN, and COMMON documents.

Installation

Install the package globally:

npm install -g @xenonbyte/document-review-loop

After installation, the drfx command is available:

drfx --help
drfx check

The package requires Node.js 20 or newer.

Platform Install and Uninstall

Install generated routes into one or more supported agent platforms:

drfx install --platform claude,codex,gemini
drfx install --platform claude
drfx install --platform codex
drfx install --platform gemini

Uninstall manifest-owned generated routes:

drfx uninstall --platform claude,codex,gemini

drfx install --platform supports claude, codex, and gemini.

Route differences:

• Claude installs command files under ~/.claude/commands.
• Codex installs generated skill directories under ~/.codex/skills/review-fix-*. Codex installs generated shared workflow files inside each skill directory, plus ownership markers used by safe reinstall and uninstall.
• Gemini installs command TOML files under ~/.gemini/commands, but Gemini v1 routes are advisory-only. Gemini v1 routes are advisory-only because v1 has no verified isolated write-blocked reviewer adapter.

drfx check reads and writes capability descriptors at ~/.docs-review-fix/capabilities/<platform>.json, runs the safe local fingerprint probe, validates current-run capability proof, and reports the advisory-only reason when required capabilities are unverified or unsupported.

Install and uninstall are manifest-backed. Uninstall removes only files listed as generated by this package and refuses unsafe ownership or path cases.

Four Command Usage Guide

The four user-facing routes are:

review-fix-spec   -> SPEC documents
review-fix-plan   -> PLAN documents
review-fix-design -> DESIGN documents
review-fix-doc    -> COMMON documents

Each entry route has a fixed entry-skill type mapping and no user-supplied type parameter. Do not pass type=; the route name selects the document type.

Examples:

review-fix-spec docs/spec.md
review-fix-plan docs/plan.md strict
review-fix-design docs/design.md read-only
review-fix-doc docs/notes.md resume
review-fix-spec target=docs/spec.md
review-fix-plan target=docs/plan.md ref=docs/spec.md strict
review-fix-design target=docs/design.md ref=docs/requirements.md ref=docs/brand.md
review-fix-doc target=docs/notes.md read-only
review-fix-spec target=docs/spec.md resume
review-fix-plan target=docs/plan.md ledger=.docs-review-fix/targets/plan-abc123def456/issues/custom.md root=/repo

Supported input tokens:

• target= selects the one target document that may be reviewed and, in fix mode, edited.
• Repeated ref= values add read-only reference documents; duplicate refs are de-duplicated.
• ledger= selects a custom issue ledger path inside the target state directory.
• root= sets the project root used for target containment and state layout.
• strict and normal select PASS strictness; they are mutually exclusive. normal is the default strictness.
• read-only and review-and-fix select mode; they are mutually exclusive.
• resume resumes from target-local state.

Parsing rules are intentionally strict. A single unlabeled target path is allowed, but once target= is used, unlabeled paths are rejected. Duplicate target= and duplicate root= are rejected. Unknown key=value tokens and unknown dash options are rejected. Paths with spaces must be shell quoted, or the host runtime must preserve the path as one target= or ref= token; the parser does not split paths. Natural-language input is accepted only when the target/reference roles are unambiguous; otherwise use explicit target= and ref=.

Built-In Review Rules

Every route applies the COMMON rubric first. Specialized routes then add one type-specific rubric:

• COMMON (shared/rubrics/common.md): baseline review for purpose, coherence, actionability, assumptions, constraints, risks, project alignment, terminology, placeholders, and external facts.
• SPEC (shared/rubrics/spec.md): requirements, product behavior, API behavior, feature definitions, scope, actors, permissions, data ownership, integrations, acceptance criteria, edge cases, and verifiability.
• PLAN (shared/rubrics/plan.md): implementation, migration, rollout, refactor, and execution plans with ordered steps, prerequisites, tooling, verification, rollback, failure handling, data safety, compatibility, and handoff readiness.
• DESIGN (shared/rubrics/design.md): UX, UI, product, workflow, system, architecture, and interaction designs with flows, states, transitions, contracts, data flow, ownership, accessibility, responsiveness, localization, constraints, and risks.

Route mapping:

• review-fix-spec: COMMON plus SPEC.
• review-fix-plan: COMMON plus PLAN.
• review-fix-design: COMMON plus DESIGN.
• review-fix-doc: COMMON only.

Reviewer findings must be structured enough to triage. A finding should include severity, location, issue summary, why_it_matters, suggested fix, confidence, and sensitive-content metadata when relevant.

Review-Fix Flow

The canonical loop is:

review -> triage -> fix -> diff review -> full re-review -> repeat until PASS or terminal state

The coordinator owns the loop and is the only role allowed to mark PASS. Initial review and every full re-review require an isolated read-only reviewer. The coordinator triages findings before any fix. The coordinator fixes accepted issues by default; a fixer subagent may be used only for a bounded accepted issue list and must run serially.

normal is the default strictness. High and medium findings block PASS until they are fixed, merged into fixed issues, rejected with rationale, downgraded with rationale, or deferred according to the workflow. Deferred high and medium findings stop as stopped-with-deferrals, not PASS. strict mode additionally makes low findings blocking unless they are explicitly accepted as non-blocking. normal mode allows low issues to remain non-blocking when the coordinator accepts that they do not affect the objective. read-only mode reviews and triages only, does not edit files, and stops as read-only-findings when blocking findings remain. review-and-fix mode may edit only the target document.

Terminal and pause states include pass, stopped-with-deferrals, read-only-findings, blocked, unsupported, externally-changed, possible-target-replacement, user stop, and checkpoint.

User-Global and Project-Local Rule Configuration

Optional custom rule files:

~/.docs-review-fix/RULE.md
.docs-review-fix/RULE.md

Rule heading restrictions are strict: only second-level headings named ## COMMON, ## SPEC, ## PLAN, and ## DESIGN are accepted. Unknown rule headings are rejected. Custom rules may extend review expectations but may not weaken hard workflow constraints such as reviewer isolation, read-only references, full re-review, redaction, target-local state, PASS criteria, or serial fixing.

Example RULE.md shape:

## COMMON

- Apply to every document type.

## SPEC

- Apply only to SPEC reviews.

## PLAN

- Apply only to PLAN reviews.

## DESIGN

- Apply only to DESIGN reviews.

Seven-layer precedence is:

1. workflow hard constraints
2. built-in COMMON rubric
3. built-in document-type rubric
4. user-global COMMON rules
5. user-global document-type rules
6. project-local COMMON rules
7. project-local document-type rules

Project-local rules are more specific than user-global rules, but no custom layer can override hard constraints.

State and Resume

Persistent state is target-local under:

.docs-review-fix/targets/<target-key>/

The target key is derived from the normalized target path relative to the project root: a readable slug plus a 12-character SHA-256 prefix. It is path-based, not content-based.

Project-local .docs-review-fix/ top-level layout:

.docs-review-fix/
  RULE.md
  index.md
  targets/

RULE.md is shared project configuration. index.md is project-level index material when present. targets/<target-key>/ is single-target workflow state.

Default target state layout:

.docs-review-fix/targets/<target-key>/
  MANIFEST.md
  ISSUES.md
  CONTINUITY.md
  SUMMARY.md
  LOCK/
    lease.json
  stale-locks/
  rounds/

MANIFEST.md records the target path, normalized target, document type, strictness, mode, target key, ledger path, status, current round, content fingerprints, file metadata, references, and timestamps. The default ledger is .docs-review-fix/targets/<target-key>/ISSUES.md; a custom ledger= must stay inside that target directory and must not point into reserved paths such as LOCK/, stale-locks/, rounds/, MANIFEST.md, CONTINUITY.md, or SUMMARY.md.

Before target modification, the workflow uses a target lock at .docs-review-fix/targets/<target-key>/LOCK/lease.json. Locks contain owner, process, host, timing, mode, strictness, and target fingerprint fields. Unexpired locks block concurrent editing. Expired locks are archived to stale-locks/ only when fingerprints remain safe. Immediately before a fix, the target fingerprint is checked again.

Round receipts live under rounds/ when an audit trail is requested, the loop reaches round 2, or the workflow stops for interruption, context pressure, or a blocker. Receipts summarize phase, status, touched issue IDs, files changed, verification, next action, and redacted risk details.

resume uses target-local files, not chat history. There is no runtime objective/session/platform memory dependency for resume. Resume derives the target key, reads MANIFEST.md, reads the ledger, loads CONTINUITY.md when present, rebuilds current merged rules, checks fingerprints, and continues only when state is still valid. A stale prior PASS is cleared if current content no longer matches the last passed fingerprint.

Safety and Redaction

Reference documents are read-only. Fixes must modify only the target document. The workflow must not mutate external systems or production state.

Sensitive values must not be printed or stored in ledgers, receipts, manifests, summaries, prompts, or final responses. Use the canonical redaction marker [REDACTED:<kind>], for example [REDACTED:api-token], [REDACTED:private-key], [REDACTED:cookie], or [REDACTED:credential].

For sensitive findings, store location anchors and secret kind, not raw values, partial prefixes, suffixes, hashes, checksums, raw logs, or transcript excerpts.

Final response requirements:

• final terminal or pause state
• changes made, including issue IDs when available
• files changed
• verification performed
• blockers, deferrals with issue IDs, reason, owner, and next action, unsupported reasons, or not-fixed items
• residual risk, or none identified

Advisory-Only Runtime Behavior

drfx check writes capability descriptors under ~/.docs-review-fix/capabilities/. Capability fields are status, proof, proofRunId, and detail. Supported statuses are verified, unverified, and unsupported; verified capabilities require a non-none proof and current-run proof ID.

Automatic review-fix PASS requires verified reviewer isolation, verified reviewer write blocking, and a verified fingerprint guard for the current run. When those capabilities are missing, the route may still provide advisory review, but it must not claim automatic PASS.

Claude and Codex v1 adapters currently report reviewer isolation and reviewer write blocking as unverified unless a runtime supplies current proof. Gemini v1 reports those capabilities as unsupported, so Gemini v1 routes are advisory-only and must not edit files or claim workflow PASS.