@sabaiway/agent-workflow-kit 14.4.3 → 14.5.0

package/CHANGELOG.md

@@ -4,6 +4,60 @@ 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.
 
+## 14.5.0 — an upgrade delivers its migration notes and entry-point blocks through two new tools, and `init` removes the files the package does not carry from an existing kit home (AD-151)
+
+**Three things the upgrade already promised now run as code.** Up to 14.4.3 the upgrade mode asked the agent to pick
+the migration notes newer than the project's stamp by itself and to paste two entry-point blocks by hand, and `init`
+only added files, so a kit home kept every file a later package stopped shipping (except two paths the installer named
+by hand). 14.5.0 adds two command-line tools and one library the installer calls. Story S1 of the epic
+`CONSUMERS-MOVE-ONTO-THE-FULL-FLOW`; contract `docs/ai/specs/kit/upgrade-delivery/` (revision 1).
+
+- **`tools/migration-notes.mjs --cwd <project>`** (read-only). Lists each note under `migrations/` whose version is
+  newer than the project's `docs/ai/.workflow-version` and not newer than the deployment-lineage head, in ascending
+  order, one stdout line each: `note <version> <path> :: <headline>`. A refusal is one stderr line that opens with its
+  name; a usage error exits 2 before anything is read.
+- **`tools/migration-blocks.mjs --cwd <project> [--language <text>] [--attribution on|off] [--apply]`**. Places the
+  Communication language and Attribution blocks into the project's `AGENTS.md` from the kit's
+  `references/templates/AGENTS.md`, now the kit's only copy of their text. Without `--apply` it previews and writes
+  nothing; with `--apply` it writes every missing block in one atomic write, writes nothing when both blocks are
+  already present, and writes nothing when it refuses, naming the refusal in one stderr line.
+- **`tools/payload-prune.mjs`** (library). After its copy, `init` compares each of the five folders it installs
+  (`references/`, `tools/`, `migrations/`, `launchers/`, `bridges/`) with the same folder in the kit home. A regular file the package does not carry is removed with one `removed` line, a file
+  you placed there yourself included; a directory or symlink the package does not carry is kept with a `kept` line
+  (the files inside such a directory are removed all the same). `init` now refuses an existing folder that is
+  neither empty nor a kit home (a `SKILL.md` whose frontmatter names `agent-workflow-kit`): it exits 1 before
+  writing anything. A kind mismatch or a failed enumeration
+  stops the prune before it removes anything; a failed removal is reported by path and the other files still go. When
+  the prune reports a failure, `init` prints a non-convergence line in place of the line that names the installed
+  version, still runs its launcher, bridge, memory and engine steps, and exits 1. The hand-kept `RETIRED_PATHS` list
+  is gone.
+- **Upgrade mode.** Steps 6 and 7 of `references/modes/upgrade.md` run the notes tool and the blocks writer, relay
+  their lines and act on their exits: `stamp-absent` returns to step 1, `answer-missing` asks for the named answers
+  and re-runs once, any other refusal stops the upgrade before the stamp.
+- **Notes and docs.** Notes 1.1.0 and 1.2.0 no longer carry block text; they name the writer. The
+  `.claude/settings.json` step of 1.2.0 stays a hand step, taken whenever the Attribution block reads `off`. The
+  migrations README names the notes tool as the only selection. The README and `init --help` no longer say `init` is
+  additive: it never deletes project settings, and in an existing kit home it removes each file in the kit's folders
+  that the package does not carry, one line each.
+- **Reference profile.** `references/reference-profile.json` names the profile `full-flow`: ten items, each keyed to
+  the story that delivers it. `test/upgrade-full-flow.test.mjs` seeds an older kit home and project, upgrades them
+  once with the real tools and checks each landed story's items; S1's three items pass, and every story not yet landed
+  is asserted to show a gap.
+- **Tests.** Suites for the three new modules; `test/package-content.test.mjs` pins 328 packed files and names the
+  four new ones; the legacy-path case and the two symlink cases of `bin/install.test.mjs` seed the kit's `SKILL.md`
+  their existing homes stand for.
+
+**Upgrade criterion.** Nothing to do by hand, unless you keep a file of your own in the kit home's `references/`,
+`tools/`, `migrations/`, `launchers/` or `bridges/` folders: move it out first. The first `init` of 14.5.0 over an
+existing kit home (`~/.claude/skills/agent-workflow-kit/` by default) removes every file in those five folders that
+the package does not carry, one `removed` line each; that is the intended cleanup. A home that an `init` before 1.15.2
+wrote, or one copied by hand from the source tree, also loses the test files and fixtures under `tools/` that the
+package does not ship, and the folders they leave empty are reported as `kept` on every run until you remove them. A
+folder an earlier `init` wrote the kit's `SKILL.md` into counts as a kit home, a project folder included: if you once
+pointed `--dir` at a project, delete the kit's `SKILL.md` there before you run `init` into it again, or the project's
+own files in those five folders are removed. A `--dir` or `AGENT_WORKFLOW_KIT_DIR` that names an
+existing folder which is neither empty nor a kit home is now refused; point it at a new or empty folder instead.
+
 ## 14.4.3 — cleanup after the two splits: one false doc pointer, a test title, a list order, comments and whitespace; nothing the kit decides, prints or records changes
 
 **Six small review findings from the review-state and core-evidence splits are fixed.** The only shipped doc change is in

package/README.md

@@ -196,7 +196,8 @@ other agent). The manual path works identically but **isn't reflected in install
 <details>
 <summary><b>What <code>init</code> touches — and how to undo it</b></summary>
 
-`init` is **additive — it never deletes your settings.** It writes its own namespaced slots, then
+`init` **never deletes your project settings**, and it installs only into a new or empty folder or an existing kit home: any other `--dir` is refused before anything is written. In an existing kit home it removes every file in the kit's
+`references/`, `tools/`, `migrations/`, `launchers/` and `bridges/` folders that the package does not carry, a file you put there included, one reported line per file. It writes its own namespaced slots, then
 refreshes the other npm core members so a returning `init` leaves **no stale core member**:
 
 | Path | What |

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: '14.4.3'
+  version: '14.5.0'
 ---
 
 # agent-workflow-kit

package/bin/install.mjs

@@ -30,13 +30,14 @@
 //
 // Dependency-free, Node >= 22.
 
-import { readFile, mkdir, rm } from 'node:fs/promises';
+import { readFile, mkdir } from 'node:fs/promises';
 import { existsSync, lstatSync, realpathSync } from 'node:fs';
 import { dirname, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { copyTreeRefresh } from '../tools/fs-safe.mjs';
+import { assertInstallableHome, prunePayload } from '../tools/payload-prune.mjs';
 // Dependency-free semver, shared with the family registry's bridge freshness probe (one leaf, no
 // second drifting copy). The null-on-unparseable contract is load-bearing here: legacy installs
 // predate any version stamp, so an unparseable side means "no gate", never a false ordering.
@@ -75,12 +76,6 @@ const PAYLOAD = [
   'bridges',
 ];
 
-// Kit-owned files the package NO LONGER ships (Plan 3D retired the bundled methodology mirror). The
-// refresh copy is additive, so a 1.10.0→1.11.0 upgrade would leave these dead copies behind; remove
-// exactly these known kit paths from the target on install (never user content, never a dir/symlink),
-// so an upgraded install has the same single-source-of-truth shape as a fresh one.
-const RETIRED_PATHS = ['references/planning.md', 'tools/methodology-slot.md'];
-
 // Collapse only a LEADING homedir() to "~" — anchored at the string start (boundary-checked with
 // `sep`), never a mid-path occurrence (Issue-004 parity with the engine/memory installers).
 const tildify = (path) =>
@@ -305,7 +300,8 @@ Installs/refreshes the kit at ~/.claude/skills/agent-workflow-kit
   launcher file (backed up first). The bridges are never PLACED by init (first placement
   stays /agent-workflow-kit setup, opt-in); once placed, init refreshes them from the kit's
   own bundled copies — local files only, never a downgrade — and --no-bridges skips that
-  refresh. init is additive — it never deletes your settings. If the
+  refresh. init never deletes your project settings; in an existing kit home it removes each
+  file in its folders that the package does not carry, one line each. If the
   installed kit is newer than the version you ran, init refuses (no network — it compares
   the version on disk) and points you at @latest; --allow-downgrade overrides that
   refusal (distinct from --force, which is launcher-only).
@@ -373,19 +369,14 @@ const main = async () => {
     process.exit(1);
   }
 
+  assertInstallableHome(target);
   await mkdir(target, { recursive: true });
   for (const entry of PAYLOAD.filter((e) => existsSync(resolve(PKG_ROOT, e)))) {
     copyTreeRefresh(resolve(PKG_ROOT, entry), resolve(target, entry), target);
   }
-  // Remove the retired mirror files an older install may have left (additive refresh never deletes).
-  // Only a regular file at the exact known path is removed — lstat (no-follow) so a dir/symlink is
-  // left untouched, and the path is a hardcoded kit-owned constant (no traversal, never user content).
-  for (const rel of RETIRED_PATHS) {
-    const retired = resolve(target, rel);
-    if (lstatNoFollow(retired)?.isFile()) {
-      await rm(retired, { force: true });
-      console.log(`[agent-workflow-kit] removed retired file ${tildify(retired)} (now read live from the engine).`);
-    }
+  const prune = prunePayload({ packageRoot: PKG_ROOT, home: target, payload: PAYLOAD });
+  for (const line of prune.lines) {
+    console.log(line);
   }
   // Verb keyed on the OBSERVED version relation (cmp), never on mere presence: null (fresh install,
   // or a legacy/unstamped one whose prior version is unknowable) → "installed"; -1 → a real update;
@@ -397,7 +388,11 @@ const main = async () => {
     : cmp === 1 ? 'downgraded the kit to'
     : cmp === -1 ? 'updated the kit to'
     : 'installed';
-  console.log(`[agent-workflow-kit] ${verb} v${version} -> ${tildify(target)}`);
+  if (prune.ok) {
+    console.log(`[agent-workflow-kit] ${verb} v${version} -> ${tildify(target)}`);
+  } else {
+    console.log(prune.nonConvergence);
+  }
 
   // F12 restart hint — any run over a PRE-EXISTING install (every cmp outcome, incl. the legacy
   // unstamped one) leaves an already-open agent session still holding the PREVIOUS kit files in
@@ -545,6 +540,9 @@ const main = async () => {
     console.log('[agent-workflow-kit] methodology engine installed.');
   }
 
+  // The non-convergence line already took the verb's place.
+  if (!prune.ok) process.exit(1);
+
   // This command (de)installed the *kit* globally. Deploying it into a project is a
   // separate, in-agent step — and which sub-command depends on whether that project
   // already has the kit. Spell both out so it's unambiguous (see README "Use").

package/capability.json

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

package/migrations/1.1.0-communication-language.md

@@ -20,21 +20,18 @@ translated either. This migration changes *one* doc block, nothing else.
    this migration is done; skip to Verification.
 3. **Ask the user** which language the agent should converse in (questions, explanations,
    summaries, status). Offer the language they're already writing in as the default.
-4. Insert this block immediately **after the opening blockquote** (before `## 🧭 Memory Map`),
-   replacing `<their language>` with the answer from step 3:
-
-   ```markdown
-   ---
-
-   ## 🗣️ Communication language
-
-   > **Talk to the user in <their language>** — every question, explanation, summary, and status update.
-   > Keep code, identifiers, file paths, shell commands, log output, and abbreviations in their **source language** — translating them breaks copy-paste, search, and tooling.
-   > This sets the **dialogue** language only — it does not translate the files in `docs/ai/` or this entry point, which stay in their source language (for cross-agent / cross-team portability).
-   ```
-
-5. Keep `AGENTS.md` within its ≤100-line budget (the block is ~6 lines; it fits). Do **not**
-   touch any other section, and do **not** translate existing file contents.
+   Reuse an answer already collected by the upgrade's step-6 prompt; never re-ask it.
+4. Preview with `node ${CLAUDE_SKILL_DIR}/tools/migration-blocks.mjs --cwd <project>`; it writes nothing.
+   Then insert from the kit's `references/templates/AGENTS.md` with
+   `node ${CLAUDE_SKILL_DIR}/tools/migration-blocks.mjs --cwd <project> --apply --language <answer>`.
+   If the Attribution block is absent too, collect its answer and pass `--attribution <off|on>`
+   in the same run: both blocks land in one atomic write, only after all answers are collected.
+   Otherwise `answer-missing` on stderr withholds the write; ask only for the answers stdout
+   names and re-run apply once. A second withheld result stops the migration.
+   Any other named refusal on stderr stops the migration; relay it as worded before any stamp update.
+   The upgrade's step 7 runs this same command with the answers its step-6 prompt collected.
+5. The writer refuses with `cap` rather than push `AGENTS.md` past its 100-line budget.
+   Relay that refusal, trim `AGENTS.md`, then re-run the upgrade; do not translate existing contents.
 
 ## Verification
 

package/migrations/1.2.0-agent-attribution.md

@@ -16,30 +16,26 @@ keeps it permanently via PR refs — so the safe default is "no mention anywhere
 ## Steps
 
 1. Open the project's entry point `AGENTS.md` (the real file; `CLAUDE.md` is a symlink to it).
-2. **Idempotency check** — if it already contains a `## ✍️ Attribution` heading, skip to Verification.
-3. **Ask the user**: may the agent attribute work to itself / AI anywhere (commits, PRs, code,
-   comments, docs)? **Default to `off`** unless they opt in.
-4. Insert this block immediately **after the *Communication language* block** (or, if that is
-   absent, after the opening blockquote — before `## 🧭 Memory Map`), replacing `<off|on>` with
-   the answer from step 3:
-
-   ```markdown
-   ---
-
-   ## ✍️ Attribution
-
-   > **Agent attribution: <off|on>** (chosen at setup).
-   > **off** → never attribute work to the agent, AI, or the model: no `Co-Authored-By` trailers, no "Generated with …" footers, no AI/agent/model mentions in code, comments, commit messages, PR titles/bodies, branch names, or docs. Author everything as the human.
-   > **on** → the agent may add its standard `Co-Authored-By` trailer / footer per your tooling defaults.
-   > Claude Code also honours `includeCoAuthoredBy` in `.claude/settings.json`; this block binds every agent for everything written by hand.
-   ```
-
-5. **If the answer is `off` and the project uses Claude Code**, also set the harness flag so the
-   automatic trailer stops (a doc directive cannot stop a harness-added trailer):
+2. **Idempotency check** — if it already contains a `## ✍️ Attribution` heading, skip step 4;
+   step 5 still applies.
+3. **Ask only for a missing block's answer not already collected**: may the agent attribute work
+   to itself / AI anywhere (commits, PRs, code, comments, docs)? **Default to `off`** unless opted in.
+4. Preview with `node ${CLAUDE_SKILL_DIR}/tools/migration-blocks.mjs --cwd <project>`; it writes nothing.
+   Re-run that command with `--apply --attribution <off|on>` to insert from the kit's template.
+   If the Communication language block is absent too, collect its answer and pass `--language <answer>`
+   in the same run: the writer places both blocks in ONE atomic write, or withholds with
+   `answer-missing` and writes nothing if an answer is missing.
+   Upgrade step 7 runs this same command with the answers its step-6 prompt collected; never re-ask them.
+   Relay the writer's lines; a named refusal on stderr stops the migration and is relayed as worded.
+   For `answer-missing`, ask exactly the missing answers and retry `--apply` once; a second withheld run stops.
+5. **Whenever the Attribution block reads `off`**, whether just inserted or already present,
+   keep this hand step outside the writer: for Claude Code, set the harness flag so the automatic
+   trailer stops (a doc directive cannot stop a harness-added trailer):
    - Ensure `.claude/settings.json` exists in the project root; create it as `{}` if absent.
    - Set `"includeCoAuthoredBy": false` (merge into the existing JSON; do not clobber other keys).
    - For other tools, disable their equivalent co-author / footer setting if present.
-6. Keep `AGENTS.md` within its ≤100-line budget (the block is ~7 lines; it fits). Do **not**
+6. The writer refuses with `cap` rather than push `AGENTS.md` past its 100-line budget;
+   trim the entry point and re-run the upgrade. Do **not**
    retroactively rewrite existing git history here — that is a separate, deliberate operation.
 
 ## Verification

package/migrations/README.md

@@ -8,8 +8,13 @@ releases add files/templates, which `upgrade` reconciles without a migration.
 ## How `upgrade` applies them
 
 1. Read the project's stamped version from `docs/ai/.workflow-version`.
-2. Select every migration whose `<version>` is **strictly newer** than the stamp.
-3. Apply them in **ascending semver order**.
+2. Run `node ${CLAUDE_SKILL_DIR}/tools/migration-notes.mjs --cwd <project>` as the sole selector.
+   It lists every migration whose `<version>` is **strictly newer** than the stamp and not newer than the head.
+   Each line is `note <version> <path> :: <headline>`, with an absolute `<path>` under the running kit.
+   The headline is the note's first `# ` line, with that prefix removed and surrounding whitespace trimmed.
+   The upgrade must relay those stdout lines verbatim and apply exactly the listed notes.
+   A named refusal stops the upgrade, except `stamp-absent`, which routes it back to the upgrade's step 1.
+3. Apply them in the order the tool listed them (**ascending semver order**).
 4. Re-stamp `docs/ai/.workflow-version` to the **deployment-lineage head** (`3.0.0` today — the
    shared lineage, **not** this skill's npm package version). A stamp greater than the head → STOP.
 
@@ -19,6 +24,7 @@ releases add files/templates, which `upgrade` reconciles without a migration.
 - **Non-destructive** — never clobber project-authored content (their `decisions.md`, `known_issues.md`, page specs). Add/rename/restructure only what the kernel owns.
 - **Self-contained** — exact paths + commands, readable cold, like a mini-plan.
 - **Mention rollback** — note how to undo if the step is risky.
+- **Template blocks** — a note never pastes entry-point block text; `tools/migration-blocks.mjs` places it from the kit's template.
 
 ## Template
 

package/package.json

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

@@ -99,6 +99,6 @@ Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md · ${CLAUDE_SKI
    - **Print the report footer** in the canonical order (version block → one-line backend-status line → welcome mat — the shared contracts in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`; rendered from the helpers, same host-can't-run skip-with-reason). The welcome mat closes on **one** caveat-aware next step (a behind member first, else `setup` / `recipes` / `velocity` / `agents` / `hook`).
    - **Then ask before committing — never auto-commit.** If step 3 added the slot (or anything else changed), report it and ask. If step 3 was a pure zero-diff no-op and nothing else changed, give the plain **settings already current — no update needed** message (the *Success state* contract in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`) and still print the read-only version block (installed package versions) + backend line — but **no `docs/ai` structure version and no two-axes note** (nothing changed, so the number is inert here).
 5. Show the relevant `${CLAUDE_SKILL_DIR}/CHANGELOG.md` diff (entries newer than the project's stamp).
-6. **Collect the migration answers FIRST, then apply.** If `AGENTS.md` is missing BOTH the *Communication language* and *Attribution* blocks — i.e. both blocks are missing (a pre-1.1.0 deployment) — ask the two questions as ONE structured multi-question prompt; record each answer individually, write nothing until ALL are answered, and carry the answers into the migrations below: a migration whose answer was already collected never re-asks (its own "Ask the user" step is the standalone fallback); a single missing block keeps its single ask (step 7). Then apply `${CLAUDE_SKILL_DIR}/migrations/<version>-<slug>.md` in **semver order**, only those newer than the project's stamp. Migrations are **idempotent** — safe to re-run.
-7. Reconcile drift: add any kernel files/scripts the project is missing; never clobber project-authored content (their `decisions.md`, `known_issues.md`, page specs stay). Any user question a migration raises follows the same rule as bootstrap — **structured multiple-choice where supported** (`AskUserQuestion` in Claude Code), otherwise prose. If `AGENTS.md` has no *Communication language* block (pre-1.1.0 deployment), **ask the user their conversational language** and insert the block — see `migrations/1.1.0-communication-language.md`. If it has no *Attribution* block (pre-1.2.0 deployment), **ask whether the agent may attribute work to itself / AI** and insert the block (defaulting to `off`) — see `migrations/1.2.0-agent-attribution.md`. (An answer already collected by the step-6 batched prompt is carried in — never re-asked here.) **Then, before the stamp, re-run the LATE navigator finalizer:** the migrations of steps 6–7 may have added or changed `docs/ai` files, so run the one op again — `node ${CLAUDE_SKILL_DIR}/tools/ensure-configs.mjs --reconcile --only index --cwd <project>` — and relay THAT line in the step-8 report (idempotent: an untouched tree reports `already-current`; a failure STOPs this upgrade like any other ensure).
+6. **Collect the migration answers FIRST, then apply.** Run `node ${CLAUDE_SKILL_DIR}/tools/migration-notes.mjs --cwd <project>` and relay its stdout lines verbatim, in order; a non-zero exit relays its one named line and STOPs, except `stamp-absent`, which routes back to step 1. Then run the preview `node ${CLAUDE_SKILL_DIR}/tools/migration-blocks.mjs --cwd <project>`. If its lines say both blocks are missing (pre-1.1.0), ask the two questions as ONE structured multi-question prompt; record each answer individually, write nothing until ALL are answered, and carry the answers into the migrations below: a migration whose answer was already collected never re-asks; a single missing block keeps its single ask (step 7). Then apply exactly the notes the tool listed, in its order ("only those newer than the project's stamp" is why, never a second selection). Migrations are **idempotent** — safe to re-run.
+7. Reconcile drift: add any kernel files/scripts the project is missing; never clobber project-authored content (their `decisions.md`, `known_issues.md`, page specs stay). Any user question a migration raises follows the same rule as bootstrap — **structured multiple-choice where supported** (`AskUserQuestion` in Claude Code), otherwise prose. For a block the preview names as needing its answer, **ask the user their conversational language** (`--language`) or **whether the agent may attribute work to itself / AI** (`--attribution`, defaulting to `off`), never re-asking a step-6 answer; then re-run the preview with `--apply` and the answers, relaying its lines. Exit 1 `answer-missing`: ask exactly what its lines name and re-run `--apply` once; a second one STOPs. Any other exit 1 is a named refusal: relay it with its recovery (`cap`: trim `AGENTS.md`, re-run) and STOP before the finalizer and the stamp. **Then, before the stamp, re-run the LATE navigator finalizer:** the migrations of steps 6–7 may have changed `docs/ai` files, so run the one op again — `node ${CLAUDE_SKILL_DIR}/tools/ensure-configs.mjs --reconcile --only index --cwd <project>` — and relay THAT line in the step-8 report (idempotent: an untouched tree reports `already-current`; a failure STOPs this upgrade like any other ensure).
 8. Re-stamp `docs/ai/.workflow-version` to the **deployment-lineage head** (`3.0.0`, not the package version — mechanics unchanged: the atomic write to the stamp file). In the report, **describe what the upgrade changed in plain human terms** — which parts of their `docs/ai` are now different (the migrations that ran), plus the step-3 run-list outcomes, each as step 4 words it: the `pointers` slots, the `footprint` visibility verdict (and what a consented re-run migrated), the **eight project-configuration ensure** (`configs`) lines (enumerated in step 3) — the navigator one being the late `--only index` run at the end of step 7, the **`gates-migration`** result, the **placed-bridge refresh** (`bridges`) lines (pasted verbatim), the **agent-rules lens** (`lens`) + **Communication-section** outcomes (same outcome sets as step 4), and the **bridge-settings reconcile** (`bridge-settings`) outcome (line(s) pasted verbatim) — rather than reciting a version number; **omit the raw structure number**, and do **not** print the two-axes note here (it belongs to *Version disclosure* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`, on demand only). Then **render the mandatory Recommendations section**: run `node ${CLAUDE_SKILL_DIR}/tools/recommendations.mjs --cwd <project-root>` and PRESENT its output — from the `## Recommendations (agent-workflow)` header — in the user's conversational language (every fact, count and item, nothing added or dropped; commands, paths, hosts and rule strings byte-exact; raw tool block on request; present-even-when-empty: `no recommendations — flow optimal.`), then OFFER the consent-gated applies (per picked item: posture note → explicit confirm → run EXACTLY the rendered one-liner; a HAND-APPLY item is never run by you — `${CLAUDE_SKILL_DIR}/references/modes/recommendations.md`). **Every current host/session claim in this report is tool-composed only** — prompts fired, sandbox scope, whether a bypass was needed, network reachability and approval counts must trace to **live tool output** from **this session**, a memory/handover snapshot is **context, never report facts**, and an unbacked claim is **omitted or explicitly marked unverified** (full clause: *Live host/session facts* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`). Then **print the report footer** in the canonical order (version block → one-line backend-status line → welcome mat — the shared contracts in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`; rendered from the helpers, same host-can't-run skip-with-reason; the welcome mat closes on one caveat-aware next step). Then **ask before committing** — the pinned order on this exit is: Recommendations block → optional applies → report footer → the commit ask.

package/references/reference-profile.json

@@ -0,0 +1,37 @@
+{
+  "schema": 1,
+  "name": "full-flow",
+  "lineage": "4.0.0",
+  "items": [
+    { "id": "migration-notes-delivered",
+      "story": "S1",
+      "has": "An upgrade tells you every migration note your project's version selects, by path and headline." },
+    { "id": "migration-blocks-placed",
+      "story": "S1",
+      "has": "The entry point carries the communication-language and attribution blocks, placed from your answers." },
+    { "id": "payload-converged",
+      "story": "S1",
+      "has": "The installed kit holds no file the package stopped shipping." },
+    { "id": "story-sessions-section",
+      "story": "S2",
+      "has": "The project's rules carry the story-sessions section." },
+    { "id": "epic-task-slots",
+      "story": "S3",
+      "has": "The orchestration settings carry the epic and task slots, each resolved to your environment or to solo with the reason." },
+    { "id": "epic-store-seeded",
+      "story": "S3",
+      "has": "The epic store is seeded." },
+    { "id": "checker-gates-declared",
+      "story": "S4",
+      "has": "The kit-owned checker gates are declared." },
+    { "id": "session-close-rules",
+      "story": "S5",
+      "has": "The rules your project reads state the session-close value section and one task per session." },
+    { "id": "named-queue-row-seed",
+      "story": "S5",
+      "has": "A new work queue is seeded with the named row." },
+    { "id": "profile-gap-screen",
+      "story": "S6",
+      "has": "The Recommendations screen names every difference from this profile you have not declined, with the command for each." }
+  ]
+}

package/tools/migration-blocks.mjs

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+import { lstatSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { AGENTS_MD_CAP } from './inject-methodology.mjs';
+import { writeContainedFileAtomic } from './atomic-write.mjs';
+import { isDirectRun } from './direct-run.mjs';
+
+const LF = String.fromCharCode(10);
+const CRLF = String.fromCharCode(13) + LF;
+const ANCHOR = '## 🧭 Memory Map';
+const TEMPLATE_PATH = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'references', 'templates', 'AGENTS.md');
+const REINSTALL = 'npx @sabaiway/agent-workflow-kit@latest init';
+const BLOCKS = [
+  { name: 'communication', heading: '## 🗣️ Communication language', flag: 'language', placeholder: '{{COMM_LANGUAGE}}' },
+  { name: 'attribution', heading: '## ✍️ Attribution', flag: 'attribution', placeholder: '{{AGENT_ATTRIBUTION}}' },
+];
+const FLAGS = ['--cwd', '--language', '--attribution', '--apply'];
+const USAGE = 'usage: migration-blocks.mjs --cwd <project> [--language <text>] [--attribution on|off] [--apply]';
+const CONTROL_BYTES = /[\x00-\x1f\x7f\u2028\u2029]/u;
+
+const makeResult = (code, stdout = '', stderr = '') => ({ code, stdout, stderr });
+const renderDetail = (detail) => String(detail).replace(/[\r\n\u2028\u2029]+/gu, ' ');
+const refuse = (name, detail) => makeResult(1, '', detail ? `${name}: ${renderDetail(detail)}` : name);
+const countLines = (text) => text.split(LF).length - Number(text.endsWith(LF));
+const findHeadings = (lines, heading) => lines.flatMap((line, index) => line.trimEnd() === heading ? [index] : []);
+
+const parseArgs = (argv) => {
+  const parsed = argv.reduce((state, argument) => {
+    if (state.pending) {
+      if (argument.startsWith('--')) throw new Error(`${state.pending} needs a value`);
+      return { options: { ...state.options, [state.pending.slice(2)]: argument }, pending: null };
+    }
+    if (!FLAGS.includes(argument)) throw new Error(`unknown argument ${argument}`);
+    const key = argument.slice(2);
+    if (Object.hasOwn(state.options, key)) throw new Error(`${argument} repeated`);
+    if (argument === '--apply') return { options: { ...state.options, apply: true }, pending: null };
+    return { options: state.options, pending: argument };
+  }, { options: {}, pending: null });
+  if (parsed.pending) throw new Error(`${parsed.pending} needs a value`);
+  if (!parsed.options.cwd) throw new Error('--cwd is required');
+  return parsed.options;
+};
+
+const checkAnswers = ({ language, attribution }) => {
+  if (language !== undefined && (!language.trim() || CONTROL_BYTES.test(language))) {
+    return refuse('language', 'provide one nonempty line without control bytes');
+  }
+  if (attribution !== undefined && !['on', 'off'].includes(attribution)) {
+    return refuse('attribution', 'expected on or off');
+  }
+  return null;
+};
+
+const extractSpans = (template) => {
+  const lines = template.split(CRLF).join(LF).split(LF);
+  return BLOCKS.map((block) => {
+    const headings = findHeadings(lines, block.heading);
+    if (headings.length !== 1) throw new Error(`${block.name} heading must occur once`);
+    const start = headings[0];
+    const next = lines.findIndex((line, index) => index > start && line.startsWith('## '));
+    const span = next < 0 ? lines.slice(start).join(LF) : lines.slice(start, next).join(LF) + LF;
+    if (span.split(block.placeholder).length !== 2) {
+      throw new Error(`${block.name} placeholder must occur once in its span`);
+    }
+    return { ...block, span };
+  });
+};
+
+const readTemplate = (path, deps) => {
+  try {
+    const read = deps.readFileSync ?? readFileSync;
+    return { spans: extractSpans(read(path, 'utf8')) };
+  } catch (error) {
+    return { error: refuse('template', `${error.message}; run ${REINSTALL}`) };
+  }
+};
+
+const readDocument = (path, deps) => {
+  const probe = deps.lstatSync ?? lstatSync;
+  const read = deps.readFileSync ?? readFileSync;
+  const status = (() => {
+    try {
+      return { stat: probe(path) };
+    } catch (error) {
+      const name = error.code === 'ENOENT' ? 'file-absent' : 'file-unreadable';
+      return { error: refuse(name, error.message) };
+    }
+  })();
+  if (status.error) return status;
+  if (status.stat.isSymbolicLink()) return { error: refuse('file-symlink', path) };
+  if (!status.stat.isFile()) return { error: refuse('file-unreadable', `${path} is not a regular file`) };
+  try {
+    return { text: read(path, 'utf8') };
+  } catch (error) {
+    return { error: refuse('file-unreadable', error.message) };
+  }
+};
+
+const classifyBlock = (block, lines, answers, newline) => {
+  const headings = findHeadings(lines, block.heading);
+  const answer = answers[block.flag];
+  if (headings.length > 1) return { error: refuse('heading-twice', block.name) };
+  if (headings.length === 1) {
+    return { ...block, state: 'present', index: headings[0], ignored: answer !== undefined };
+  }
+  if (answer === undefined) return { ...block, state: 'needs' };
+  const body = block.span.split(block.placeholder).join(answer).split(LF).join(newline);
+  return { ...block, state: 'planned', body };
+};
+
+const renderBlock = (block, applied) => {
+  if (block.state === 'present') return `${block.name}: present${block.ignored ? '; answer ignored' : ''}`;
+  if (block.state === 'needs') return `${block.name}: needs --${block.flag}`;
+  return `${block.name}: ${applied ? 'inserted' : 'planned'}`;
+};
+
+const insertBlocks = (text, lines, blocks) => {
+  const planned = blocks.filter((block) => block.state === 'planned');
+  if (planned.length === 0) return { body: text };
+  const anchors = lines.flatMap((line, index) => line.replace(/\r$/u, '') === ANCHOR ? [index] : []);
+  if (anchors.length === 0) return { error: refuse('anchor-absent', ANCHOR) };
+  if (anchors.length !== 1) return { error: refuse('anchor-repeated', ANCHOR) };
+  const total = countLines(text) + planned.reduce((count, block) => count + countLines(block.body), 0);
+  if (total > AGENTS_MD_CAP) {
+    return { error: refuse('cap', `${total} lines exceed ${AGENTS_MD_CAP}; trim AGENTS.md and re-run`) };
+  }
+  const anchor = anchors[0];
+  const attribution = blocks.find((block) => block.name === 'attribution');
+  const insertions = planned.map((block) => ({
+    ...block,
+    index: block.name === 'communication' && attribution.state === 'present' && attribution.index < anchor
+      ? attribution.index : anchor,
+  }));
+  const body = lines.map((line, index) => {
+    const prefix = insertions.filter((block) => block.index === index).map((block) => block.body).join('');
+    return prefix + line;
+  }).join(LF);
+  return { body };
+};
+
+export const planBlocks = ({ text, spans, language, attribution, apply = false }) => {
+  const lines = text.split(LF);
+  const newline = text.includes(CRLF) ? CRLF : LF;
+  const blocks = spans.map((block) => classifyBlock(block, lines, { language, attribution }, newline));
+  const refused = blocks.find((block) => block.error);
+  if (refused) return { result: refused.error, write: false };
+  const insertion = insertBlocks(text, lines, blocks);
+  if (insertion.error) return { result: insertion.error, write: false };
+  const missing = blocks.some((block) => block.state === 'needs');
+  const write = apply && !missing && blocks.some((block) => block.state === 'planned');
+  const stdout = blocks.map((block) => renderBlock(block, write)).join(LF);
+  const result = apply && missing ? makeResult(1, stdout, 'answer-missing') : makeResult(0, stdout);
+  return { result, write, body: insertion.body };
+};
+
+const runBlocks = (options, deps) => {
+  const invalid = checkAnswers(options);
+  if (invalid) return invalid;
+  const template = readTemplate(deps.templatePath ?? TEMPLATE_PATH, deps);
+  if (template.error) return template.error;
+  const root = resolve(options.cwd);
+  const destination = resolve(root, 'AGENTS.md');
+  const document = readDocument(destination, deps);
+  if (document.error) return document.error;
+  const plan = planBlocks({ ...options, text: document.text, spans: template.spans });
+  if (plan.write) {
+    try {
+      writeContainedFileAtomic(root, destination, plan.body, {
+        writeFile: deps.writeFile,
+        rename: deps.rename,
+        rm: deps.rm,
+      });
+    } catch (error) {
+      return refuse('write-failed', error.message);
+    }
+  }
+  return plan.result;
+};
+
+export const main = (argv, deps = {}) => {
+  const parsed = (() => {
+    try {
+      return { options: parseArgs(argv) };
+    } catch (error) {
+      return { error: makeResult(2, '', `${USAGE}; ${renderDetail(error.message)}`) };
+    }
+  })();
+  return parsed.error ?? runBlocks(parsed.options, deps);
+};
+
+if (isDirectRun(import.meta.url)) {
+  const result = await main(process.argv.slice(2));
+  if (result.stdout) console.log(result.stdout);
+  if (result.stderr) console.error(result.stderr);
+  process.exit(result.code);
+}

package/tools/migration-notes.mjs

@@ -0,0 +1,218 @@
+import { lstatSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { EXPECTED_WORKFLOW_VERSION } from './cheap-agents-read.mjs';
+import { isDirectRun } from './direct-run.mjs';
+
+const NOTES_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'migrations');
+const STAMP_PATH = 'docs/ai/.workflow-version';
+const VERSION_PATTERN = /^[0-9]+[.][0-9]+[.][0-9]+$/u;
+const SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const CONTROL_PATTERN = /[\p{Cc}\p{Zl}\p{Zp}]/gu;
+const NOTE_SUFFIX = '.md';
+const README_NAME = 'README.md';
+const HEADLINE_PREFIX = '# ';
+const LF = String.fromCharCode(10);
+const CR = String.fromCharCode(13);
+const EXIT_ACCEPTED = 0;
+const EXIT_REFUSED = 1;
+const EXIT_USAGE = 2;
+
+const formatDetail = (value) => String(value).replace(CONTROL_PATTERN, ' ');
+const makeRefusal = (name, detail) => ({
+  code: EXIT_REFUSED,
+  stdout: '',
+  stderr: `${name}: ${formatDetail(detail)}`,
+});
+const matchesEntire = (text, pattern) => text.match(pattern)?.[0] === text;
+const parseVersion = (version) => version.split('.').map((field) => BigInt(field));
+const compareVersions = (left, right) => {
+  const rightFields = parseVersion(right);
+  for (const [index, field] of parseVersion(left).entries()) {
+    if (field < rightFields[index]) {
+      return -1;
+    }
+    if (field > rightFields[index]) {
+      return 1;
+    }
+  }
+  return 0;
+};
+
+const judgeStamp = (stamp, head) => {
+  if (!matchesEntire(stamp, VERSION_PATTERN)) {
+    return makeRefusal('stamp-unparseable', 'expected one major.minor.patch version');
+  }
+  if (compareVersions(stamp, head) > 0) {
+    return makeRefusal('stamp-above-head', `${stamp} is newer than ${head}; never downgrade`);
+  }
+  return null;
+};
+
+const shouldIgnore = (name) => name.startsWith('.') || !name.endsWith(NOTE_SUFFIX);
+const parseNote = (entry) => {
+  const stem = entry.name.slice(0, -NOTE_SUFFIX.length);
+  const separator = stem.indexOf('-');
+  const version = stem.slice(0, separator);
+  const slug = stem.slice(separator + 1);
+  const valid = separator > 0 && matchesEntire(version, VERSION_PATTERN) && matchesEntire(slug, SLUG_PATTERN);
+  return { ...entry, version, valid };
+};
+
+const readHeadline = (text) => {
+  const line = text.split(LF).find((candidate) => candidate.startsWith(HEADLINE_PREFIX));
+  if (line === undefined) {
+    return null;
+  }
+  const content = (line.endsWith(CR) ? line.slice(0, -CR.length) : line).slice(HEADLINE_PREFIX.length);
+  return content.search(CONTROL_PATTERN) < 0 && content.trim() !== '' ? content.trim() : null;
+};
+
+const findDuplicate = (notes) => {
+  const versions = new Set();
+  for (const note of notes) {
+    const key = parseVersion(note.version).join('.');
+    if (versions.has(key)) {
+      return note;
+    }
+    versions.add(key);
+  }
+  return null;
+};
+
+// The caller has trimmed and judged the stamp; main judges every stamp cell before reading the notes directory.
+export const selectNotes = (stamp, entries, head) => {
+  const candidates = entries.filter(({ name }) => !shouldIgnore(name));
+  const unreadable = candidates.find(({ kind }) => kind === 'unreadable');
+  if (unreadable) {
+    return makeRefusal('notes-unreadable', `${unreadable.name}: ${unreadable.detail}`);
+  }
+  const parsed = candidates.map(parseNote);
+  const invalid = parsed.find(({ kind, name, valid }) => kind !== 'file' || (name !== README_NAME && !valid));
+  if (invalid) {
+    return makeRefusal('notes-entry', invalid.name);
+  }
+  const notes = parsed.filter(({ name }) => name !== README_NAME);
+  const aboveHead = notes.find(({ version }) => compareVersions(version, head) > 0);
+  if (aboveHead) {
+    return makeRefusal('note-above-head', `${aboveHead.name} is newer than ${head}`);
+  }
+  const duplicate = findDuplicate(notes);
+  if (duplicate) {
+    return makeRefusal('note-version-twice', duplicate.version);
+  }
+  const titled = notes.map((note) => ({ ...note, headline: readHeadline(note.text) }));
+  const untitled = titled.find(({ headline }) => headline === null);
+  if (untitled) {
+    return makeRefusal('note-headline', untitled.name);
+  }
+  const selected = titled
+    .filter(({ version }) => compareVersions(version, stamp) > 0 && compareVersions(version, head) <= 0)
+    .sort((left, right) => compareVersions(left.version, right.version));
+  const none = compareVersions(stamp, head) === 0
+    ? `none: stamp ${stamp} equals head ${head}; no note applies`
+    : `none: no notes newer than stamp ${stamp} through head ${head}`;
+  const lines = selected.map(({ version, path, headline }) => `note ${version} ${path} :: ${headline}`);
+  const ignored = entries.filter(({ name }) => shouldIgnore(name)).map(({ name }) => `ignored: ${formatDetail(name)}`);
+  return {
+    code: EXIT_ACCEPTED,
+    stdout: lines.length > 0 ? lines.join(LF) : none,
+    stderr: ignored.join(LF),
+  };
+};
+
+const probePath = (path, fs) => {
+  try {
+    const stat = fs.lstatSync(path);
+    if (stat.isSymbolicLink()) {
+      return { kind: 'symlink' };
+    }
+    if (stat.isFile()) {
+      return { kind: 'file' };
+    }
+    return { kind: stat.isDirectory() ? 'directory' : 'other' };
+  } catch (error) {
+    return { kind: error.code === 'ENOENT' ? 'absent' : 'unreadable', detail: error.message };
+  }
+};
+
+const readStamp = (path, fs) => {
+  const probe = probePath(path, fs);
+  if (probe.kind === 'absent') {
+    return { refusal: makeRefusal('stamp-absent', `${path}; use step 1 conservative re-bootstrap`) };
+  }
+  if (probe.kind !== 'file') {
+    return { refusal: makeRefusal('stamp-unreadable', `${path}: ${probe.detail ?? probe.kind}`) };
+  }
+  try {
+    return { text: fs.readFileSync(path, 'utf8') };
+  } catch (error) {
+    return { refusal: makeRefusal('stamp-unreadable', `${path}: ${error.message}`) };
+  }
+};
+
+const readEntry = (notesDir, name, fs) => {
+  const path = join(notesDir, name);
+  if (shouldIgnore(name)) {
+    return { name, path };
+  }
+  const probe = probePath(path, fs);
+  if (probe.kind !== 'file' || name === README_NAME) {
+    return { name, path, ...probe };
+  }
+  try {
+    return { name, path, kind: 'file', text: fs.readFileSync(path, 'utf8') };
+  } catch (error) {
+    return { name, path, kind: 'unreadable', detail: error.message };
+  }
+};
+
+const readNotes = (notesDir, fs) => {
+  const probe = probePath(notesDir, fs);
+  if (probe.kind === 'absent') {
+    return { refusal: makeRefusal('notes-absent', notesDir) };
+  }
+  if (probe.kind !== 'directory') {
+    return { refusal: makeRefusal('notes-unreadable', `${notesDir}: ${probe.detail ?? probe.kind}`) };
+  }
+  try {
+    return { entries: fs.readdirSync(notesDir).map((name) => readEntry(notesDir, name, fs)) };
+  } catch (error) {
+    return { refusal: makeRefusal('notes-unreadable', `${notesDir}: ${error.message}`) };
+  }
+};
+
+export const main = (argv, deps = {}) => {
+  const validUsage = argv.length === 2 && argv[0] === '--cwd'
+    && typeof argv[1] === 'string' && argv[1].trim() !== '' && !argv[1].startsWith('--');
+  if (!validUsage) {
+    return { code: EXIT_USAGE, stdout: '', stderr: 'usage: migration-notes.mjs --cwd <project>' };
+  }
+  const fs = {
+    lstatSync: deps.lstatSync ?? lstatSync,
+    readFileSync: deps.readFileSync ?? readFileSync,
+    readdirSync: deps.readdirSync ?? readdirSync,
+  };
+  const stamp = readStamp(resolve(argv[1], STAMP_PATH), fs);
+  if (stamp.refusal) {
+    return stamp.refusal;
+  }
+  const stampText = stamp.text.trim();
+  const stampRefusal = judgeStamp(stampText, EXPECTED_WORKFLOW_VERSION);
+  if (stampRefusal) {
+    return stampRefusal;
+  }
+  const notes = readNotes(resolve(deps.notesDir ?? NOTES_DIR), fs);
+  return notes.refusal ?? selectNotes(stampText, notes.entries, EXPECTED_WORKFLOW_VERSION);
+};
+
+if (isDirectRun(import.meta.url)) {
+  const result = await main(process.argv.slice(2));
+  if (result.stdout) {
+    console.log(result.stdout);
+  }
+  if (result.stderr) {
+    console.error(result.stderr);
+  }
+  process.exit(result.code);
+}

package/tools/payload-prune.mjs

@@ -0,0 +1,173 @@
+import { lstatSync, readdirSync, readFileSync, unlinkSync } from 'node:fs';
+import { resolve, sep } from 'node:path';
+import { assertContainedRealPath } from './fs-safe.mjs';
+import { lstatNoFollowRead } from './fs-read-nofollow.mjs';
+
+const PREFIX = '[agent-workflow-kit]';
+const NON_CONVERGENCE = `${PREFIX} the kit home did not converge to the package (see the lines above) `
+  + '— fix them, then re-run npx @sabaiway/agent-workflow-kit@latest init';
+
+export const readHomeOwner = (home) => {
+  try {
+    const stat = lstatSync(home, { throwIfNoEntry: false });
+    if (stat === undefined) {
+      return 'absent';
+    }
+    if (!stat.isDirectory()) {
+      return 'other';
+    }
+    if (readdirSync(home).length === 0) {
+      return 'empty';
+    }
+    const skill = resolve(home, 'SKILL.md');
+    if (!lstatSync(skill).isFile()) {
+      return 'other';
+    }
+    const lines = readFileSync(skill, 'utf8').split('\n').map((line) => line.replace(/\r$/, ''));
+    if (lines[0] !== '---') {
+      return 'other';
+    }
+    const end = lines.findIndex((line, index) => index > 0 && line === '---');
+    if (end < 0) {
+      return 'other';
+    }
+    return lines.slice(1, end).some((line) => line.trimEnd() === 'name: agent-workflow-kit') ? 'kit' : 'other';
+  } catch {
+    return 'other';
+  }
+};
+
+export const assertInstallableHome = (home) => {
+  const owner = readHomeOwner(home);
+  if (owner === 'other') {
+    throw new Error(
+      `${PREFIX} refusing to install into ${home}: it is not empty and holds no agent-workflow-kit SKILL.md; `
+      + 'choose a new or empty folder, or an existing kit home',
+    );
+  }
+  return owner;
+};
+
+const describeKind = (stat) => {
+  if (stat.isSymbolicLink()) {
+    return 'symlink';
+  }
+  if (stat.isDirectory()) {
+    return 'directory';
+  }
+  return stat.isFile() ? 'file' : 'non-regular object';
+};
+
+const reportFailure = (path, error) => ({
+  ok: false,
+  line: `${PREFIX} failed ${path}: ${error.message}`,
+});
+
+const finishReport = (reports) => {
+  const ok = reports.every((report) => report.ok);
+  return {
+    ok,
+    lines: reports.map((report) => report.line),
+    nonConvergence: ok ? null : NON_CONVERGENCE,
+  };
+};
+
+const readTree = (root, entry, reports, directoryOnly = false) => {
+  const entries = new Map();
+  const visitEntry = (path, first = false) => {
+    try {
+      const absolute = resolve(root, path);
+      const stat = lstatSync(absolute, { throwIfNoEntry: !first });
+      if (!stat || (first && directoryOnly && !stat.isDirectory())) {
+        return;
+      }
+      const kind = describeKind(stat);
+      entries.set(path, kind);
+      if (kind === 'directory') {
+        for (const name of readdirSync(absolute).sort()) {
+          visitEntry(`${path}/${name}`);
+        }
+      }
+    } catch (error) {
+      reports.push(reportFailure(path, error));
+    }
+  };
+  try {
+    const stat = lstatSync(root, { throwIfNoEntry: false });
+    if (!stat) {
+      return entries;
+    }
+    if (!stat.isDirectory()) {
+      throw new Error(`the root is a ${describeKind(stat)}, not a real directory`);
+    }
+    visitEntry(entry, true);
+  } catch (error) {
+    reports.push(reportFailure(entry, error));
+  }
+  return entries;
+};
+
+const planSubtree = (carried, installed, orphans, reports) => {
+  for (const [path, kind] of installed) {
+    if (carried.has(path)) {
+      const packageKind = carried.get(path);
+      if (kind !== packageKind) {
+        reports.push({
+          ok: false,
+          line: `${PREFIX} kind-mismatch ${path}: the home holds a ${kind}, the package a ${packageKind}`,
+        });
+      }
+    } else if (kind === 'file') {
+      orphans.push(path);
+    } else {
+      reports.push({
+        ok: true,
+        line: `${PREFIX} kept ${path} (a ${kind} the package does not carry — yours to remove by hand)`,
+      });
+    }
+  }
+};
+
+const removeOrphan = (home, path, remove) => {
+  const absolute = resolve(home, path);
+  try {
+    remove.assertContainedRealPath(home, absolute);
+    const stat = remove.lstatNoFollowRead(absolute);
+    if (stat === null) {
+      return [];
+    }
+    if (!stat.isFile()) {
+      throw new Error('the leaf is no longer a regular file');
+    }
+    remove.unlinkSync(absolute);
+    return [{ ok: true, line: `${PREFIX} removed ${path} (not in the package)` }];
+  } catch (error) {
+    return [reportFailure(path, error)];
+  }
+};
+
+export const prunePayload = ({ packageRoot, home, payload }, deps = {}) => {
+  const reports = [];
+  const orphans = [];
+  for (const entry of new Set(payload)) {
+    const path = entry.split(sep).join('/');
+    const carried = readTree(packageRoot, path, reports, true);
+    if (![...carried.values()].includes('file')) {
+      continue;
+    }
+    const installed = readTree(home, path, reports);
+    planSubtree(carried, installed, orphans, reports);
+  }
+  if (reports.some((report) => !report.ok)) {
+    return finishReport(reports);
+  }
+  const remove = {
+    assertContainedRealPath: deps.assertContainedRealPath ?? assertContainedRealPath,
+    lstatNoFollowRead: deps.lstatNoFollowRead ?? lstatNoFollowRead,
+    unlinkSync: deps.unlinkSync ?? unlinkSync,
+  };
+  for (const path of orphans) {
+    reports.push(...removeOrphan(home, path, remove));
+  }
+  return finishReport(reports);
+};