@sublang/playbook 17.7.0 → 17.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "17.7.0",
+  "version": "17.8.0",
   "type": "module",
   "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, REVIEW, DECIDE, DEV, BRANCH, PR, and INSPECT workflows driven by GEARS specs.",
   "license": "Apache-2.0",

package/reference/sdlc/code.playbook/bin/repository-effects.js

@@ -976,27 +976,43 @@ async function isAncestor(worktree, baselineHead, afterHead) {
   }
 }
 
-async function descendantCount(worktree, baselineHead, afterHead) {
-  const value = await runGitText(worktree, [
+// DR-088 §1: the commits reachable from the after HEAD and not from the
+// baseline HEAD — every reachable commit for the null HEAD — oldest first, so
+// the last is the after HEAD itself.
+async function newCommits(worktree, baselineHead, afterHead) {
+  const raw = await runGitText(worktree, [
     'rev-list',
-    '--count',
+    '--topo-order',
+    '--reverse',
     baselineHead === NULL_GIT_OID ? afterHead : `${baselineHead}..${afterHead}`,
   ]);
-  const count = Number(value);
-  if (!Number.isSafeInteger(count) || count < 0) {
+  const commits = raw.length === 0 ? [] : raw.split('\n');
+  if (
+    commits.some((oid) => !/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(oid)) ||
+    new Set(commits).size !== commits.length ||
+    (commits.length > 0 && commits.at(-1) !== afterHead)
+  ) {
     throw new RepositoryObservationAmbiguousError(
-      'Git returned an invalid descendant count',
+      'Git returned an invalid list of new commits',
     );
   }
-  return count;
+  return commits;
 }
 
-function receipt(classification, baseline, after, commitOid, preExisting) {
+function receipt(
+  classification,
+  baseline,
+  after,
+  commitOid,
+  preExisting,
+  commits,
+) {
   return deepFreeze({
     classification,
     baseline,
     ...(after === undefined ? {} : { after }),
     ...(commitOid === undefined ? {} : { commitOid }),
+    ...(commits === undefined ? {} : { commits }),
     ...(preExisting === undefined ? {} : { preExisting }),
   });
 }
@@ -1049,12 +1065,13 @@ export async function classifyRepositoryReceipt(
   ) {
     return receipt('rewritten-or-non-descendant', baseline, after);
   }
-  const count = await descendantCount(after.worktree, baseline.head, after.head);
-  if (count > 1) return receipt('multiple-commits', baseline, after);
-  if (count !== 1) {
+  // DR-088 §1: HEAD advanced by one or more new commits; a receipt of more
+  // than one lists every one, oldest first.
+  const commits = await newCommits(after.worktree, baseline.head, after.head);
+  if (commits.length === 0) {
     return receipt('rewritten-or-non-descendant', baseline, after);
   }
-  // DR-062 §2: the one commit proves itself when every baseline entry is
+  // DR-062 §2: the advance proves itself when every baseline entry is
   // preserved, absorbed, or altered and carried by it, and the after
   // projection holds nothing else.
   const fates = await baselineEntryFates(baseline, after);
@@ -1071,6 +1088,7 @@ export async function classifyRepositoryReceipt(
     after,
     unattributable ? undefined : after.head,
     preExistingFromFates(fates),
+    unattributable || commits.length === 1 ? undefined : commits,
   );
 }
 

package/reference/sdlc/code.playbook/host-capabilities.d.ts

@@ -42,6 +42,8 @@ export interface PlaybookRepositoryReceipt {
   readonly baseline: PlaybookRepositoryObservation;
   readonly after?: PlaybookRepositoryObservation;
   readonly commitOid?: string;
+  /** Every new commit, oldest first, where HEAD advanced by more than one (DR-088). */
+  readonly commits?: readonly string[];
   readonly preExisting?: PlaybookRepositoryPreExistingChanges;
 }
 export interface RepositoryReceiptOptions {

package/reference/sdlc/code.playbook/playbook-captain.js

@@ -621,6 +621,112 @@ function carriedPreExistingFacts(carried) {
         return `The commit ${commitOid} carries changes that were uncommitted before the step: ${lists.join('; ')}.`;
     });
 }
+function commitsBeforeFailure(ledger, boundaryPrefixCount, unresolvedEffects) {
+    // An entry names a commit by its proven OID, or — for a receipt listing
+    // several commits, which projects as `multiple-commits` (DR-088 §3) — by
+    // its after HEAD, the last of them.
+    const named = new Set(unresolvedEffects.flatMap(({ classification, afterHead, commitOid }) => commitOid !== undefined
+        ? [commitOid]
+        : classification === 'multiple-commits' && afterHead !== undefined
+            ? [afterHead]
+            : []));
+    const commits = [];
+    for (const boundary of ledger.boundaries) {
+        if (boundary.sequence <= boundaryPrefixCount)
+            continue;
+        const receipt = boundary.physicalReceipt;
+        if (receipt?.classification !== 'one-descendant-commit' ||
+            receipt.commitOid === undefined ||
+            named.has(receipt.commitOid)) {
+            continue;
+        }
+        named.add(receipt.commitOid);
+        commits.push({
+            baselineHead: receipt.baseline.head,
+            commitOid: receipt.commitOid,
+            ...(receipt.commits === undefined ? {} : { commits: receipt.commits }),
+        });
+    }
+    return commits;
+}
+/** What one step committed, with every commit where it made several (DR-088). */
+function commitBeforeFailureClause({ baselineHead, commitOid, commits, }) {
+    const made = commits === undefined
+        ? 'made one new commit'
+        : `made ${commits.length} new commits, oldest first: ${boundedPathList(commits)}`;
+    return `${made}; HEAD moved from ${baselineHead} to the proven commit ${commitOid}.`;
+}
+function commitBeforeFailureFact(commit) {
+    return `Before the failure, a step ${commitBeforeFailureClause(commit)}`;
+}
+function commitsBeforeFailureReport(commits) {
+    if (commits.length === 0)
+        return undefined;
+    return [
+        'Repository changes made before the failure:',
+        ...commits.map((commit) => `- A step ${commitBeforeFailureClause(commit)}`),
+        'The failure does not undo these commits.',
+    ].join('\n');
+}
+/**
+ * DR-088 §2: whether a final text names one commit as a word, by its full OID
+ * or by an abbreviation of at least seven leading hex digits — the
+ * reconciler's own designation rule, read here to say what it accepted.
+ */
+function finalTextNamesCommit(finalText, oid) {
+    for (const [word] of finalText.matchAll(/(?<![0-9A-Za-z_])[0-9A-Fa-f]{7,64}(?![0-9A-Za-z_])/g)) {
+        if (oid.startsWith(word.toLowerCase()))
+            return true;
+    }
+    return false;
+}
+/**
+ * DR-088 §3: what the steps completed after `boundaryPrefixCount` committed,
+ * one statement each, in boundary sequence order: every new commit where a
+ * receipt proves more than one, and the commit already at HEAD where a step
+ * whose outcomes all commit or ask named it over an `unchanged` receipt. A
+ * step in a deferred chain reads the chain's cumulative receipt at its last
+ * boundary.
+ */
+function stepCommitStatements(ledger, boundaryPrefixCount) {
+    const statements = [];
+    for (const boundary of ledger.boundaries) {
+        if (boundary.sequence <= boundaryPrefixCount)
+            continue;
+        let receipt = boundary.physicalReceipt;
+        if (boundary.logicalOperationId !== undefined) {
+            const operation = ledger.logicalOperations.find(({ operationId }) => operationId === boundary.logicalOperationId);
+            if (operation?.boundaryIds.at(-1) !== boundary.boundaryId)
+                continue;
+            receipt = operation.logicalReceipt;
+        }
+        if (receipt === undefined)
+            continue;
+        if (receipt.classification === 'one-descendant-commit' &&
+            receipt.commits !== undefined) {
+            statements.push(`The step made ${receipt.commits.length} new commits, oldest first: ${boundedPathList(receipt.commits)}.`);
+            continue;
+        }
+        const candidate = boundary.semanticCandidate;
+        const guard = candidate !== null &&
+            typeof candidate === 'object' &&
+            !Array.isArray(candidate)
+            ? candidate.guard
+            : undefined;
+        const head = receipt.after?.head;
+        if (receipt.classification === 'unchanged' &&
+            head !== undefined &&
+            !/^0+$/.test(head) &&
+            boundary.dispositions.includes('one-descendant-commit') &&
+            !boundary.dispositions.includes('unchanged') &&
+            typeof guard === 'string' &&
+            guard !== BOSS_QUESTION_OUTCOME &&
+            finalTextNamesCommit(boundary.finalText?.trim() ?? '', head)) {
+            statements.push(`The step made no new commit; it named ${head}, already at HEAD, as its work.`);
+        }
+    }
+    return statements;
+}
 // DR-063 §4: the Boss-visible failure report. Every host sees the same
 // sentences because the shell composes them from the structured cause instead
 // of asking a model to describe facts it may drop. The report exposes no file
@@ -2402,6 +2508,15 @@ async function buildEnablements(options, loadModule, hostCapabilities) {
 const unresolvedEffectFromReceipt = (receipt, baselineHead = receipt.baseline.head) => {
     if (receipt.classification === 'unchanged')
         return undefined;
+    // DR-088 §3: a receipt listing more than one new commit reads as
+    // `multiple-commits`, whose entry names more than one commit and no OID.
+    if (receipt.commits !== undefined) {
+        return {
+            classification: 'multiple-commits',
+            baselineHead,
+            ...(receipt.after === undefined ? {} : { afterHead: receipt.after.head }),
+        };
+    }
     return {
         classification: receipt.classification,
         baselineHead,
@@ -2478,12 +2593,18 @@ const cumulativeOpenLogicalEffect = (operation, boundaries) => {
     }
     if (receipt.classification === 'one-descendant-commit' &&
         (sameProjection || receiptAccountsFromOriginal)) {
-        return {
-            classification: 'one-descendant-commit',
-            baselineHead: original.head,
-            afterHead: after.head,
-            commitOid: after.head,
-        };
+        return receipt.commits === undefined
+            ? {
+                classification: 'one-descendant-commit',
+                baselineHead: original.head,
+                afterHead: after.head,
+                commitOid: after.head,
+            }
+            : {
+                classification: 'multiple-commits',
+                baselineHead: original.head,
+                afterHead: after.head,
+            };
     }
     return {
         classification: 'observation-ambiguous',
@@ -2792,21 +2913,30 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         if (turn.carriedEffectPrefix !== undefined)
             return;
         let carried;
+        let commitStatements;
         try {
             const ledger = assertPlaybookEffectLedger(currentEffectLedger());
             carried = carriedPreExistingChanges(ledger, presentedEffectPrefix);
+            commitStatements = stepCommitStatements(ledger, presentedEffectPrefix);
             turn.carriedEffectPrefix = ledger.boundaries.length;
         }
         catch {
             return;
         }
         const report = carriedPreExistingReport(carried);
-        if (report === undefined)
-            return;
-        const facts = carriedPreExistingFacts(carried);
-        appendMandatoryPresentationSuffix(turn, report, facts);
-        for (const fact of facts) {
-            joinSettlementFact(turn, fact);
+        if (report !== undefined) {
+            const facts = carriedPreExistingFacts(carried);
+            appendMandatoryPresentationSuffix(turn, report, facts);
+            for (const fact of facts) {
+                joinSettlementFact(turn, fact);
+            }
+        }
+        // DR-088 §3: the commits each step took, read from the same boundaries.
+        if (commitStatements.length > 0) {
+            appendMandatoryPresentationSuffix(turn, commitStatements.join('\n'), commitStatements);
+            for (const fact of commitStatements) {
+                joinSettlementFact(turn, fact);
+            }
         }
     };
     /**
@@ -6203,6 +6333,26 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             controls: failureControlLines(view, fenced),
         };
         joinSettlementFact(turn, fact, statement?.fact, speak);
+        reportCommitsBeforeFailure(turn, unresolvedEffects);
+    };
+    // DR-089: the commits the turn's receipts proved before its leaf parked,
+    // stated beside the failure report and joined to the settlement facts the
+    // closing-reply prompt reads.
+    const reportCommitsBeforeFailure = (turn, unresolvedEffects) => {
+        let commits;
+        try {
+            commits = commitsBeforeFailure(assertPlaybookEffectLedger(currentEffectLedger()), presentedEffectPrefix, unresolvedEffects);
+        }
+        catch {
+            return;
+        }
+        const report = commitsBeforeFailureReport(commits);
+        if (report === undefined)
+            return;
+        const facts = commits.map(commitBeforeFailureFact);
+        appendMandatoryPresentationSuffix(turn, report, facts);
+        for (const fact of facts)
+            joinSettlementFact(turn, fact);
     };
     // The runtimes own each frame's position. The shell only joins their stack.
     const saveProgress = async (starting, step, required = true) => {

package/reference/sdlc/code.playbook/playbook-captain.ts

@@ -1490,6 +1490,158 @@ function carriedPreExistingFacts(
   });
 }
 
+// DR-089: a turn whose leaf parks in failure still states, as fact, every
+// commit its steps proved before the failure, so a closing reply never tells
+// the Boss that nothing was written when a receipt shows otherwise. A commit
+// the unresolved-effect report already names is not said twice.
+interface CommitBeforeFailure {
+  readonly baselineHead: string;
+  readonly commitOid: string;
+  /** Every new commit, oldest first, where the step made more than one (DR-088). */
+  readonly commits?: readonly string[];
+}
+
+function commitsBeforeFailure(
+  ledger: PlaybookEffectLedger,
+  boundaryPrefixCount: number,
+  unresolvedEffects: readonly PlaybookCaptainUnresolvedEffect[],
+): readonly CommitBeforeFailure[] {
+  // An entry names a commit by its proven OID, or — for a receipt listing
+  // several commits, which projects as `multiple-commits` (DR-088 §3) — by
+  // its after HEAD, the last of them.
+  const named = new Set(
+    unresolvedEffects.flatMap(({ classification, afterHead, commitOid }) =>
+      commitOid !== undefined
+        ? [commitOid]
+        : classification === 'multiple-commits' && afterHead !== undefined
+          ? [afterHead]
+          : [],
+    ),
+  );
+  const commits: CommitBeforeFailure[] = [];
+  for (const boundary of ledger.boundaries) {
+    if (boundary.sequence <= boundaryPrefixCount) continue;
+    const receipt = boundary.physicalReceipt;
+    if (
+      receipt?.classification !== 'one-descendant-commit' ||
+      receipt.commitOid === undefined ||
+      named.has(receipt.commitOid)
+    ) {
+      continue;
+    }
+    named.add(receipt.commitOid);
+    commits.push({
+      baselineHead: receipt.baseline.head,
+      commitOid: receipt.commitOid,
+      ...(receipt.commits === undefined ? {} : { commits: receipt.commits }),
+    });
+  }
+  return commits;
+}
+
+/** What one step committed, with every commit where it made several (DR-088). */
+function commitBeforeFailureClause({
+  baselineHead,
+  commitOid,
+  commits,
+}: CommitBeforeFailure): string {
+  const made =
+    commits === undefined
+      ? 'made one new commit'
+      : `made ${commits.length} new commits, oldest first: ${boundedPathList(commits)}`;
+  return `${made}; HEAD moved from ${baselineHead} to the proven commit ${commitOid}.`;
+}
+
+function commitBeforeFailureFact(commit: CommitBeforeFailure): string {
+  return `Before the failure, a step ${commitBeforeFailureClause(commit)}`;
+}
+
+function commitsBeforeFailureReport(
+  commits: readonly CommitBeforeFailure[],
+): string | undefined {
+  if (commits.length === 0) return undefined;
+  return [
+    'Repository changes made before the failure:',
+    ...commits.map(
+      (commit) => `- A step ${commitBeforeFailureClause(commit)}`,
+    ),
+    'The failure does not undo these commits.',
+  ].join('\n');
+}
+
+/**
+ * DR-088 §2: whether a final text names one commit as a word, by its full OID
+ * or by an abbreviation of at least seven leading hex digits — the
+ * reconciler's own designation rule, read here to say what it accepted.
+ */
+function finalTextNamesCommit(finalText: string, oid: string): boolean {
+  for (const [word] of finalText.matchAll(
+    /(?<![0-9A-Za-z_])[0-9A-Fa-f]{7,64}(?![0-9A-Za-z_])/g,
+  )) {
+    if (oid.startsWith(word.toLowerCase())) return true;
+  }
+  return false;
+}
+
+/**
+ * DR-088 §3: what the steps completed after `boundaryPrefixCount` committed,
+ * one statement each, in boundary sequence order: every new commit where a
+ * receipt proves more than one, and the commit already at HEAD where a step
+ * whose outcomes all commit or ask named it over an `unchanged` receipt. A
+ * step in a deferred chain reads the chain's cumulative receipt at its last
+ * boundary.
+ */
+function stepCommitStatements(
+  ledger: PlaybookEffectLedger,
+  boundaryPrefixCount: number,
+): readonly string[] {
+  const statements: string[] = [];
+  for (const boundary of ledger.boundaries) {
+    if (boundary.sequence <= boundaryPrefixCount) continue;
+    let receipt = boundary.physicalReceipt;
+    if (boundary.logicalOperationId !== undefined) {
+      const operation = ledger.logicalOperations.find(
+        ({ operationId }) => operationId === boundary.logicalOperationId,
+      );
+      if (operation?.boundaryIds.at(-1) !== boundary.boundaryId) continue;
+      receipt = operation.logicalReceipt;
+    }
+    if (receipt === undefined) continue;
+    if (
+      receipt.classification === 'one-descendant-commit' &&
+      receipt.commits !== undefined
+    ) {
+      statements.push(
+        `The step made ${receipt.commits.length} new commits, oldest first: ${boundedPathList(receipt.commits)}.`,
+      );
+      continue;
+    }
+    const candidate = boundary.semanticCandidate;
+    const guard =
+      candidate !== null &&
+      typeof candidate === 'object' &&
+      !Array.isArray(candidate)
+        ? (candidate as { readonly [key: string]: JsonValue }).guard
+        : undefined;
+    const head = receipt.after?.head;
+    if (
+      receipt.classification === 'unchanged' &&
+      head !== undefined &&
+      !/^0+$/.test(head) &&
+      boundary.dispositions.includes('one-descendant-commit') &&
+      !boundary.dispositions.includes('unchanged') &&
+      typeof guard === 'string' &&
+      guard !== BOSS_QUESTION_OUTCOME &&
+      finalTextNamesCommit(boundary.finalText?.trim() ?? '', head)
+    ) {
+      statements.push(
+        `The step made no new commit; it named ${head}, already at HEAD, as its work.`,
+      );
+    }
+  }
+  return statements;
+}
+
 // DR-063 §4: the Boss-visible failure report. Every host sees the same
 // sentences because the shell composes them from the structured cause instead
 // of asking a model to describe facts it may drop. The report exposes no file
@@ -4250,6 +4402,15 @@ const unresolvedEffectFromReceipt = (
   baselineHead = receipt.baseline.head,
 ): PlaybookCaptainUnresolvedEffect | undefined => {
   if (receipt.classification === 'unchanged') return undefined;
+  // DR-088 §3: a receipt listing more than one new commit reads as
+  // `multiple-commits`, whose entry names more than one commit and no OID.
+  if (receipt.commits !== undefined) {
+    return {
+      classification: 'multiple-commits',
+      baselineHead,
+      ...(receipt.after === undefined ? {} : { afterHead: receipt.after.head }),
+    };
+  }
   return {
     classification: receipt.classification,
     baselineHead,
@@ -4352,12 +4513,18 @@ const cumulativeOpenLogicalEffect = (
     receipt.classification === 'one-descendant-commit' &&
     (sameProjection || receiptAccountsFromOriginal)
   ) {
-    return {
-      classification: 'one-descendant-commit',
-      baselineHead: original.head,
-      afterHead: after.head,
-      commitOid: after.head,
-    };
+    return receipt.commits === undefined
+      ? {
+          classification: 'one-descendant-commit',
+          baselineHead: original.head,
+          afterHead: after.head,
+          commitOid: after.head,
+        }
+      : {
+          classification: 'multiple-commits',
+          baselineHead: original.head,
+          afterHead: after.head,
+        };
   }
   return {
     classification: 'observation-ambiguous',
@@ -4772,19 +4939,33 @@ export function createPlaybookCaptainShell(
   const reportCarriedPreExistingChanges = (turn: ActiveTurn): void => {
     if (turn.carriedEffectPrefix !== undefined) return;
     let carried: readonly CarriedPreExistingChanges[];
+    let commitStatements: readonly string[];
     try {
       const ledger = assertPlaybookEffectLedger(currentEffectLedger());
       carried = carriedPreExistingChanges(ledger, presentedEffectPrefix);
+      commitStatements = stepCommitStatements(ledger, presentedEffectPrefix);
       turn.carriedEffectPrefix = ledger.boundaries.length;
     } catch {
       return;
     }
     const report = carriedPreExistingReport(carried);
-    if (report === undefined) return;
-    const facts = carriedPreExistingFacts(carried);
-    appendMandatoryPresentationSuffix(turn, report, facts);
-    for (const fact of facts) {
-      joinSettlementFact(turn, fact);
+    if (report !== undefined) {
+      const facts = carriedPreExistingFacts(carried);
+      appendMandatoryPresentationSuffix(turn, report, facts);
+      for (const fact of facts) {
+        joinSettlementFact(turn, fact);
+      }
+    }
+    // DR-088 §3: the commits each step took, read from the same boundaries.
+    if (commitStatements.length > 0) {
+      appendMandatoryPresentationSuffix(
+        turn,
+        commitStatements.join('\n'),
+        commitStatements,
+      );
+      for (const fact of commitStatements) {
+        joinSettlementFact(turn, fact);
+      }
     }
   };
 
@@ -8965,6 +9146,31 @@ export function createPlaybookCaptainShell(
       controls: failureControlLines(view, fenced),
     };
     joinSettlementFact(turn, fact, statement?.fact, speak);
+    reportCommitsBeforeFailure(turn, unresolvedEffects);
+  };
+
+  // DR-089: the commits the turn's receipts proved before its leaf parked,
+  // stated beside the failure report and joined to the settlement facts the
+  // closing-reply prompt reads.
+  const reportCommitsBeforeFailure = (
+    turn: ActiveTurn,
+    unresolvedEffects: readonly PlaybookCaptainUnresolvedEffect[],
+  ): void => {
+    let commits: readonly CommitBeforeFailure[];
+    try {
+      commits = commitsBeforeFailure(
+        assertPlaybookEffectLedger(currentEffectLedger()),
+        presentedEffectPrefix,
+        unresolvedEffects,
+      );
+    } catch {
+      return;
+    }
+    const report = commitsBeforeFailureReport(commits);
+    if (report === undefined) return;
+    const facts = commits.map(commitBeforeFailureFact);
+    appendMandatoryPresentationSuffix(turn, report, facts);
+    for (const fact of facts) joinSettlementFact(turn, fact);
   };
 
   // The runtimes own each frame's position. The shell only joins their stack.

package/slc/link.md

@@ -341,6 +341,7 @@ interface PlaybookRepositoryReceipt {
   readonly baseline: PlaybookRepositoryObservation;
   readonly after?: PlaybookRepositoryObservation;
   readonly commitOid?: string;
+  readonly commits?: readonly string[];
 }
 
 type PlaybookRepositoryDisposition =
@@ -1286,6 +1287,12 @@ runtime-owned payload field; `guard` shall name exactly one outcome declared
 by both the live result map and `outcomeAuthority`; and every semantic-owned
 field shall satisfy the result map's required-field type before any actor
 output is delivered.
+That type is the value shape the compiled FSM's own validator admits for the
+field: the shared engine reads it once at construction by presenting each
+governed outcome's accepting arm with sample values of a closed set of shapes,
+a field whose shape the FSM admits as a string or does not reveal stays a
+string, and the judge prompt and validation error name every non-string shape
+([DR-089](../specs/decisions/089-judge-replies-take-the-machines-shapes.md)).
 The judge prompt shall render each governed outcome's description with its
 meaning verbatim and its `Output shall include` clause replaced by that reply
 contract — exactly `guard` plus the semantic-owned fields, each keeping its
@@ -1320,10 +1327,16 @@ physical receipt, or the complete cumulative logical receipt of a deferred
 operation, whose classification is exactly the outcome's declared
 `unchanged` or `one-descendant-commit` disposition; a `one-descendant-commit`
 receipt shall carry exactly the after-HEAD OID used for the arm's effect-owned
-fields, while an `unchanged` receipt's complete validated observation supplies
-its observed HEAD OID for them, and a receipt that cannot prove that observed
-HEAD shall leave the envelope unresolved rather than inject a fabricated
-value.
+fields, and lists every new commit in `commits` where HEAD advanced by more
+than one, while an `unchanged` receipt's complete validated observation
+supplies its observed HEAD OID for them, and a receipt that cannot prove that
+observed HEAD shall leave the envelope unresolved rather than inject a
+fabricated value.
+A `one-descendant-commit` outcome shall also resolve over an `unchanged`
+receipt whose HEAD names a commit when no outcome of that call declares
+`unchanged` and the trimmed `finalText` names that commit as a word, by its
+full OID or an abbreviation of at least seven leading hex digits; its
+effect-owned fields then take that HEAD OID.
 A `deferred` candidate shall be admissible only for its already-validated
 effect-authorized `needsBossReply` outcome and only from a complete after
 observation whose HEAD equals the logical operation's original baseline HEAD
@@ -1373,10 +1386,16 @@ player or judge call.
 The adjudicator shall use the same document-order tolerant JSON recovery as
 the Boss classifier. Unlike invalid classification, a reply from which no
 object can be recovered, an undeclared guard, or a missing required field is a
-control-plane error for nongoverned delegated-player and direct-Captain adjudication and
+control-plane error for nongoverned delegated-player adjudication and
 shall throw after the invocation reaches its FSM error path and ordered
 emissions drain; schema-3 governed adjudication follows the bounded
 reconciliation contract above instead.
+Direct-Captain adjudication treats such a reply, or one carrying an undeclared
+field, as a structural error: it makes exactly one corrective adjudication over
+the same visible output that restates the reply and its validation error, and
+a second structural error routes the invocation to its FSM failure state as a
+recoverable `judge-failed` failure rather than a control-plane error
+([DR-089](../specs/decisions/089-judge-replies-take-the-machines-shapes.md)).
 
 Two default adjudication strategies, in selection order:
 
@@ -1389,7 +1408,11 @@ Two default adjudication strategies, in selection order:
   `{ guard, …semanticOwnedPayloadFields }` and explicitly forbids every other
   payload field. The governed form also permits the blocked report above when no outcome matches.
   Both forms exclude the runtime-injected direct-Captain
-  `question` and `response` fields above. The prompt shall identify hidden control work,
+  `question` and `response` fields above. A direct-Captain prompt keeps each
+  description and states under it the exact reply that key takes — `guard`
+  plus the structural fields its `Output shall include` clause names, each with
+  its authored placeholder — naming `question` and `response` as
+  runtime-supplied. The prompt shall identify hidden control work,
   prohibit tool use, file inspection, and external evidence, direct the judge
   to decide only from the supplied actor output and declared outcomes, and
   require exactly one JSON object with no prose. The judge prompt shall not