@sabaiway/agent-workflow-kit 1.10.0 → 1.12.0

package/CHANGELOG.md

@@ -4,6 +4,74 @@ 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.
 
+## 1.12.0 — See the whole family, and uninstall it cleanly
+
+Two new in-agent modes, built on a single **unified family registry**. `/agent-workflow-kit status`
+shows — read-only — which family members (kit / memory / engine / the two bridges) are installed, at
+what version, and (in a project) what is deployed (`docs/ai`, the version stamps, the hidden-mode
+fence). `/agent-workflow-kit uninstall` is the **guarded teardown**: it reverses what `init` and
+`setup` placed — installed skill dirs + bridge wrappers, and in a project the hidden-mode fence + the
+marker pre-commit hook — but it **never deletes user-authored content** (`docs/ai`, `AGENTS.md`, your
+`.claude/settings.json`); for those it prints the exact commands and lets you run them. It removes only
+what is **provably ours** (a valid manifest, name + kind match; a wrapper symlink that points at our
+source) — anything else is left untouched — and it **previews with `--dry-run` and preflights before
+it touches anything**, so a conflict makes zero changes. The deployment-lineage head stays **`1.3.0`**
+(no `docs/ai` structural change; no migration file). See **AD-017**.
+
+### Added
+- `tools/family-registry.mjs` — the unified, kit-owned registry over every family member (the
+  `KNOWN_BACKENDS` precedent, generalized to all five). Resolves each member's `detect.installed`,
+  manifest health, and installed version; powers `/agent-workflow-kit status`. A drift-guard test pins
+  it to the five in-repo `capability.json` files.
+- `tools/uninstall.mjs` — the guarded uninstaller behind `/agent-workflow-kit uninstall`: a pure
+  classifier (`buildPlan`) + a preflight-then-mutate executor (`executePlan`). Four surface classes —
+  safe-remove (provably-ours skill dirs), managed-marker (wrapper symlinks / the hidden-mode fence /
+  the marker hook), report-only (never-deleted user content), and stop (present-but-not-ours).
+- `tools/fs-safe.mjs` gains `removeTreeManaged` + `unlinkManaged` — the symlink-safe inverses of
+  `copyTreeRefresh` / `linkManaged` (refuse to delete through a symlink or outside the root; remove
+  only a symlink whose target is ours).
+
+### Changed
+- `tools/manifest/validate.mjs` exports `readAuthoritativeVersion` so the registry reports an installed
+  member's version from the same authoritative source the validator checks.
+- The kit's own `capability.json` now declares `uninstall.removeResolved` (uniform with memory +
+  engine); the guarded uninstaller's behavior matches it — it removes exactly the resolved
+  `detect.installed` dir, so the long-declared teardown is now realized, not just documented.
+
+The bounded methodology fragment the kit writes into a project's `AGENTS.md` is now read **live from
+the installed `@sabaiway/agent-workflow-engine`** — the family's single source of truth. The kit's old
+bundled mirror of that text (and its drift-guard) is **retired**: there is exactly one copy now, in the
+engine. `npx @sabaiway/agent-workflow-kit@latest init` installs the engine as a **core** part of the
+kit (it is core methodology, not an optional backend — deliberately diverging from AD-011 §5), so the
+slot can always be filled. The read is **lazy + fail-loud**: the engine is consulted only when a slot
+actually needs filling — a deployment whose slot is already filled upgrades to a **zero-diff no-op even
+without the engine** — and when a fill *is* needed but the engine is absent/invalid the reconcile
+**STOPs** with the exact install command, never a silent fallback. The deployment-lineage head stays
+**`1.3.0`** (no `docs/ai` structural change; no migration file). See **AD-016**.
+
+### Added
+- `tools/engine-source.mjs` — resolves the installed engine via the family `detect.installed` pattern
+  (env `AGENT_WORKFLOW_ENGINE_DIR` → `~/.claude/skills/agent-workflow-engine`, **not** an npm
+  dependency), validates it with the kit's own manifest validator, and reads the live fragment —
+  throwing a loud, actionable error (with the install command) when the engine is needed but absent.
+- `npx … init` now installs the engine after placing the kit. `--no-engine` opts out (the live read
+  then STOPs until the engine is installed by hand). An install failure **retries once**, then fails
+  loudly with concrete recovery steps and a non-zero exit (the kit itself is already on disk).
+
+### Changed
+- `tools/inject-methodology.mjs` sources the fragment live from the engine (a lazy `slotNeedsFill`
+  guard), not a bundled file. `SKILL.md` / `README.md` rewired to the live-read reality; the
+  `init-command-uses-latest` drift-guard now also covers the engine's `init` command.
+
+### Removed
+- The bundled mirror (`references/planning.md` + `tools/methodology-slot.md`) and its drift-guard
+  `test/methodology-mirror.test.mjs` — retired in favor of the live read.
+
+### Honesty
+- `init` now contacts a server (it fetches the engine over npm) and the kit gains a **runtime
+  dependency on the installed engine**; the "nothing contacts a server" / "no new dependency" notes
+  were scoped accordingly. The stale-version gate stays no-network, and there is still no telemetry.
+
 ## 1.10.0 — Hidden mode covers the full AI/agent footprint, project-local
 
 Hidden visibility now hides the **full AI/agent footprint** — the kit's own artifacts **and** every

package/README.md

@@ -159,8 +159,10 @@ different sub-commands:
 > [`@sabaiway/agent-workflow-memory`](https://www.npmjs.com/package/@sabaiway/agent-workflow-memory).
 > If a **healthy** copy is installed (the kit validates it with its own shipped validator), the kit
 > **delegates** substrate deployment to it and injects the workflow methodology; otherwise it uses
-> its **own bundled copy** — the one command above keeps working with no new dependency. Same
-> `docs/ai/` either way.
+> its **own bundled copy** — the one command above keeps working with **no new dependency on the
+> memory substrate**. Same `docs/ai/` either way. (The **methodology slot** is a separate axis: its
+> fragment is read **live from the installed `agent-workflow-engine`**, which `npx … init` installs
+> for you — a runtime dependency placed by `init`, read live.)
 
 ### Refresh the kit itself — same command with `@latest`
 
@@ -218,6 +220,8 @@ command is printed).
 | `/agent-workflow-kit upgrade` | existing deployment | reads `docs/ai/.workflow-version`, shows the changelog diff, preserves your authored memory, applies migrations, re-stamps — then prints a **read-only** one-line backend-status line (what's set up vs missing); never installs a bridge — set one up with `/agent-workflow-kit setup` |
 | `/agent-workflow-kit backends` | any time | **read-only** check of the optional execution-backends (the `codex` / `agy` bridges): what's set up vs missing and the next step. Never writes, never commits, never runs a subscription CLI (credentials = marker-file presence, not a live login). |
 | `/agent-workflow-kit setup [backend]` | opt-in, any time | **link-only** auto-setup of a bridge: places the bundled bridge skill (only into an absent / empty / managed dir — never overwrites an unmanaged one) + links its wrappers onto `PATH` via managed symlinks (idempotent; refuses to clobber a non-symlink; try `--dry-run` to preview). The binary install + the one-time subscription login stay **manual**: it prints the exact **login** command and points the binary install at each bridge's `setup/README.md`. POSIX wrappers — on Windows use WSL. Never commits, never runs a subscription CLI. |
+| `/agent-workflow-kit status` | any time | **read-only** view of the whole family: which members (kit / memory / engine / the two bridges) are installed and at what version, and — with a project — what's deployed (`docs/ai`, the version stamps, and whether the AI files are git-ignored for hidden mode). Never writes, never commits, never runs a subscription CLI. |
+| `/agent-workflow-kit uninstall` | opt-in, any time | **guarded teardown** — the inverse of `init` / `setup`. Removes only what's **provably ours** (managed skill dirs + bridge wrappers; in a project, the hidden-mode git-ignore block it added + the pre-commit hook it installed); **never deletes** your `docs/ai` / `AGENTS.md` / settings — for those it prints the exact `rm` commands to run by hand. Always `--dry-run` first; preflight-then-mutate; never commits. |
 
 It **never auto-commits** and **never overwrites** an existing `AGENTS.md` without asking.
 
@@ -248,7 +252,7 @@ the kit globally; the composition happens when you **deploy it in a repo** (`/ag
 agent-workflow-kit  —  the composition root (installed via npx … init)
    on /agent-workflow-kit in a repo, the kit:
    ├─ delegates ─▶ memory substrate   (healthy copy, else bundled fallback)
-   ├─ injects   ─▶ workflow methodology  (engine = future supplier; stub)
+   ├─ injects   ─▶ workflow methodology  (live from the installed engine)
    ├─ deploys   ─▶ AGENTS.md + docs/ai/ + Node scripts + pre-commit hook
    ├─ detects   ─▶ optional backends   (codex / agy, read-only)
    └─ sets up   ─▶ a bridge (opt-in)   (place skill + link wrappers)
@@ -296,15 +300,17 @@ agent-workflow-kit/
 ├── references/
 │   ├── templates/   ← AGENTS.md + every docs/ai file
 │   ├── scripts/     ← caps / archive / index + tests
-│   ├── contracts.md ← visibility / language / attribution rules
-│   └── planning.md  ← plan lifecycle + continuity
+│   └── contracts.md ← visibility / language / attribution rules
 ├── tools/           ← family tooling:
 │   ├── manifest/    ← capability-manifest schema + validator
 │   ├── delegation.mjs        ← detect substrate · delegate-or-fall-back
 │   ├── inject-methodology.mjs ← write the methodology slot
+│   ├── engine-source.mjs     ← live engine fragment read (fail-loud)
 │   ├── detect-backends.mjs    ← read-only backend detector
 │   ├── setup-backends.mjs     ← link-only backend setup
-│   ├── fs-safe.mjs            ← symlink-safe copy/link
+│   ├── fs-safe.mjs            ← symlink-safe copy/link/remove/unlink
+│   ├── family-registry.mjs    ← unified family registry (status)
+│   ├── uninstall.mjs          ← guarded teardown (uninstall)
 │   └── release-scan.mjs       ← attribution / release gate
 ├── bridges/         ← bundled bridge skill mirrors (codex / antigravity)
 ├── launchers/       ← Codex / Devin Desktop / Cursor entries

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: '1.10.0'
+  version: '1.12.0'
 ---
 
 # agent-workflow-kit
@@ -24,7 +24,10 @@ This kit is the **composition root** of the `agent-workflow` family. The memory
 (`docs/ai/`, the entry-point doc, caps / archive / index, the setup contracts) is owned by
 **`agent-workflow-memory`**. The kit **prefers to delegate** substrate deployment to that skill
 when it is present and healthy, and otherwise uses its **own bundled copy** (`references/`,
-`migrations/`) — so the existing one-command install keeps working with **no new dependency**.
+`migrations/`) — so the existing one-command install keeps working with **no new dependency on the
+memory substrate**. (The methodology slot is a separate axis: its fragment is read **live from the
+installed `agent-workflow-engine`**, which `npx @sabaiway/agent-workflow-kit@latest init` installs — a
+runtime dependency placed by `init` and read live; see *Methodology slot reconciliation* below.)
 
 **Detection (kit-owned, decided BEFORE any project write).** Run the kit's **own shipped**
 validator — `node ${CLAUDE_SKILL_DIR}/tools/manifest/validate.mjs <memory-skill-dir>` — never a
@@ -67,11 +70,16 @@ made: a partial/broken memory install discovered mid-flow must not disable the w
 **one atomic operation**: **ensure the slot exists** (insert an empty marker pair right after the
 Session-Protocols anchor when a legacy entry point lacks one) → **inject the bounded fragment ONLY
 IF the slot is empty** (a filled / user-customized slot is preserved verbatim) → **cap-check**
-(keeps `AGENTS.md` ≤100 lines). The fragment is a short summary + pointer (source: the kit's bundled
-`tools/methodology-slot.md`, a **byte-identical mirror of the `agent-workflow-engine` canon**) —
-**not** the full `references/planning.md`. Contract: exactly one ordered `start → end` pair; a
-malformed slot (single, reversed, nested, duplicate) or a missing / duplicate anchor → **STOP with
-an error**, never edit (the file is left byte-for-byte unchanged).
+(keeps `AGENTS.md` ≤100 lines). The fragment is a short summary + pointer read **live from the
+installed `agent-workflow-engine`** (`references/methodology-slot.md`, the family's one source of
+truth) — **not** a bundled mirror, and **not** the full `references/planning.md`. The live read is
+**lazy + fail-loud**: the engine is consulted **only when the slot actually needs filling**, so a
+deployment whose slot is already filled reconciles to a zero-diff no-op even on a host without the
+engine; but when a fill **is** needed and the engine is **absent/invalid**, reconcile **STOPs** —
+report it in plain language with the one-line install command `npx @sabaiway/agent-workflow-engine@latest init`
+(`npx @sabaiway/agent-workflow-kit@latest init` installs the engine for you; translate, never leak tool internals). Contract:
+exactly one ordered `start → end` pair; a malformed slot (single, reversed, nested, duplicate) or a
+missing / duplicate anchor → **STOP with an error**, never edit (the file is left byte-for-byte unchanged).
 
 **One composition-level commit gate.** The delegated memory mode performs **no** commit and
 raises **no** "ask to commit". There is exactly **one** gate, owned by the kit, **after**
@@ -88,6 +96,8 @@ Pick the mode from the user's invocation. Auto-detect an existing `docs/ai/` to
 - **`/agent-workflow-kit upgrade`** — upgrade an existing deployment to the skill's current `version`.
 - **`/agent-workflow-kit backends`** — read-only environment check: which optional **execution-backends** (the `codex` / `agy` bridges) are set up vs missing. Never writes, never commits, never runs a subscription CLI.
 - **`/agent-workflow-kit setup [backend]`** — the **link-only**, opt-in companion to `backends`: place the bundled bridge skill + link its wrappers onto `PATH`. **In-agent only** — `init` (npx) never places bridges. The binary install + the interactive subscription login stay **manual** (it prints the exact commands); idempotent; refuses to clobber a non-symlink; never commits, never runs a subscription CLI.
+- **`/agent-workflow-kit status`** — read-only view of the **whole family**: which members (kit / memory / engine / the two bridges) are installed, at what version, and — in a project — what is deployed (`docs/ai`, the version stamps, the hidden-mode fence). Never writes, never commits, never runs a subscription CLI.
+- **`/agent-workflow-kit uninstall`** — the **guarded teardown** companion to `init`/`setup`. Removes what they placed — installed skill dirs + the bridge wrappers — and, in a project, reverses the hidden-mode fence + the marker pre-commit hook. **Never deletes user-authored content** (`docs/ai`, `AGENTS.md`, `.claude/settings.json`): it prints the exact commands for you to run by hand. `--dry-run` first, always; preflight-then-mutate; never commits.
 
 ### Version status & the two axes — surface this on every invocation
 
@@ -175,11 +185,17 @@ Fill strategy:
 
 1. Read `docs/ai/.workflow-version` (the project's stamped lineage). If missing, treat as a pre-versioned deployment and offer to re-bootstrap conservatively.
 2. **Never-downgrade gate — FIRST, before any write.** Compare the stamp to the **deployment-lineage head** (`1.3.0` — NOT this kit's package version). If the stamp is **greater than the head** or unparseable → **STOP and report**; do not touch a newer / unknown deployment at all (not even the methodology slot).
-3. **Reconcile the methodology slot — stamp-independent, BEFORE the equal-head short-circuit.** Reached only when the stamp **≤ head**. Run `node ${CLAUDE_SKILL_DIR}/tools/inject-methodology.mjs reconcile <project>/AGENTS.md`. This ensures the `workflow:methodology` slot exists and is filled on **every** upgrade, idempotently (zero-diff when already present + filled) — so even a legacy / current **`1.3.0`** deployment gains the slot **without a lineage-head bump** (the head stays `1.3.0`; **no `agent-workflow-memory` change**). It inserts an empty slot at the Session-Protocols anchor if absent, preserves a customized slot verbatim, and STOPs (never edits) on a malformed slot or a missing / duplicate anchor.
+3. **Reconcile the methodology slot — stamp-independent, BEFORE the equal-head short-circuit.** Reached only when the stamp **≤ head**. Run `node ${CLAUDE_SKILL_DIR}/tools/inject-methodology.mjs reconcile <project>/AGENTS.md`. This ensures the `workflow:methodology` slot exists and is filled on **every** upgrade, idempotently (zero-diff when already present + filled) — so even a legacy / current **`1.3.0`** deployment gains the slot **without a lineage-head bump** (the head stays `1.3.0`; **no `agent-workflow-memory` change**). It inserts an empty slot at the Session-Protocols anchor if absent, preserves a customized slot verbatim, and STOPs (never edits) on a malformed slot, a missing / duplicate anchor, or **when a fill is needed but the installed `agent-workflow-engine` is absent/invalid** (the fragment is read live from it — see the three distinct non-zero outcomes below).
 
-   **Cap-refusal is a soft, reported skip — not a STOP.** If — and ONLY if — `reconcile` exits non-zero because filling the slot would exceed the deployed `AGENTS.md` 100-line cap (the entry point is already at / over budget), leave the file byte-for-byte unchanged (the tool already did) and **continue** the upgrade without the slot. A malformed slot or a missing / duplicate anchor is a *different* non-zero exit and still **STOPs** (above) — never soft-skip those. This is **not** a silent skip (Hard Constraint — no silent failures): report it explicitly in the successful-exit report (**step 4** on an equal-head deployment, else **step 8**), in plain language, e.g. *"The workflow-methodology pointer wasn't added — `AGENTS.md` is N lines, over its 100-line limit. The methodology is already documented in `docs/ai/agent_rules.md`; to add the pointer, trim the entry point (move detail into `docs/ai/`) and re-run upgrade."* N is the file's **current** line count — never the tool's number (that is the would-be post-injection size). Because the entry point is already over cap, ensure the rest of the upgrade does not push it further: any mandatory `AGENTS.md` edit must keep it ≤100 lines or pause for an explicit trim — never bust the cap to land a migration.
+   **`reconcile` has THREE distinct non-zero exits — classify by the stderr text, handle each differently:**
 
-   **No-Node project:** open `AGENTS.md`; if there is no `<!-- workflow:methodology:start/end -->` pair, **count the lines first** — if pasting the pair + the fragment from `tools/methodology-slot.md` would take the file over 100 lines, **skip it and report the skip** (as above — the methodology is already in `docs/ai/agent_rules.md`; trim to add the pointer). Otherwise paste the pair right after the *Read it before any code change.* line and fill it from `tools/methodology-slot.md`.
+   (a) **Cap-refusal — a soft, reported skip (CONTINUE the upgrade).** If — and ONLY if — `reconcile` exits non-zero because filling the slot would exceed the deployed `AGENTS.md` 100-line cap (the entry point is already at / over budget), leave the file byte-for-byte unchanged (the tool already did) and **continue** the upgrade without the slot. This is **not** a silent skip (Hard Constraint — no silent failures): report it explicitly in the successful-exit report (**step 4** on an equal-head deployment, else **step 8**), in plain language, e.g. *"The workflow-methodology pointer wasn't added — `AGENTS.md` is N lines, over its 100-line limit. The methodology is already documented in `docs/ai/agent_rules.md`; to add the pointer, trim the entry point (move detail into `docs/ai/`) and re-run upgrade."* N is the file's **current** line count — never the tool's number (that is the would-be post-injection size). Because the entry point is already over cap, ensure the rest of the upgrade does not push it further: any mandatory `AGENTS.md` edit must keep it ≤100 lines or pause for an explicit trim — never bust the cap to land a migration.
+
+   (b) **Malformed slot / missing-or-duplicate anchor — a hard STOP (do NOT continue).** A different non-zero exit (above); never soft-skip it.
+
+   (c) **`methodology engine not found/invalid …` — a hard STOP (do NOT continue).** A fill was needed but the installed `agent-workflow-engine` (the live source of the fragment) is **absent/invalid**. Report it in plain language with the one-line install command `npx @sabaiway/agent-workflow-engine@latest init` (or note that `npx @sabaiway/agent-workflow-kit@latest init` installs the engine for you), then re-run upgrade once it is present. **Never** treat (c) as the cap soft-skip (a) — its message is distinct, and mis-handling it as a soft-skip would silently drop the slot (a no-silent-failures violation). (b) and (c) STOP the upgrade; only (a) continues.
+
+   **No-Node project:** the fragment lives only in the **installed `agent-workflow-engine`** (`references/methodology-slot.md`, under `~/.claude/skills/agent-workflow-engine` or `$AGENT_WORKFLOW_ENGINE_DIR`) — there is no bundled copy. A No-Node host also cannot run the `npx` engine install. Open `AGENTS.md` and classify the slot by hand: a **filled / customized** slot → leave it verbatim (no-op, no engine needed); a **malformed** slot (not exactly one ordered `start → end` pair) → STOP, do not edit. A slot that needs filling — **absent markers OR a present-but-empty pair** — needs the engine's fragment, so: if the engine is **not installed**, the pointer **cannot be added** — report that plainly (mirroring the Node STOP: the methodology is already in `docs/ai/agent_rules.md`; install the engine to add the pointer). If the engine **is** present, **count the lines first** — if adding/filling the pair with that fragment would take the file over 100 lines, **skip it and report the skip** (as above — trim to add the pointer). Otherwise: when markers are absent, paste the pair right after the *Read it before any code change.* line; then fill the empty pair from the engine's `references/methodology-slot.md` (never inline a copy — that would re-create the retired mirror).
 
    **Hidden-mode footprint reconcile — stamp-independent, same gate, BEFORE the equal-head short-circuit (D9 / AD-014).** A deployment does not record whether it chose `hidden`, so first **infer visibility**: `node ${CLAUDE_SKILL_DIR}/tools/hide-footprint.mjs --dir <project> --reconcile --dry-run` (writes **zero bytes**). It reports one of — **visible** (the entry point is tracked) → nothing to do; **ambiguous** (untracked but not ignored — could be a fresh uncommitted repo, or a hide that broke) → **ASK** the user which it is, never guess; **hidden** → re-run without `--dry-run` to migrate any older **machine-global** hide to the **project-local** `.git/info/exclude` (one managed block; folds in the legacy `.claude/skills/` line), idempotently (a clean re-run is zero-diff). Handle its surfaced paths exactly as bootstrap step 9 (already-committed → show `git rm --cached`, ask before `--include`; generic-name present file → ask; **leftover machine-wide ignore block → ASK before `--remove-global`**, default keep + report). No Node on the agent host / Windows → as step 9. This runs on **every** hidden upgrade, like the methodology slot — no lineage-head bump, no migration file.
 4. **Equal-head exit — a real successful-exit report, not a bare stop.** If the stamp **equals** the head, the lineage is up to date — but step 3 (the methodology-slot **and** hidden-mode footprint reconciles) ran first and may have changed things, so this is a proper exit report, not a no-op:
@@ -221,6 +237,36 @@ For each backend it:
 
 **Exit codes:** `0` = done / already set up / only manual steps remain (guidance is never a failure); **non-zero** = a STOP (a dir/symlink it refuses to clobber), a bad argument, a missing bundle, or a native fs error (the underlying reason is preserved in the message).
 
+### Mode: status
+
+Read-only. Answers *"which family members are installed (and at what version), and what is deployed in this project?"* across the **whole family** — the unified registry behind it (`tools/family-registry.mjs`) aggregates every member's `capability.json`. It **never writes, never commits, and never runs a subscription CLI**.
+
+Run `node ${CLAUDE_SKILL_DIR}/tools/family-registry.mjs [--dir <project>]` and present its two-axis table:
+
+1. **Skill axis (always):** per member — `installed` + the manifest health (`ok` / `not-installed` / `foreign` / `stub` / `invalid-manifest` / `unsupported-schema`, the same precedence the backend detector uses) + the installed version (read from the member's own `SKILL.md`, the authoritative source).
+2. **Deploy axis (`--dir <project>`):** the deployment stamps (`docs/ai/.workflow-version`, `.memory-version`), whether `docs/ai/` exists, and whether the hidden-mode managed fence is present.
+
+State plainly that the two version axes stay decoupled (an installed *skill* version is not a project's deployment-lineage stamp — see *Version status & the two axes*). The installed version reflects whatever is on disk under `~/.claude/skills/…`; a stale install shows its real (older) version, honestly.
+
+### Mode: uninstall
+
+The **guarded teardown** — the inverse of `init` (the kit + engine skills) + `setup` (the bridges) + a hidden deploy. **In-agent, opt-in**, and built around one hard rule: **it never deletes user-authored content.** Run **`--dry-run` first, always**, show the user the classified plan in plain language, get explicit consent, then re-run with `--yes`. It **never commits**.
+
+Run `node ${CLAUDE_SKILL_DIR}/tools/uninstall.mjs [<member>] [--dir <project>] [--bindir <path>] [--dry-run | --yes]`:
+
+- `<member>` — limit the skill axis to one member (`agent-workflow-kit` / `-memory` / `-engine` / a bridge); omit for the **whole family**.
+- `--dir <project>` — also reverse the **project-deployment** surfaces in `<project>`.
+- `--bindir <path>` — where the bridge wrappers were linked (default `~/.local/bin`, mirrors `setup`).
+- `--dry-run` — print the plan and change **nothing** (run this first). `--yes` — apply the **auto-removable** set.
+
+It classifies every surface into four classes and acts accordingly:
+
+- **remove** (safe) — an installed skill dir that is **provably ours** (valid manifest, `name`+`kind` match). A dir present but **not provably ours** (`foreign`/`stub`/`invalid`/unreadable) → **STOP**: left untouched **and reported**, while the teardown still removes the members that ARE ours (a not-ours surface is never clobbered, and never blocks removing the rest — the per-item `setup` posture). **Preflight-then-mutate:** if a mutable surface **changed since the dry-run** (a skill no longer ours, a wrapper turned foreign, a hook that lost our marker, a malformed fence), the run **aborts with zero changes**.
+- **reverse** (managed-marker) — a bridge **wrapper symlink that points at our source** (a foreign/non-symlink one → STOP); the hidden-mode **managed fence** (via the existing `--unhide` path — only the fenced lines); a **pre-commit hook carrying our marker** (an unmarked / user hook → left + reported).
+- **KEEP — never deleted** (report-only) — `docs/ai`, `AGENTS.md`, `CLAUDE.md`, `docs/plans`, and the `.claude/settings.json` `includeCoAuthoredBy` edit. The tool **prints the exact `rm` / `git rm --cached` commands**; the **user** runs them. Surface this in plain language; never delete on their behalf.
+
+**Shared globals:** removing `agent-workflow-memory` / `agent-workflow-engine` / a bridge removes a **global** skill that another project on the machine may use — say so before applying. **Windows:** the wrappers are POSIX; the skill-dir + project arms still work, the wrapper arm reports *use WSL*.
+
 ---
 
 ## Gotchas
@@ -237,6 +283,7 @@ The non-obvious traps — scan these before bootstrapping or upgrading. Each is
 - **Conversational language never translates artifacts.** It governs *dialogue only*. Code, identifiers, paths, commands, log output, abbreviations, and every deployed `docs/ai/` / `AGENTS.md` file stay in their source language. See [Communication contract](references/contracts.md#communication-contract).
 - **Never auto-commit.** Report quality-gate results and wait for explicit approval — in both modes.
 - **Never leak kit internals to the user.** No ADR ids, tool / function / operation names (`reconcile`, `inject`, `ensureSlot`), marker / slot / fragment / anchor terminology, or verbatim tool stderr in anything the user reads. Translate every tool outcome into plain language a third-party user — who has never read this `SKILL.md` — can understand and act on (e.g. the cap-refusal report in *Mode: upgrade* step 3).
+- **Uninstall never deletes user-authored content, and dry-runs first.** `/agent-workflow-kit uninstall` removes only what is **provably ours** (a managed skill dir / wrapper symlink / fenced block / marker hook) and **prints — never runs** the `rm` / `git rm --cached` for `docs/ai`, the entry-point docs, and `.claude/settings.json`. Always run `--dry-run` first, show the plan, get consent, then `--yes`. A skill dir or symlink that is not provably ours is a STOP, never a clobber (the `setup` posture, inverted). Removing a shared global (memory/engine/a bridge) may affect another project — say so.
 
 ---
 
@@ -287,11 +334,11 @@ Deploy these into `AGENTS.md`; remove rows that don't apply to the stack.
 ## References
 
 - [`references/contracts.md`](references/contracts.md) — the three setup contracts (visibility, conversational language, agent attribution) in full; the *Setup contracts* section above points here.
-- [`references/planning.md`](references/planning.md) — plan vocabulary (Plan→Phase→Step→Substep), lifecycle, `queue.md` series-index, mandatory Cleanup, session-continuity heuristic.
+- **Plan vocabulary** (Plan→Phase→Step→Substep), lifecycle, `queue.md` series-index, mandatory Cleanup, session-continuity heuristic — the single home is the **installed `agent-workflow-engine`** canon (`~/.claude/skills/agent-workflow-engine/references/planning.md`, or `$AGENT_WORKFLOW_ENGINE_DIR`); there is no bundled mirror. `npx @sabaiway/agent-workflow-kit@latest init` installs the engine.
 - [`references/templates/`](references/templates/) — stack-agnostic `AGENTS.md`, `agent_rules.md`, and all `docs/ai/` files to deploy.
 - [`references/scripts/`](references/scripts/) — the Node enforcement scripts (caps + staleness + index-freshness gate, 3-tier archive, hook installer) and their unit tests.
 - [`migrations/`](migrations/) — per-version upgrade steps; see `migrations/README.md`.
 - [`launchers/`](launchers/) — run the bootstrapper from non-Claude agents (`SKILL.md` is a native Codex skill; a Devin Desktop workflow launcher + install script). See `launchers/README.md`.
-- [`tools/`](tools/) — the family-wide tooling the kit **owns and ships**: `manifest/{schema.md,validate.mjs}` (the `capability.json` schema + the validator the kit runs as the memory detector, and root CI invokes), `delegation.mjs` (the executable delegate/fallback decision + hand-off plan), `inject-methodology.mjs` + `methodology-slot.md` (the bounded slot reconciliation — ensure-slot / inject-if-empty / cap; the fragment is a byte-identical mirror of the `agent-workflow-engine` canon, pinned by `methodology-mirror.test.mjs`), `detect-backends.mjs` (the read-only **backend detector** behind `/agent-workflow-kit backends`, plus the axis-aware `guideFor`), `setup-backends.mjs` (the **link-only** backend setup behind `/agent-workflow-kit setup` — place the bundled bridge + link wrappers), `fs-safe.mjs` (the shared symlink-traversal-safe copy/link primitives both `setup-backends` and the npx installer use), `known-footprint.mjs` + `hide-footprint.mjs` (the **hidden-mode** registry + the single hide-writer behind step 9 / the upgrade reconcile — one managed block in the **project-local** `.git/info/exclude` covering the full AI/agent footprint; pinned by `known-footprint.test.mjs` drift-guard + `hide-footprint.test.mjs` / `.integration.test.mjs`), and `release-scan.mjs` (the attribution-off release gate). The bundled bridge skill mirrors live under [`bridges/`](bridges/) (byte-identical to the repo-root bridges, pinned by `test/bridges-mirror.test.mjs`). See [`tools/manifest/schema.md`](tools/manifest/schema.md).
+- [`tools/`](tools/) — the family-wide tooling the kit **owns and ships**: `manifest/{schema.md,validate.mjs}` (the `capability.json` schema + the validator the kit runs as the memory detector, and root CI invokes), `delegation.mjs` (the executable delegate/fallback decision + hand-off plan), `inject-methodology.mjs` + `engine-source.mjs` (the bounded slot reconciliation — ensure-slot / inject-if-empty / cap; the fragment is read **live** from the installed `agent-workflow-engine` via `engine-source.mjs` — the family's one source of truth, no bundled mirror; fail-loud when the engine is needed but absent), `detect-backends.mjs` (the read-only **backend detector** behind `/agent-workflow-kit backends`, plus the axis-aware `guideFor`), `setup-backends.mjs` (the **link-only** backend setup behind `/agent-workflow-kit setup` — place the bundled bridge + link wrappers), `fs-safe.mjs` (the shared symlink-traversal-safe copy/link/**remove/unlink** primitives that `setup-backends`, the npx installer, and the uninstaller use), `known-footprint.mjs` + `hide-footprint.mjs` (the **hidden-mode** registry + the single hide-writer behind step 9 / the upgrade reconcile — one managed block in the **project-local** `.git/info/exclude` covering the full AI/agent footprint; pinned by `known-footprint.test.mjs` drift-guard + `hide-footprint.test.mjs` / `.integration.test.mjs`), `family-registry.mjs` (the **unified family registry** behind `/agent-workflow-kit status` — aggregates every member's `capability.json`; pinned by a `family-registry.test.mjs` drift-guard), `uninstall.mjs` (the **guarded teardown** behind `/agent-workflow-kit uninstall` — classify each surface, preflight-then-mutate, never delete user-authored content), and `release-scan.mjs` (the attribution-off release gate). The bundled bridge skill mirrors live under [`bridges/`](bridges/) (byte-identical to the repo-root bridges, pinned by `test/bridges-mirror.test.mjs`). See [`tools/manifest/schema.md`](tools/manifest/schema.md).
 - [`capability.json`](capability.json) — the kit's own `agent-workflow` family manifest (`kind: composition-root`).
 - [`CHANGELOG.md`](CHANGELOG.md) — version history of this kernel.

package/bin/install.mjs

@@ -14,17 +14,19 @@
 // docs/ai deployment — see README "Use".
 //
 // No telemetry, no phone-home: adoption is the npm registry's public, passive per-version
-// download numbers (api.npmjs.org/downloads). Nothing here contacts a server — including the
-// stale-version defenses below, which compare the version already on disk (the installed SKILL.md)
-// against this runner's own version, never the registry. That is why `@latest` (above) is the
-// documented form: a bare `npx … init` can reuse an OLDER cached build of this installer, so a
-// returning user must bypass the cache to actually upgrade. See decisions.md AD-012.
+// download numbers (api.npmjs.org/downloads). The stale-version GATE below is no-network — it
+// compares the version already on disk (the installed SKILL.md) against this runner's own version,
+// never the registry — which is why `@latest` (above) is the documented form: a bare `npx … init`
+// can reuse an OLDER cached build of this installer, so a returning user must bypass the cache to
+// actually upgrade (see decisions.md AD-012). One step DOES contact a server: `init` fetches and
+// installs the methodology engine the kit reads live (`npx @sabaiway/agent-workflow-engine@latest
+// init`), skippable with `--no-engine` (Plan 3D / AD-016). No tracking either way.
 //
 // Dependency-free, Node >= 18.
 
-import { readFile, mkdir } from 'node:fs/promises';
+import { readFile, mkdir, rm } from 'node:fs/promises';
 import { existsSync, lstatSync, realpathSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
+import { dirname, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { spawnSync } from 'node:child_process';
@@ -50,7 +52,16 @@ const PAYLOAD = [
   'bridges',
 ];
 
-const tildify = (path) => path.replace(homedir(), '~');
+// 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) =>
+  path === homedir() ? '~' : path.startsWith(homedir() + sep) ? `~${path.slice(homedir().length)}` : path;
 
 const readVersion = async () => {
   try {
@@ -135,12 +146,63 @@ const parseArgs = (argv) => {
     help: argv.includes('--help') || argv.includes('-h'),
     version: argv.includes('--version') || argv.includes('-v'),
     noLaunchers: argv.includes('--no-launchers'),
+    noEngine: argv.includes('--no-engine'),
     force: argv.includes('--force'),
     allowDowngrade: argv.includes('--allow-downgrade'),
     dir: dirFlag >= 0 ? argv[dirFlag + 1] : undefined,
   };
 };
 
+// Mandatory engine install (Plan 3D / AD-016). The kit reads the methodology fragment LIVE from the
+// installed agent-workflow-engine, so init places it as a CORE part of the kit (not an optional
+// execution-backend — this deliberately diverges from AD-011 §5). It is fetched over npm, consistent
+// with the kit's own npx install context; NO engine canon is bundled into the kit (that would
+// re-create the mirror Plan 3D deletes). --no-engine skips it for air-gapped/scripted installs.
+export const ENGINE_PACKAGE = '@sabaiway/agent-workflow-engine';
+
+// The exact command + argv to install the engine. Windows resolution: spawn `npx.cmd` on win32,
+// `npx` elsewhere, WITHOUT shell:true (no shell-parse overhead/inconsistency; the repo has no
+// npx-spawn precedent to inherit a shell from). Pure → unit-tested in-process, no network.
+export const engineInstallArgv = (platform) => ({
+  command: platform === 'win32' ? 'npx.cmd' : 'npx',
+  args: [`${ENGINE_PACKAGE}@latest`, 'init'],
+  options: { stdio: 'inherit' }, // note: no `shell: true`
+});
+
+// The default runner — the only place that actually spawns. Injected in tests so the suite never
+// hits the network.
+const spawnEngine = ({ command, args, options }) => spawnSync(command, args, options);
+
+// Synchronous backoff before the single retry. The common first-attempt failure is a TRANSIENT
+// npm/network blip (rate-limit, registry hiccup, momentary DNS) — an immediate retry tends to hit the
+// same blip, so wait briefly first. Atomics.wait is a dependency-free sync sleep (the install flow is
+// already synchronous here). Injected in tests as a 0ms no-op so the suite never actually sleeps.
+const ENGINE_RETRY_DELAY_MS = 1500;
+const sleepSync = (ms) => {
+  if (ms > 0) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+};
+
+// D1 failure policy: attempt → wait → retry-once → fail. Retry exactly once before giving up. Pure
+// aside from the injected runner/sleep; returns { ok } so the caller prints the loud manual-recovery
+// message + nonzero exit on a hard failure (the kit is already on disk — recovery is one step; never
+// a silent skip).
+export const installEngine = (platform, runner, { sleep = sleepSync, retryDelayMs = ENGINE_RETRY_DELAY_MS } = {}) => {
+  const descriptor = engineInstallArgv(platform);
+  const ranOk = (label) => {
+    const res = runner(descriptor);
+    const ok = (res?.status ?? 1) === 0 && !res?.error;
+    if (!ok) {
+      const why = res?.error ? `: ${res.error.message}` : ` (exit ${res?.status ?? 'unknown'})`;
+      console.warn(`[agent-workflow-kit] methodology engine install ${label} failed${why}.`);
+    }
+    return ok;
+  };
+  if (ranOk('attempt 1')) return { ok: true };
+  sleep(retryDelayMs); // brief backoff so the retry does not immediately re-hit a transient blip
+  if (ranOk('retry')) return { ok: true };
+  return { ok: false };
+};
+
 const resolveTarget = (dirArg) => {
   if (dirArg) return resolve(dirArg);
   if (process.env.AGENT_WORKFLOW_KIT_DIR) return resolve(process.env.AGENT_WORKFLOW_KIT_DIR);
@@ -151,7 +213,7 @@ const printHelp = (version) => {
   console.log(`agent-workflow-kit ${version}
 
 Usage:
-  npx @sabaiway/agent-workflow-kit@latest init [--dir <path>] [--no-launchers] [--force] [--allow-downgrade]
+  npx @sabaiway/agent-workflow-kit@latest init [--dir <path>] [--no-launchers] [--no-engine] [--force] [--allow-downgrade]
   npx @sabaiway/agent-workflow-kit@latest --version
   npx @sabaiway/agent-workflow-kit@latest --help
 
@@ -160,11 +222,14 @@ Use the @latest form: a bare \`npx … init\` (no @latest) can reuse an OLDER ca
 
 Installs/refreshes the kit at ~/.claude/skills/agent-workflow-kit
   (override with --dir <path> or AGENT_WORKFLOW_KIT_DIR), then wires any
-  Codex / Devin Desktop you have. --no-launchers skips that wiring; --force replaces a
-  pre-existing non-kit launcher file (backed up first). init is additive — it never
-  deletes your settings. 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).
+  Codex / Devin Desktop you have, then installs the methodology engine the kit reads
+  live (npx ${ENGINE_PACKAGE}@latest init). --no-launchers skips the
+  launcher wiring; --no-engine skips the engine install (the live methodology read then
+  STOPs until you install it by hand); --force replaces a pre-existing non-kit launcher
+  file (backed up first). init is additive — it never deletes your settings. 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).
 
 After install, invoke the skill in your agent, inside a project:
   first time in the project  ->  /agent-workflow-kit
@@ -232,6 +297,16 @@ const main = async () => {
   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).`);
+    }
+  }
   console.log(`[agent-workflow-kit] ${wasPresent ? 'updated the kit to' : 'installed'} v${version} -> ${tildify(target)}`);
 
   // No-op re-run: the install just refreshed the skill with the SAME version it already had. For a
@@ -260,6 +335,34 @@ const main = async () => {
     }
   }
 
+  // Mandatory engine install — AFTER the kit + launchers but BEFORE the success block, so a failure
+  // never first claims everything succeeded. The kit reads the methodology fragment live from the
+  // installed engine; this places it (over npm, no canon bundled into the kit). --no-engine opts out.
+  const engineCmd = `npx ${ENGINE_PACKAGE}@latest init`;
+  if (args.noEngine) {
+    console.log(
+      `[agent-workflow-kit] --no-engine: skipped installing the methodology engine. The methodology ` +
+        `slot is read LIVE from the installed engine, so a reconcile/upgrade will STOP until you run:\n` +
+        `    ${engineCmd}`,
+    );
+  } else {
+    console.log(`[agent-workflow-kit] installing the methodology engine the kit reads live: ${engineCmd}`);
+    const engine = installEngine(process.platform, spawnEngine);
+    if (!engine.ok) {
+      // D1: two attempts failed → loud error + concrete recommendations + nonzero exit. The kit IS on
+      // disk, so recovery is one step. Never a silent skip (Hard Constraint: no silent failures).
+      console.error(
+        `[agent-workflow-kit] FAILED to install the methodology engine after two attempts. The kit ` +
+          `itself IS installed at ${tildify(target)}, but the methodology-slot read will STOP until the ` +
+          `engine is present. Finish with EITHER:\n` +
+          `    ${engineCmd}                                          (install the engine — recommended)\n` +
+          `    npx @sabaiway/agent-workflow-kit@latest init --no-engine   (skip it deliberately)`,
+      );
+      process.exit(1);
+    }
+    console.log('[agent-workflow-kit] methodology engine installed.');
+  }
+
   // 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").