Reviewer brief

Supply

• the assigned document’s project-root-relative path;
• the routed rubric path (the reviewer does not re-resolve it) and its version;
• the mechanical-validation result;
• the exact sha256: source hash;
• the snapshot timestamp: Review-only startedAt, or in Iterate the UTC time (date -u +%Y-%m-%dT%H:%M:%SZ) the PM captures just before dispatching that review (the same value for a correction);
• in Review-only, the review ID (R1 …);
• optionally, the frozen effective review-context path and hash;
• exactly one assigned, unused scratch report path (project-root-relative) in the document’s cache root (.authoring-kit-cache/documents/<source-directory>/<document-key>/), to which the reviewer writes the whole report (see Scratch report);
• a link to the reviewer workflow.

Every fresh reviewer receives the same unchanged inputs. Never include another version, writer notes, research, ledgers, previous reports or sibling reports.

Scratch report

The reviewer writes its report to the path the brief assigns and returns only that path.

• Review-only: init-review-run.mjs allocates two paths per review ID before any dispatch, so parallel mode is safe: review-<n>-attempt-1.md and review-<n>-attempt-2.md. Give each reviewer only its own ID’s first path.
• Iterate: start-iterate and add-iteration report the draft’s two paths as next.reviewerScratchPaths (drafts/scratch/draft-<nnn>-review-attempt-<k>.md in the cache root).
• A correction gets the same review’s next unused path (attempt 2). Never reuse an earlier scratch file, and never pass a reviewer any path but its own.

Accept

Require the returned path to match the assigned path exactly, and read only that path. Recompute the source hash after every reviewer returns, in every mode: the scratch path is the only file a reviewer is meant to write, and the brief is the only limit on it, so a changed source means the run is stale. The PM copies the accepted scratch report to its durable name; it never retypes the report.

In Review-only, first run check-review-report.mjs on the scratch report with --role=reviewer (see Review-only); its warnings are advisory for now. In every mode, check the report against Review reporting and verify, by eye or from the script’s result:

• exactly one complete version 3 reviewer snapshot is present, including model;
• snapshot and brief source hashes match;
• rating, reason, and every applicable lens assessment are present;
• every applicable lens has a one-sentence rationale, and every Mixed or Weak rationale cites at least one substantive finding ID;
• each Mixed or Weak assessment has a substantive finding and each finding maps to one;
• every substantive finding meets the required format;
• every context item is accounted for and the context hash matches;
• no known item appears as an F-numbered finding or as the cause of a Mixed or Weak lens.

On failure, return one specific omission for one correction attempt. Do not suggest a finding or rating. A correction for the same review ID and frozen inputs remains a delegated review, not a direct user request; keep startedAt unchanged. If the report remains incomplete, record the limitation and stop.

The PM invokes the synthesiser only after all requested reports pass acceptance.

See also