@sabaiway/agent-workflow-kit 3.4.0 → 3.6.0

package/CHANGELOG.md

@@ -4,6 +4,68 @@ 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.6.0 — the dependency-free install posture: a proof, never a default (AD-067)
+
+On a provably dependency-free project the provision record and the default-lane report no longer
+print a generic `npm install` hint: both state
+`no install needed — the project declares no dependencies` (recorded node_modules mode
+`no-dependencies`), and a `doc-parity` binding pins the posture string to the mode doc.
+
+The verdict is a PROOF granted only on evidence the tool actually read — the WORKTREE'S OWN LIVE
+checkout: what an install run there would actually read, exactly HEAD at provision time and the
+satellite's own committed state on `--resume`, never MAIN's mutable working tree (which can
+diverge from what the satellite actually holds; real-git tests pin both refresh directions).
+Everything the tool cannot vouch for leaves the posture UNKNOWN with the honest advice kept — the
+fail-safe direction, because a false "nothing to install" is worse than a redundant hint:
+
+- a `workspaces` field of ANY shape, outright — a workspace install materializes member links and
+  `.bin` shims even with zero dependencies, so a workspace tree is never provably install-free;
+- an external workspace manifest beside the root (`pnpm-workspace.yaml`/`.yml`, `lerna.json`);
+- a malformed manifest, dependency field, or `scripts` shape (three-valued verdicts — malformed is
+  `unknown`, never "none"; a lifecycle key with a non-string value fails closed);
+- an install-lifecycle script — dependency-free is NOT install-free: the CLOSED, test-pinned set
+  is the npm lifecycle (including the deprecated `prepublish`) plus `pnpm:devPreinstall`; a
+  native-addon manifest (`binding.gyp`) is a mandatory install too.
+
+The posture COMPOSES with the shipped record contract, and LIVE STATE WINS: a node already at the
+worktree — a directory, or a symlink left by an earlier provision, even dangling — records
+`present` before any MAIN-state early return, the AD-065 symlink unlink-first arm is untouched for
+every non-proven project, and `--install` remains an explicit request that is always answered with
+the isolated-install command while the record still states the posture.
+
+Third safe slice of the deferred parallel-track work (AD-063); node_modules ownership and
+resume-verify semantics stay separate redesigns.
+
+## 3.5.0 — the provision record orients a fresh satellite session (AD-065)
+
+The worktrees provision record was an identity stub; a fresh satellite session could not derive
+three facts from its own checkout. The record now carries all three, and the mode doc is pinned to
+the live constants:
+
+- **`shared-queue`** — the ABSOLUTE path to MAIN's `docs/plans/queue.md`, followed by the verbatim
+  rule: the series index is SHARED, read it at that path, never copy it (a machine-local copy
+  silently diverges); findings ride the handoff record and main appends them to the index. The rule
+  ships only WITH the path — a record from an earlier kit carries neither. `--include` refuses to
+  copy the index (or any directory containing it) into the worktree, at preflight AND re-asserted
+  at the point of copy on the canonical pair resolved before `git worktree add`.
+- **`landing`** — landing runs FROM MAIN, never from the worktree, with the runnable
+  `… land <slug> --prepare` command already `cd`-ing back to main.
+- **`install`** — the resolved install posture: the runnable isolated-install command, or the
+  honest by-hand advice when the package manager is ambiguous.
+
+The record is line-oriented and parsed back for IDENTITY, so it now REFUSES any value it cannot
+round-trip: control bytes (an injected newline forges a field line or an `## …` heading that
+truncates the section) and U+2028/U+2029 (which write fine and are then silently DROPPED on read —
+a lost field with no error) are a typed STOP, never sanitized. Every value the record will carry is
+validated BEFORE any git mutation — a refusal at compose time would strand a created worktree with
+no handoff, which neither `--resume` nor `cleanup --abandon` can recover. Optional fields are
+omitted when absent, never rendered as `null`, so a record written by an earlier kit survives a
+refresh. Two new `doc-parity` bindings (`queue-shared-rule`, `landing-from-main`) pin
+`references/modes/worktrees.md` to the emitted strings.
+
+Second safe slice extracted from the deferred parallel-track work (AD-063) — no
+node_modules-ownership coupling; the provable dependency-free install posture is the next slice.
+
 ## 3.4.0 — review-state names a latent arm on a clean-tree PASS (AD-064)
 
 `review-state --check` under a configured `reviewed` or `council` recipe on a clean tree no longer

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.4.0'
+  version: '3.6.0'
 ---
 
 # agent-workflow-kit

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "3.4.0",
+  "version": "3.6.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

@@ -59,6 +59,20 @@ 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`)
+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.
+- `landing` — landing runs FROM MAIN, never from this worktree, with the runnable
+  `… land <slug> --prepare` command already `cd`-ing back to main.
+- `install` — the install posture the tool resolved for THIS worktree: the runnable
+  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: exactly HEAD at provision time, the satellite's own committed state on `--resume`, never MAIN's mutable working tree) 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.
+
 **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
 goes through its one no-follow descriptor door (identity-bound source, exclusive destination,
@@ -98,7 +112,9 @@ free-form session-records digest slot (every section outside `## Provision recor
 and byte-preserved by the tool).
 
 **Ownership:** MAIN owns MAIN-tree files, commits, pushes, releases, the gate matrix, every
-docs/ai record, `docs/plans/queue.md`, and all shared git state — stash, hooks, repo config,
+docs/ai record, `docs/plans/queue.md` (the satellite READS it at the absolute main path and never
+writes it — its findings ride the handoff and main appends them; see **Provision record** above),
+and all shared git state — stash, hooks, repo config,
 `.git/info/exclude`, and every ref except the satellite's configured branch. The SATELLITE owns
 that one branch (`aw/<slug>` or the `--branch` override), its feature edits, its seeded plan, and
 the user-owned handoff sections; `## Provision record` remains tool-owned. Satellite forbidden
@@ -106,7 +122,8 @@ verbs (the v1 docs-only bar): no `git commit`/`push`/`tag`/`git stash`/history r
 legal rewrite is the tool-printed `git reset --hard` recovery of the satellite's OWN configured
 branch (`aw/<slug>` or the `--branch` override) — no kit lifecycle writers
 (`init`/`upgrade`/`setup`/`hide-footprint`/`install-git-hooks`/`sandbox-masks`/`ack-write`), no
-queue.md writes, no version bumps or publishes, no edits to MAIN's files from the satellite
+queue.md writes and no LOCAL queue.md copy — findings go into the handoff record, which main folds
+into the index at landing, no version bumps or publishes, no edits to MAIN's files from the satellite
 session — divergence and the landed verification enforce the observable half; the rest is the
 stated contract. A symlinked `node_modules` under npm workspaces resolves
 workspace self-links to MAIN-tree sources — use the printed isolated install when that matters.

package/tools/doc-parity.mjs

@@ -34,6 +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 } from './worktrees.mjs';
 
 const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -43,6 +44,7 @@ const UPGRADE_DOC = 'references/modes/upgrade.md';
 const VELOCITY_DOC = 'references/modes/velocity.md';
 const SETUP_DOC = 'references/modes/setup.md';
 const REVIEW_STATE_DOC = 'references/modes/review-state.md';
+const WORKTREES_DOC = 'references/modes/worktrees.md';
 
 // A typed usage failure (exit 2) for the CLI parser — the codebase's typed-error idiom (no classes).
 const usageFail = (message) => Object.assign(new Error(message), { exitCode: 2 });
@@ -96,6 +98,13 @@ export const BINDINGS = Object.freeze([
   // It was a prose-only bar a doc could silently drop, so it is pinned to the live string the tool
   // actually emits — a reworded doc dropping the notice fails this pin plus the gate.
   valueBinding('latent-arm-notice', LATENT_ARM_NOTICE, LATENT_ARM_NOTICE, [REVIEW_STATE_DOC]),
+  // The provision-record orientation contract (same "the tool knows and does not say" class): the
+  // shared-queue rule, the landing-from-main fact, and the no-dependencies install posture were
+  // prose-only bars a doc could silently drop, so all are pinned to the live strings the record
+  // actually carries.
+  valueBinding('queue-shared-rule', QUEUE_SHARED_RULE, QUEUE_SHARED_RULE, [WORKTREES_DOC]),
+  valueBinding('landing-from-main', LANDING_FROM_MAIN, LANDING_FROM_MAIN, [WORKTREES_DOC]),
+  valueBinding('no-dependencies-posture', NO_DEPENDENCIES_POSTURE, NO_DEPENDENCIES_POSTURE, [WORKTREES_DOC]),
 ].map((b) => Object.freeze(b)));
 
 // ── the pure checker (readText is injectable for hermetic tests) ────────────────────────
@@ -142,8 +151,9 @@ Usage:
 A CLOSED, exported registry binds each live code constant — the autonomy-doctor contract (the EXIT
 table, the status tokens, the trusted-dir allowlist), the recommendations/upgrade presentation
 contract (section header, empty line, verdict templates), the acks-store path, the setup refresh
-degrade token, and the review-state clean-tree latent-arm notice — to the exact token its
-references/modes/*.md contract must carry, and
+degrade token, the review-state clean-tree latent-arm notice, and the worktrees provision-record
+orientation contract (shared-queue rule, landing-from-main, no-dependencies install posture) — 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

@@ -927,16 +927,62 @@ const assertResumePlanCompatibility = ({ wtRoot, seedName, fs }) => {
 
 // ── the handoff artifact (the tool's own record inside it; list/cleanup read it) ───────
 
-const composeProvisionRecordSection = ({ slug, branch, includes, nodeModules, vscode, prepared = null }) => [
+// The orientation facts a fresh satellite session cannot derive from its own checkout. They are
+// CONSTANTS so the doc-parity registry can pin the mode doc to the exact strings the tool emits.
+export const QUEUE_BASENAME = 'queue.md';
+export const QUEUE_SHARED_RULE =
+  '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';
+export const LANDING_FROM_MAIN = 'landing runs FROM MAIN, never from this worktree';
+export const NO_DEPENDENCIES_POSTURE = 'no install needed — the project declares no dependencies';
+// The recorded node_modules mode for that same verdict: provision neither advised nor created a
+// node_modules for this worktree.
+export const NODE_MODULES_NONE = 'no-dependencies';
+
+// 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
+// the whole section). Values reach here from the repo ROOT path and from --include, both of which
+// may legally carry a newline on POSIX — so the guard is the only thing between them and a forged
+// record. U+2028/U+2029 ride the same refusal: they are line terminators to the JS regex `.` but
+// not to String.split('\n'), so such a value WRITES fine and is then silently DROPPED on read —
+// a lost field with no error, which is the one outcome this codebase never allows.
+// Fail closed: refuse to write, never sanitize silently.
+const RECORD_CONTROL_BYTE = /[\u0000-\u001F\u007F\u2028\u2029]/;
+const recordValue = (name, value) => {
+  const text = String(value);
+  if (RECORD_CONTROL_BYTE.test(text)) {
+    throw stop(`handoff record: the ${name} value carries a control character (newline/CR/NUL) — refusing to write a record whose fields could be forged by an injected line`);
+  }
+  // The parser `.trim()`s every value on read, and String.prototype.trim strips UNICODE whitespace
+  // — so an edge space (a Unicode one is legal even in a git branch name) writes fine and reads
+  // back as a DIFFERENT identity, stranding the worktree behind a record that no longer matches.
+  if (text !== text.trim()) {
+    throw stop(`handoff record: the ${name} value carries leading or trailing whitespace, which the record trims on read — the identity would change across a write→read round-trip: ${JSON.stringify(text)}`);
+  }
+  return text;
+};
+
+// An OPTIONAL field is omitted when absent, never rendered as "null": a record written by an
+// earlier kit is re-composed from its PARSED form at every refresh (land --prepare), so a field
+// that kit never wrote must survive the round-trip as absence, not as a literal null string.
+const optionalField = (name, value) => (value == null ? [] : [`- ${name}: ${recordValue(name, value)}`]);
+
+const composeProvisionRecordSection = ({ slug, branch, includes, nodeModules, vscode, install = null, sharedQueue = null, landing = null, prepared = null }) => [
   '## Provision record',
   '',
-  `- slug: ${slug}`,
-  `- branch: ${branch}`,
-  ...(includes.length === 0 ? ['- include: (none)'] : includes.map((p) => `- include: ${p}`)),
-  `- node_modules: ${nodeModules}`,
-  `- vscode-settings: ${vscode}`,
-  ...(prepared === null ? [] : [`- prepared-tree: ${prepared}`]),
+  `- slug: ${recordValue('slug', slug)}`,
+  `- branch: ${recordValue('branch', branch)}`,
+  ...(includes.length === 0 ? ['- include: (none)'] : includes.map((p) => `- include: ${recordValue('include', p)}`)),
+  `- node_modules: ${recordValue('node_modules', nodeModules)}`,
+  `- vscode-settings: ${recordValue('vscode-settings', vscode)}`,
+  ...optionalField('install', install),
+  ...optionalField('shared-queue', sharedQueue),
+  ...optionalField('landing', landing),
+  ...optionalField('prepared-tree', prepared),
   '',
+  // The rule says "at the absolute path above", so it ships only WITH that path: a record from an
+  // earlier kit carries no shared-queue field, and a rule pointing at nothing is worse than silence.
+  ...(sharedQueue == null ? [] : [QUEUE_SHARED_RULE, '']),
 ].join('\n');
 
 export const composeHandoffStub = (fields) => [
@@ -965,10 +1011,11 @@ const locateProvisionRecordSection = (text) => {
 export const parseProvisionRecord = (text) => {
   const section = locateProvisionRecordSection(text);
   const scan = section.source.slice(section.start, section.end).split('\n').slice(1);
-  const record = { slug: null, branch: null, includes: [], nodeModules: null, vscode: null, prepared: null };
+  const record = { slug: null, branch: null, includes: [], nodeModules: null, vscode: null, install: null, sharedQueue: null, landing: null, prepared: null };
   const single = {
     slug: 'slug', branch: 'branch', node_modules: 'nodeModules',
     'vscode-settings': 'vscode', 'prepared-tree': 'prepared',
+    install: 'install', 'shared-queue': 'sharedQueue', landing: 'landing',
   };
   const seen = new Set();
   for (const line of scan) {
@@ -988,11 +1035,67 @@ export const parseProvisionRecord = (text) => {
   return record;
 };
 
-const pendingHandoffFields = ({ slug, branch }) =>
-  ({ slug, branch, includes: [], nodeModules: 'pending', vscode: 'pending' });
+// Derived from MAIN's root, so the satellite reads an absolute path and a command that already
+// cd-s back to main — neither is derivable from inside the worktree.
+const orientationFields = ({ root, slug }) => ({
+  sharedQueue: join(root, PLANS_REL, QUEUE_BASENAME),
+  landing: `${LANDING_FROM_MAIN} — ${composeOwnToolPrefix(root)} land ${shellQuoteArg(slug)} --prepare`,
+});
+
+// Pre-mutation gate for everything the record will carry. `sharedQueue`/`landing` are derived from
+// the repo ROOT, so validating them here validates the root itself.
+const assertRecordValuesComposable = ({ root, slug, branch }) => {
+  recordValue('slug', slug);
+  recordValue('branch', branch);
+  const orientation = orientationFields({ root, slug });
+  recordValue('shared-queue', orientation.sharedQueue);
+  recordValue('landing', orientation.landing);
+};
+
+// An `- include:` value also round-trips through the literal `(none)` empty-list sentinel, so that
+// exact text reads back as NO value at all and cleanup would not recognize the copied path.
+// (Edge whitespace is refused inside recordValue — the same trim-on-read hazard for every field.)
+const assertIncludeRoundTrips = (rel) => {
+  recordValue('include', rel);
+  // No empty-rel arm: an include resolving TO the repo root is already refused by the containment
+  // check above (`isInside` excludes the root itself), so a guard here would be unreachable.
+  if (rel === '(none)') {
+    throw stop('--include resolves to the literal "(none)", which the provision record uses as its empty-list sentinel — rename the path before provisioning');
+  }
+};
+
+// The shared series index must never reach a satellite — a machine-local copy silently diverges
+// from what main and every other worktree are writing, which is the whole point of the
+// read-only-at-the-absolute-path contract. `--include` is the one lane that could smuggle it in,
+// by naming the file OR any directory that contains it. The compare runs in BOTH spaces: `incReal`
+// is canonical, so a queue.md (or docs/plans) that is itself a symlink canonicalizes AWAY from the
+// lexical queue path and would walk straight through a lexical-only compare while copying the very
+// content the rule fences. Fail closed: ONLY an ABSENT queue path (ENOENT — nothing exists there
+// to smuggle) falls back to the lexical compare alone; any other realpath failure (EACCES/EIO)
+// means the canonical identity cannot be established, and a silent fallback would quietly disable
+// the guard it exists to enforce.
+const assertIncludeNeverCopiesTheQueue = ({ rootReal, incReal, inc, fs }) => {
+  const queueLexical = join(rootReal, PLANS_REL, QUEUE_BASENAME);
+  const queuePaths = [queueLexical];
+  try {
+    queuePaths.push(fs.realpath(queueLexical));
+  } catch (err) {
+    if (err?.code !== 'ENOENT') {
+      throw stop(`--include: cannot resolve the shared series index path (${err?.code ?? 'error'}), so the queue-copy guard cannot establish its canonical identity: ${PLANS_REL}/${QUEUE_BASENAME} — fix the path (or drop the --include) and re-run`);
+    }
+  }
+  for (const queuePath of queuePaths) {
+    if (incReal === queuePath || isInside(incReal, queuePath)) {
+      throw stop(`--include would copy the SHARED series index (${PLANS_REL}/${QUEUE_BASENAME}) into the worktree: ${inc}. The index lives only in main and is read there — a local copy silently diverges.`);
+    }
+  }
+};
+
+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 = ({ wtRoot, slug, branch, fs, report }) => {
+const writeHandoffStubIfAbsent = ({ root, wtRoot, slug, branch, fs, report }) => {
   const dst = join(wtRoot, PLANS_REL, handoffBasename(slug));
   const cur = readFileNoFollow(fs, dst);
   if (cur.bytes) {
@@ -1004,7 +1107,7 @@ const writeHandoffStubIfAbsent = ({ wtRoot, slug, branch, fs, report }) => {
   }
   guardDst(fs, wtRoot, dirname(dst));
   fs.mkdir(dirname(dst));
-  writeContainedFileAtomic(wtRoot, dst, composeHandoffStub(pendingHandoffFields({ slug, branch })), fs, { stop: (m) => stop(m) });
+  writeContainedFileAtomic(wtRoot, dst, composeHandoffStub(pendingHandoffFields({ root, slug, branch })), fs, { stop: (m) => stop(m) });
 };
 
 const writeHandoffRecord = ({ wtRoot, slug, branch, fields, fs, report }) => {
@@ -1070,26 +1173,25 @@ const writeSeedPlan = ({ wtRoot, srcAbs, name, fs, report }) => {
   report.push(`  seeded plan: ${PLANS_REL}/${name}`);
 };
 
-const provisionIncludes = ({ root, rootReal, wtRoot, includes, git, fs, report, copied }) => {
+// The include set is resolved and identity-checked in runProvision — BEFORE `git worktree add` —
+// against the queue-copy guard and the round-trip guard, and arrives here as {rel, real} pairs.
+// 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, git, fs, report, copied }) => {
   const recorded = [];
-  for (const inc of includes) {
-    const srcAbs = resolve(root, inc);
-    let srcReal;
-    try {
-      srcReal = fs.realpath(srcAbs);
-    } catch {
-      throw stop(`--include: not found: ${inc}`);
-    }
-    if (!isInside(rootReal, srcReal)) throw stop(`--include must resolve inside the main repo: ${inc}`);
-    const rel = relative(rootReal, srcReal);
-    const probeRel = fs.lstat(srcReal).isDirectory() ? `${rel}/` : rel;
+  for (const { rel, real } of includeSources) {
+    // Defence in depth: re-assert the queue-copy prohibition on the canonical path at the POINT OF
+    // USE, so it holds where the copy happens and not only where the path was first checked.
+    assertIncludeNeverCopiesTheQueue({ rootReal, incReal: real, inc: rel, fs });
+    const probeRel = fs.lstat(real).isDirectory() ? `${rel}/` : rel;
     if (!checkIgnored(git, probeRel, wtRoot)) {
       throw stop(
         `--include destination is not ignored in the worktree: ${rel} — it would become a land-preflight leftover. ` +
           'Recovery: ignore the path (shared exclude / .gitignore) or drop the --include.',
       );
     }
-    copyNode({ srcAbs: srcReal, dstAbs: join(wtRoot, rel), wtRoot, rel, fs, report, copied });
+    copyNode({ srcAbs: real, dstAbs: join(wtRoot, rel), wtRoot, rel, fs, report, copied });
     recorded.push(rel);
   }
   return recorded;
@@ -1152,7 +1254,110 @@ const resolveInstallAdvice = ({ root, wtRoot, fs }) => {
   return { command, instruction: command };
 };
 
-const provisionNodeModules = ({ root, rootReal, wtRoot, installFlag, git, fs, report }) => {
+// Exported and frozen so the closed sets are test-pinned in BOTH directions (a member can neither
+// be dropped nor smuggled in without failing the pin).
+export const DEPENDENCY_FIELDS = Object.freeze(['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies']);
+// Workspace declarations this tool cannot read. Their presence makes the dependency inventory
+// unknowable from package.json alone, so it is never proof.
+export const EXTERNAL_WORKSPACE_MANIFESTS = Object.freeze(['pnpm-workspace.yaml', 'pnpm-workspace.yml', 'lerna.json']);
+
+const readPackageJson = (fs, path) => {
+  const file = readFileNoFollow(fs, path);
+  if (!file.bytes) return null;
+  try {
+    const parsed = JSON.parse(String(file.bytes));
+    return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+};
+
+// A dependency field is read THREE ways, never two: 'has' (a non-empty plain object), 'none' (the
+// field is absent, or an empty plain object), and 'unknown' for every other shape — a string, an
+// array, null. A malformed manifest is evidence of NOTHING, so it must never read as "none".
+const dependencyFieldsVerdict = (pkg) => {
+  let verdict = 'none';
+  for (const field of DEPENDENCY_FIELDS) {
+    if (!Object.hasOwn(pkg, field)) continue;
+    const value = pkg[field];
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) return 'unknown';
+    if (Object.keys(value).length > 0) verdict = 'has';
+  }
+  return verdict;
+};
+
+// A project with NO declared dependencies can still REQUIRE an install: a package-manager install
+// runs the WHOLE install-lifecycle set — the npm set (including the deprecated `prepublish`, which
+// historically fired on install) plus pnpm's `pnpm:devPreinstall` — so a manifest declaring any of
+// them, ROOT or member, needs an install even with no dependencies. dependency-free is NOT
+// install-free. The list is CLOSED and stated: a hook from a manager this tool has never heard of is
+// the honest residual of a closed-world check, the same shape as EXTERNAL_WORKSPACE_MANIFESTS.
+export const INSTALL_LIFECYCLE_SCRIPTS = Object.freeze(['preinstall', 'install', 'postinstall', 'prepare', 'preprepare', 'postprepare', 'prepublish', 'pnpm:devPreinstall']);
+// Fail-closed like the dependency check: a `scripts` field of the wrong SHAPE, or a lifecycle key
+// present with a NON-STRING value, is 'unknown' (never "no hook"). An empty-string value is a no-op,
+// not a trigger; 'has' only when a lifecycle key holds a non-empty command string.
+const installHookVerdict = (pkg) => {
+  if (!Object.hasOwn(pkg, 'scripts')) return 'none';
+  const scripts = pkg.scripts;
+  if (scripts === null || typeof scripts !== 'object' || Array.isArray(scripts)) return 'unknown';
+  let verdict = 'none';
+  for (const name of INSTALL_LIFECYCLE_SCRIPTS) {
+    if (!Object.hasOwn(scripts, name)) continue;
+    if (typeof scripts[name] !== 'string') return 'unknown';
+    if (scripts[name].length > 0) verdict = 'has';
+  }
+  return verdict;
+};
+// A native-addon manifest triggers an implicit `node-gyp rebuild` on install even with an empty
+// scripts block, so its presence — root or member — is a mandatory install, never proof of none.
+const declaresNativeBuild = (fs, dir) => lstatNoFollow(fs.lstat, join(dir, 'binding.gyp')) !== null;
+
+// PROVABLY dependency-free, or nothing — read from the WORKTREE'S OWN LIVE CHECKOUT, never from
+// MAIN's mutable working tree: the evidence is what an install run in THIS worktree would actually
+// read. At provision time that is exactly HEAD; on --resume it follows the session's own edits, in
+// both directions (gained dependencies revoke the proof, shed ones grant it) — the same live lane
+// as the node_modules symlink probe. A dirty main manifest must neither grant nor revoke a verdict
+// about content it does not describe. A `workspaces` field of ANY shape
+// is UNKNOWN outright — a workspace install materializes member links and `.bin` shims even with
+// zero dependencies, so a workspace tree is never provably install-free. Everything else the tool
+// cannot enumerate — an absent/unparseable package.json, a malformed dependency or scripts field,
+// an install-lifecycle script, a native-addon manifest (binding.gyp), an external workspace
+// manifest — leaves the posture UNKNOWN, and unknown keeps the existing install advice: a false
+// "nothing to install" is worse than a redundant hint.
+const declaresNoDependencies = ({ wtRoot, fs }) => {
+  const pkg = readPackageJson(fs, join(wtRoot, 'package.json'));
+  if (pkg === null || dependencyFieldsVerdict(pkg) !== 'none' || installHookVerdict(pkg) !== 'none') return false;
+  if (Object.hasOwn(pkg, 'workspaces')) return false;
+  if (declaresNativeBuild(fs, wtRoot)) return false;
+  // A workspace set can be declared OUTSIDE package.json too. The list is CLOSED and stated: an
+  // exotic third manifest this tool has never heard of would still read as proof, which is the
+  // honest residual of a closed-world check (the same shape as INSTALL_LIFECYCLE_SCRIPTS).
+  for (const manifest of EXTERNAL_WORKSPACE_MANIFESTS) {
+    if (lstatNoFollow(fs.lstat, join(wtRoot, manifest)) !== null) return false;
+  }
+  return true;
+};
+
+// What the RECORD states about installing — the resolved posture for THIS worktree (the runnable
+// isolated-install command, or the honest by-hand advice), never a lane-dependent hint. Probed on
+// the LIVE worktree after the node_modules step, and LIVE STATE WINS: a symlinked node_modules
+// records the unlink-first form even on a dependency-free checkout (`--resume` can meet a symlink
+// an earlier provision left — an install through it writes into MAIN, and the posture must never
+// hide that). Only then may a PROVEN dependency-free checkout short-circuit: a verdict of
+// "nothing to install" must not ride an install instruction.
+const resolveInstallPosture = ({ root, wtRoot, dependencyFree, fs }) => {
+  const nmPath = join(wtRoot, 'node_modules');
+  const nm = lstatNoFollow(fs.lstat, nmPath);
+  if (nm !== null && nm.isSymbolicLink()) {
+    const advice = resolveInstallAdvice({ root, wtRoot, fs });
+    const separator = advice.command === null ? ' — ' : ' && ';
+    return `the provisioned node_modules is a symlink into MAIN (an install through it writes into MAIN) — for isolation remove it first: rm ${shellQuoteArg(nmPath)}${separator}${advice.instruction}`;
+  }
+  if (dependencyFree) return NO_DEPENDENCIES_POSTURE;
+  return resolveInstallAdvice({ root, wtRoot, fs }).instruction;
+};
+
+const provisionNodeModules = ({ root, rootReal, wtRoot, installFlag, dependencyFree, git, fs, report }) => {
   const install = resolveInstallAdvice({ root, wtRoot, fs });
   if (installFlag) {
     const dst = join(wtRoot, 'node_modules');
@@ -1168,6 +1373,22 @@ const provisionNodeModules = ({ root, rootReal, wtRoot, installFlag, git, fs, re
       : `  node_modules: install it yourself (zero spawn): ${install.instruction}`);
     return 'install-printed';
   }
+  // 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');
+  if (lstatNoFollow(fs.lstat, dst) !== null) {
+    report.push('  node_modules: already present in the worktree');
+    return 'present';
+  }
+  // Only then may a PROVEN dependency-free checkout short-circuit the rest. Composing the posture
+  // into one of the arms below instead produced a self-contradicting line ("after your own
+  // install there, re-run --resume, or: no install needed"). `--install` is untouched above —
+  // that request was explicit.
+  if (dependencyFree) {
+    report.push(`  node_modules: ${NO_DEPENDENCIES_POSTURE}`);
+    return NODE_MODULES_NONE;
+  }
   const mainNm = join(root, 'node_modules');
   const node = classifyNodeNoFollow(mainNm, fs);
   if (node.kind === 'absent') {
@@ -1201,11 +1422,6 @@ const provisionNodeModules = ({ root, rootReal, wtRoot, installFlag, git, fs, re
     report.push(`  node_modules: main's resolves outside the repo — not symlinked; ${install.instruction}`);
     return 'outside-repo';
   }
-  const dst = join(wtRoot, 'node_modules');
-  if (lstatNoFollow(fs.lstat, dst) !== null) {
-    report.push('  node_modules: already present in the worktree');
-    return 'present';
-  }
   guardDst(fs, wtRoot, dst);
   try {
     fs.symlink(mainNm, dst);
@@ -1323,6 +1539,11 @@ export const runProvision = ({ argvSlug, flags, cwd, git, deps, log }) => {
   const branch = flags.branch ?? `${DEFAULT_BRANCH_PREFIX}${slug}`;
   if (flags.plan == null) throw usageStop('provision requires --plan <path> (the ONE feature plan the worktree starts with)');
   const { root, commonDir } = resolveRoots(cwd, git);
+  // Composing the record is the LAST step of provision, so a refusal there would leave a created
+  // worktree with no handoff — which neither --resume nor `cleanup --abandon` can recover, because
+  // both bind on the handoff identity. Every value the record will carry is therefore checked HERE,
+  // before the first fs read and long before `git worktree add`.
+  assertRecordValuesComposable({ root, slug, branch });
   const rootReal = fs.realpath(root);
   const config = loadWorktreesConfig(root, deps);
   const targetAbs = resolveTargetDir({ root, slug, dirFlag: flags.dir ?? null, parentDir: config.parentDir });
@@ -1356,9 +1577,16 @@ export const runProvision = ({ argvSlug, flags, cwd, git, deps, log }) => {
       throw stop(`--include: not found: ${inc}`);
     }
     if (!isInside(rootReal, incReal)) throw stop(`--include must resolve inside the main repo: ${inc}`);
-    includeSources.push({ rel: relative(rootReal, incReal), real: incReal });
+    assertIncludeNeverCopiesTheQueue({ rootReal, incReal, inc, fs });
+    const rel = relative(rootReal, incReal);
+    assertIncludeRoundTrips(rel);
+    includeSources.push({ rel, real: incReal });
   }
   assertTargetOutsideSources({ targetReal, sources: [...sources, ...includeSources] });
+  // The TARGET path reaches the record too — the `install` field embeds the worktree dir — and it
+  // is only known here, after --dir/parentDir resolution. Validating it now keeps the whole record
+  // composable BEFORE `git worktree add`, which is the point of every check above.
+  recordValue('target-dir', targetReal);
 
   const probeDir = resolveProbeDir(dirname(targetReal), deps);
   // the probe itself is a create+delete write — on resume it runs only AFTER every identity check
@@ -1399,7 +1627,7 @@ 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 {
-    return finishProvision({ root, rootReal, targetPath: targetReal, slug, branch, flags, seed, git, deps, fs, report, log });
+    return finishProvision({ root, rootReal, targetPath: targetReal, slug, branch, flags, seed, includeSources, git, deps, fs, report, log });
   } catch (err) {
     if (!flags.resume && err?.message) {
       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).`;
@@ -1408,8 +1636,8 @@ export const runProvision = ({ argvSlug, flags, cwd, git, deps, log }) => {
   }
 };
 
-const finishProvision = ({ root, rootReal, targetPath, slug, branch, flags, seed, git, deps, fs, report, log }) => {
-  writeHandoffStubIfAbsent({ wtRoot: targetPath, slug, branch, fs, report });
+const finishProvision = ({ root, rootReal, targetPath, slug, branch, flags, seed, includeSources, git, deps, fs, report, log }) => {
+  writeHandoffStubIfAbsent({ root, wtRoot: targetPath, slug, branch, fs, report });
 
   const copied = new Set();
   report.push('copying the provision set (copy-if-missing; tracked files come from the checkout):');
@@ -1419,8 +1647,11 @@ const finishProvision = ({ root, rootReal, targetPath, slug, branch, flags, seed
   }
 
   writeSeedPlan({ wtRoot: targetPath, srcAbs: seed.srcAbs, name: seed.name, fs, report });
-  const includesRecorded = provisionIncludes({ root, rootReal, wtRoot: targetPath, includes: flags.include, git, fs, report, copied });
-  const nodeModulesMode = provisionNodeModules({ root, rootReal, wtRoot: targetPath, installFlag: flags.install, git, fs, report });
+  const includesRecorded = provisionIncludes({ rootReal, wtRoot: targetPath, includeSources, git, fs, report, copied });
+  // 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 });
 
   rebasePins({ root, wtRoot: targetPath, git, fs, report });
@@ -1429,7 +1660,15 @@ const finishProvision = ({ root, rootReal, targetPath, slug, branch, flags, seed
     wtRoot: targetPath,
     slug,
     branch,
-    fields: { slug, branch, includes: includesRecorded, nodeModules: nodeModulesMode, vscode: vscodeMode },
+    fields: {
+      slug,
+      branch,
+      includes: includesRecorded,
+      nodeModules: nodeModulesMode,
+      vscode: vscodeMode,
+      install: resolveInstallPosture({ root, wtRoot: targetPath, dependencyFree, fs }),
+      ...orientationFields({ root, slug }),
+    },
     fs,
     report,
   });