@sabaiway/agent-workflow-kit 3.3.0 → 3.5.0

package/CHANGELOG.md

@@ -4,6 +4,50 @@ 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.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
+returns a bare `PASS — nothing to review`. It now NAMES every plan still in flight and states the
+forward consequence — `this gate arms as soon as the
+tree is dirty` — so a spent boot prompt left under a bare name is discoverable BEFORE it blocks,
+instead of surfacing at the worst moment: a pending commit, or the landing of a feature worktree when
+main first turns dirty. The quiet case (configured `solo`, no plan in flight, a non-git cwd) still
+passes silently through the earlier-returning arms; dirty-tree behaviour is unchanged. A `doc-parity`
+binding pins the
+live notice to `references/modes/review-state.md`, so a reworded doc that drops it fails the gate — a
+prose-only bar becomes a mechanism. This is the safe, converged slice of the deferred parallel-track
+work (AD-063), shipped on its own with no worktrees-ownership coupling.
+
 ## 3.3.0 — version-pin honesty: the profile stops claiming a limit it never observed (AD-062)
 
 `velocity --autonomy` told every user their credentials could not be protected by the sandbox —

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

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "3.3.0",
+  "version": "3.5.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/review-state.md

@@ -5,7 +5,7 @@ Read-only **review-receipt checker** (AD-038) — it makes *"reviewed ≠ shippe
 Run `node ${CLAUDE_SKILL_DIR}/tools/review-state.mjs [--check] [--json]`:
 
 1. Plain run → the human report: resolved recipe + source, plan-in-flight, tree fingerprint, per-backend receipt state (current / stale / ungrounded / probe / rejected / missing) with verdict + grounding + timestamp.
-2. **`--check`** → the gate exit code. The **normative exit contract lives in the tool header** (the single home — do not re-enumerate it elsewhere): exit 0 for a CONFIGURED solo recipe (a computed readiness-degrade NEVER silently becomes solo — it needs the explicit degrade record below), no plan in flight (the `docs/plans` naming convention: `queue.md` and `EXECUTE-`/`FEEDBACK-`-prefixed or `PROMPT`/`prompt`/`handoff`-carrying names are scratch), a clean tree, a non-git cwd, or every recipe-named backend SATISFIED for the current tree. **Satisfaction is ship-class-only on the LATEST NORMAL receipt (D3(b)):** per backend, the latest probe-free current-fingerprint receipt is selected FIRST and THEN verdict-checked — only the recognized ship-class vocabulary (`ship` / `ship with nits`) satisfies; a recognized NEGATIVE (`revise` / `rethink` / `rework`) is an authoritative VETO (an earlier ship never survives a later revise); an UNRECOGNIZED verdict (e.g. `unknown` from a dead run) fails CLOSED unconditionally — a later `unknown` never lets an earlier SHIP stand, and a fresh normal re-run supersedes it. **The ONLY escape is an explicit degrade RECORD** (`core-evidence.mjs degrade --backend <name> --reason "…"`, fingerprint-bound to the current tree) — and never all backends: ≥1 non-degraded ship-class receipt is required whenever ≥1 backend is configured; a malformed evidence store denies the escape fail-closed but never fails an independently-satisfied tree. Exit 1 otherwise — missing, **stale** (ANY edit after a review moves the fingerprint), ungrounded, vetoed, or unrecognized. Plan/diff receipts and continuations (`agy-review --continue`) are **informational-only**: after a fold, only a **fresh grounded re-run** (`codex-review code`; `agy-review code --facts @f`) restores green. **Probe receipts never attest either:** a `CODEX_PROBE=1` / `AGY_PROBE=1` review runs with the frontier-model/max-effort guard OFF, so the wrapper stamps `probe:true` and this checker excludes it — per receipt, so a real review at the same fingerprint still satisfies. **Silence is not a declaration:** a malformed *or* absent probe marker is rejected fail-closed and stated in the check line. Honest bound: receipts are **not authenticated** (a forger could write `probe:false` as easily as any other field) — like the rest of the receipt this is a self-discipline mechanism, not a security boundary.
+2. **`--check`** → the gate exit code. The **normative exit contract lives in the tool header** (the single home — do not re-enumerate it elsewhere): exit 0 for a CONFIGURED solo recipe (a computed readiness-degrade NEVER silently becomes solo — it needs the explicit degrade record below), no plan in flight (the `docs/plans` naming convention: `queue.md` and `EXECUTE-`/`FEEDBACK-`-prefixed or `PROMPT`/`prompt`/`handoff`-carrying names are scratch), a clean tree, a non-git cwd, or every recipe-named backend SATISFIED for the current tree. **A clean-tree PASS under a NON-SOLO review obligation is never silent about a latent arm:** when a `reviewed` or `council` recipe is configured, it NAMES every plan in flight and states that this gate arms as soon as the tree is dirty — the condition is discoverable BEFORE it blocks, instead of surfacing at the worst moment (a pending commit, or the landing of a feature worktree when main first turns dirty). Nothing is announced under a configured `solo` recipe or a non-git cwd, where the gate can never arm. **Satisfaction is ship-class-only on the LATEST NORMAL receipt (D3(b)):** per backend, the latest probe-free current-fingerprint receipt is selected FIRST and THEN verdict-checked — only the recognized ship-class vocabulary (`ship` / `ship with nits`) satisfies; a recognized NEGATIVE (`revise` / `rethink` / `rework`) is an authoritative VETO (an earlier ship never survives a later revise); an UNRECOGNIZED verdict (e.g. `unknown` from a dead run) fails CLOSED unconditionally — a later `unknown` never lets an earlier SHIP stand, and a fresh normal re-run supersedes it. **The ONLY escape is an explicit degrade RECORD** (`core-evidence.mjs degrade --backend <name> --reason "…"`, fingerprint-bound to the current tree) — and never all backends: ≥1 non-degraded ship-class receipt is required whenever ≥1 backend is configured; a malformed evidence store denies the escape fail-closed but never fails an independently-satisfied tree. Exit 1 otherwise — missing, **stale** (ANY edit after a review moves the fingerprint), ungrounded, vetoed, or unrecognized. Plan/diff receipts and continuations (`agy-review --continue`) are **informational-only**: after a fold, only a **fresh grounded re-run** (`codex-review code`; `agy-review code --facts @f`) restores green. **Probe receipts never attest either:** a `CODEX_PROBE=1` / `AGY_PROBE=1` review runs with the frontier-model/max-effort guard OFF, so the wrapper stamps `probe:true` and this checker excludes it — per receipt, so a real review at the same fingerprint still satisfies. **Silence is not a declaration:** a malformed *or* absent probe marker is rejected fail-closed and stated in the check line. Honest bound: receipts are **not authenticated** (a forger could write `probe:false` as easily as any other field) — like the rest of the receipt this is a self-discipline mechanism, not a security boundary.
 3. **Wire it as a gate by hand OR via the explicit-consent init preview — never without consent (AD-021/D9).** The candidate line for your own `docs/ai/gates.json`: `{ "id": "review-state", "title": "Review receipts current for the uncommitted tree", "cmd": "node <path-to-this-skill>/tools/review-state.mjs --check" }` — with the path your project actually reaches the kit by, QUOTED so a path with spaces survives, executable from the project root. The consent-gated gates-init preview (`${CLAUDE_SKILL_DIR}/references/modes/gates.md`, consent-fill section) offers exactly this entry — path resolved and quoted — ONLY when your `docs/ai/orchestration.json` declares `reviewed`/`council` on `plan-execution.review` (the slot this checker enforces); it writes nothing without your explicit yes. Once declared, the opt-in `${CLAUDE_SKILL_DIR}/references/modes/hook.md` auto-approves it like any other declared gate — and `run-gates --final` requires this check among its canonical core gates.
 4. **`--await [--timeout <s>]`** (BUGFREE-3 / AD-049) → BLOCK until every recipe-named backend is SATISFIED for the current tree (i.e. until `--check` would PASS), or the bounded timeout elapses (a loud exit 1; default 900s). Run it after dispatching the review bridges to WAIT for their receipts to land instead of hand-polling a pid: the durable completion signal is the **receipt**, never a process event (a harness "completed" notification fires early; a bridge's output late-flushes). It inherits the `--check` decision whole — a backend with a current-tree degrade RECORD stops being waited on (the shared decideCheck), so you never hand-`--await` around a known degrade. Still read-only (it re-reads the receipts + the evidence store); solo / no-plan / clean-tree resolve instantly.
 

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. `--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

@@ -33,6 +33,8 @@ import {
   ACKS_FILE,
 } 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 } from './worktrees.mjs';
 
 const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -41,6 +43,8 @@ const RECOMMENDATIONS_DOC = 'references/modes/recommendations.md';
 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 });
@@ -90,6 +94,15 @@ export const BINDINGS = Object.freeze([
   // (setup.md owns --refresh-placed; upgrade.md pastes its lines) — a reworded doc dropping the
   // outcome fails this pin plus the gate. The token tracks the exported SETUP constant.
   valueBinding('refresh-skipped-readonly', SKIPPED_READONLY, SKIPPED_READONLY, [SETUP_DOC, UPGRADE_DOC]),
+  // The "the tool knows and does not say" contract: a clean-tree PASS must still name a latent arm.
+  // 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 and the landing-from-main fact were prose-only bars a doc could silently
+  // drop, so both 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]),
 ].map((b) => Object.freeze(b)));
 
 // ── the pure checker (readText is injectable for hermetic tests) ────────────────────────
@@ -135,8 +148,10 @@ 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, and the setup
-refresh degrade token — to the exact token its references/modes/*.md contract must carry, and
+contract (section header, empty line, verdict templates), the acks-store path, the setup refresh
+degrade token, the review-state clean-tree latent-arm notice, and the worktrees provision-record
+orientation contract (shared-queue rule, landing-from-main) — 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/review-state.mjs

@@ -13,7 +13,11 @@
 //           absent config with no reviewer backend ready); when no plan is in flight (docs/plans/
 //           holds no top-level .md that is not queue.md and not scratch by the naming convention:
 //           prefixes EXECUTE- / FEEDBACK-, or a name containing PROMPT / prompt / handoff); when
-//           the tree is clean (nothing to review); when the cwd is not a git work tree; and when
+//           the tree is clean (nothing to review — under a non-solo review obligation the PASS
+//           still NAMES every plan in flight and states that the gate arms as soon as the tree
+//           turns dirty, so a latent arm is discoverable before it blocks a pending commit); when
+//           the cwd is not a git work tree
+//           (the gate can never arm there, so nothing is announced); and when
 //           the obligations are SATISFIED: under `reviewed`, >=1 backend's latest normal receipt
 //           attests SHIP-CLASS (ship / ship with nits) for the current tree; under `council`,
 //           EVERY review-capable backend attests ship-class OR carries an explicit current-tree
@@ -172,6 +176,25 @@ const maskAdvisoryLine = (state) =>
 
 // ── plan-in-flight detector (the AD-038 naming convention; documented in queue.md) ─────
 
+// The clean-tree PASS wording, split so the doc-parity registry can bind the forward-looking half
+// to the mode doc — the notice is the contract, not decoration.
+export const CLEAN_TREE_PASS = 'the working tree is clean — nothing to review';
+export const LATENT_ARM_NOTICE = 'this gate arms as soon as the tree is dirty';
+
+const UNSAFE_INLINE_SCALARS = /[\u007f-\u009f\u2028\u2029]/gu;
+// A plan FILENAME reaches a one-line gate report. JSON quoting handles the C0 control bytes; the C1
+// range (DEL + U+0080..U+009F, including the U+0085 line break) and the two Unicode line separators
+// survive JSON.stringify and can still break a line, so they are escaped explicitly — every escape a
+// valid JSON \uXXXX, so the token round-trips through JSON.parse. The plan set stays STRING-typed for
+// its consumers (procedures / worktrees / the JSON surface); a name carrying INVALID UTF-8 bytes is a
+// stated residual (queue: PARALLEL-TRACK-REDESIGN — two such names could collapse in the DISPLAY only,
+// never in the gate decision, which keys on the receipt fingerprint, not the name).
+export const quoteReportName = (name) =>
+  JSON.stringify(name).replace(
+    UNSAFE_INLINE_SCALARS,
+    (value) => `\\u${value.codePointAt(0).toString(16).padStart(4, '0')}`,
+  );
+
 // Scratch by the naming convention: EXECUTE-/FEEDBACK- prefixes, or a name carrying PROMPT/prompt/
 // handoff. queue.md is the series index, never a plan.
 export const isScratchPlanName = (name) =>
@@ -183,7 +206,7 @@ export const isScratchPlanName = (name) =>
   name.includes('handoff');
 
 // The in-flight plan files: top-level docs/plans/*.md minus queue.md minus scratch. [] when the
-// directory is absent (no plans → nothing in flight).
+// directory is absent (no plans → nothing in flight). STRING-typed for every consumer.
 export const plansInFlight = (cwd, readdir = readdirSync) => {
   let entries;
   try {
@@ -392,7 +415,14 @@ export const decideCheck = (state) => {
   }
   if (state.plans.length === 0) return { code: 0, reason: `no plan in flight (docs/plans/ holds no active plan) — no receipt required${earlyNotes}` };
   if (state.fingerprint == null) return { code: 0, reason: `not a git work tree — nothing to fingerprint${earlyNotes}` };
-  if (state.clean === true) return { code: 0, reason: `the working tree is clean — nothing to review${earlyNotes}` };
+  // A clean tree PASSES, but never silently: the no-plan arm above already returned, so reaching
+  // here means >=1 plan IS in flight and this gate arms the moment the tree turns dirty. Naming
+  // each file forward-looking is what makes the arm discoverable BEFORE it blocks a pending commit.
+  if (state.clean === true) {
+    // Each name is byte-preserving and quoted because this reason is one gate-report line.
+    const named = state.plans.map((p) => quoteReportName(p)).join(', ');
+    return { code: 0, reason: `${CLEAN_TREE_PASS} — ${state.plans.length} plan(s) in flight: ${named} — ${LATENT_ARM_NOTICE}${earlyNotes}` };
+  }
   const exempt = new Set(state.degradedExempt);
   const satisfied = state.backends.filter((b) => b.state === 'current' && b.shipClass);
   const vetoed = state.backends.filter((b) => b.state === 'current' && !b.shipClass);
@@ -463,7 +493,7 @@ const formatHuman = (state, check) => {
     `review-state — ${ACTIVITY}.${SLOT} = ${state.obligations.recipe ?? '(unknowable)'} (${src})${state.requiredBackends.length ? ` → ${state.requiredBackends.join(' + ')}${state.obligations.perBackend ? '' : ' (any one, ship-class)'}` : ''}`,
   ];
   if (state.detectionWarning) lines.push(`  ⚠ ${state.detectionWarning}`);
-  lines.push(`  plan in flight: ${state.plans.length ? state.plans.join(', ') : '(none)'}`);
+  lines.push(`  plan in flight: ${state.plans.length ? state.plans.map((name) => quoteReportName(name)).join(', ') : '(none)'}`);
   if (state.fingerprint == null) lines.push('  tree: not a git work tree');
   else if (state.clean === true) lines.push('  tree: clean (nothing to review)');
   else lines.push(`  tree fingerprint: ${state.fingerprint}`);
@@ -517,7 +547,8 @@ The ONLY escape for an unavailable backend under council is an explicit current-
 record (node core-evidence.mjs degrade) — and never all backends.
 
 --check exits 0/1 per the normative contract in the tool header: 0 for solo / no plan in flight /
-a clean tree / not-a-git-tree / obligations satisfied (reviewed: >=1 ship-class attestation;
+a clean tree (under a non-solo review obligation the PASS names every plan in flight and its arm) /
+not-a-git-tree / obligations satisfied (reviewed: >=1 ship-class attestation;
 council: every backend ship-class or degrade-recorded, >=1 real ship); 1 on a veto, an
 unrecognized verdict, a missing/stale/ungrounded/probe-only backend without a degrade record,
 an all-degraded tree, or a down detector with no configured recipe.

package/tools/worktrees.mjs

@@ -927,16 +927,58 @@ 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';
+
+// 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 +1007,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 +1031,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 +1103,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 +1169,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,6 +1250,20 @@ const resolveInstallAdvice = ({ root, wtRoot, fs }) => {
   return { command, instruction: command };
 };
 
+// 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: a plain `cd … && install` through a SYMLINKED
+// node_modules writes into MAIN — never presented as isolated; the symlink case records the
+// unlink-first form instead (the same contract the --install lane already prints).
+const resolveInstallPosture = ({ root, wtRoot, fs }) => {
+  const advice = resolveInstallAdvice({ root, wtRoot, fs });
+  const nmPath = join(wtRoot, 'node_modules');
+  const nm = lstatNoFollow(fs.lstat, nmPath);
+  if (nm === null || !nm.isSymbolicLink()) return advice.instruction;
+  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}`;
+};
+
 const provisionNodeModules = ({ root, rootReal, wtRoot, installFlag, git, fs, report }) => {
   const install = resolveInstallAdvice({ root, wtRoot, fs });
   if (installFlag) {
@@ -1323,6 +1435,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 +1473,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 +1523,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 +1532,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,7 +1543,7 @@ 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 includesRecorded = provisionIncludes({ rootReal, wtRoot: targetPath, includeSources, git, fs, report, copied });
   const nodeModulesMode = provisionNodeModules({ root, rootReal, wtRoot: targetPath, installFlag: flags.install, git, fs, report });
   const vscodeMode = provisionVscode({ root, wtRoot: targetPath, slug, git, fs, report });
 
@@ -1429,7 +1553,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, fs }),
+      ...orientationFields({ root, slug }),
+    },
     fs,
     report,
   });