@sublang/playbook 11.0.0 → 12.1.0

package/reference/sdlc/review.playbook/review.fsm.ts

@@ -25,8 +25,14 @@ export interface PendingBossQuestion {
 }
 
 export interface ReviewOutput {
-  approvedCommit: 'latest';
   noUnsettledFindings: true;
+  /**
+   * Exact receipt-derived repository revision at which the review scope was
+   * evaluated: the closing clean round's `unchanged` receipt observes it as
+   * HEAD — the last review-fix commit when one landed, or the caller-supplied
+   * scope revision when none did (DR-045).
+   */
+  evaluatedRevision: string;
 }
 
 export type ReviewInput = Readonly<Record<string, never>>;
@@ -35,6 +41,10 @@ export interface ReviewContext {
   callerInput?: string;
   reviewerOutput?: string;
   coderOutput?: string;
+  /** Receipt-derived OID of the latest review-fix commit (never player prose). */
+  latestCommit?: string;
+  /** Observed HEAD of the closing clean round's unchanged receipt (DR-045). */
+  evaluatedRevision?: string;
   lastError?: unknown;
   pendingBossQuestion?: PendingBossQuestion;
   bossReply?: string;
@@ -62,14 +72,15 @@ export interface PlayerInput {
   callerInput?: string;
   reviewerOutput?: string;
   coderOutput?: string;
+  latestCommit?: string;
   pendingBossQuestion?: PendingBossQuestion;
   bossReply?: string;
 }
 
 export type PlayerOutput =
   | { guard: 'hasFindings'; reviewerOutput: string }
-  | { guard: 'noFindings' }
-  | { guard: 'committed'; coderOutput: string }
+  | { guard: 'noFindings'; evaluatedRevision: string }
+  | { guard: 'committed'; coderOutput: string; latestCommit: string }
   | { guard: 'rejectedAll'; coderOutput: string }
   | { guard: 'needsBossReply'; question: string };
 
@@ -80,13 +91,16 @@ const NEEDS_BOSS_REPLY_DESCRIPTION =
 
 const SHARED_REVIEW_INSTRUCTION = [
   'Understand the full picture and think systematically about the underlying design.',
-  'Continue to identify issues or improvements, if any (numbered; no duplication).',
-  'For any rebuttal, accept or challenge it.',
-  'Treat as settled, and do not raise again, any finding in this review rejected twice with reasoning.',
+  'Continue to identify issues or improvements, if any, without duplication.',
+  'Number the findings consistently across rounds.',
   'Flag only what materially affects correctness, behavior, or spec quality — not style, equally valid alternatives, or theoretical threats.',
-  'For specs, flag stale, missing, over-specified, or under-specified ones.',
+  'For specs, flag stale, missing, over-specified, or under-specified ones, if any.',
   'Avoid unnecessary complexity in code or tests, but flag any fundamental design flaw when leaving it would cost more in later patches than fixing it now.',
   '',
+  'If an issue represents a class of defect, find every instance within the review scope worth fixing rather than surfacing one or two per round, which drags out the review.',
+  'For any rebuttal, accept or challenge it.',
+  'Treat as settled, and do not raise again, any finding in this review rejected twice with reasoning.',
+  '',
   'Do not re-run tests or builds whose inputs have not changed since any previous reported run.',
   'Do not edit files or commit; report findings only.',
   '',
@@ -95,8 +109,9 @@ const SHARED_REVIEW_INSTRUCTION = [
 ].join('\n');
 
 const INITIAL_REVIEW_PROMPT = [
-  'A new review begins on the latest commit.',
-  'Review the latest commit and resulting repository state; read the commit message first for its intent, scope, and rationale.',
+  'A new review begins for the review scope.',
+  'Keep to the original intent and follow what it asks.',
+  'When the scope names commits, read each commit message for its context and rationale; otherwise use repository history and commit messages wherever they help establish that context.',
   '',
   '> <caller-input>',
   '',
@@ -104,8 +119,12 @@ const INITIAL_REVIEW_PROMPT = [
 ].join('\n');
 
 const POST_COMMIT_REVIEW_PROMPT = [
-  'Review the latest commit and resulting repository state; read the commit message first for its intent, scope, and rationale.',
+  'A new review round begins for the review scope in the cumulative committed state, with particular attention to the latest review-fix commit.',
+  'Keep to the original intent and follow what it asks.',
+  "Read the latest review-fix commit's message and see Coder's feedback below.",
   '',
+  '> <caller-input>',
+  '> <latest-commit>',
   '> <coder-output>',
   '',
   SHARED_REVIEW_INSTRUCTION,
@@ -113,26 +132,31 @@ const POST_COMMIT_REVIEW_PROMPT = [
 
 const REBUTTAL_REVIEW_PROMPT = [
   'No new commit was made because Coder rejected every finding.',
+  "See Coder's feedback below.",
   '',
+  '> <caller-input>',
   '> <coder-output>',
   '',
   SHARED_REVIEW_INSTRUCTION,
 ].join('\n');
 
 const CODER_DISPOSITION_PROMPT = [
+  '> <caller-input>',
   '> <reviewer-output>',
   '',
   'For each review item, accept or reject it.',
   'Before deciding, understand the full picture and think systematically about the underlying design.',
+  'Keep to the original intent and follow what it asks.',
   'Reject anything that is not essential or is not worth fixing now.',
-  'If you accept an item, fix its root cause, including any fundamental design flaw - do not patch around it.',
+  'If you accept an item, fix its root cause, including any fundamental design flaw — do not patch around it; if it represents a class of defect, find every instance within the review scope worth fixing rather than addressing one or two per round, which drags out the review.',
   'If you reject an item, give the reasoning and cite code or test output that supports it.',
   'Do not re-run tests or builds whose inputs have not changed since any previous reported run.',
   '',
-  'If you accept any item, make minimal changes and commit them as one new commit; never amend the reviewed commit.',
+  'If you accept any item, make minimal changes and add one new review-fix commit; never rewrite any existing commit.',
   'Follow @specs/packages/git.md.',
   'Make the commit message explain concisely what changed and why, including relevant verification.',
-  'Coder is <coder-llm>; Reviewer is <reviewer-llm>; format model tokens in conventional human form.',
+  'Identify every new commit you make.',
+  'Coder is <coder-llm>; Reviewer is <reviewer-llm>.',
   '',
   'If you reject every item, change nothing and make no commit.',
   'Report every disposition, all relevant run results, and every rebuttal.',
@@ -141,7 +165,8 @@ const CODER_DISPOSITION_PROMPT = [
 const REVIEW_RESULTS = {
   hasFindings:
     'Reviewer raised one or more unsettled findings. Output shall include `reviewerOutput: <verbatim final text>`.',
-  noFindings: 'Reviewer raised no unsettled findings.',
+  noFindings:
+    'Reviewer affirmatively reported the requested review complete with no unsettled findings remaining; a progress report, status update, or promise of a later result supports no review outcome. Output shall include `evaluatedRevision: <repository revision>`.',
   needsBossReply: NEEDS_BOSS_REPLY_DESCRIPTION,
 } as const;
 
@@ -149,31 +174,31 @@ const REBUTTAL_RESULTS = {
   hasFindings:
     'Reviewer kept one or more unsettled findings. Output shall include `reviewerOutput: <verbatim final text>`.',
   noFindings:
-    'Reviewer accepted the rebuttals and no unsettled findings remain.',
+    'Reviewer accepted the rebuttals and affirmatively reported the requested review complete with no unsettled findings remaining; a progress report, status update, or promise of a later result supports no review outcome. Output shall include `evaluatedRevision: <repository revision>`.',
   needsBossReply: NEEDS_BOSS_REPLY_DESCRIPTION,
 } as const;
 
 const CODER_RESULTS = {
   committed:
-    'Coder accepted at least one item and made one new commit. Output shall include `coderOutput: <verbatim final text>`.',
+    'Coder accepted at least one item and added one new review-fix commit. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.',
   rejectedAll:
     'Coder rejected every item and made no commit. Output shall include `coderOutput: <verbatim final text>`.',
   needsBossReply: NEEDS_BOSS_REPLY_DESCRIPTION,
 } as const;
 
 const stateDescriptions = {
-  ready: 'Waits for a caller to start a committed-work review.',
+  ready: 'Waits for a caller to start a scoped committed-work review.',
   reviewInitial:
-    'REVIEW-1: Reviewer examines the latest commit against the caller input.',
+    "REVIEW-1: Reviewer reviews the caller's review scope against the original intent.",
   addressFindings:
     'REVIEW-2: Coder accepts or rejects every current review finding.',
   reviewAfterCommit:
-    'REVIEW-3: Reviewer examines the new review-fix commit and repository state.',
+    'REVIEW-3: Reviewer reviews the cumulative committed state after a review-fix commit.',
   reviewAfterRebuttal:
     'REVIEW-4: Reviewer adjudicates an all-rejected Coder disposition.',
   awaitBossReply: 'Waits for Boss to answer the active player question.',
   failed: 'Retains a recoverable REVIEW failure for the caller.',
-  done: 'The latest commit is approved with no unsettled findings.',
+  done: 'The requested review is complete: no unsettled findings remain within the review scope.',
 } as const;
 
 const playbookMeta = <StateId extends keyof typeof stateDescriptions>(
@@ -240,11 +265,19 @@ export const reviewMachine = setup({
         isNonEmptyString(output.reviewerOutput)
       );
     },
-    noFindings: ({ event }) => outputOf(event).guard === 'noFindings',
+    noFindings: ({ event }) => {
+      const output = outputOf(event);
+      return (
+        output.guard === 'noFindings' &&
+        isNonEmptyString(output.evaluatedRevision)
+      );
+    },
     committed: ({ event }) => {
       const output = outputOf(event);
       return (
-        output.guard === 'committed' && isNonEmptyString(output.coderOutput)
+        output.guard === 'committed' &&
+        isNonEmptyString(output.coderOutput) &&
+        isNonEmptyString(output.latestCommit)
       );
     },
     rejectedAll: ({ event }) => {
@@ -305,6 +338,8 @@ export const reviewMachine = setup({
         event.type === 'START_REVIEW' ? event.callerInput : undefined,
       reviewerOutput: undefined,
       coderOutput: undefined,
+      latestCommit: undefined,
+      evaluatedRevision: undefined,
       lastError: undefined,
       pendingBossQuestion: undefined,
       bossReply: undefined,
@@ -314,6 +349,8 @@ export const reviewMachine = setup({
         event.type === 'BOSS_INTERRUPT' ? event.bossIntent : undefined,
       reviewerOutput: undefined,
       coderOutput: undefined,
+      latestCommit: undefined,
+      evaluatedRevision: undefined,
       lastError: undefined,
       pendingBossQuestion: undefined,
       bossReply: undefined,
@@ -336,11 +373,29 @@ export const reviewMachine = setup({
           ? output.coderOutput
           : undefined;
       },
+      // The receipt-derived review-fix commit identity replaces the prior one
+      // only when Coder committed; an all-rejected round leaves the evaluated
+      // revision unchanged.
+      latestCommit: ({ context, event }) => {
+        const output = outputOf(event);
+        return output.guard === 'committed'
+          ? output.latestCommit
+          : context.latestCommit;
+      },
       lastError: undefined,
       pendingBossQuestion: undefined,
       bossReply: undefined,
     }),
-    clearBossReplyContext: assign({
+    rememberEvaluatedRevision: assign({
+      // DR-045: the closing clean round's unchanged receipt observes the
+      // exact revision the review scope was evaluated at.
+      evaluatedRevision: ({ context, event }) => {
+        const output = outputOf(event);
+        return output.guard === 'noFindings'
+          ? output.evaluatedRevision
+          : context.evaluatedRevision;
+      },
+      lastError: undefined,
       pendingBossQuestion: undefined,
       bossReply: undefined,
     }),
@@ -478,7 +533,7 @@ export const reviewMachine = setup({
                   acceptedOutcome: 'noFindings',
                 },
               },
-              'clearBossReplyContext',
+              'rememberEvaluatedRevision',
             ],
           },
           {
@@ -516,6 +571,7 @@ export const reviewMachine = setup({
           role: 'coder',
           prompt: CODER_DISPOSITION_PROMPT,
           result: CODER_RESULTS,
+          callerInput: context.callerInput,
           reviewerOutput: context.reviewerOutput,
           pendingBossQuestion: context.pendingBossQuestion,
           bossReply: context.bossReply,
@@ -586,6 +642,8 @@ export const reviewMachine = setup({
           role: 'reviewer',
           prompt: POST_COMMIT_REVIEW_PROMPT,
           result: REVIEW_RESULTS,
+          callerInput: context.callerInput,
+          latestCommit: context.latestCommit,
           coderOutput: context.coderOutput,
           pendingBossQuestion: context.pendingBossQuestion,
           bossReply: context.bossReply,
@@ -618,7 +676,7 @@ export const reviewMachine = setup({
                   acceptedOutcome: 'noFindings',
                 },
               },
-              'clearBossReplyContext',
+              'rememberEvaluatedRevision',
             ],
           },
           {
@@ -656,6 +714,7 @@ export const reviewMachine = setup({
           role: 'reviewer',
           prompt: REBUTTAL_REVIEW_PROMPT,
           result: REBUTTAL_RESULTS,
+          callerInput: context.callerInput,
           coderOutput: context.coderOutput,
           pendingBossQuestion: context.pendingBossQuestion,
           bossReply: context.bossReply,
@@ -688,7 +747,7 @@ export const reviewMachine = setup({
                   acceptedOutcome: 'noFindings',
                 },
               },
-              'clearBossReplyContext',
+              'rememberEvaluatedRevision',
             ],
           },
           {
@@ -777,8 +836,15 @@ export const reviewMachine = setup({
       type: 'final',
     },
   },
-  output: (): ReviewOutput => ({
-    approvedCommit: 'latest',
-    noUnsettledFindings: true,
-  }),
+  output: ({ context }): ReviewOutput => {
+    if (!isNonEmptyString(context.evaluatedRevision)) {
+      throw new Error(
+        'REVIEW reached done without a receipt-observed evaluated revision',
+      );
+    }
+    return {
+      noUnsettledFindings: true,
+      evaluatedRevision: context.evaluatedRevision,
+    };
+  },
 });

package/reference/sdlc/review.playbook/review.gears.md

@@ -1,30 +1,41 @@
 <!-- SPDX-License-Identifier: Apache-2.0 -->
 <!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
 
-# REVIEW: Commit Review Workflow
+# REVIEW: Scoped Committed-Work Review Workflow
 
 Roles:
 
 - Coder
 - Reviewer
 
+The caller supplies one caller input carrying the original intent, the review scope in the caller's own words, and optional relevant context and run results.
+The caller's review scope is the baseline for every round, and each review-fix commit joins that scope as it lands, so every later round reviews the cumulative committed state.
+`review` examines committed work only.
+Captain takes the evaluated repository revision from repository authority, not from either player's prose: the repository-effect receipt is the authoritative identity of any review-fix commit, and a clean round's `unchanged` receipt proves the observed revision it evaluated.
+Finding numbers are references within this review only; no review transition depends on numbering or any fixed presentation format of either player's reply.
+Rounds continue until Reviewer affirmatively reports that the requested review is complete and no unsettled findings remain; `review` then returns the exact repository revision at which the review scope was evaluated and the fact that no unsettled findings remain within that scope.
+
 ### REVIEW-1
 
 When the caller starts a review, Captain shall relay the complete caller input to Reviewer with the first-round and shared review instructions:
 
-> A new review begins on the latest commit.
-> Review the latest commit and resulting repository state; read the commit message first for its intent, scope, and rationale.
+> A new review begins for the review scope.
+> Keep to the original intent and follow what it asks.
+> When the scope names commits, read each commit message for its context and rationale; otherwise use repository history and commit messages wherever they help establish that context.
 >
 > > <caller-input>
 >
 > Understand the full picture and think systematically about the underlying design.
-> Continue to identify issues or improvements, if any (numbered; no duplication).
-> For any rebuttal, accept or challenge it.
-> Treat as settled, and do not raise again, any finding in this review rejected twice with reasoning.
+> Continue to identify issues or improvements, if any, without duplication.
+> Number the findings consistently across rounds.
 > Flag only what materially affects correctness, behavior, or spec quality — not style, equally valid alternatives, or theoretical threats.
-> For specs, flag stale, missing, over-specified, or under-specified ones.
+> For specs, flag stale, missing, over-specified, or under-specified ones, if any.
 > Avoid unnecessary complexity in code or tests, but flag any fundamental design flaw when leaving it would cost more in later patches than fixing it now.
 >
+> If an issue represents a class of defect, find every instance within the review scope worth fixing rather than surfacing one or two per round, which drags out the review.
+> For any rebuttal, accept or challenge it.
+> Treat as settled, and do not raise again, any finding in this review rejected twice with reasoning.
+>
 > Do not re-run tests or builds whose inputs have not changed since any previous reported run.
 > Do not edit files or commit; report findings only.
 >
@@ -33,49 +44,59 @@ When the caller starts a review, Captain shall relay the complete caller input t
 
 Results:
 - `hasFindings`: Reviewer raised one or more unsettled findings. Output shall include `reviewerOutput: <verbatim final text>`.
-- `noFindings`: Reviewer raised no unsettled findings.
+- `noFindings`: Reviewer affirmatively reported the requested review complete with no unsettled findings remaining; a progress report, status update, or promise of a later result supports no review outcome. Output shall include `evaluatedRevision: <repository revision>`.
 
 ### REVIEW-2
 
-When Reviewer raises or keeps any finding, Captain shall relay Reviewer's output to Coder with the disposition instruction:
+When Reviewer raises or keeps any finding, Captain shall relay the caller input and Reviewer's findings to Coder with the disposition prompt:
 
+> > <caller-input>
 > > <reviewer-output>
 >
 > For each review item, accept or reject it.
 > Before deciding, understand the full picture and think systematically about the underlying design.
+> Keep to the original intent and follow what it asks.
 > Reject anything that is not essential or is not worth fixing now.
-> If you accept an item, fix its root cause, including any fundamental design flaw - do not patch around it.
+> If you accept an item, fix its root cause, including any fundamental design flaw — do not patch around it; if it represents a class of defect, find every instance within the review scope worth fixing rather than addressing one or two per round, which drags out the review.
 > If you reject an item, give the reasoning and cite code or test output that supports it.
 > Do not re-run tests or builds whose inputs have not changed since any previous reported run.
 >
-> If you accept any item, make minimal changes and commit them as one new commit; never amend the reviewed commit.
+> If you accept any item, make minimal changes and add one new review-fix commit; never rewrite any existing commit.
 > Follow @specs/packages/git.md.
 > Make the commit message explain concisely what changed and why, including relevant verification.
-> Coder is <coder-llm>; Reviewer is <reviewer-llm>; format model tokens in conventional human form.
+> Identify every new commit you make.
+> Coder is <coder-llm>; Reviewer is <reviewer-llm>.
 >
 > If you reject every item, change nothing and make no commit.
 > Report every disposition, all relevant run results, and every rebuttal.
 
 Results:
-- `committed`: Coder accepted at least one item and made one new commit. Output shall include `coderOutput: <verbatim final text>`.
+- `committed`: Coder accepted at least one item and added one new review-fix commit. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.
 - `rejectedAll`: Coder rejected every item and made no commit. Output shall include `coderOutput: <verbatim final text>`.
 
 ### REVIEW-3
 
-When Coder makes a review-fix commit, Captain shall relay Coder's output to Reviewer with the next-round and shared review instructions:
+When Coder makes a review-fix commit, Captain shall relay the caller input, the review-fix commit, and Coder's feedback to Reviewer with the next-round and shared review instructions:
 
-> Review the latest commit and resulting repository state; read the commit message first for its intent, scope, and rationale.
+> A new review round begins for the review scope in the cumulative committed state, with particular attention to the latest review-fix commit.
+> Keep to the original intent and follow what it asks.
+> Read the latest review-fix commit's message and see Coder's feedback below.
 >
+> > <caller-input>
+> > <latest-commit>
 > > <coder-output>
 >
 > Understand the full picture and think systematically about the underlying design.
-> Continue to identify issues or improvements, if any (numbered; no duplication).
-> For any rebuttal, accept or challenge it.
-> Treat as settled, and do not raise again, any finding in this review rejected twice with reasoning.
+> Continue to identify issues or improvements, if any, without duplication.
+> Number the findings consistently across rounds.
 > Flag only what materially affects correctness, behavior, or spec quality — not style, equally valid alternatives, or theoretical threats.
-> For specs, flag stale, missing, over-specified, or under-specified ones.
+> For specs, flag stale, missing, over-specified, or under-specified ones, if any.
 > Avoid unnecessary complexity in code or tests, but flag any fundamental design flaw when leaving it would cost more in later patches than fixing it now.
 >
+> If an issue represents a class of defect, find every instance within the review scope worth fixing rather than surfacing one or two per round, which drags out the review.
+> For any rebuttal, accept or challenge it.
+> Treat as settled, and do not raise again, any finding in this review rejected twice with reasoning.
+>
 > Do not re-run tests or builds whose inputs have not changed since any previous reported run.
 > Do not edit files or commit; report findings only.
 >
@@ -84,24 +105,29 @@ When Coder makes a review-fix commit, Captain shall relay Coder's output to Revi
 
 Results:
 - `hasFindings`: Reviewer raised one or more unsettled findings. Output shall include `reviewerOutput: <verbatim final text>`.
-- `noFindings`: Reviewer raised no unsettled findings.
+- `noFindings`: Reviewer affirmatively reported the requested review complete with no unsettled findings remaining; a progress report, status update, or promise of a later result supports no review outcome. Output shall include `evaluatedRevision: <repository revision>`.
 
 ### REVIEW-4
 
-When Coder rejects every finding and makes no commit, Captain shall relay Coder's output to Reviewer with the rebuttal and shared review instructions:
+When Coder rejects every finding and makes no commit, Captain shall relay the caller input and Coder's feedback to Reviewer with the rebuttal and shared review instructions:
 
 > No new commit was made because Coder rejected every finding.
+> See Coder's feedback below.
 >
+> > <caller-input>
 > > <coder-output>
 >
 > Understand the full picture and think systematically about the underlying design.
-> Continue to identify issues or improvements, if any (numbered; no duplication).
-> For any rebuttal, accept or challenge it.
-> Treat as settled, and do not raise again, any finding in this review rejected twice with reasoning.
+> Continue to identify issues or improvements, if any, without duplication.
+> Number the findings consistently across rounds.
 > Flag only what materially affects correctness, behavior, or spec quality — not style, equally valid alternatives, or theoretical threats.
-> For specs, flag stale, missing, over-specified, or under-specified ones.
+> For specs, flag stale, missing, over-specified, or under-specified ones, if any.
 > Avoid unnecessary complexity in code or tests, but flag any fundamental design flaw when leaving it would cost more in later patches than fixing it now.
 >
+> If an issue represents a class of defect, find every instance within the review scope worth fixing rather than surfacing one or two per round, which drags out the review.
+> For any rebuttal, accept or challenge it.
+> Treat as settled, and do not raise again, any finding in this review rejected twice with reasoning.
+>
 > Do not re-run tests or builds whose inputs have not changed since any previous reported run.
 > Do not edit files or commit; report findings only.
 >
@@ -110,4 +136,4 @@ When Coder rejects every finding and makes no commit, Captain shall relay Coder'
 
 Results:
 - `hasFindings`: Reviewer kept one or more unsettled findings. Output shall include `reviewerOutput: <verbatim final text>`.
-- `noFindings`: Reviewer accepted the rebuttals and no unsettled findings remain.
+- `noFindings`: Reviewer accepted the rebuttals and affirmatively reported the requested review complete with no unsettled findings remaining; a progress report, status update, or promise of a later result supports no review outcome. Output shall include `evaluatedRevision: <repository revision>`.

package/reference/sdlc/review.playbook/review.playbook.js

@@ -7,7 +7,8 @@
 // Boss event:    deterministic START_REVIEW entry; exact Boss text becomes
 //                callerInput; pending player questions retain BOSS_REPLY
 // Adjudication:  LLM judge per state; coderOutput and reviewerOutput are
-//                carried verbatim
+//                carried verbatim; latestCommit is receipt-owned effect
+//                evidence, never taken from either player's prose
 // Compat:        artifact schema 3 / runtime ABI 1
 import { createXStatePlaybookRuntime, snapshotJsonValue, } from '@sublang/playbook/xstate-runtime';
 import { reviewMachine, } from './review.fsm.js';
@@ -90,7 +91,7 @@ const runtimeSpec = {
     roleStates: {
         reviewInitial: {
             role: 'reviewer',
-            label: 'REVIEW-1: Reviewer examines the latest commit against the caller input.',
+            label: "REVIEW-1: Reviewer reviews the caller's review scope against the original intent.",
         },
         addressFindings: {
             role: 'coder',
@@ -98,7 +99,7 @@ const runtimeSpec = {
         },
         reviewAfterCommit: {
             role: 'reviewer',
-            label: 'REVIEW-3: Reviewer examines the new review-fix commit and repository state.',
+            label: 'REVIEW-3: Reviewer reviews the cumulative committed state after a review-fix commit.',
         },
         reviewAfterRebuttal: {
             role: 'reviewer',
@@ -113,7 +114,9 @@ const runtimeSpec = {
                     repositoryDisposition: 'unchanged',
                 },
                 noFindings: {
-                    fields: {},
+                    // DR-045: the clean round's unchanged receipt observes the exact
+                    // evaluated revision as HEAD; the reconciler injects it here.
+                    fields: { evaluatedRevision: 'effect' },
                     repositoryDisposition: 'unchanged',
                 },
                 needsBossReply: {
@@ -123,7 +126,10 @@ const runtimeSpec = {
             },
             addressFindings: {
                 committed: {
-                    fields: { coderOutput: 'presentation' },
+                    fields: {
+                        coderOutput: 'presentation',
+                        latestCommit: 'effect',
+                    },
                     repositoryDisposition: 'one-descendant-commit',
                 },
                 rejectedAll: {
@@ -141,7 +147,9 @@ const runtimeSpec = {
                     repositoryDisposition: 'unchanged',
                 },
                 noFindings: {
-                    fields: {},
+                    // DR-045: the clean round's unchanged receipt observes the exact
+                    // evaluated revision as HEAD; the reconciler injects it here.
+                    fields: { evaluatedRevision: 'effect' },
                     repositoryDisposition: 'unchanged',
                 },
                 needsBossReply: {
@@ -155,7 +163,9 @@ const runtimeSpec = {
                     repositoryDisposition: 'unchanged',
                 },
                 noFindings: {
-                    fields: {},
+                    // DR-045: the clean round's unchanged receipt observes the exact
+                    // evaluated revision as HEAD; the reconciler injects it here.
+                    fields: { evaluatedRevision: 'effect' },
                     repositoryDisposition: 'unchanged',
                 },
                 needsBossReply: {

package/reference/sdlc/review.playbook/review.playbook.ts

@@ -7,7 +7,8 @@
 // Boss event:    deterministic START_REVIEW entry; exact Boss text becomes
 //                callerInput; pending player questions retain BOSS_REPLY
 // Adjudication:  LLM judge per state; coderOutput and reviewerOutput are
-//                carried verbatim
+//                carried verbatim; latestCommit is receipt-owned effect
+//                evidence, never taken from either player's prose
 // Compat:        artifact schema 3 / runtime ABI 1
 
 import {
@@ -181,7 +182,7 @@ const runtimeSpec = {
     reviewInitial: {
       role: 'reviewer',
       label:
-        'REVIEW-1: Reviewer examines the latest commit against the caller input.',
+        "REVIEW-1: Reviewer reviews the caller's review scope against the original intent.",
     },
     addressFindings: {
       role: 'coder',
@@ -190,7 +191,7 @@ const runtimeSpec = {
     reviewAfterCommit: {
       role: 'reviewer',
       label:
-        'REVIEW-3: Reviewer examines the new review-fix commit and repository state.',
+        'REVIEW-3: Reviewer reviews the cumulative committed state after a review-fix commit.',
     },
     reviewAfterRebuttal: {
       role: 'reviewer',
@@ -206,7 +207,9 @@ const runtimeSpec = {
           repositoryDisposition: 'unchanged',
         },
         noFindings: {
-          fields: {},
+          // DR-045: the clean round's unchanged receipt observes the exact
+          // evaluated revision as HEAD; the reconciler injects it here.
+          fields: { evaluatedRevision: 'effect' },
           repositoryDisposition: 'unchanged',
         },
         needsBossReply: {
@@ -216,7 +219,10 @@ const runtimeSpec = {
       },
       addressFindings: {
         committed: {
-          fields: { coderOutput: 'presentation' },
+          fields: {
+            coderOutput: 'presentation',
+            latestCommit: 'effect',
+          },
           repositoryDisposition: 'one-descendant-commit',
         },
         rejectedAll: {
@@ -234,7 +240,9 @@ const runtimeSpec = {
           repositoryDisposition: 'unchanged',
         },
         noFindings: {
-          fields: {},
+          // DR-045: the clean round's unchanged receipt observes the exact
+          // evaluated revision as HEAD; the reconciler injects it here.
+          fields: { evaluatedRevision: 'effect' },
           repositoryDisposition: 'unchanged',
         },
         needsBossReply: {
@@ -248,7 +256,9 @@ const runtimeSpec = {
           repositoryDisposition: 'unchanged',
         },
         noFindings: {
-          fields: {},
+          // DR-045: the clean round's unchanged receipt observes the exact
+          // evaluated revision as HEAD; the reconciler injects it here.
+          fields: { evaluatedRevision: 'effect' },
           repositoryDisposition: 'unchanged',
         },
         needsBossReply: {

package/reference/sdlc/review.playbook/review.registry.js

@@ -47,7 +47,7 @@ export function validateReviewOptions(optionSlice) {
 export const reviewPlaybookRegistryEntry = {
     id: 'review',
     command: 'review',
-    intent: 'review the latest commit until no material correctness or spec findings remain',
+    intent: 'review a supplied scope of committed work until no unsettled findings remain',
     artifactSchema: 3,
     runtimeProfile: Object.freeze({
         kind: 'shared-factory',

package/reference/sdlc/review.playbook/review.registry.ts

@@ -104,7 +104,7 @@ export const reviewPlaybookRegistryEntry: ReviewPlaybookRegistryEntry = {
   id: 'review',
   command: 'review',
   intent:
-    'review the latest commit until no material correctness or spec findings remain',
+    'review a supplied scope of committed work until no unsettled findings remain',
   artifactSchema: 3,
   runtimeProfile: Object.freeze({
     kind: 'shared-factory',