@sabaiway/agent-workflow-kit 1.10.0 → 1.11.0

package/CHANGELOG.md

@@ -4,6 +4,42 @@ 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.11.0 — One source of truth: the kit reads the methodology live from the installed engine
+
+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`
 
@@ -248,7 +250,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,12 +298,12 @@ 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

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.11.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**
@@ -175,11 +183,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:
@@ -287,11 +301,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 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).
 - [`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").

package/bin/install.test.mjs

@@ -7,11 +7,16 @@ import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { engineInstallArgv, installEngine, ENGINE_PACKAGE } from './install.mjs';
+
 const INSTALLER = join(dirname(fileURLToPath(import.meta.url)), 'install.mjs');
 const KIT_ROOT = dirname(dirname(INSTALLER));
-// --no-launchers so the test never wires Codex/Devin on the host. `extra` appends flags (e.g. --force).
+// --no-launchers so the test never wires Codex/Devin on the host; --no-engine so a full install never
+// spawns a real `npx … agent-workflow-engine init` (network + a write to the real engine dir). The
+// dedicated engine-step tests cover that path in-process / via a deliberately-broken PATH. `extra`
+// appends flags (e.g. --force, --allow-downgrade).
 const runInstaller = (target, extra = []) =>
-  spawnSync(process.execPath, [INSTALLER, '--dir', target, '--no-launchers', ...extra], { encoding: 'utf8' });
+  spawnSync(process.execPath, [INSTALLER, '--dir', target, '--no-launchers', '--no-engine', ...extra], { encoding: 'utf8' });
 
 // Rewrite / read the installed skill's frontmatter version — used to simulate "a newer kit is already
 // installed" (the stale-cache downgrade scenario). The installer reads exactly this field.
@@ -44,6 +49,21 @@ describe('kit installer — payload + symlink-traversal hardening', () => {
     assert.equal(existsSync(join(target, 'bin/install.mjs')), false);
   });
 
+  it('removes retired mirror files an older install left behind (single source of truth on upgrade)', async () => {
+    const target = join(dir, 'agent-workflow-kit');
+    // Seed a pre-3D install carrying the now-retired bundled mirror files.
+    await mkdir(join(target, 'references'), { recursive: true });
+    await mkdir(join(target, 'tools'), { recursive: true });
+    await writeFile(join(target, 'references', 'planning.md'), 'stale mirror\n');
+    await writeFile(join(target, 'tools', 'methodology-slot.md'), 'stale mirror\n');
+    const res = runInstaller(target);
+    assert.equal(res.status, 0, res.stderr);
+    assert.equal(existsSync(join(target, 'references', 'planning.md')), false, 'retired references/planning.md removed');
+    assert.equal(existsSync(join(target, 'tools', 'methodology-slot.md')), false, 'retired tools/methodology-slot.md removed');
+    assert.ok(existsSync(join(target, 'SKILL.md')), 'the real payload is still installed');
+    assert.ok(existsSync(join(target, 'references', 'contracts.md')), 'non-retired references/ content survives');
+  });
+
   it('refuses to write through a symlinked INTERMEDIATE dest component (no leak)', async () => {
     const target = join(dir, 'target');
     const evil = join(dir, 'evil');
@@ -96,7 +116,7 @@ describe('kit installer — runs through the npx bin symlink', () => {
     const shim = join(dir, 'agent-workflow-kit'); // stands in for node_modules/.bin/<name>
     await symlink(INSTALLER, shim);
     const target = join(dir, 'home', 'agent-workflow-kit');
-    const res = spawnSync(process.execPath, [shim, '--dir', target, '--no-launchers'], { encoding: 'utf8' });
+    const res = spawnSync(process.execPath, [shim, '--dir', target, '--no-launchers', '--no-engine'], { encoding: 'utf8' });
     assert.equal(res.status, 0, res.stderr);
     assert.match(res.stdout, /installed v|updated the kit/);
     assert.ok(existsSync(join(target, 'SKILL.md')), 'install through the symlink must write the payload');
@@ -211,8 +231,107 @@ describe('kit installer — stale-cache defenses (no network)', () => {
   });
 });
 
-describe('kit installer — published tarball bundles the bridges', () => {
-  it('npm pack ships bridges/<name>/ (the execution-backend skill mirrors)', () => {
+describe('kit installer — mandatory engine install dispatch (Plan 3D, in-process, no network)', () => {
+  it('engineInstallArgv: `npx @…/engine@latest init` on POSIX, `npx.cmd` on win32, no shell:true', () => {
+    const posix = engineInstallArgv('linux');
+    assert.equal(posix.command, 'npx');
+    assert.deepEqual(posix.args, [`${ENGINE_PACKAGE}@latest`, 'init']);
+    assert.equal(posix.options.shell, undefined, 'must not spawn through a shell');
+    assert.equal(engineInstallArgv('darwin').command, 'npx');
+    assert.equal(engineInstallArgv('win32').command, 'npx.cmd');
+  });
+
+  it('installEngine: first attempt succeeds → ok, runner called once (no retry)', () => {
+    let calls = 0;
+    const res = installEngine('linux', () => {
+      calls += 1;
+      return { status: 0 };
+    });
+    assert.deepEqual(res, { ok: true });
+    assert.equal(calls, 1);
+  });
+
+  const NO_SLEEP = { sleep: () => {} }; // skip the real backoff so the suite never actually waits
+
+  it('installEngine: fail once then succeed → backoff + retried exactly once, ends ok (D1)', () => {
+    let calls = 0;
+    let slept = 0;
+    const res = installEngine('linux', () => {
+      calls += 1;
+      return { status: calls === 1 ? 1 : 0 };
+    }, { sleep: () => { slept += 1; } });
+    assert.deepEqual(res, { ok: true });
+    assert.equal(calls, 2);
+    assert.equal(slept, 1, 'backoff runs exactly once, before the single retry');
+  });
+
+  it('installEngine: fails twice → not ok (D1 hard-failure outcome), no third attempt', () => {
+    let calls = 0;
+    const res = installEngine('linux', () => {
+      calls += 1;
+      return { status: 1 };
+    }, NO_SLEEP);
+    assert.deepEqual(res, { ok: false });
+    assert.equal(calls, 2);
+  });
+
+  it('installEngine: a spawn error (npx not found) counts as a failure', () => {
+    const res = installEngine('linux', () => ({ status: null, error: new Error('spawn npx ENOENT') }), NO_SLEEP);
+    assert.deepEqual(res, { ok: false });
+  });
+
+  it('installEngine: hands the runner the exact descriptor (command/args/options, no shell)', () => {
+    let received;
+    installEngine('win32', (d) => {
+      received = d;
+      return { status: 0 };
+    });
+    assert.equal(received.command, 'npx.cmd');
+    assert.deepEqual(received.args, [`${ENGINE_PACKAGE}@latest`, 'init']);
+    assert.equal(received.options.shell, undefined);
+  });
+});
+
+describe('kit installer — mandatory engine install (subprocess)', () => {
+  let dir;
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'aw-kit-engine-'));
+  });
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('--no-engine skips the engine install and prints the live-read STOP note (exit 0)', () => {
+    const target = join(dir, 'agent-workflow-kit'); // runInstaller appends --no-engine by default
+    const res = runInstaller(target);
+    assert.equal(res.status, 0, res.stderr);
+    assert.match(res.stdout, /--no-engine: skipped installing the methodology engine/);
+    assert.match(res.stdout, /@latest init/);
+    assert.match(res.stdout, /installed v|updated the kit/, 'the kit itself still installs');
+  });
+
+  it('D1: when `npx` cannot run (both attempts fail) → nonzero exit, recommendations, success block NOT printed first', async () => {
+    // Force both engine-install attempts to fail deterministically WITHOUT network: run a real install
+    // (no --no-engine) with an empty PATH so `npx` resolves to ENOENT. The kit copy + the version gate
+    // do not need PATH; only the engine spawn does. This exercises the D1 loud-error + nonzero exit.
+    const target = join(dir, 'agent-workflow-kit');
+    const emptyBin = join(dir, 'emptybin');
+    await mkdir(emptyBin, { recursive: true });
+    const res = spawnSync(process.execPath, [INSTALLER, '--dir', target, '--no-launchers'], {
+      encoding: 'utf8',
+      env: { ...process.env, PATH: emptyBin },
+    });
+    assert.notEqual(res.status, 0, 'an engine-install failure must exit nonzero');
+    assert.match(res.stderr, /FAILED to install the methodology engine/);
+    assert.match(res.stderr, /@latest init/, 'recommends the manual engine install');
+    assert.match(res.stderr, /--no-engine/, 'recommends the opt-out');
+    assert.doesNotMatch(res.stdout, /Next — open your agent/, 'must NOT claim success before the engine failed');
+    assert.ok(existsSync(join(target, 'SKILL.md')), 'the kit itself is still on disk (recovery is one step)');
+  });
+});
+
+describe('kit installer — published tarball bundles the bridges + the live-read tool', () => {
+  it('npm pack ships bridges/<name>/ and tools/engine-source.mjs', () => {
     // The real `files` whitelist decides what publishes — assert against `npm pack`, not the source
     // tree, so a dropped `bridges/` entry in package.json fails here (not silently at install time).
     const res = spawnSync('npm', ['pack', '--dry-run', '--json'], { cwd: KIT_ROOT, encoding: 'utf8' });
@@ -220,5 +339,9 @@ describe('kit installer — published tarball bundles the bridges', () => {
     const paths = JSON.parse(res.stdout)[0].files.map((f) => f.path);
     assert.ok(paths.includes('bridges/codex-cli-bridge/SKILL.md'), 'codex bridge SKILL.md not packed');
     assert.ok(paths.includes('bridges/antigravity-cli-bridge/bin/agy.sh'), 'antigravity agy.sh not packed');
+    assert.ok(paths.includes('tools/engine-source.mjs'), 'the live-read resolver must ship in the tarball');
+    // The retired mirror must NOT ship — the whole point of Plan 3D is one source of truth.
+    assert.ok(!paths.includes('tools/methodology-slot.md'), 'retired mirror tools/methodology-slot.md must not be packed');
+    assert.ok(!paths.includes('references/planning.md'), 'retired mirror references/planning.md must not be packed');
   });
 });

package/capability.json

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

package/package.json

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