@sabaiway/agent-workflow-kit 12.4.0 → 13.1.0

package/tools/exec-producer.mjs

@@ -1,29 +1,32 @@
 // exec-producer.mjs — the GIT-side metric producer for an exec return (delegation Plan 2, Phase 1).
 // It answers the two questions a return record cannot answer for itself: which objects the delegated
-// run touched and how many bytes they represent, and what the canonical integration bundle is. It
-// never writes, never appends and never spawns anything but git reads.
+// run touched and how many bytes they represent, and what the canonical integration bundle is.
+// Under a checkpoint base the walks use the leaf's own temporary index and forced-add blob objects;
+// the real index is never written, and head walks spawn only git reads.
 //
 // dispatch-record.mjs:74-76 named this module before it existed: "the metric's byte domains are
 // computed over STRUCTURED inputs handed in by a producer; the git-side producer is Plan 2, and it
 // owns minting a stable objectId".
 //
-// ONE DOMAIN, THREE LAYERS (D7). The enumeration walks HEAD → index → worktree, exactly the layers
+// ONE DOMAIN, THREE LAYERS (D7) under a head base. The enumeration walks HEAD → index → worktree, exactly the layers
 // the canonical payload concatenates — never the collapsed HEAD → worktree view. The difference is
 // not academic: a staged change reverted in the worktree keeps its bytes in the payload (and so in
 // the DENOMINATOR) while HEAD→worktree shows nothing at all, so the object would vanish from the
 // NUMERATOR and the two halves of one ratio would describe different change sets. The diff bytes are
-// computeFingerprintPayload's own bytes, imported rather than rebuilt.
+// computeFingerprintPayload's own bytes, imported rather than rebuilt. Under a checkpoint base the
+// walk is one layer against the base tree, through the leaf's temporary index.
 //
-// ONE OBJECT, ONE ENTRY. An object touched in both layers is a single entry, and its pre-image is
+// ONE OBJECT, ONE ENTRY. Under a head base an object touched in both layers is a single entry, and its pre-image is
 // always the HEAD blob — never the index blob: the numerator answers what the delegate could have
 // spared the ORCHESTRATOR, measured against the dispatch baseline, and a metric-eligible dispatch
-// starts from a clean tree where HEAD is that baseline.
+// starts from a clean tree where HEAD is that baseline. Under a checkpoint base the pre-image is the base blob.
 //
 // RENAMES ARE NOT RECONSTRUCTED, AND THAT IS THE DESIGN — a boundary, not an omission. git's OWN
 // rename detection is consumed where git offers it (`--raw -M` sees a staged `git mv` within a layer),
-// but a rename a delegate actually makes — the wrapper's git-write shim blocks every git write verb,
+// but under a head base a rename a delegate actually makes — the wrapper's git-write shim blocks every git write verb,
 // so every one arrives as a tracked deletion plus an UNTRACKED creation — is accounted as exactly
-// that: a deletion plus a creation.
+// that: a deletion plus a creation. Under a checkpoint base git's own rename detection applies inside
+// the single base-relative layer, and a detected rename is counted once as `renamed`.
 //
 // This module once matched those pairs by blob identity, and the machinery was SUBTRACTED after it
 // produced silent-error edges in four consecutive review rounds: hashing that read through symlinks
@@ -35,7 +38,7 @@
 // An identity heuristic buys accuracy on the ordinary refactor and pays for it in exactly that
 // currency, so the trade was refused.
 //
-// The cost is stated with its DIRECTION, per case, because the direction is NOT the same in all of
+// The head-base cost is stated with its DIRECTION, per case, because the direction is NOT the same in all of
 // them — and a blanket "always optimistic" would be a false reassurance about an accounting number.
 // Write O for the pre-image size:
 //   • A PLAIN RENAME `a→b` emits `deleted pre:a (O)` + `new new:b (O)` = 2O against a recognised O.
@@ -54,18 +57,11 @@
 // Every object here is one git can PROVE: a tracked path with a recorded blob, or an untracked path
 // that exists. Nothing is paired on a resemblance.
 //
-// CONFIG-HIDDEN PATHS ARE A STATED LIMIT, and the limit is the PAYLOAD's, not this module's. `git
-// diff` honours `diff.ignoreSubmodules` and skips index entries carrying assume-unchanged or
-// skip-worktree, so a path can be changed and stay invisible to both probes below. The kit already
-// owns a probe that sees them — computeWorkingState (core-evidence.mjs:341) forces
-// `--ignore-submodules=none` and folds in flaggedIndexLag — and `isTreeClean` consumes it, so a
-// dispatch opened over such a tree records baselineClean:false and its return is metric-INELIGIBLE by
-// name. What this module must NOT do is force those flags HERE: D7 binds the numerator to the byte
-// domain of computeFingerprintPayload, which uses the same plain `git diff` — forcing them on one
-// side only would let the numerator count objects the denominator cannot see, a worse failure than
-// the blindness. Closing it for real means changing the shared payload, which is a Plan-1-frozen
-// surface the review lane also consumes; that is queued as its own item, and Phase 2's `return` owns
-// the return-time guard.
+// CONFIG-HIDDEN PATHS ARE A STATED LIMIT, and not this module's to close. Under a head base `git
+// diff` skips index entries carrying assume-unchanged or skip-worktree, so a path can be changed and
+// stay invisible to both probes below; the doors refuse a concealing tree rather than measure it. The
+// checkpoint walks force `--ignore-submodules=none` because the checkpoint payload they are measured
+// against does.
 //
 // IDENTITY CARRIES ITS DOMAIN (D6). `pre:<path>` for an object with a pre-image (keyed by the name it
 // HAD) and `new:<path>` for a created one. The prefix is load-bearing: a rename a→b beside a
@@ -79,12 +75,12 @@
 // paying it zero would drop a whole object's bytes out of the numerator on a type change. Every OTHER
 // unknown size REFUSES — the fail-closed rule is never a silent zero.
 //
-// A TRANSIENT object (staged, then deleted from the worktree) counts its INDEX image once: the
+// Under a head base a TRANSIENT object (staged, then deleted from the worktree) counts its INDEX image once: the
 // delegate authored those bytes, the payload carries them in both layers, and dropping them would
 // credit the delegate with less than it wrote.
 //
-// Fail closed: outside a git work tree, on an unborn branch (no HEAD means no pre-image to attribute
-// bytes against), on any git read that fails, and on any size it cannot establish.
+// Fail closed: outside a git work tree, on an unborn branch (the inherited no-HEAD limit
+// applies to both bases), on any git read that fails, and on any size it cannot establish.
 
 import { join } from 'node:path';
 import { createHash } from 'node:crypto';
@@ -92,7 +88,8 @@ import {
   gitBuf, computeFingerprintPayload, isBinaryFile, isNeverCommittableStat, resolveBase,
 } from './core-evidence.mjs';
 import { lstatNoFollowRead } from './fs-read-nofollow.mjs';
-import { frameIntegrationBundle } from './dispatch-record.mjs';
+import { frameIntegrationBundle, HEAD_BASELINE } from './dispatch-record.mjs';
+import { runBaseDiff, computeBasePayload } from './dispatch-baseline.mjs';
 
 const refuse = (reason) => ({ ok: false, reason });
 
@@ -100,6 +97,8 @@ const GITLINK_MODE = '160000';
 const SYMLINK_MODE = '120000';
 const ABSENT_MODE = '000000';
 const SUBMODULE_BYTES = 0;
+const BASE_RAW_ARGS = ['--raw', '-z', '-M', '--no-abbrev', '--no-ext-diff', '--ignore-submodules=none'];
+const BASE_NUMSTAT_ARGS = ['--numstat', '-z', '-M', '--no-ext-diff', '--ignore-submodules=none'];
 
 export const PRE_IMAGE_ID_PREFIX = 'pre:';
 export const NEW_IMAGE_ID_PREFIX = 'new:';
@@ -229,7 +228,7 @@ export const parseNumstatMarkers = (buf, where) => {
 };
 
 // ── the object model ──────────────────────────────────────────────────────────────────────────────
-// One record per touched object: where it came from in HEAD, where it ended up, and every name it
+// One record per touched object: where it came from in the base tree, where it ended up, and every name it
 // wore in between (the names the binary oracle and the type probes are asked about).
 
 const makeObject = ({ headPath, headSha, headMode }) => ({
@@ -247,7 +246,7 @@ const kindForModes = (modes) => {
 
 const buildObjects = (staged, unstaged) => {
   const objects = [];
-  // HEAD → index. A staged record's DESTINATION name is how the unstaged layer will refer to it.
+  // Base tree → index. Under a head base the DESTINATION name links to the unstaged layer.
   const byIndexPath = new Map();
   for (const r of staged) {
     const hasHead = !isAbsentSha(r.srcSha) && r.srcMode !== ABSENT_MODE;
@@ -312,7 +311,7 @@ const entryForObject = (top, object, binary, lstat) => {
   if (typeKind !== null) {
     // The COUNTED image decides the size, even when the emitted kind comes from another layer. A
     // gitlink in ANY layer makes the kind `submodule` (TYPE beats STATUS, D6) — but a regular file
-    // REPLACED by a gitlink is still counted at its HEAD blob, and paying it the submodule's
+    // REPLACED by a gitlink is still counted at its base blob, and paying it the submodule's
     // deliberate zero would drop a whole object's bytes out of the numerator on a type change. Zero
     // belongs to a counted image that is ITSELF a gitlink: that is the case where the move costs this
     // repository no bytes.
@@ -359,6 +358,24 @@ const entryForUntracked = (top, rel, lstat) => {
     : { ok: true, entry: { kind: 'new', path: rel, objectId, postImageBytes: stat.size } };
 };
 
+const enumerateCheckpointObjects = (top, base, io) => {
+  const raw = runBaseDiff(top, base, BASE_RAW_ARGS, io);
+  if (raw === null) return refuse('git could not read the base-relative change set (fail closed)');
+  const parsed = parseRawRecords(raw, 'the base-relative change set');
+  if (!parsed.ok) return parsed;
+  const numstat = runBaseDiff(top, base, BASE_NUMSTAT_ARGS, io);
+  if (numstat === null) return refuse('git could not read the numstat binary markers (fail closed)');
+  const binary = parseNumstatMarkers(numstat, 'the base-relative binary markers');
+  if (!binary.ok) return binary;
+  const entries = [];
+  for (const object of buildObjects(parsed.records, [])) {
+    const built = entryForObject(top, object, binary.names, io.lstat);
+    if (!built.ok) return built;
+    entries.push(built.entry);
+  }
+  return { ok: true, entries };
+};
+
 // enumerateReturnedObjects(cwd, io?) → { ok: true, entries } | { ok: false, reason }. The entries are
 // the STRUCTURED input computeNumerator consumes; this module never computes the numerator itself, so
 // the closed vocabulary stays the single authority on what a component is. `io.lstat` and
@@ -370,6 +387,8 @@ export const enumerateReturnedObjects = (cwd = process.cwd(), io = {}) => {
   if (resolveBase(top) == null) {
     return refuse('the branch is unborn (no HEAD) — there is no pre-image to attribute delegated bytes against (fail closed)');
   }
+  const base = io.base ?? HEAD_BASELINE;
+  if (base.kind === 'checkpoint') return enumerateCheckpointObjects(top, base, io);
   // ABSENT and UNREADABLE are different answers. ENOENT means the path vanished between `ls-files`
   // and the stat, which the payload itself records name-only — mirroring it keeps numerator and
   // denominator over ONE object set. Every OTHER errno (EACCES, EIO, ENOTDIR, ELOOP on a parent) is
@@ -442,9 +461,10 @@ export const enumerateReturnedObjects = (cwd = process.cwd(), io = {}) => {
   return refusedProbe() ?? { ok: true, entries };
 };
 
-// computeReturnedDiff(cwd) → the canonical uncommitted-state payload BYTES, or a refusal. This is the
-// diff half of the integration bundle, and it is the very payload computeTreeFingerprint digests — so
-// the bytes the denominator counts and the digest the records bind describe one state. It refuses
+// computeReturnedDiff(cwd) → the payload BYTES the thread's own base fingerprint digests, or a refusal:
+// computeTreeFingerprint's under a head base, the leaf's base-relative payload under a checkpoint.
+// This is the diff half of the integration bundle, so the bytes the denominator counts and the
+// digest the records bind describe one state. It refuses
 // where the enumeration refuses: one entry point may not answer for a tree the other rejects. That
 // sentence used to hold only for the two SHARED preconditions below, which let an AMBIGUOUS rename
 // refuse the enumeration while the diff still handed back bytes — so the enumeration is run here and
@@ -457,18 +477,18 @@ export const computeReturnedDiff = (cwd = process.cwd(), io = {}) => {
   }
   const enumerated = enumerateReturnedObjects(cwd, io);
   if (!enumerated.ok) return enumerated;
-  // The payload builder guards its lstat but reads untracked file BYTES unguarded, so an unreadable
+  // The head payload builder guards its lstat but reads untracked file BYTES unguarded, so an unreadable
   // or vanishing untracked file throws out of it. This entry point promises a refusal object, and a
   // caller that framed a bundle around a thrown read would have no bytes and no reason either.
-  let payload;
   try {
-    payload = computeFingerprintPayload(cwd);
+    const base = io.base ?? HEAD_BASELINE;
+    const payload = base.kind === 'checkpoint' ? computeBasePayload(cwd, base, io) : computeFingerprintPayload(cwd);
+    return payload == null
+      ? refuse('the canonical payload could not be computed (fail closed)')
+      : { ok: true, diff: payload };
   } catch (err) {
     return refuse(`the canonical payload could not be read (${err?.code ?? err?.message ?? 'read failed'}) — the returned diff is refused rather than framed around a partial read (fail closed)`);
   }
-  return payload == null
-    ? refuse('the canonical payload could not be computed (fail closed)')
-    : { ok: true, diff: payload };
 };
 
 // assembleIntegrationBundle(diff, report) → the framed bundle with its digest and length. The framing

package/tools/held-session.mjs

@@ -1,10 +1,12 @@
 import { escapeForDisplay, isRenderableLine, shellQuoteArg } from './repo-lex.mjs';
 import { wrapperCmdFor } from './detect-backends.mjs';
 import { DISPLAY_ALIASES } from './recipes.mjs';
+import { readsBaseline, TERMINAL_RETURN_OUTCOMES } from './dispatch-record.mjs';
 
 const CODE_STEP = 'code';
 const FOLD_KIND = 'fold';
 const RETURN_KIND = 'return';
+const DEGRADE_KIND = 'degrade';
 const EXECUTE_BACKEND = 'codex-cli-bridge';
 const UNPOPULATED_HELD_ID = '<held id>';
 
@@ -24,6 +26,7 @@ const findsDispatch = (dispatches, nonce) => dispatches.find((dispatch) => dispa
 const findsReturn = (returns, nonce) => returns.find((returned) => returned.nonce === nonce) ?? null;
 const hasCoveredReplacement = (returned, degrades) =>
   degrades.some((degrade) => degrade.fingerprint === returned.postTreeDigest);
+const expectsSession = (dispatch, baseKind) => dispatch.baselineClean === false || baseKind === 'checkpoint';
 const collectsRetryChainNonces = (dispatches, nonce, collected = new Set()) => {
   if (nonce === null || collected.has(nonce)) return collected;
   const next = new Set(collected).add(nonce);
@@ -33,26 +36,28 @@ const collectsRetryChainNonces = (dispatches, nonce, collected = new Set()) => {
 const accumulatesFacts = (degrades) => (state, record) => {
   if (record.kind === 'dispatch' && state.epochNonces.has(record.nonce)) {
     const expectedId = state.heldId;
+    const baseKind = readsBaseline(record).kind;
     return {
       ...state,
       dispatches: [...state.dispatches, record],
-      threads: [...state.threads, { nonce: record.nonce, expectedId, actualId: null, status: 'OPEN' }],
-      open: record.baselineClean === false ? [...state.open, { nonce: record.nonce, expectedId }] : state.open,
+      threads: [...state.threads, { nonce: record.nonce, expectedId, actualId: null, status: 'OPEN', baseKind }],
+      open: expectsSession(record, baseKind) ? [...state.open, { nonce: record.nonce, expectedId }] : state.open,
     };
   }
   if (record.kind === RETURN_KIND && state.epochNonces.has(record.nonce)) {
     const dispatch = findsDispatch(state.dispatches, record.nonce);
     if (dispatch === null) return state;
+    const baseKind = readsBaseline(dispatch).kind;
     const expectedId = state.threads.find((thread) => thread.nonce === record.nonce)?.expectedId ?? null;
     const status = record.sessionId === null ? 'FAILED'
       : expectedId === null ? 'FIRST'
       : dispatch.retryOf !== null || record.sessionId === expectedId ? 'CONTINUED'
         : 'SUBSTITUTED';
-    const substitution = status === 'SUBSTITUTED' && dispatch.baselineClean === false
-      && !hasCoveredReplacement(record, degrades)
+    const substitution = status === 'SUBSTITUTED' && expectsSession(dispatch, baseKind)
+      && (baseKind === 'checkpoint' ? !TERMINAL_RETURN_OUTCOMES.includes(record.outcome) : !hasCoveredReplacement(record, degrades))
       ? {
         nonce: record.nonce, expectedId, actualId: record.sessionId,
-        postTreeDigest: record.postTreeDigest, folded: false,
+        postTreeDigest: record.postTreeDigest, folded: false, baseKind,
       }
       : null;
     return {
@@ -71,7 +76,7 @@ const accumulatesFacts = (degrades) => (state, record) => {
     if (dispatch === null || returned === null || returned.sessionId === null) return state;
     const establishes = state.heldId === null;
     const retries = dispatch.retryOf !== null;
-    const replaces = returned.sessionId !== state.heldId && hasCoveredReplacement(returned, degrades);
+    const replaces = readsBaseline(dispatch).kind === 'head' && returned.sessionId !== state.heldId && hasCoveredReplacement(returned, degrades);
     const retryChain = retries ? collectsRetryChainNonces(state.dispatches, dispatch.retryOf) : new Set();
     const foldedSubstitutions = state.substitutions.map((substitution) =>
       (substitution.nonce === record.nonce ? { ...substitution, folded: true } : substitution));
@@ -81,6 +86,10 @@ const accumulatesFacts = (degrades) => (state, record) => {
     if (establishes || retries || replaces) return { ...state, heldId: returned.sessionId, substitutions };
     return { ...state, substitutions };
   }
+  if (record.kind === DEGRADE_KIND && state.epochNonces.has(record.nonce)
+    && state.substitutions.some((substitution) => substitution.nonce === record.nonce && substitution.baseKind === 'checkpoint')) {
+    return { ...state, heldId: null, substitutions: state.substitutions.filter((substitution) => substitution.nonce !== record.nonce) };
+  }
   return state;
 };
 
@@ -109,11 +118,15 @@ export const judgeHeldSession = (records, { head, backend, degrades = [] }) => {
     heldId: accumulated.heldId,
     folds: countsHeldFolds(records, epochNonces, accumulated.heldId),
     substitution: accumulated.substitutions[0] ?? null,
-    threads: accumulated.threads,
+    threads: accumulated.threads.map((thread) => ({
+      ...thread, substituted: accumulated.substitutions.some((substitution) => substitution.nonce === thread.nonce),
+    })),
     open: accumulated.open,
   };
 };
 
+export const threadVerdict = (facts, nonce) => facts.threads.find((thread) => thread.nonce === nonce) ?? null;
+
 export const judgeLedger = (ledger, { backend, degrades = [] }) => {
   if (ledger.state === 'absent') {
     return { state: 'absent', heldId: null, folds: 0, substitution: null, threads: [], open: [] };
@@ -137,7 +150,7 @@ export const decideHeldSession = (facts) => {
     const reason = `delegated code thread "${nonce}" substituted held session "${escapeForDisplay(expectedId)}" with "${escapeForDisplay(actualId)}"`;
     return { code: 1, reason, line: `held session: SUBSTITUTED — ${reason}` };
   }
-  if (facts.heldId === null) return { code: 0, reason: 'no folded code thread in the commit epoch carries a session yet', line: 'held session: none' };
+  if (facts.heldId === null) return { code: 0, reason: 'no held session stands: no folded code thread established one in this commit epoch, or the last one was withdrawn by a checkpoint thread\'s ledger degrade', line: 'held session: none' };
   const heldId = escapeForDisplay(facts.heldId);
   return { code: 0, reason: `held session "${heldId}" is continuous`, line: `held session: ${heldId} — ${facts.folds} fold(s) rode it` };
 };
@@ -159,7 +172,7 @@ export const foldLaneLines = (facts) => {
     `  run:  ${HELD_EXECUTE_WRAPPER} --resume ${heldId} --nonce <nonce> <fold-brief>`,
     '  the fold brief is a dispatch file carrying the finding and the accepted fold; dispatch open precedes the run, then dispatch return and fold follow it',
     '  the orchestrator runs the suites, verifies the returned diff, re-mints the red-proofs and owns the commit',
-    '  a fresh session is a forbidden substitution; a retry of a failed thread or a recorded execute degrade is the exception; the wrapper sidecar is never read',
+    '  a fresh session is a forbidden substitution; a retry of a failed thread or, for a head base, a recorded execute degrade is the exception (a checkpoint thread\'s substitution closes by its ledger degrade); the wrapper sidecar is never read',
   ];
   return caveat === null ? lines : [...lines, `  caveat: ${caveat}`];
 };

package/tools/plan-shape-facts.mjs

@@ -4,13 +4,18 @@ import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
 import { classIds, readShippedRobustnessLiterals } from './robustness-literals.mjs';
 import { segmentPrefixOf, validateSourceSizeConfig } from './source-size-config.mjs';
 import { getLineCount, isSweep, resolveAnchorCandidates, unique } from './plan-shape.mjs';
+import { listStories } from './claim-relation.mjs';
+import { EPICS_REL, readEpicStore } from './epic-store.mjs';
+import { sweepSiblings } from './epic-shape-ledger.mjs';
+import { PIN_FILE } from './plan-shape-ownership.mjs';
 
 const SOURCE_SIZE_REL = 'docs/ai/source-size.json';
 const PACKAGE_FILE = 'package.json';
-const PIN_FILE = 'package-content.test.mjs';
 const EXCLUDED_DIRECTORIES = new Set(['.git', 'node_modules']);
 const NEGATED_CLASS = /\[[!^]/;
 const UNSUPPORTED_GLOB = /[()\\\u0000-\u001f]/;
+const STORE_REFUSED = 'refused';
+const FINDING_SEPARATOR = '; ';
 
 const usageError = (message, scope = 'repository') => Object.assign(new Error(message), { exitCode: 2, scope });
 const planError = (message) => usageError(message, 'plan');
@@ -200,18 +205,31 @@ const describePath = (root, path, practice, repoFiles, packageCache) => {
   };
 };
 
+const readStoryFacts = (root) => {
+  const store = readEpicStore(root);
+  if (store.outcome === STORE_REFUSED) return { stories: [], landedEpics: [], storeRefusal: `${EPICS_REL}: ${store.reason}` };
+  const sweep = sweepSiblings(store.entries, EPICS_REL);
+  return {
+    stories: sweep.ok ? listStories(sweep.epics) : [],
+    landedEpics: sweep.ok ? sweep.landedEpics : [],
+    storeRefusal: sweep.ok ? null : sweep.findings.map((finding) => finding.message).join(FINDING_SEPARATOR),
+  };
+};
+
 export const openRepo = (root, { robustnessDeps } = {}) => {
   const repoRoot = realpathSync(root);
-  return { repoRoot, repoFiles: walkRegularFiles(repoRoot), practice: loadPractice(repoRoot), robustClasses: loadRobustClasses(robustnessDeps), packageCache: new Map() };
+  return { repoRoot, repoFiles: walkRegularFiles(repoRoot), practice: loadPractice(repoRoot), robustClasses: loadRobustClasses(robustnessDeps),
+    packageCache: new Map(), ...readStoryFacts(repoRoot) };
 };
 
 export const expandSweepPaths = (root, patterns) => expandPatterns(walkRegularFiles(realpathSync(root)), patterns);
 
 export const buildFacts = (root, { paths = [], robustnessDeps, repo = openRepo(root, { robustnessDeps }) } = {}) => {
-  const { repoRoot, repoFiles, practice, robustClasses, packageCache } = repo;
+  const { repoRoot, repoFiles, practice, robustClasses, packageCache, stories, landedEpics, storeRefusal } = repo;
   const expansions = expandPatterns(repoFiles, paths.filter(isSweep));
   const allPaths = unique([...paths, ...Object.values(expansions).flat()]);
   const pathFacts = Object.fromEntries(allPaths.map((path) => [path, describePath(repoRoot, path, practice, repoFiles, packageCache)]));
   const candidates = (suffix, precedingPaths = []) => resolveAnchorCandidates(repoFiles, suffix, precedingPaths);
-  return { capDeclared: practice.capDeclared, cap: practice.cap, robustClasses, pathFacts, expansions, repoFiles, candidates };
+  return { capDeclared: practice.capDeclared, cap: practice.cap, robustClasses, pathFacts, expansions, repoFiles, candidates,
+    stories, landedEpics, storeRefusal };
 };

package/tools/plan-shape-ownership.mjs

@@ -0,0 +1,83 @@
+import { posix } from 'node:path';
+import { hasPathOverlap } from './claim-relation.mjs';
+
+const STORY_LINE = /^Story: (S[1-9]\d*) of ([^\s/]+)$/;
+const STORY_FIELDS = 'stories';
+export const PIN_FILE = 'package-content.test.mjs';
+const MARKDOWN_SUFFIX = '.md';
+const FIRST_LINE = 1;
+const LANDED = 'landed';
+const OWNS = 'owns';
+const SHARED = 'shared';
+const STRING_TYPE = 'string';
+export const PIN_VERBS = new Set(['create', 'delete']);
+const CODES = Object.freeze({ line: 'story-line', store: 'story-store', landed: 'story-epic-landed',
+  unknown: 'story-unknown', owns: 'story-owns', shared: 'story-shared', scope: 'story-scope' });
+const ONE_STORY = 'the plan names its story with one line';
+const NAME_STORY = 'name the story that carries the file';
+const ORDER_STORIES = 'declare a transitive depends-on order between the stories';
+const makeFinding = (line, code, message, rowId = null) => ({ line, code, message, rowId });
+const sortFindings = (findings) => ({ findings: findings.sort((left, right) => left.line - right.line) });
+const hasIdentity = (left, right) => left.path === right.path && left.id === right.id;
+const hasClaimCover = (claim, path) => claim.ground.some((ground) => hasPathOverlap(path, ground));
+const hasOwnCover = (own, path) => own.claims.some((claim) => hasClaimCover(claim, posix.normalize(path)));
+
+export const readStoryLine = (lines) => {
+  const [story = null, second] = lines.flatMap(({ text, line }) => {
+    const match = STORY_LINE.exec(text.trim());
+    if (!match) return [];
+    const [, id, epic] = match;
+    return [{ id, epic, line }];
+  });
+  return { story, findings: second ? [makeFinding(second.line, CODES.line, ONE_STORY)] : [] };
+};
+
+const findOwnStory = (story, facts) => {
+  if (!story) return { own: null, findings: [] };
+  const epics = facts.stories.filter((record) => posix.basename(record.path, MARKDOWN_SUFFIX) === story.epic);
+  const own = epics.find((record) => record.id === story.id) ?? null;
+  if (facts.landedEpics?.includes(story.epic)) {
+    return { own: null, findings: [makeFinding(story.line, CODES.landed, `${story.epic} is landed; name a story of an open epic`)] };
+  }
+  if (!own) {
+    const name = epics.length ? `${story.epic} ${story.id}` : story.epic;
+    return { own: null, findings: [makeFinding(story.line, CODES.unknown, `${name} is unknown; name a story present in an open epic`)] };
+  }
+  return { own, findings: [] };
+};
+
+const checkCollision = (row, path, record, claim, own) => {
+  if (!hasClaimCover(claim, posix.normalize(path))) return [];
+  const message = `${row.id} path ${path} overlaps ${record.path} ${record.id} ${claim.field} ${claim.path}`;
+  if (claim.field === OWNS) return [makeFinding(row.line, CODES.owns, message, row.id)];
+  if (claim.field !== SHARED) return [];
+  if (own && (record.path !== own.path || own.reachable.has(record.id) || record.reachable.has(own.id))) return [];
+  return [makeFinding(row.line, CODES.shared, `${message}; ${own ? ORDER_STORIES : NAME_STORY}`, row.id)];
+};
+
+const hasPinCover = (path, rows, facts, own) => posix.basename(path) === PIN_FILE && rows.some((row) => {
+  const fact = facts.pathFacts?.[row.path];
+  return PIN_VERBS.has(row.verb) && fact?.shipped === true && fact.pinTest === path && hasOwnCover(own, row.path);
+});
+const checkScope = (row, path, rows, facts, own) => {
+  if (!own || facts.pathFacts?.[path]?.inScope !== true || hasOwnCover(own, path) || hasPinCover(path, rows, facts, own)) return [];
+  return [makeFinding(row.line, CODES.scope,
+    `${row.id} path ${path} is in the declared practice and no claim of ${own.id} covers it`, row.id)];
+};
+
+export const checkStoryOwnership = ({ rows, goalLines, facts, getConcretePaths }) => {
+  const { story, findings } = readStoryLine(goalLines);
+  if (!Object.hasOwn(facts, STORY_FIELDS)) return { findings };
+  if (typeof facts.storeRefusal === STRING_TYPE) {
+    return sortFindings([...findings, makeFinding(FIRST_LINE, CODES.store, facts.storeRefusal)]);
+  }
+  const resolved = findOwnStory(story, facts);
+  const own = resolved.own;
+  const others = facts.stories.filter((record) => record.state !== LANDED && (!own || !hasIdentity(record, own)));
+  const validRows = rows.filter((row) => row.valid);
+  const relation = validRows.flatMap((row) => getConcretePaths(row, facts).flatMap((path) => [
+    ...others.flatMap((record) => record.claims.flatMap((claim) => checkCollision(row, path, record, claim, own))),
+    ...checkScope(row, path, validRows, facts, own),
+  ]));
+  return sortFindings([...findings, ...resolved.findings, ...relation]);
+};

package/tools/plan-shape.mjs

@@ -1,5 +1,8 @@
+import { posix } from 'node:path';
 import { tokenizeMarkdown } from '../references/scripts/markdown-blocks.mjs';
 import { parseRobustTag } from './robustness-literals.mjs';
+import { unique } from './claim-relation.mjs';
+import { checkStoryOwnership, PIN_FILE, PIN_VERBS } from './plan-shape-ownership.mjs';
 
 export const PLAN_TITLE_PREFIX = '# Plan: ';
 export const PLAN_HEADINGS = Object.freeze([
@@ -31,7 +34,7 @@ const BULLET = /^-\s+\S/;
 export const getLineCount = (text) => text === '' ? 0 : text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
 export const isSweep = (path) => GLOB_BYTE.test(path);
 const endsWithPath = (path, suffix) => path === suffix || path.endsWith(`/${suffix}`);
-export const unique = (items) => [...new Set(items)];
+export { unique } from './claim-relation.mjs';
 const getFindingLine = (document, index) => document.frontLines + index + 1;
 const makeFinding = (line, code, message, rowId = null) => ({ line, code, message, rowId });
 const getHeading = (document, text) => document.headings.find((heading) => heading.text === text);
@@ -54,7 +57,8 @@ const getFigure = (value) => Number(String(value).replace(/^~/, ''));
 const getConcretePaths = (row, facts) => isSweep(row.path) ? facts.expansions?.[row.path] ?? [] : [row.path];
 const getPathFact = (facts, path) => facts.pathFacts?.[path] ?? null;
 const getAnchorPath = (anchor) => anchor.replace(/:[1-9]\d*$/, '');
-const hasPathDefect = (path) => path.startsWith('/') || path.includes('\\') || path.split('/').includes('..');
+const hasPathDefect = (path) => !(!path.includes('\\') &&
+  path.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..'));
 const hasRaiseBullet = (verificationBullets, path) => verificationBullets.some((bullet) =>
   bullet.includes('--write-baseline') && bullet.includes('--reason') && bullet.includes(path));
 
@@ -174,6 +178,22 @@ const checkHeadings = (text, document) => {
   return findings;
 };
 
+const isPinRow = (row, path) => row.verb === 'modify' && row.path === path && posix.basename(row.path) === PIN_FILE;
+const checkPinBindings = (rows, owners, facts) => {
+  if (!Object.hasOwn(facts, 'pathFacts')) return [];
+  return [...owners].flatMap(([path, group]) => {
+    const pins = group.filter((row) => isPinRow(row, path));
+    if (pins.length < 2) return [];
+    const taken = new Set();
+    return pins.flatMap((pin) => {
+      const above = rows.slice(0, rows.indexOf(pin)).findLast((row) => row.valid && PIN_VERBS.has(row.verb) && !taken.has(row) &&
+        getPathFact(facts, row.path)?.shipped === true && getPathFact(facts, row.path)?.pinTest === path);
+      if (above) { taken.add(above); return []; }
+      return [makeFinding(pin.line, 'pin-unbound', `${pin.id} is a repeated pin row with no untaken shipped create or delete above it`, pin.id)];
+    });
+  });
+};
+
 const checkLedgerStructure = (parsed, facts) => {
   const findings = [];
   const nonBlank = parsed.entries.filter((entry) => entry.raw.trim() !== '');
@@ -206,11 +226,15 @@ const checkLedgerStructure = (parsed, facts) => {
   const owners = new Map();
   for (const row of parsed.rows.filter((item) => item.valid)) {
     for (const path of getConcretePaths(row, facts)) {
-      const prior = owners.get(path);
-      if (prior) findings.push(makeFinding(row.line, 'duplicate-path', `${path} is owned by both ${prior} and ${row.id}`, row.id));
-      else owners.set(path, row.id);
+      const prior = owners.get(path) ?? [];
+      const conflicting = prior.find((owner) => !isPinRow(owner, path) || !isPinRow(row, path));
+      if (conflicting) {
+        findings.push(makeFinding(row.line, 'duplicate-path', `${path} is owned by both ${conflicting.id} and ${row.id}`, row.id));
+      }
+      owners.set(path, [...prior, row]);
     }
   }
+  findings.push(...checkPinBindings(parsed.rows, owners, facts));
   const last = nonBlank.at(-1);
   if (!parsed.total || (parsed.totals ?? []).length !== 1 || last?.line !== parsed.total?.line) {
     findings.push(makeFinding(last?.line ?? 1, 'total', 'the exact total line must be the last non-blank ledger line'));
@@ -236,9 +260,9 @@ const getAnchorCandidates = (row, preceding, facts) => {
   return facts.candidates(suffix, precedingPaths);
 };
 
-const getCurrentLines = (rows, facts, verbs) => rows
+const getCurrentLines = (rows, facts, verbs) => unique(rows
   .filter((row) => row.valid && verbs.has(row.verb) && row.budget !== 'n/a')
-  .flatMap((row) => getConcretePaths(row, facts))
+  .flatMap((row) => getConcretePaths(row, facts)))
   .reduce((sum, path) => sum + (getPathFact(facts, path)?.lines ?? 0), 0);
 
 const checkAuthoring = (parsed, facts) => {
@@ -335,7 +359,11 @@ const judge = (text, facts, stateRules) => {
     return { findings: [makeFinding(line, 'block-model', parsedResult.error.message)], skips: [], parsed: null };
   }
   const parsed = parsedResult.parsed;
-  const structural = [...checkHeadings(String(text ?? ''), parsed.document), ...checkLedgerStructure(parsed, facts)];
+  const goal = getHeading(parsed.document, PLAN_HEADINGS[0]);
+  const goalLines = goal ? getSectionLines(parsed.document, PLAN_HEADINGS[0])
+    .map((text, offset) => ({ text, line: getFindingLine(parsed.document, goal.index + 1 + offset) })) : [];
+  const structural = [...checkHeadings(String(text ?? ''), parsed.document), ...checkLedgerStructure(parsed, facts),
+    ...checkStoryOwnership({ rows: parsed.rows, goalLines, facts, getConcretePaths }).findings];
   const state = stateRules ? stateRules(parsed, facts) : { findings: [], skips: [] };
   const findings = [...structural, ...state.findings].map((finding, index) => ({ ...finding, order: index }))
     .sort((left, right) => left.line - right.line || left.order - right.order)

package/tools/review-state.mjs

@@ -11,9 +11,10 @@
 // Normative `--check` exit contract (the single home of this list — SKILL.md points here):
 // Before the review-recipe exits, configured plan-execution.execute=delegated with a plan and a
 // dirty, fingerprintable tree audits the delegation ledger. An absent ledger is inert; an
-// unavailable ledger, a HEAD error or a SUBSTITUTED held session refuses unless a codex-exec degrade at the
-// substituted return's tree, standing after every later fold, accepts it, or the fold of that thread's
-// retry lifts it (codex never grants it).
+// unavailable ledger or a HEAD error refuses. A SUBSTITUTED held session refuses: for a head-base thread,
+// a codex-exec degrade at the substituted return's tree, standing after every later fold, accepts it,
+// or the fold of that thread's retry lifts it (codex never grants it); a checkpoint-based thread's
+// substitution closes only by its own ledger degrade.
 //   exit 0  when the CONFIGURED plan-execution.review recipe is solo (or the computed default is —
 //           absent config with no reviewer backend ready); when no plan is in flight (docs/plans/
 //           holds no top-level .md that is not queue.md and not scratch by the naming convention:
@@ -149,6 +150,7 @@ export {
 const ACTIVITY = 'plan-execution';
 const SLOT = 'review';
 const CORE_EVIDENCE_TOOL = shellQuoteArg(join(dirname(fileURLToPath(import.meta.url)), 'core-evidence.mjs'));
+const DISPATCH_TOOL = shellQuoteArg(join(dirname(fileURLToPath(import.meta.url)), 'dispatch.mjs'));
 // --await (BUGFREE-3 / AD-049, item (d)) bounds + poll cadence. The default timeout is generous —
 // a real grounded bridge review can take minutes — and every value is overridable (--timeout / the
 // injectable clock) so hermetic tests never spend wall-clock.
@@ -531,6 +533,9 @@ const backendFailurePart = (b, state) => {
 const describesHeldRecovery = (state) => {
   const substitution = state.heldSession.substitution;
   if (substitution === null) return '';
+  if (substitution.baseKind === 'checkpoint') {
+    return ` — a checkpoint-based thread: no core-evidence degrade lifts it; record its ledger degrade (node ${DISPATCH_TOOL} degrade --wave <wave> --nonce ${shellQuoteArg(substitution.nonce)} --step-class code --rationale "...") then retry it (cap permitting) or open a new thread on the held session, and fold that`;
+  }
   const canRetry = substitution.folded === false;
   if (state.evidenceUnavailable === true) {
     const retry = canRetry ? '; or fold the retry of that thread' : '';
@@ -784,8 +789,7 @@ record (node core-evidence.mjs degrade) — and never all backends.
 below, a configured plan-execution.execute = delegated with a plan in flight and a dirty,
 fingerprintable tree audits the delegation ledger: an absent ledger is inert; an unreadable,
 malformed, foreign or audit-refused ledger, a failed HEAD read, or a SUBSTITUTED held session
-exits 1 (a substitution is lifted only by a codex-exec degrade at the substituted return's own
-tree, or the fold of that thread's retry). THEN: 0 for solo / no plan in flight /
+exits 1. THEN: 0 for solo / no plan in flight /
 a clean tree (under a non-solo review obligation the PASS names every plan in flight and its arm) /
 a cwd where git ITSELF answers not-a-repository (the only passing non-work-tree state; the four others exit 1 by name) / obligations satisfied (reviewed: >=1 ship-class attestation;
 council: every backend ship-class or degrade-recorded, >=1 real ship); 1 on a veto, an