@sublang/playbook 14.0.0 → 14.1.0

package/docs/cli.md

@@ -124,20 +124,20 @@ untouched
 The current CODE, REVIEW, DECIDE, DEV, BRANCH, and PR workflows take their
 deterministic initial event from the selecting Boss turn. CODE and DECIDE then
 call REVIEW as a nested playbook, while DEV — the repository-aware planner
-behind `/dev` — analyzes a development request and itself calls CODE, or
-DECIDE and then CODE, as nested playbooks. When the request names a GitHub
-issue or asks for pull-request delivery, DEV reads the issue and its comments
-while planning, calls BRANCH before that path and PR after CODE succeeds, and
-ends with a merged pull request and a closed issue — or with a named failure
-that leaves the pull request open for a later `/pr`. Both are usable on their
-own: `/branch <issue or request>` creates and checks out `issue-N-slug` (or a
-request slug) at the current commit, changing nothing else; `/pr` pushes the
-checked-out branch, opens or reuses its pull request against the default
-branch, waits for the checks, fixes red checks through one nested CODE call,
-merges with a merge commit, and fast-forwards the local default branch. A
-repository without checks merges on CODE's nested review alone. BRANCH, PR,
-and issue-aware DEV planning require the GitHub CLI `gh`, authenticated for
-the repository's GitHub remote
+behind `/dev` — chooses the development path for a request and itself calls
+CODE, or DECIDE and then CODE, as nested playbooks. When the request names a
+GitHub issue or asks for pull-request delivery, DEV reads the issue and its
+comments while planning, calls BRANCH before that path and PR after CODE
+succeeds, and ends with a merged pull request and a closed issue — or with a
+named failure that leaves the pull request open for a later `/pr`. Both are
+usable on their own: `/branch <issue or request>` creates and checks out
+`issue-N-slug` (or a request slug) at the current commit, changing nothing
+else; `/pr` pushes the checked-out branch, opens or reuses its pull request
+against the default branch, waits for the checks, fixes red checks through one
+nested CODE call, merges with a merge commit, and fast-forwards the local
+default branch. A repository without checks merges on CODE's nested review
+alone. BRANCH, PR, and issue-aware DEV planning require the GitHub CLI `gh`,
+authenticated for the repository's GitHub remote
 ([DR-050](https://github.com/sublang-ai/playbook/blob/main/specs/decisions/050-pull-request-delivery.md)).
 Local role names do not imply continuity: each frame
 uses the exact stable player IDs configured under its `roles` map. Equal IDs

package/package.json

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

package/reference/sdlc/branch.playbook/branch.fsm.d.ts

@@ -131,7 +131,7 @@ export declare const branchMachine: import("xstate").StateMachine<BranchContext,
 } | {
     type: "resumesCreateBranch";
     params: unknown;
-}, never, "failed" | "awaitBossReply" | "ready" | "refused" | "createBranch" | "branched", string, Readonly<Record<string, never>>, {
+}, never, "failed" | "ready" | "awaitBossReply" | "refused" | "createBranch" | "branched", string, Readonly<Record<string, never>>, {
     readonly status: "branched";
     /** Exact name of the new branch now checked out. */
     readonly branch: string;

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

@@ -520,14 +520,169 @@ function projectionText(projection) {
   return JSON.stringify(projection);
 }
 
-function projectionPreservesBaseline(baseline, after) {
-  return Object.entries(baseline).every(
-    ([path, entry]) =>
-      Object.prototype.hasOwnProperty.call(after, path) &&
-      JSON.stringify(after[path]) === JSON.stringify(entry),
+const MISSING_CONTENT_IDENTITY = Object.freeze({ kind: 'missing' });
+
+function hasPath(projection, path) {
+  return Object.prototype.hasOwnProperty.call(projection, path);
+}
+
+// DR-062 §1: a rename, an unmerged path, a submodule, or a nested worktree is
+// preserved when byte-equal and otherwise lost, because no content matching is
+// attempted for them.
+function nonComparableBaselineEntry(entry) {
+  return (
+    entry.kind === 'rename-or-copy' ||
+    entry.kind === 'unmerged' ||
+    (entry.submodule !== undefined && entry.submodule !== 'N...') ||
+    entry.worktree?.kind === 'directory'
   );
 }
 
+// The entry the baseline HEAD tree held for a path: an ordinary porcelain-v2
+// record carries its HEAD mode and OID, `000000` means the path did not exist
+// there, an untracked path never did, and an unborn baseline HEAD holds none.
+function baselineHeadEntry(baseline, entry) {
+  if (baseline.head === NULL_GIT_OID) return undefined;
+  if (entry.kind !== 'ordinary') return undefined;
+  if (entry.headMode === undefined || entry.headMode === '000000') {
+    return undefined;
+  }
+  return { mode: entry.headMode, oid: entry.headOid };
+}
+
+function sameTreeEntry(left, right) {
+  if (left === undefined || right === undefined) return left === right;
+  return left.mode === right.mode && left.oid === right.oid;
+}
+
+// The baseline recorded nothing at the path: a deleted worktree entry, or a
+// staged deletion whose index holds no object.
+function baselineEntryIsDeletion(entry) {
+  return entry.worktree === undefined
+    ? entry.indexMode === '000000'
+    : entry.worktree.kind === 'missing';
+}
+
+// The entry one commit's tree holds for an exact path, or undefined when that
+// tree holds none.
+async function afterTreeEntry(worktree, head, path) {
+  const raw = await runGitText(worktree, [
+    'ls-tree',
+    '-z',
+    '--full-tree',
+    head,
+    '--',
+    path,
+  ]);
+  for (const record of raw.split('\0')) {
+    if (record.length === 0) continue;
+    const tab = record.indexOf('\t');
+    const fields = tab < 0 ? [] : record.slice(0, tab).split(' ');
+    if (fields.length !== 3) {
+      throw new RepositoryObservationAmbiguousError(
+        'Git returned a malformed tree record',
+      );
+    }
+    if (record.slice(tab + 1) !== path) continue;
+    return { mode: fields[0], oid: fields[2] };
+  }
+  return undefined;
+}
+
+// A blob addressed exactly as `worktreePathIdentity` addresses the same bytes
+// in the working tree, so a committed object and the Boss's own content are
+// comparable by the projection's content addressing rather than by Git OID.
+async function blobContentIdentity(worktree, mode, oid) {
+  const bytes = await runGit(worktree, ['cat-file', 'blob', oid]);
+  return {
+    kind: mode === '120000' ? 'symlink' : 'file',
+    mode,
+    content: `sha256:${sha256(bytes)}`,
+  };
+}
+
+function baselineContentIdentity(worktree, entry) {
+  return entry.worktree === undefined
+    ? blobContentIdentity(worktree, entry.indexMode, entry.indexOid)
+    : entry.worktree;
+}
+
+function sameContentIdentity(left, right) {
+  return (
+    left.kind === right.kind &&
+    left.mode === right.mode &&
+    left.content === right.content
+  );
+}
+
+// DR-062 §1: the fate of one baseline projection entry at the end of a
+// governed call — `preserved`, `altered-uncommitted`, `altered-committed`,
+// `absorbed`, or `lost`.
+async function baselineEntryFate(baseline, after, path, entry) {
+  if (hasPath(after.projection, path)) {
+    return JSON.stringify(after.projection[path]) === JSON.stringify(entry)
+      ? 'preserved'
+      : 'altered-uncommitted';
+  }
+  // The entry left the working tree, so only a commit this call made can hold
+  // the Boss's content; a call that moved no HEAD made none.
+  if (baseline.head === after.head) return 'lost';
+  if (nonComparableBaselineEntry(entry)) return 'lost';
+  try {
+    const treeEntry = await afterTreeEntry(after.worktree, after.head, path);
+    if (sameTreeEntry(treeEntry, baselineHeadEntry(baseline, entry))) {
+      // The commit left the path exactly as the baseline HEAD held it, so it
+      // carried no change of the Boss's and his content is nowhere.
+      return 'lost';
+    }
+    if (baselineEntryIsDeletion(entry)) {
+      return treeEntry === undefined ? 'absorbed' : 'lost';
+    }
+    if (treeEntry?.mode === '160000') return 'lost';
+    const [baselineIdentity, treeIdentity] = await Promise.all([
+      baselineContentIdentity(after.worktree, entry),
+      treeEntry === undefined
+        ? MISSING_CONTENT_IDENTITY
+        : blobContentIdentity(after.worktree, treeEntry.mode, treeEntry.oid),
+    ]);
+    return sameContentIdentity(baselineIdentity, treeIdentity)
+      ? 'absorbed'
+      : 'altered-committed';
+  } catch {
+    // Content the after HEAD cannot produce leaves the baseline entry
+    // unaccounted for, which fails closed exactly as a lost entry does.
+    return 'lost';
+  }
+}
+
+async function baselineEntryFates(baseline, after) {
+  const fates = [];
+  for (const [path, entry] of Object.entries(baseline.projection)) {
+    fates.push([path, await baselineEntryFate(baseline, after, path, entry)]);
+  }
+  return fates;
+}
+
+// DR-062 §3: the accounting a receipt records, present exactly when one list
+// is nonempty so that an all-preserved call keeps today's receipt shape.
+function preExistingFromFates(fates) {
+  const absorbed = [];
+  const altered = [];
+  const lost = [];
+  for (const [path, fate] of fates) {
+    if (fate === 'absorbed') absorbed.push(path);
+    else if (fate === 'altered-uncommitted' || fate === 'altered-committed') {
+      altered.push(path);
+    } else if (fate === 'lost') lost.push(path);
+  }
+  if (absorbed.length + altered.length + lost.length === 0) return undefined;
+  return {
+    absorbed: absorbed.sort(),
+    altered: altered.sort(),
+    lost: lost.sort(),
+  };
+}
+
 async function rawRepositoryStatus(worktree, env) {
   return runGit(
     worktree,
@@ -788,12 +943,13 @@ async function descendantCount(worktree, baselineHead, afterHead) {
   return count;
 }
 
-function receipt(classification, baseline, after, commitOid) {
+function receipt(classification, baseline, after, commitOid, preExisting) {
   return deepFreeze({
     classification,
     baseline,
     ...(after === undefined ? {} : { after }),
     ...(commitOid === undefined ? {} : { commitOid }),
+    ...(preExisting === undefined ? {} : { preExisting }),
   });
 }
 
@@ -821,16 +977,19 @@ export async function classifyRepositoryReceipt(
   if (allowed.every((value) => value === 'unchanged')) {
     return receipt('concurrent-or-foreign-change', baseline, after);
   }
+  // DR-062 §2: a same-HEAD delta admits altered pre-existing entries beside
+  // new ones; only an entry whose change is nowhere keeps it ambiguous.
   if (sameHead) {
-    if (!projectionPreservesBaseline(baseline.projection, after.projection)) {
-      return receipt('observation-ambiguous', baseline, after);
-    }
+    const fates = await baselineEntryFates(baseline, after);
+    const lost = fates.some(([, fate]) => fate === 'lost');
     return receipt(
-      allowed.includes('one-descendant-commit')
+      !lost && allowed.includes('one-descendant-commit')
         ? 'worktree-only-change'
         : 'observation-ambiguous',
       baseline,
       after,
+      undefined,
+      preExistingFromFates(fates),
     );
   }
   // A HEAD that stopped naming a commit lost its history; every commit
@@ -847,10 +1006,24 @@ export async function classifyRepositoryReceipt(
   if (count !== 1) {
     return receipt('rewritten-or-non-descendant', baseline, after);
   }
-  if (!sameProjection) {
-    return receipt('observation-ambiguous', baseline, after);
-  }
-  return receipt('one-descendant-commit', baseline, after, after.head);
+  // DR-062 §2: the one commit 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);
+  const unattributable =
+    fates.some(
+      ([, fate]) => fate === 'lost' || fate === 'altered-uncommitted',
+    ) ||
+    Object.keys(after.projection).some(
+      (path) => !hasPath(baseline.projection, path),
+    );
+  return receipt(
+    unattributable ? 'observation-ambiguous' : 'one-descendant-commit',
+    baseline,
+    after,
+    unattributable ? undefined : after.head,
+    preExistingFromFates(fates),
+  );
 }
 
 export async function captureRepositoryReceipt(baseline, options = {}) {

package/reference/sdlc/code.playbook/code.fsm.d.ts

@@ -212,7 +212,7 @@ export declare const codingMachine: import("xstate").StateMachine<CodingContext,
 } | {
     type: "resumesIrTask";
     params: unknown;
-}, never, "done" | "failed" | "awaitBossReply" | "ready" | "runFirstPhase" | "reviewFirstCommit" | "runIrTask" | "reviewIrTask" | "reportedReviewFailure", string, CodingInput, {
+}, never, "done" | "failed" | "ready" | "awaitBossReply" | "runFirstPhase" | "reviewFirstCommit" | "runIrTask" | "reviewIrTask" | "reportedReviewFailure", string, CodingInput, {
     readonly status: "complete";
     /** Exact identity of the last CODE-owned commit. */
     readonly lastCodeCommit: string;

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

@@ -32,11 +32,17 @@ export interface PlaybookRepositoryObservation extends RepositoryIdentity {
   readonly projection: Readonly<Record<string, JsonValue>>;
   readonly projectionDigest: string;
 }
+export interface PlaybookRepositoryPreExistingChanges {
+  readonly absorbed: readonly string[];
+  readonly altered: readonly string[];
+  readonly lost: readonly string[];
+}
 export interface PlaybookRepositoryReceipt {
   readonly classification: RepositoryReceiptClassification;
   readonly baseline: PlaybookRepositoryObservation;
   readonly after?: PlaybookRepositoryObservation;
   readonly commitOid?: string;
+  readonly preExisting?: PlaybookRepositoryPreExistingChanges;
 }
 export interface RepositoryReceiptOptions {
   readonly allowedDispositions: readonly PlaybookRepositoryDisposition[];

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

@@ -1,6 +1,6 @@
 import { type Captain, type CaptainSession, type TuningSelection } from '@sublang/cligent/tmux-play';
 import type { Effort, PermissionPolicy } from '@sublang/cligent';
-import type { JsonValue, PlaybookEffectLedger, PlaybookEffectLedgerCommandBatch, PlaybookControlAction, PlaybookRuntime, PlaybookRuntimeSnapshot } from '@sublang/playbook/runtime';
+import type { JsonValue, PlaybookEffectLedger, PlaybookEffectLedgerCommandBatch, PlaybookControlAction, PlaybookFailureCause, PlaybookRuntime, PlaybookRuntimeSnapshot } from '@sublang/playbook/runtime';
 import { type CaptainControllerPort } from '../captain.playbook/captain.playbook.js';
 import type { PlaybookSummaryPolicy } from './code.registry.js';
 interface SessionAgent {
@@ -176,9 +176,11 @@ type PlaybookCaptainShellSnapshotValue = PlaybookCaptainShellSnapshotFields & ({
     readonly frames: readonly PlaybookCaptainFrameSnapshot[];
     readonly retainedEffectReconciliation?: PlaybookCaptainRetainedEffectReconciliation;
     readonly pendingBossQuestions?: JsonValue;
+    /** DR-063 §2: the parked failure's cause travels with its error. */
     readonly lastError?: {
         readonly name: string;
         readonly message: string;
+        readonly cause?: PlaybookFailureCause;
     };
 });
 export type PlaybookCaptainShellSnapshot = DeepReadonly<PlaybookCaptainShellSnapshotValue>;