@sabaiway/agent-workflow-kit 3.10.0 → 3.12.0

package/CHANGELOG.md

@@ -4,6 +4,83 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 3.12.0 — `--resume` tolerates the session's work: the verify proves per placed path (AD-073)
+
+`provision --resume` no longer refuses a satellite you have worked in. The closing slice of the
+resume-verify design: the post-provision verify stopped asking "is the whole tree clean?" and now
+asks "is every path THIS run placed or kept in a git lane provision can prove?" — so your
+uncommitted edits, untracked scratch and hook-created files are out of scope BY CONSTRUCTION.
+
+- **What `--resume` now tolerates:** uncommitted tracked edits (including a dirty `package.json`,
+  whose live state steers the refreshed install posture in both directions), untracked scratch at
+  any depth, renamed tracked files, hook-created content, and every ignored file. A worktree wedged
+  by a `post-checkout` hook that dirtied its fresh checkout now completes on `--resume` — previously
+  both lanes refused at the same verify and the only way out was deleting the hook's files by hand.
+- **What still refuses, fail-closed:** a path provision itself placed or kept whose lane is
+  UNTRACKED, and any lane probe that errors. The STOP names the exact leaf — never a directory, never
+  a session path — and carries the convergent fix first: restore the ignore rule (the only
+  convergent fix for copy-set leaves, the `node_modules` link and `.vscode/settings.json`, since the
+  next resume simply re-places a removed node). A droppable `--include` gets ONE instruction for its
+  whole destination ROOT — dropping the flag orphans every copy under it — namely: move the root OUT
+  of the worktree and drop `--include <root>` together. No removal command is ever derived (the tool
+  cannot see what else you put inside that directory), and leaving it in place is not offered either
+  (an orphan is what blocks landing). A node this attempt did not create is never advised away, and
+  an unprovable probe carries no recovery command at all.
+- **The proof set is a closed, frozen registry** (`PLACEMENT_REGISTRY`): the handoff stub, the seeded
+  plan, copy-set leaves, include leaves, the `node_modules` link, `.vscode/settings.json`,
+  pin-rebase targets, and the record refresh. It is leaf-only and kind-gated — a real `node_modules`
+  directory where the tool places a symlink is YOUR content, never probed and never touched — and it
+  freezes at the verify, so the record refresh can only write at the path the stub already
+  journaled. The kind gate applies to KEPT nodes only: anything the run itself created stays proven.
+- **The lane probes are literal.** Live-probed on git 2.43: `check-ignore` refuses pathspec magic and
+  otherwise answers for a name that glob-matches a TRACKED sibling, so a file literally named
+  `feature-[a].md` would read "not ignored" merely because `feature-a.md` is tracked. Tracked-ness is
+  decided first by an explicit literal pathspec whose output must match the path BYTE-EXACTLY (a
+  pathspec naming a directory lists its descendants, which prove nothing about the path itself), and
+  the ignore probe runs `--no-index`. A `.vscode/settings.json` an earlier run placed is proven even
+  when the current run's door skips writing it, so a lost ignore rule can no longer hide behind a
+  successful resume.
+- **The FIRST provision stays deliberately strict** — any dirt still refuses — and its untracked
+  visibility is now explicit, so a repo's `status.showUntrackedFiles=no` can no longer turn that
+  check into a silent no-op. Default behavior is unchanged.
+- **The contract ships as a live constant** (`RESUME_VERIFY_RULE`) printed on every resume-verify
+  STOP and pinned into the mode doc by the doc-parity gate. The record's fields are documented for
+  what they are: `slug`, `branch` and the seeded plan name authorize a resume; `include`,
+  `node_modules` and `vscode-settings` are recorded facts that never do.
+
+## 3.11.0 — the record attests only a verified provision; tracked plans-chain paths refuse (AD-072)
+
+Two provision honesty fixes from the converged resume-verify design (its slice R1; the
+tolerance flip is the next slice):
+
+- **The provision record is refreshed LAST — after the in-flight-plan check and the
+  post-provision verify, in BOTH lanes.** The record now attests only a VERIFIED provision: a
+  first provision that fails after the stub write leaves the STUB (identity still binds from
+  it — `--resume` completes as before; a pre-write refusal leaves no handoff at all), and a
+  failed resume leaves the PRIOR record bytes byte-exact. Previously a failed
+  run left a freshly refreshed record (the 3.6.0 stated residual — now eliminated). A refresh
+  failure after a clean verify keeps the worktree and names the exact re-run command in both
+  lanes, preserving the original failure cause.
+- **A TRACKED plans-chain path — the handoff or the seeded plan — refuses fail-closed in both
+  lanes.** Its drift is undeliverable (`land` categorically refuses docs/plans, and satellite
+  commits are not a lane), so tolerating it would strand the worktree. A fresh provision proves
+  both paths untracked at ONE captured commit — the same OID the branch is cut from — and
+  re-probes the new worktree's index and branch HEAD before the first write, catching
+  post-checkout hooks that force-add or even COMMIT them (a committed add leaves the tree
+  clean, invisible to the clean-tree verify). `--resume` probes the branch HEAD tree
+  unconditionally plus the live index before reading the handoff identity.
+- **Recovery is surgical and honest.** An index-only entry names a pathspec-LITERAL
+  `git rm --cached` (a magic-shaped seed name never touches a pattern-matching neighbor) plus
+  the ignore-rule restoration when the worktree's live rules lost it; a branch-HEAD-tracked
+  file names salvage FIRST, then consented `cleanup --abandon` ONLY where the record identity
+  binds (a malformed record routes to the shipped record recovery — abandon is never promised);
+  the post-add hook STOP names inspect/salvage, then plain-git removal (never `cleanup
+  --abandon` — no handoff identity exists yet); an irregular entry (tree / symlink / gitlink)
+  fails closed with NO recovery command. Recovery never routes through the landing lane.
+- **The mode doc states both contracts verbatim** (the corrected verify-then-refresh order and
+  the plans-chain refusal), each pinned by a named test. Resume tolerance is UNCHANGED this
+  release: the blanket clean-tree verify stays, pinned byte-exact.
+
 ## 3.10.0 — install advice reads the worktree checkout (AD-071)
 
 The install advice picked its package manager from MAIN's `package.json` and lockfiles while the

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '3.10.0'
+  version: '3.12.0'
 ---
 
 # agent-workflow-kit

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "3.10.0",
+  "version": "3.12.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "3.10.0",
+  "version": "3.12.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/modes/worktrees.md

@@ -33,6 +33,41 @@ own verbatim error through the existing Git-error surface.
   is read from exactly one REQUIRED `## Provision record` section (a decoy field elsewhere cannot
   hijack identity); a missing or repeated section, or a duplicated single-valued field, is a typed
   STOP, never last-wins.
+  A TRACKED plans-chain path — the handoff or the seeded plan — refuses fail-closed in BOTH lanes (its drift is undeliverable at land, a manufactured dead end): a fresh provision proves both paths untracked at ONE captured commit before `git worktree add` and re-probes the new worktree's index and branch HEAD before any provision write; `--resume` probes the branch HEAD tree and the live index before reading the handoff identity; recovery is surgical (an index-only entry names a literal index removal — plus the ignore restoration where the rule was lost; a HEAD-tracked regular file names salvage first, then consented abandon only where identity binds) and never routes through land.
+  The provision record is refreshed LAST, after the post-provision verify, in both lanes — the
+  record attests only a verified provision, and a failed run leaves the prior record bytes: on a
+  first provision that failed after the stub write, the stub; a refusal BEFORE any provision
+  write (the tracked-plans-chain and probe-error STOPs) leaves no handoff at all.
+  The post-provision verify is lane-specific:
+  the resume verify proves only what THIS run placed or kept: every journaled leaf must be tracked or ignored in the worktree, an untracked owned leaf or any probe error stops the run naming the exact leaf, and every other path — the session's own work — is never probed and never a stop cause; a first provision keeps the blanket clean-tree verify.
+  The proof list is THIS run's live placement journal — the closed-world placement registry (the
+  handoff stub, the seeded plan, copy-set leaves, include leaves, the `node_modules` link,
+  `.vscode/settings.json`, the pin-rebase targets, and the record refresh at its already-journaled
+  path), leaf-only (files and symlinks; directories are containers, never proof obligations) and
+  kind-gated: membership requires the live node's kind to match what that lane's SOURCE places, so
+  a directory, a special node, or a kind-mismatched link at an owned path is session content the
+  verifier never probes. The journal FREEZES at the verify. Lane probes are LITERAL — pathspec
+  magic in a placed name is inert — and tracked-priority (tracked > ignored > untracked). An
+  untracked owned leaf STOPs with the convergent fix first: restore the ignore rule (the only
+  convergent fix for a mandatory copy-set leaf, the `node_modules` link, and
+  `.vscode/settings.json` — each is placed only where a check-ignore gate proved the destination
+  ignored, and removing the node is non-convergent because the next resume re-places it). A
+  droppable `--include` instead gets ONE grouped instruction on its destination ROOT — dropping the
+  flag orphans every copy under that root, since cleanup derives ownership from the recorded
+  includes — namely: salvage or relocate the whole root OUT of the worktree AND drop
+  `--include <root>` in the same run, either alone recurs. No removal is ever derived there: the
+  journal cannot see session content or kind-excluded nodes inside that root, so no `rm` over it
+  could be proven safe; and leaving it in place is not offered either, because an orphaned
+  destination is exactly what stops land. A kept node is never advised away, an excluded dir
+  (`docs/plans`, `docs/ai`) never gets a tracking arm, and a probe error carries NO recovery
+  command. The tracked lane is proven by a byte-exact path match, never by a non-empty listing — a
+  pathspec naming a directory lists its descendants, which prove nothing about the path itself. Membership itself is kind-gated only for a KEPT node: a
+  node THIS attempt created is owned by construction and stays in the proof set whatever its live
+  kind became. So a `--resume` in a worked-in satellite completes
+  with the session's uncommitted tracked edits, untracked scratch, and hook-created files
+  untouched — while the FIRST provision stays deliberately stricter, refusing any dirt at the
+  blanket clean-tree verify (its untracked visibility is explicit, so repo `status` configuration
+  cannot blind it).
   `--include` sources are identity-bound: preflight records each include root's identity (device,
   inode, and kind of the canonical node) BEFORE `git worktree add`, and a root that is neither a
   regular file nor a directory — or whose identity probe fails — is refused before any mutation.
@@ -93,8 +128,10 @@ own verbatim error through the existing Git-error surface.
   Foreign content stops cleanup. `--abandon` is the ONE destructive arm: it DESTROYS unlanded work,
   requires the handoff identity, and is the only path where `--force` may appear.
 
-**Provision record (`docs/plans/handoff-<slug>.md`, `## Provision record` — tool-owned):** identity
-(`slug`, `branch`, `include`, `node_modules`, `vscode-settings`, and after a prepare `prepared-tree`)
+**Provision record (`docs/plans/handoff-<slug>.md`, `## Provision record` — tool-owned):** resume
+IDENTITY (`slug`, `branch`, and the seeded plan name — a mismatch STOPs) · recorded provision FACTS
+that never authorize a resume (`include`, `node_modules`, `vscode-settings`) · and, after a prepare,
+`prepared-tree`, which is a land/cleanup attestation-and-recovery surface, not resume identity —
 PLUS the three facts a fresh satellite session cannot derive from its own checkout:
 
 - `shared-queue` — the ABSOLUTE path to MAIN's `docs/plans/queue.md`, followed by the rule the record states verbatim: the series index is SHARED and lives ONLY in main: read it at the absolute path above, and never copy it into this worktree, because docs/plans is git-ignored and machine-local, so a copy silently diverges from what main and every other worktree are writing. This worktree never WRITES that file: reaching outside it is an fs_outside_repo action the autonomy policy denies by default. Put new findings in THIS handoff record instead — it is the channel that survives the landing, and main appends them to the index from here. Provision never seeds a copy: the queue is deliberately absent from the satellite, and the absolute path is the only pointer — `--include` refuses to copy the index (or any directory containing it) into the worktree.
@@ -104,9 +141,9 @@ PLUS the three facts a fresh satellite session cannot derive from its own checko
   isolated-install command when the package manager is unambiguous, the honest install-by-hand
   advice when it is not, and — when the provisioned `node_modules` is a SYMLINK into main — the
   unlink-first form, because a plain install through the symlink writes into MAIN and is never
-  presented as isolated. When the WORKTREE'S OWN LIVE CHECKOUT is provably dependency-free (its `package.json` declares no dependencies, no `workspaces` field of any shape, no install-lifecycle script, no native-addon manifest, no external workspace manifest beside it — the evidence is what an install run in the satellite would actually read: the checkout's LIVE files at the moment the posture is resolved; on `--resume` a dirty tree is then refused by the clean-tree verify, after the record refresh) the record and the default-lane report both state `no install needed — the project declares no dependencies` and print no install command. A workspace tree is NEVER provably install-free — a workspace install materializes member links and `.bin` shims even with zero dependencies — and anything else the tool cannot enumerate (an absent or unparseable `package.json`, a malformed dependency or scripts field, an install-lifecycle script — dependency-free is not install-free) leaves the posture UNKNOWN and keeps the existing advice: a false "nothing to install" is worse than a redundant hint. `--install` remains an EXPLICIT request and is always answered with the
+  presented as isolated. When the WORKTREE'S OWN LIVE CHECKOUT is provably dependency-free (its `package.json` declares no dependencies, no `workspaces` field of any shape, no install-lifecycle script, no native-addon manifest, no external workspace manifest beside it — the evidence is what an install run in the satellite would actually read: the checkout's LIVE files at the moment the posture is resolved; on `--resume` that includes the session's own uncommitted edits, which the per-owned-path verify tolerates, and a failed resume leaves the prior record bytes) the record and the default-lane report both state `no install needed — the project declares no dependencies` and print no install command. A workspace tree is NEVER provably install-free — a workspace install materializes member links and `.bin` shims even with zero dependencies — and anything else the tool cannot enumerate (an absent or unparseable `package.json`, a malformed dependency or scripts field, an install-lifecycle script — dependency-free is not install-free) leaves the posture UNKNOWN and keeps the existing advice: a false "nothing to install" is worse than a redundant hint. `--install` remains an EXPLICIT request and is always answered with the
   isolated-install command.
-  All manifest/lockfile install evidence — the dependency-free proof AND the package-manager selection (the `packageManager` field, lockfiles) — is read from the worktree's own LIVE files at the moment the posture is resolved (on `--resume` too, where a dirty tree is then refused by the clean-tree verify); MAIN's mutable working tree never steers manager selection.
+  All manifest/lockfile install evidence — the dependency-free proof AND the package-manager selection (the `packageManager` field, lockfiles) — is read from the worktree's own LIVE files at the moment the posture is resolved (on `--resume` too, over the session's own live edits); MAIN's mutable working tree never steers manager selection.
 
 **Honesty:** there is NO preview step on the writers — over-warned by design. The tool never
 commits, never pushes, never runs a subscription CLI. Every content read and regular-file copy

package/tools/doc-parity.mjs

@@ -34,7 +34,7 @@ import {
 } from './recommendations.mjs';
 import { SKIPPED_READONLY } from './setup-backends.mjs';
 import { LATENT_ARM_NOTICE } from './review-state.mjs';
-import { QUEUE_SHARED_RULE, LANDING_FROM_MAIN, NO_DEPENDENCIES_POSTURE, CLEANUP_OWNERSHIP_RULE, INCLUDE_IDENTITY_RULE } from './worktrees.mjs';
+import { QUEUE_SHARED_RULE, LANDING_FROM_MAIN, NO_DEPENDENCIES_POSTURE, CLEANUP_OWNERSHIP_RULE, INCLUDE_IDENTITY_RULE, RESUME_VERIFY_RULE } from './worktrees.mjs';
 
 const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -112,6 +112,10 @@ export const BINDINGS = Object.freeze([
   // a reworded mode doc dropping the preflight-binding × door-time-queue contract fails this pin
   // plus the gate.
   valueBinding('include-identity-rule', INCLUDE_IDENTITY_RULE, INCLUDE_IDENTITY_RULE, [WORKTREES_DOC]),
+  // The resume-verify contract (slice R2): the exact live sentence every resume-verify STOP emits —
+  // a reworded mode doc dropping the per-owned-path × session-never-probed contract fails this pin
+  // plus the gate.
+  valueBinding('resume-verify-rule', RESUME_VERIFY_RULE, RESUME_VERIFY_RULE, [WORKTREES_DOC]),
 ].map((b) => Object.freeze(b)));
 
 // ── the pure checker (readText is injectable for hermetic tests) ────────────────────────
@@ -160,7 +164,8 @@ table, the status tokens, the trusted-dir allowlist), the recommendations/upgrad
 contract (section header, empty line, verdict templates), the acks-store path, the setup refresh
 degrade token, the review-state clean-tree latent-arm notice, the worktrees provision-record
 orientation contract (shared-queue rule, landing-from-main, no-dependencies install posture), the
-worktrees cleanup-ownership rule, and the worktrees include-identity rule — to
+worktrees cleanup-ownership rule, the worktrees include-identity rule, and the worktrees
+resume-verify rule — to
 the exact token its references/modes/*.md contract must carry, and
 asserts the CURRENT value renders into every bound file. A drifted doc, an unreadable bound file,
 or an absent token FAILS CLOSED.

package/tools/worktrees.mjs

@@ -785,7 +785,9 @@ const failAfterCopy = ({ cause, dstAbs, wtRoot, fs }) => {
   throw stop(`${primary} — partial destination removed; re-run provision`);
 };
 
-const copyNode = ({ srcAbs, dstAbs, wtRoot, rel, fs, report, copied, door = null }) => {
+const NO_JOURNAL = Object.freeze({ record: () => {} });
+
+const copyNode = ({ srcAbs, dstAbs, wtRoot, rel, fs, report, copied, door = null, journal = NO_JOURNAL, surface = 'copy-set-leaf', journalRoot = null }) => {
   if (EXCLUDED_BASENAMES.has(basename(srcAbs))) {
     report.push(`  skip (session sidecar): ${rel}`);
     return;
@@ -809,6 +811,7 @@ const copyNode = ({ srcAbs, dstAbs, wtRoot, rel, fs, report, copied, door = null
         // Fresh-provision include lane: an existing destination is aliasing the overlap
         // comparator missed (nothing legitimate pre-populates it) — fail closed, never "kept".
         if (door?.fresh) throw includeIdentityStop(rel, INCLUDE_PREEXIST_CAUSE);
+        journal.record({ rel, surface, outcome: 'kept', kind: 'symlink', root: journalRoot });
         report.push(`  kept (already present): ${rel}`);
         return;
       }
@@ -842,6 +845,7 @@ const copyNode = ({ srcAbs, dstAbs, wtRoot, rel, fs, report, copied, door = null
       guardDst(fs, wtRoot, dstAbs);
       fs.symlink(target, dstAbs);
       copied.add(rel);
+      journal.record({ rel, surface, outcome: 'written', kind: 'symlink', root: journalRoot });
       report.push(`  linked: ${rel} -> ${target}`);
     } else if (st.isDirectory()) {
       if (lstatNoFollow(fs.lstat, dstAbs) === null) {
@@ -854,11 +858,12 @@ const copyNode = ({ srcAbs, dstAbs, wtRoot, rel, fs, report, copied, door = null
         throw includeIdentityStop(rel, INCLUDE_PREEXIST_CAUSE);
       }
       for (const entry of fs.readdir(srcAbs)) {
-        copyNode({ srcAbs: join(srcAbs, entry), dstAbs: join(dstAbs, entry), wtRoot, rel: `${rel}/${entry}`, fs, report, copied, door });
+        copyNode({ srcAbs: join(srcAbs, entry), dstAbs: join(dstAbs, entry), wtRoot, rel: `${rel}/${entry}`, fs, report, copied, door, journal, surface, journalRoot });
       }
     } else if (st.isFile()) {
       if (lstatNoFollow(fs.lstat, dstAbs) !== null) {
         if (door?.fresh) throw includeIdentityStop(rel, INCLUDE_PREEXIST_CAUSE);
+        journal.record({ rel, surface, outcome: 'kept', root: journalRoot });
         report.push(`  kept (already present): ${rel}`);
         return;
       }
@@ -870,6 +875,7 @@ const copyNode = ({ srcAbs, dstAbs, wtRoot, rel, fs, report, copied, door = null
         failAfterCopy({ cause, dstAbs, wtRoot, fs });
       }
       copied.add(rel);
+      journal.record({ rel, surface, outcome: 'written', root: journalRoot });
       report.push(`  copied: ${rel}`);
     } else {
       throw stop(`refusing to copy a special file (device/FIFO/socket): ${rel}`);
@@ -1059,6 +1065,223 @@ const assertResumePlanCompatibility = ({ wtRoot, seedName, fs }) => {
   );
 };
 
+// ── D10: the tracked plans-chain refusal (slice R1 of the resume-verify design) ────────
+// A tracked handoff or seeded plan is a manufactured dead end: the landing lane
+// categorically refuses docs/plans (staged AND unstaged) and satellite commits are not a
+// lane, so drift on such a path can never be delivered. Both lanes refuse fail-closed
+// BEFORE any provision write. Probes are LITERAL by construction (D11): git lists the
+// docs/plans CONTAINER (that prefix carries no magic bytes) and each leaf is byte-compared
+// in code, so pathspec magic in a leaf name is inert.
+
+const PLANS_CHAIN_KIND = Object.freeze({
+  100644: 'regular', 100755: 'regular', 120000: 'symlink', 160000: 'gitlink', '040000': 'tree',
+});
+const plansChainKind = (mode) => PLANS_CHAIN_KIND[mode] ?? `mode-${mode}`;
+
+// `ls-tree -z`/`ls-files -z` lines: "<meta…>\t<path>" NUL-terminated → Map path → [entry].
+// A MULTIMAP on purpose: an unmerged index carries several stages of one path, and a
+// last-wins single value could hide an irregular stage behind a regular one. Each lister
+// maps its own meta shape (`ls-tree`: mode type oid · `ls-files --stage`: mode oid stage —
+// the STAGE is kept: a single stage-1/2/3 entry is unmerged even alone).
+const parseZPathEntries = (stdout, toEntry) => {
+  const entries = new Map();
+  for (const field of stdout.split('\0')) {
+    const tab = field.indexOf('\t');
+    if (tab === -1) continue;
+    const rel = field.slice(tab + 1);
+    if (!entries.has(rel)) entries.set(rel, []);
+    entries.get(rel).push(toEntry(field.slice(0, tab).split(' ')));
+  }
+  return entries;
+};
+
+// docs/plans entries of a tree-ish (an absent dir lists empty, exit 0).
+const listPlansTreeEntries = ({ git, cwd, treeish }) => {
+  const r = git(['ls-tree', '-z', treeish, `${PLANS_REL}/`], cwd);
+  if (r.status !== 0) return { error: (r.stderr || r.stdout).trim() || 'git ls-tree failed' };
+  return { entries: parseZPathEntries(r.stdout, (meta) => ({ mode: meta[0], stage: '0' })) };
+};
+
+const listPlansIndexEntries = ({ git, cwd }) => {
+  const r = git(['ls-files', '--cached', '--stage', '-z', '--', PLANS_REL], cwd);
+  if (r.status !== 0) return { error: (r.stderr || r.stdout).trim() || 'git ls-files failed' };
+  return { entries: parseZPathEntries(r.stdout, (meta) => ({ mode: meta[0], stage: meta[2] ?? '0' })) };
+};
+
+const plansChainRels = ({ slug, seedName }) =>
+  [...new Set([`${PLANS_REL}/${handoffBasename(slug)}`, `${PLANS_REL}/${seedName}`])];
+
+// The finding kind is decided over EVERY entry of the path from BOTH sources; an unmerged
+// index state — several stages OR a single non-zero stage — is irregular outright, never a
+// surgical-recovery candidate.
+const classifyPlansChainFinding = ({ headEntries = [], indexEntries = [] }) => {
+  const kinds = [...headEntries, ...indexEntries].map(({ mode }) => plansChainKind(mode));
+  const unmerged = indexEntries.length > 1 || indexEntries.some(({ stage }) => stage !== '0');
+  const irregular = unmerged || kinds.some((k) => k !== 'regular');
+  return { irregular, kind: unmerged ? 'unmerged-index' : (kinds.find((k) => k !== 'regular') ?? 'regular') };
+};
+
+const literalIndexRemoval = (rel) => `git rm --cached -- ${shellQuoteArg(`:(literal)${rel}`)}`;
+
+// FRESH, pre-mutation: the tree proof reads EXACTLY the captured commit — the same OID the
+// branch is cut from — so probe and mutation bind to one object.
+const assertPlansChainCleanAtCapturedOid = ({ git, root, oid, rels }) => {
+  const tree = listPlansTreeEntries({ git, cwd: root, treeish: oid });
+  if (tree.error) {
+    throw stop(`provision: the plans-chain tree probe failed at the captured commit ${oid}: ${tree.error}`);
+  }
+  for (const rel of rels) {
+    const headEntries = tree.entries.get(rel);
+    if (headEntries === undefined) continue;
+    const { irregular, kind } = classifyPlansChainFinding({ headEntries });
+    if (irregular) {
+      throw stop(`provision refuses: ${rel} is tracked as a ${kind} entry in the captured commit ${oid} — fail-closed; no worktree was created. ${PLANS_REL} must stay git-ignored and untracked.`);
+    }
+    // The reachable poisoned state usually has the removal ALREADY STAGED at main (with the
+    // path still index-tracked the docs/plans entry gate refuses first) — the advice must
+    // match the live index, else the printed command fails «pathspec did not match».
+    const index = listPlansIndexEntries({ git, cwd: root });
+    if (index.error) {
+      throw stop(`provision: the plans-chain index probe failed at main: ${index.error}`);
+    }
+    const stillIndexed = index.entries.has(rel);
+    throw stop([
+      `provision refuses: ${rel} is tracked in the captured commit ${oid} — a tracked plans-chain path is undeliverable and would strand the worktree. No worktree was created.`,
+      ...(stillIndexed
+        ? ['Recovery (surgical, at main): untrack it and commit the removal —', `  ${literalIndexRemoval(rel)}`, 'then commit and re-run provision.']
+        : ['Recovery (surgical, at main): the removal is already staged — commit it, then re-run provision.']),
+      `${PLANS_REL} must stay git-ignored and untracked.`,
+    ].join('\n'));
+  }
+};
+
+// FRESH, post-add, pre-write: a post-checkout hook may force-add or even COMMIT a
+// plans-chain path on the new branch (a committed add leaves the tree clean, invisible to
+// the blanket verify) — re-probe the live index AND the branch HEAD before the first write.
+const assertPlansChainCleanPostAdd = ({ git, wtRoot, branch, rels }) => {
+  const head = listPlansTreeEntries({ git, cwd: wtRoot, treeish: 'HEAD' });
+  if (head.error) throw stop(`provision: the post-add plans-chain probe failed in the new worktree: ${head.error}`);
+  const index = listPlansIndexEntries({ git, cwd: wtRoot });
+  if (index.error) throw stop(`provision: the post-add plans-chain probe failed in the new worktree: ${index.error}`);
+  const offending = rels
+    .filter((rel) => head.entries.has(rel) || index.entries.has(rel))
+    .map((rel) => ({ rel, ...classifyPlansChainFinding({ headEntries: head.entries.get(rel), indexEntries: index.entries.get(rel) }) }));
+  if (offending.length === 0) return;
+  // The kind matrix holds in every lane: ANY irregular entry → fail-closed, no recovery
+  // command at all. Both STOPs suppress the generic kept-worktree NOTE — its --resume advice
+  // would steer away from (or contradict) the honest lane here.
+  if (offending.some(({ irregular }) => irregular)) {
+    throw stop([
+      'provision refuses: the new worktree already tracks irregular plans-chain entr(y/ies) before any provision write — fail-closed:',
+      ...offending.map(({ rel, kind }) => `  ${rel} (${kind})`),
+      'Nothing was written into the worktree.',
+    ].join('\n'), { suppressKeptNote: true });
+  }
+  throw stop([
+    'provision refuses: the new worktree already tracks plans-chain path(s) before any provision write — a post-checkout hook force-added or committed:',
+    ...offending.map(({ rel }) => `  ${rel}`),
+    'A tracked plans-chain path is undeliverable and the worktree cannot converge; nothing was written into it.',
+    'Recovery, in order:',
+    '  1. inspect the worktree and copy OUT any hook-created content you value',
+    '  2. fix or remove the offending post-checkout hook',
+    '  3. with consent, remove the kept worktree from MAIN:',
+    `       git worktree remove --force ${shellQuoteArg(wtRoot)}`,
+    `       git branch -D ${shellQuoteArg(branch)}`,
+    '  4. re-run provision',
+  ].join('\n'), { suppressKeptNote: true });
+};
+
+// RESUME: the branch HEAD tree is probed UNCONDITIONALLY plus the live index, BEFORE the
+// handoff-identity reads — the probe result is collected first; the identity parse steers
+// only the recovery wording (a malformed record never cancels a tracked classification).
+const assertPlansChainCleanOnResume = ({ git, root, wtRoot, slug, branch, rels, fs }) => {
+  const head = listPlansTreeEntries({ git, cwd: wtRoot, treeish: 'HEAD' });
+  if (head.error) {
+    throw stop(`--resume: the plans-chain probe failed (branch HEAD tree): ${head.error} — the prior record is untouched`);
+  }
+  const index = listPlansIndexEntries({ git, cwd: wtRoot });
+  if (index.error) {
+    throw stop(`--resume: the plans-chain probe failed (live index): ${index.error} — the prior record is untouched`);
+  }
+  const headTracked = [];
+  const indexOnly = [];
+  for (const rel of rels) {
+    const headEntries = head.entries.get(rel);
+    const indexEntries = index.entries.get(rel);
+    if (headEntries !== undefined) headTracked.push({ rel, ...classifyPlansChainFinding({ headEntries, indexEntries }) });
+    else if (indexEntries !== undefined) indexOnly.push({ rel, ...classifyPlansChainFinding({ indexEntries }) });
+  }
+  if (headTracked.length === 0 && indexOnly.length === 0) return;
+
+  // Best-effort identity read, for RECOVERY WORDING only: destructive removal is offered
+  // ONLY where the record identity provably binds this worktree. The failure REASON is kept
+  // and printed INLINE — advising a re-run would loop (this probe fires before the shipped
+  // identity STOP can ever be reached).
+  const identity = (() => {
+    try {
+      const rf = readFileNoFollow(fs, join(wtRoot, PLANS_REL, handoffBasename(slug)));
+      if (!rf.bytes) return { binds: false, reason: 'the handoff is not readable as a regular file' };
+      const record = parseProvisionRecord(String(rf.bytes));
+      if (record.slug !== slug) return { binds: false, reason: `the record slug is ${record.slug ?? '(missing)'}, the live slug is ${slug}` };
+      if (record.branch !== branch) return { binds: false, reason: `the record branch is ${record.branch ?? '(missing)'}, the live branch is ${branch}` };
+      return { binds: true, reason: null };
+    } catch (err) {
+      return { binds: false, reason: errorText(err) };
+    }
+  })();
+
+  // The kind matrix governs the WHOLE set: any irregular finding (an irregular mode in
+  // EITHER source, or a multistage/unmerged index entry) withholds EVERY recovery command —
+  // destructive or surgical advice for a regular sibling would also cover the irregular
+  // content the contract fails closed on.
+  if ([...headTracked, ...indexOnly].some(({ irregular }) => irregular)) {
+    throw stop([
+      '--resume refuses: irregular plans-chain entr(y/ies) are tracked in this worktree — fail-closed, recovery commands withheld for the whole set:',
+      ...headTracked.map(({ rel, kind }) => `  ${rel} (${kind}, branch HEAD)`),
+      ...indexOnly.map(({ rel, kind }) => `  ${rel} (${kind}, index only)`),
+      'The prior provision record is untouched.',
+    ].join('\n'));
+  }
+
+  // A poisoned base dominates the scenario: consented abandon disposes the WHOLE worktree,
+  // so per-path index-only surgical commands beside it would be contradictory noise — the
+  // index-only paths are LISTED as findings and the one salvage-then-abandon lane covers all.
+  if (headTracked.length > 0) {
+    throw stop([
+      ...headTracked.map(({ rel }) =>
+        `--resume refuses: ${rel} is tracked in this worktree's branch HEAD — the legacy poisoned-base pathology; its drift is undeliverable, so this worktree cannot converge.`),
+      ...indexOnly.map(({ rel }) =>
+        `--resume refuses: ${rel} is staged in this worktree's index — undeliverable beside the poisoned base above.`),
+      'Recovery, in order:',
+      '  1. salvage FIRST: copy the live files (and anything else you value) OUT of the worktree — plain file copies, no identity needed',
+      identity.binds
+        ? `  2. then, with consent: ${composeOwnToolPrefix(root)} ${composeCleanupCommand({ slug, branch, abandon: true })} (DESTROYS unlanded work)`
+        : `  2. the handoff record does not bind: ${identity.reason} — a consented destructive removal is NOT offered; repair the record before any identity-bound lane can run`,
+    ].join('\n'));
+  }
+
+  const lines = [];
+  for (const { rel } of indexOnly) {
+    // The rule probe reads the EXACT offending path, index-independently: `--no-index` skips
+    // the index consultation that makes a plain check-ignore lie about tracked paths
+    // (live-probed), and a fabricated sibling name could disagree with the real rule set.
+    const rule = git(['check-ignore', '--no-index', '--', rel], wtRoot);
+    if (rule.status !== 0 && rule.status !== 1) {
+      throw stop(`--resume: the ignore-rule probe failed for ${rel}: ${(rule.stderr || rule.stdout).trim()} — the prior record is untouched`);
+    }
+    const ignoreRuleGone = rule.status === 1;
+    lines.push(
+      `--resume refuses: ${rel} is staged in this worktree's index (absent from the branch HEAD) — a session force-add whose staged entry can never be delivered.`,
+      'Recovery (surgical, in the worktree):',
+      `  1. ${literalIndexRemoval(rel)}`,
+      `     (if git refuses — the staged content differs from the live file — salvage the staged blob first: git show ${shellQuoteArg(`:${rel}`)} > <a file OUTSIDE this worktree>, then repeat with -f; the live file stays untouched)`,
+      ...(ignoreRuleGone ? [`  2. restore the git-ignore rule covering ${rel} (provision requires ${PLANS_REL} ignored)`] : []),
+      '  then re-run --resume.',
+    );
+  }
+  throw stop(lines.join('\n'));
+};
+
 // ── the handoff artifact (the tool's own record inside it; list/cleanup read it) ───────
 
 // The orientation facts a fresh satellite session cannot derive from its own checkout. They are
@@ -1075,8 +1298,139 @@ export const NODE_MODULES_NONE = 'no-dependencies';
 // cleanup time — never provenance, never the handoff record. Doc-parity pins this exact sentence
 // into the worktrees mode doc; every ownership STOP emits it.
 export const CLEANUP_OWNERSHIP_RULE = "node_modules ownership is decided live: only a symlink whose raw target bytes equal MAIN's node_modules path, in the ignored lane, is provision-ephemeral; an absent node with no index entry is clean; every other state stops cleanup to protect user data or because inspection failed";
+export const RESUME_VERIFY_RULE = "the resume verify proves only what THIS run placed or kept: every journaled leaf must be tracked or ignored in the worktree, an untracked owned leaf or any probe error stops the run naming the exact leaf, and every other path — the session's own work — is never probed and never a stop cause; a first provision keeps the blanket clean-tree verify";
 export const INCLUDE_IDENTITY_RULE = 'An --include source is copied only through the identity door: a file include must still match the identity preflight recorded (device, inode, kind), a directory include root is re-checked at walk start, and every copied file is proven, with both descriptors open, not to be the node that IS the door-time queue — an absent queue keeps the lexical guard alone, and anything unprovable stops the copy';
 
+// ── the placement journal (slice R2) ───────────────────────────────────────────────────
+// The resume verify proves PER PLACED PATH, so it needs a proof list: this run's live placement
+// journal over a CLOSED-WORLD registry — the surfaces are enumerated POSITIVELY, so no universal
+// "every mutation" claim exists to puncture. Leaf-only (git tracks no directories), KIND-GATED (a
+// live node whose kind differs from what the lane's SOURCE places is the pre-existing kept-exit
+// residual — SESSION for the verifier), and FROZEN at the verify: the sole post-verify write, the
+// record refresh, is permitted only at its already-journaled path.
+export const PLACEMENT_REGISTRY = Object.freeze([
+  'handoff-stub',
+  'seed-plan',
+  'copy-set-leaf',
+  'include-leaf',
+  'node-modules-link',
+  'vscode-settings',
+  'pin-rebase-target',
+  'record-refresh',
+]);
+const PLACEMENT_SURFACES = new Set(PLACEMENT_REGISTRY);
+// The ONE droppable class: an --include destination may be salvaged/relocated together with
+// dropping its source. Every other surface is mandatory — the next resume re-places it, so removal
+// is not a convergent fix and is never advised.
+const DROPPABLE_SURFACES = new Set(['include-leaf']);
+
+const journalKindMatches = (fs, abs, kind) => {
+  const st = lstatNoFollow(fs.lstat, abs);
+  if (st === null) return false;
+  return kind === 'symlink' ? st.isSymbolicLink() : !st.isSymbolicLink() && st.isFile();
+};
+
+export const createPlacementJournal = ({ wtRoot, fs }) => {
+  const members = new Map();
+  const state = { frozen: false };
+  return {
+    record: ({ rel, surface, outcome, kind = 'file', root = null }) => {
+      if (!PLACEMENT_SURFACES.has(surface)) {
+        throw stop(`placement journal: "${surface}" is not a registry surface — the placement registry is closed`);
+      }
+      if (state.frozen) {
+        if (!members.has(rel)) {
+          throw stop(`placement journal: refusing a post-verify write at an unjournaled path: ${rel}`);
+        }
+        return;
+      }
+      // The kind gate is the KEPT-outcome residual only. A node THIS attempt created is owned by
+      // construction: dropping it here because its kind changed after the write would leave a path
+      // provision just placed unproven — the opposite of the fail-safe floor.
+      if (outcome !== 'written' && !journalKindMatches(fs, join(wtRoot, rel), kind)) return;
+      const entry = { rel, surface, outcome, ...(root === null ? {} : { root }) };
+      const prior = members.get(rel);
+      if (prior === undefined) members.set(rel, entry);
+      else if (outcome === 'written' && prior.outcome !== 'written') members.set(rel, { ...prior, outcome: 'written' });
+    },
+    freeze: () => {
+      state.frozen = true;
+      return [...members.values()];
+    },
+  };
+};
+
+// The per-owned-path lane probe, LITERAL by construction (D11) — live-probed against git 2.43:
+// `ls-files` accepts an explicit `:(literal)` pathspec, but `check-ignore` REFUSES pathspec magic
+// outright ("pathspec magic not supported by this command") AND, with the index in play, answers
+// for a name that GLOB-matches a tracked sibling — a file literally named `feature-[a].md` reads
+// as "not ignored" once `feature-a.md` is tracked. `--no-index` removes that shadow, leaving a
+// pure ignore-rule match. Tracked priority stays a VERSION-INDEPENDENT invariant precisely because
+// this probe decides it FIRST, on its own literal pathspec, instead of leaning on whatever
+// index-awareness a given git version bakes into `check-ignore`.
+const probeOwnedLane = ({ git, wtRoot, rel }) => {
+  const tracked = git(['ls-files', '-z', '--', literalPathspec(rel)], wtRoot);
+  if (tracked.status !== 0) {
+    return { lane: 'probe-error', detail: `git ls-files failed: ${(tracked.stderr || tracked.stdout).trim()}` };
+  }
+  // A non-empty result is NOT proof: live-probed on git 2.43, a pathspec naming a DIRECTORY lists
+  // its tracked DESCENDANTS (`:(literal)notes` → notes/note.md …). Only a field byte-equal to the
+  // probed path proves THIS path tracked; anything else falls through to the ignore/untracked
+  // proof, so a non-leaf member fails closed instead of passing on a descendant's back.
+  if (nulFields(tracked.stdout).includes(rel)) return { lane: 'tracked' };
+  const ignored = git(['check-ignore', '--no-index', '--', rel], wtRoot);
+  if (ignored.status === 0) return { lane: 'ignored' };
+  if (ignored.status === 1) return { lane: 'untracked' };
+  return { lane: 'probe-error', detail: `git check-ignore failed: ${(ignored.stderr || ignored.stdout).trim()}` };
+};
+
+// Recovery for a DROPPABLE surface is emitted ONCE per include ROOT, never per leaf: dropping the
+// flag orphans every copy under that root (cleanup derives its ownership from `record.includes`),
+// so leaf-only advice cannot converge. It never offers REMOVAL: the journal cannot see session
+// content or kind-excluded nodes sitting inside that root, so no derived `rm` could be proven safe.
+// It also never says "leave it here": an orphaned destination is exactly what stops land — the
+// convergent action is moving the whole root OUT of the worktree.
+const droppableRootRecovery = (root) =>
+  `  ${root}: salvage or relocate the whole include destination root OUT of the worktree — its contents are preserved wherever you move them — AND drop \`--include ${root}\` in the same run; either alone recurs (a remaining source re-creates the copy, and an orphaned destination stops land)`;
+
+const ownedRecoveryLines = (failures) => {
+  const lines = [];
+  const seenRoots = new Set();
+  for (const failure of failures) {
+    if (DROPPABLE_SURFACES.has(failure.surface) && failure.root) {
+      if (seenRoots.has(failure.root)) continue;
+      seenRoots.add(failure.root);
+      lines.push(droppableRootRecovery(failure.root));
+      continue;
+    }
+    lines.push(`  ${failure.rel}: restore the ignore rule covering it in this worktree (.gitignore or the shared exclude), then re-run --resume`);
+  }
+  return lines;
+};
+
+// A set containing an unprovable lane withholds EVERY recovery command: advice derived from a
+// half-read tree is worse than none (the R1 mixed-findings discipline).
+const composeOwnedVerifyStop = (failures) => [
+  'post-provision verify failed — provision cannot prove the git lane of a path it placed or kept:',
+  ...failures.map(({ rel, surface, outcome, lane, detail }) => (lane === 'probe-error'
+    ? `  ${rel} (${surface}, ${outcome}) — lane unprovable: ${detail}`
+    : `  ${rel} (${surface}, ${outcome}) — untracked`)),
+  ...(failures.some((f) => f.lane === 'probe-error')
+    ? ['No recovery command is offered: a lane probe failed, so the tree state is unproven.']
+    : ['Recovery (convergent — through land preflight, not merely the next resume):', ...ownedRecoveryLines(failures)]),
+  RESUME_VERIFY_RULE,
+].join('\n');
+
+const verifyPlacedPaths = ({ git, wtRoot, members }) => {
+  const failures = [];
+  for (const member of members) {
+    const probe = probeOwnedLane({ git, wtRoot, rel: member.rel });
+    if (probe.lane === 'tracked' || probe.lane === 'ignored') continue;
+    failures.push({ ...member, ...probe });
+  }
+  if (failures.length > 0) throw stop(composeOwnedVerifyStop(failures));
+};
+
 // The record is LINE-oriented and is parsed back for IDENTITY, so a value carrying a control byte
 // is refused rather than written: a newline spills a second line the parser reads as a real field
 // (`- include:` is exempt from the duplicate-identity STOP, and an `## …` spill truncates or bricks
@@ -1237,10 +1591,12 @@ const pendingHandoffFields = ({ root, slug, branch }) =>
   ({ slug, branch, includes: [], nodeModules: 'pending', vscode: 'pending', install: 'pending', ...orientationFields({ root, slug }) });
 
 // The stub is written only when ABSENT; the final record surgically replaces the tool section.
-const writeHandoffStubIfAbsent = ({ root, wtRoot, slug, branch, fs, report }) => {
+const writeHandoffStubIfAbsent = ({ root, wtRoot, slug, branch, fs, report, journal = NO_JOURNAL }) => {
+  const rel = `${PLANS_REL}/${handoffBasename(slug)}`;
   const dst = join(wtRoot, PLANS_REL, handoffBasename(slug));
   const cur = readFileNoFollow(fs, dst);
   if (cur.bytes) {
+    journal.record({ rel, surface: 'handoff-stub', outcome: 'kept' });
     report.push('  handoff: kept (already present)');
     return;
   }
@@ -1250,14 +1606,18 @@ const writeHandoffStubIfAbsent = ({ root, wtRoot, slug, branch, fs, report }) =>
   guardDst(fs, wtRoot, dirname(dst));
   fs.mkdir(dirname(dst));
   writeContainedFileAtomic(wtRoot, dst, composeHandoffStub(pendingHandoffFields({ root, slug, branch })), fs, { stop: (m) => stop(m) });
+  journal.record({ rel, surface: 'handoff-stub', outcome: 'written' });
 };
 
-const writeHandoffRecord = ({ wtRoot, slug, branch, fields, fs, report }) => {
+const writeHandoffRecord = ({ wtRoot, slug, branch, fields, fs, report, journal = NO_JOURNAL }) => {
   const dst = join(wtRoot, PLANS_REL, handoffBasename(slug));
   const cur = readFileNoFollow(fs, dst);
   if (!cur.bytes) {
     throw stop(`the handoff at ${PLANS_REL}/${handoffBasename(slug)} is not readable as a regular file — fix or remove it, then re-run --resume`);
   }
+  // The freeze lock, checked AFTER the content door so a node problem keeps its own precise error:
+  // this is the ONLY post-verify write, and only at the path the stub already journaled.
+  journal.record({ rel: `${PLANS_REL}/${handoffBasename(slug)}`, surface: 'record-refresh', outcome: 'kept' });
   const section = locateProvisionRecordSection(String(cur.bytes));
   const updated = `${section.source.slice(0, section.start)}${composeProvisionRecordSection(fields)}${section.source.slice(section.end)}`;
   writeContainedFileAtomic(wtRoot, dst, updated, fs, { stop: (m) => stop(m) });
@@ -1301,9 +1661,10 @@ const validateSeedPlan = ({ root, rootReal, planFlag, asFlag, fs }) => {
   return { srcAbs: srcReal, name };
 };
 
-const writeSeedPlan = ({ wtRoot, srcAbs, name, fs, report }) => {
+const writeSeedPlan = ({ wtRoot, srcAbs, name, fs, report, journal = NO_JOURNAL }) => {
   const dst = join(wtRoot, PLANS_REL, name);
   if (lstatNoFollow(fs.lstat, dst) !== null) {
+    journal.record({ rel: `${PLANS_REL}/${name}`, surface: 'seed-plan', outcome: 'kept' });
     report.push(`  kept (already present): ${PLANS_REL}/${name}`);
     return;
   }
@@ -1312,6 +1673,7 @@ const writeSeedPlan = ({ wtRoot, srcAbs, name, fs, report }) => {
   guardDst(fs, wtRoot, dirname(dst));
   fs.mkdir(dirname(dst));
   writeContainedFileAtomic(wtRoot, dst, String(src.bytes), fs, { stop: (m) => stop(m) });
+  journal.record({ rel: `${PLANS_REL}/${name}`, surface: 'seed-plan', outcome: 'written' });
   report.push(`  seeded plan: ${PLANS_REL}/${name}`);
 };
 
@@ -1320,7 +1682,7 @@ const writeSeedPlan = ({ wtRoot, srcAbs, name, fs, report }) => {
 // It is copied from that already-canonical `real`, NEVER re-resolved from the raw path: a fresh
 // realpath here (after the worktree exists) would re-open a TOCTOU where a swapped symlink could
 // redirect an include at the shared series index between the check and the copy.
-const provisionIncludes = ({ rootReal, wtRoot, includeSources, resume, git, fs, report, copied }) => {
+const provisionIncludes = ({ rootReal, wtRoot, includeSources, resume, git, fs, report, copied, journal = NO_JOURNAL }) => {
   const recorded = [];
   const queuePath = join(rootReal, PLANS_REL, QUEUE_BASENAME);
   for (const { rel, real, identity } of includeSources) {
@@ -1358,7 +1720,7 @@ const provisionIncludes = ({ rootReal, wtRoot, includeSources, resume, git, fs,
     const door = identity.kind === 'file'
       ? { identity, queuePath, fresh: !resume }
       : { queuePath, fresh: !resume };
-    copyNode({ srcAbs: real, dstAbs: join(wtRoot, rel), wtRoot, rel, fs, report, copied, door });
+    copyNode({ srcAbs: real, dstAbs: join(wtRoot, rel), wtRoot, rel, fs, report, copied, door, journal, surface: 'include-leaf', journalRoot: rel });
     recorded.push(rel);
   }
   return recorded;
@@ -1527,14 +1889,18 @@ const resolveInstallPosture = ({ wtRoot, dependencyFree, fs }) => {
   return resolveInstallAdvice({ wtRoot, fs }).instruction;
 };
 
-const provisionNodeModules = ({ root, rootReal, wtRoot, installFlag, dependencyFree, git, fs, report }) => {
+const provisionNodeModules = ({ root, rootReal, wtRoot, installFlag, dependencyFree, git, fs, report, journal = NO_JOURNAL }) => {
+  // The lane places ONLY a symlink, so the kind gate admits only a symlink at this path: a
+  // directory (a real install) is the user's, never provision's to prove or advise on.
+  const journalLink = (outcome) => journal.record({ rel: NODE_MODULES_REL, surface: 'node-modules-link', outcome, kind: 'symlink' });
   const install = resolveInstallAdvice({ wtRoot, fs });
   if (installFlag) {
-    const dst = join(wtRoot, 'node_modules');
+    const dst = join(wtRoot, NODE_MODULES_REL);
     const existing = lstatNoFollow(fs.lstat, dst);
     if (existing !== null && existing.isSymbolicLink()) {
       // isolation only exists BEFORE the link: an install through it would write into MAIN
       const separator = install.command === null ? ' — ' : ' && ';
+      journalLink('kept');
       report.push(`  node_modules: existing symlink kept — for isolation remove it first: rm ${shellQuoteArg(dst)}${separator}${install.instruction}`);
       return 'install-printed-unlink-first';
     }
@@ -1546,8 +1912,9 @@ const provisionNodeModules = ({ root, rootReal, wtRoot, installFlag, dependencyF
   // LIVE STATE WINS the whole default lane: a node already at the worktree — a directory, or a
   // symlink an earlier provision left, even dangling — is what the record states; reporting
   // MAIN's state (`absent`) beside an existing node would contradict record.install.
-  const dst = join(wtRoot, 'node_modules');
+  const dst = join(wtRoot, NODE_MODULES_REL);
   if (lstatNoFollow(fs.lstat, dst) !== null) {
+    journalLink('kept');
     report.push('  node_modules: already present in the worktree');
     return 'present';
   }
@@ -1599,12 +1966,20 @@ const provisionNodeModules = ({ root, rootReal, wtRoot, installFlag, dependencyF
     report.push(`  node_modules: symlink failed (${err?.code ?? 'error'}) — ${install.instruction}`);
     return 'symlink-failed';
   }
+  journalLink('written');
   report.push(`  node_modules: symlinked -> ${mainNm} (shared MUTABLE cache — writes through it hit MAIN's node_modules; isolation: --install; workspace self-links resolve to MAIN sources)`);
   return 'symlinked';
 };
 
-const provisionVscode = ({ root, wtRoot, slug, git, fs, report }) => {
+const provisionVscode = ({ root, wtRoot, slug, git, fs, report, journal = NO_JOURNAL }) => {
   const relPath = '.vscode/settings.json';
+  // An EXISTING satellite destination is journaled FIRST, before every source-side and gate-side
+  // early return: the doors decide only what this run WRITES, while the journal decides what gets
+  // PROVEN. Membership must not depend on MAIN's current state — a file an earlier run placed
+  // would otherwise skip here (MAIN lost its .vscode dir, MAIN's copy became tracked, or the
+  // ignore rule was lost) and ride a successful resume out as a land-blocking leftover.
+  const present = lstatNoFollow(fs.lstat, join(wtRoot, relPath)) !== null;
+  if (present) journal.record({ rel: relPath, surface: 'vscode-settings', outcome: 'kept' });
   const vscodeDir = lstatNoFollow(fs.lstat, join(root, '.vscode'));
   if (vscodeDir === null || !vscodeDir.isDirectory()) {
     report.push('  .vscode: main has no .vscode/ dir — window title not written');
@@ -1622,7 +1997,7 @@ const provisionVscode = ({ root, wtRoot, slug, git, fs, report }) => {
     report.push(`  .vscode: ${relPath} is not ignored in the worktree — skipped (it would become a land leftover)`);
     return 'skipped-not-ignored';
   }
-  if (lstatNoFollow(fs.lstat, join(wtRoot, relPath)) !== null) {
+  if (present) {
     report.push('  .vscode: kept (already present)');
     return 'kept';
   }
@@ -1651,6 +2026,7 @@ const provisionVscode = ({ root, wtRoot, slug, git, fs, report }) => {
   guardDst(fs, wtRoot, join(wtRoot, '.vscode'));
   fs.mkdir(join(wtRoot, '.vscode'));
   writeContainedFileAtomic(wtRoot, join(wtRoot, relPath), body, fs, { stop: (m) => stop(m) });
+  journal.record({ rel: relPath, surface: 'vscode-settings', outcome: 'written' });
   report.push(`  .vscode: ${relPath} written (window.title = ${slug})`);
   return 'written';
 };
@@ -1658,11 +2034,12 @@ const provisionVscode = ({ root, wtRoot, slug, git, fs, report }) => {
 // tracked/untracked is decided by GIT (a run-local copy log lies after a crash-resume); an
 // untracked pin-carrying file is rewritten ONLY when its bytes equal the MAIN source or its
 // already-rebased form — anything else is user work and stays byte-untouched (reported).
-const rebasePins = ({ root, wtRoot, git, fs, report }) => {
+const rebasePins = ({ root, wtRoot, git, fs, report, journal = NO_JOURNAL }) => {
   for (const target of REBASE_TARGETS) {
     const wtAbs = join(wtRoot, target);
     const cur = readFileNoFollow(fs, wtAbs);
     if (cur.absent) continue;
+    if (cur.bytes) journal.record({ rel: target, surface: 'pin-rebase-target', outcome: 'kept' });
     if (!cur.bytes) {
       report.push(`  ${target}: ${cur.unsafe ? 'not a regular file' : `unreadable (${cur.error})`} — left untouched`);
       continue;
@@ -1809,13 +2186,22 @@ export const runProvision = ({ argvSlug, flags, cwd, git, deps, log }) => {
     }
     const wtCommon = gitLine(git, ['rev-parse', '--path-format=absolute', '--git-common-dir'], targetReal);
     if (wtCommon !== commonDir) throw stop(`--resume identity mismatch: ${targetReal} does not share this repo's git dir`);
+    assertPlansChainCleanOnResume({ git, root, wtRoot: targetReal, slug, branch, rels: plansChainRels({ slug, seedName: seed.name }), fs });
     assertResumeHandoffIdentity({ wtRoot: targetReal, slug, branch, fs });
     assertResumePlanCompatibility({ wtRoot: targetReal, seedName: seed.name, fs });
     runWritabilityProbe();
     report.push(`resuming provision at ${targetReal} (branch ${branch})`);
   } else {
     runWritabilityProbe();
-    const add = git(['worktree', 'add', '-b', branch, targetReal], root);
+    // ONE captured commit binds the plans-chain tree proof AND the branch cut: a clean
+    // captured OID with a subsequently-moved HEAD still cuts from the captured OID.
+    const capture = git(['rev-parse', 'HEAD'], root);
+    if (capture.status !== 0) {
+      throw stop(`provision: cannot capture the base commit (git rev-parse HEAD failed in the main repo): ${(capture.stderr || capture.stdout).trim()} — the plans-chain proof and the branch cut must bind to one commit`);
+    }
+    const capturedOid = capture.stdout.replace(/\r?\n$/, '');
+    assertPlansChainCleanAtCapturedOid({ git, root, oid: capturedOid, rels: plansChainRels({ slug, seedName: seed.name }) });
+    const add = git(['worktree', 'add', '-b', branch, targetReal, capturedOid], root);
     if (add.status !== 0) {
       throw stop(
         [
@@ -1830,9 +2216,12 @@ export const runProvision = ({ argvSlug, flags, cwd, git, deps, log }) => {
   // any failure past this point leaves a real created worktree — the error must say so and
   // hand back the exact finish command, never just the local cause
   try {
+    if (!flags.resume) {
+      assertPlansChainCleanPostAdd({ git, wtRoot: targetReal, branch, rels: plansChainRels({ slug, seedName: seed.name }) });
+    }
     return finishProvision({ root, rootReal, targetPath: targetReal, slug, branch, flags, seed, includeSources, provisionSet, git, deps, fs, report, log });
   } catch (err) {
-    if (!flags.resume && err?.message) {
+    if (!flags.resume && err?.message && !err.suppressKeptNote) {
       err.message += `\nNOTE: the worktree at ${targetReal} (branch ${branch}) was created and KEPT — finish with: ${composeProvisionArgv({ root, slug, flags: { ...flags, resume: true } })} (or reclaim it with the consented cleanup).`;
     }
     throw err;
@@ -1840,41 +2229,27 @@ export const runProvision = ({ argvSlug, flags, cwd, git, deps, log }) => {
 };
 
 const finishProvision = ({ root, rootReal, targetPath, slug, branch, flags, seed, includeSources, provisionSet, git, deps, fs, report, log }) => {
-  writeHandoffStubIfAbsent({ root, wtRoot: targetPath, slug, branch, fs, report });
+  // THIS run's proof set: every lane journals the leaf it placed or kept, and nothing else is ever
+  // examined by the resume verify — the session's own work is out of scope by construction.
+  const journal = createPlacementJournal({ wtRoot: targetPath, fs });
+  writeHandoffStubIfAbsent({ root, wtRoot: targetPath, slug, branch, fs, report, journal });
 
   const copied = new Set();
   report.push('copying the provision set (copy-if-missing; tracked files come from the checkout):');
   for (const pattern of provisionSet) {
     const rel = patternToProbe(pattern).replace(/\/$/, '');
-    copyNode({ srcAbs: join(root, rel), dstAbs: join(targetPath, rel), wtRoot: targetPath, rel, fs, report, copied });
+    copyNode({ srcAbs: join(root, rel), dstAbs: join(targetPath, rel), wtRoot: targetPath, rel, fs, report, copied, journal });
   }
 
-  writeSeedPlan({ wtRoot: targetPath, srcAbs: seed.srcAbs, name: seed.name, fs, report });
-  const includesRecorded = provisionIncludes({ rootReal, wtRoot: targetPath, includeSources, resume: flags.resume, git, fs, report, copied });
+  writeSeedPlan({ wtRoot: targetPath, srcAbs: seed.srcAbs, name: seed.name, fs, report, journal });
+  const includesRecorded = provisionIncludes({ rootReal, wtRoot: targetPath, includeSources, resume: flags.resume, git, fs, report, copied, journal });
   // Computed ONCE, from the satellite's own checkout, and threaded to both consumers — the report
   // lane and the record must state the SAME verdict.
   const dependencyFree = declaresNoDependencies({ wtRoot: targetPath, fs });
-  const nodeModulesMode = provisionNodeModules({ root, rootReal, wtRoot: targetPath, installFlag: flags.install, dependencyFree, git, fs, report });
-  const vscodeMode = provisionVscode({ root, wtRoot: targetPath, slug, git, fs, report });
+  const nodeModulesMode = provisionNodeModules({ root, rootReal, wtRoot: targetPath, installFlag: flags.install, dependencyFree, git, fs, report, journal });
+  const vscodeMode = provisionVscode({ root, wtRoot: targetPath, slug, git, fs, report, journal });
 
-  rebasePins({ root, wtRoot: targetPath, git, fs, report });
-
-  writeHandoffRecord({
-    wtRoot: targetPath,
-    slug,
-    branch,
-    fields: {
-      slug,
-      branch,
-      includes: includesRecorded,
-      nodeModules: nodeModulesMode,
-      vscode: vscodeMode,
-      install: resolveInstallPosture({ wtRoot: targetPath, dependencyFree, fs }),
-      ...orientationFields({ root, slug }),
-    },
-    fs,
-    report,
-  });
+  rebasePins({ root, wtRoot: targetPath, git, fs, report, journal });
 
   const inFlight = plansInFlight(targetPath, fs.readdir);
   if (inFlight.length !== 1 || inFlight[0] !== seed.name) {
@@ -1883,12 +2258,54 @@ const finishProvision = ({ root, rootReal, targetPath, slug, branch, flags, seed
     );
   }
 
-  const porcelain = git(['status', '--porcelain'], targetPath);
-  if (porcelain.status !== 0) throw stop(`git status failed in the worktree: ${porcelain.stderr.trim()}`);
-  if (porcelain.stdout.trim() !== '') {
-    throw stop(
-      `post-provision verify failed — the worktree status is not clean (everything provision places must be ignored-or-tracked):\n${porcelain.stdout.trimEnd()}`,
-    );
+  // The journal FREEZES here: the verify is the boundary, and the only write past it — the record
+  // refresh — is a registry surface permitted solely at its already-journaled path.
+  const placed = journal.freeze();
+  if (flags.resume) {
+    // The resume lane proves PER OWNED PATH. No `git status` runs here at all: the session's work
+    // is out of scope by construction, not by subtraction.
+    verifyPlacedPaths({ git, wtRoot: targetPath, members: placed });
+  } else {
+    // `--untracked-files=normal` is EXPLICIT: `status.showUntrackedFiles=no` empties porcelain
+    // output, which would silently turn this strict verify into a no-op. Default behavior is
+    // unchanged — `normal` IS the default shape.
+    const porcelain = git(['status', '--porcelain', '--untracked-files=normal'], targetPath);
+    if (porcelain.status !== 0) throw stop(`git status failed in the worktree: ${porcelain.stderr.trim()}`);
+    if (porcelain.stdout.trim() !== '') {
+      throw stop(
+        `post-provision verify failed — the worktree status is not clean (everything provision places must be ignored-or-tracked):\n${porcelain.stdout.trimEnd()}`,
+      );
+    }
+  }
+
+  // The record refresh runs LAST, after the in-flight check and the verify, in BOTH lanes —
+  // the record attests only a VERIFIED provision; a failed run leaves the prior record bytes
+  // (the stub on a failed first provision). On resume the generic kept-worktree NOTE does not
+  // fire, so a refresh failure here wraps its own: the verify PASSED and the exact re-run
+  // command is the honest recovery, with the original cause preserved.
+  try {
+    writeHandoffRecord({
+      wtRoot: targetPath,
+      slug,
+      branch,
+      journal,
+      fields: {
+        slug,
+        branch,
+        includes: includesRecorded,
+        nodeModules: nodeModulesMode,
+        vscode: vscodeMode,
+        install: resolveInstallPosture({ wtRoot: targetPath, dependencyFree, fs }),
+        ...orientationFields({ root, slug }),
+      },
+      fs,
+      report,
+    });
+  } catch (err) {
+    if (flags.resume && err?.message) {
+      err.message += `\nNOTE: the worktree at ${targetPath} (branch ${branch}) is KEPT — the provision verify PASSED and only the record refresh failed; finish with: ${composeProvisionArgv({ root, slug, flags })} (the prior record bytes are untouched).`;
+    }
+    throw err;
   }
 
   const base = gitLine(git, ['rev-parse', 'HEAD'], targetPath) ?? '(unknown)';