@sabaiway/agent-workflow-kit 1.9.1 → 1.11.0

package/CHANGELOG.md

@@ -4,6 +4,67 @@ 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
+known foreign tool's files (Claude skills, Cursor, Windsurf, Gemini, Copilot, Aider, Continue, …) — in
+**one managed block in the project-local `.git/info/exclude`**, never the machine-global
+`core.excludesFile` (which leaked the same rules to every repo on the host). **AD-014** amends
+**AD-006** and generalizes the `.claude/skills/` one-off (AD-013). The deployment-lineage head stays
+**`1.3.0`** — this is a stamp-independent reconcile wired into bootstrap + the upgrade flow (the AD-010
+methodology-slot precedent), so there is **no migration file**.
+
+### Added
+- `tools/known-footprint.mjs` — the `KIT_OWN_PATHS` + `KNOWN_FOOTPRINT` registry (+ `patternToProbe` /
+  `expandGlob` / `matchesKnownGlob`), guarded by a frozen-snapshot + count-sentinel drift test.
+- `tools/hide-footprint.mjs` — the single hide-writer. Classifies each path (tracked → **ASK** with the
+  printed `git rm --cached`; present generic-name → **ASK**; else **hide**), writes one re-derived
+  managed fence (a clean re-run is byte-identical / zero-diff), `migrateFromGlobal` (detect + report the
+  residual machine-global block by default; `--remove-global` removes it with a printed backup),
+  `--reconcile` (upgrade-time visibility inference: visible → zero bytes, ambiguous → ASK),
+  `--unhide`, `--include`. Unit + real-`git` integration tests (worktree, precedence, delegated memory).
+
+### Changed
+- `references/contracts.md` Visibility contract rewritten (project-local; full footprint table);
+  `SKILL.md` bootstrap step 9 + the upgrade reconcile now drive the tool; root + kit READMEs corrected.
+- A **tracked** file is never silently un-tracked — the tool prints the `git rm --cached` it will not run.
+
 ## 1.9.1 — Front-door value framing for the optional bridges; kit flow-pointer
 
 The optional execution-backends (the `codex` / `agy` bridges) were **listed** but never **sold**: a

package/README.md

@@ -124,8 +124,9 @@ The Markdown memory is **stack-agnostic**; the `scripts/` + pre-commit hook are
 (dependency-free, `node --test`). Non-Node projects keep the same policy by hand.
 
 Two **visibility** modes, chosen at deploy time: **visible** (committed with the repo) or **hidden**
-(same files in-tree but git-ignored via the global `core.excludesFile`, so the repo "looks normal").
-Hidden changes how the files are *tracked*, not where agents find them.
+(same files in-tree but git-ignored via the project-local `.git/info/exclude`, so the repo "looks
+normal" — one managed block covering the full AI/agent footprint, scoped to this repo, never
+machine-wide). Hidden changes how the files are *tracked*, not where agents find them.
 
 ---
 
@@ -158,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`
 
@@ -247,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)
@@ -295,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.9.1'
+  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
@@ -51,7 +54,11 @@ made: a partial/broken memory install discovered mid-flow must not disable the w
   answers** (visibility / language / attribution) to `agent-workflow-memory`, which writes
   `docs/ai/` + `AGENTS.md` (with the empty slot) + **`.memory-version`**. The kit then
   **reconciles the bounded methodology slot** (below) and writes the kit-fallback
-  **`.workflow-version`**. → **both stamps** present.
+  **`.workflow-version`**. → **both stamps** present. In **hidden** mode the kit is the **single
+  hide authority**: after the hand-off it runs `tools/hide-footprint.mjs` (step 9), which **absorbs
+  memory's project-local footprint lines** into the one canonical `.git/info/exclude` block and adds
+  the external footprint — so there is **no machine-global write** at any step (a stale memory's
+  residual global block is cleaned via the upgrade reconcile, below).
 - **Fallback** (memory absent/invalid): the kit runs the bootstrap procedure below from its own
   bundled assets — whose entry-point template now ships the **empty methodology slot** the kit
   reconciles + fills — and writes **`.workflow-version`** only. Softly suggest installing
@@ -63,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**
@@ -91,7 +103,7 @@ Before acting, read `docs/ai/.workflow-version` (the project's stamp), state a o
 
 - **absent** → bootstrap (a fresh deployment).
 - **stamp < `1.3.0`** (the deployment-lineage head) → `upgrade`.
-- **stamp == `1.3.0`** → already current; only the stamp-independent methodology-slot reconcile may run.
+- **stamp == `1.3.0`** → already current; only the stamp-independent reconciles may run (the methodology slot **and** the hidden-mode footprint, *Mode: upgrade* step 3).
 - **stamp > head / unparseable** → STOP — never-downgrade gate (see *Mode: upgrade* step 2).
 
 **Two independent version axes — never conflate them:**
@@ -133,14 +145,21 @@ readiness. Canonical format:
    - `src/` (or equivalent) 2–3 levels deep → modules, routes/pages, components, services, types.
    - Tests (framework, location, E2E?) and linter rules.
    - Record: stack, package manager, daily commands (`dev`/`test`/`lint`/`type-check`), routes/pages, architecture layers.
-2. **Choose visibility — ASK the user explicitly and wait for the answer, before writing anything.** This decides what gets tracked and is hard to reverse after a commit, so never assume the default silently: `visible` (committed — canonical, recommended) or `hidden` (in-tree, hidden via `~/.gitignore_global`). See [Visibility contract](references/contracts.md#visibility-contract).
+2. **Choose visibility — ASK the user explicitly and wait for the answer, before writing anything.** This decides what gets tracked and is hard to reverse after a commit, so never assume the default silently: `visible` (committed — canonical, recommended) or `hidden` (in-tree, git-ignored via the **project-local** `.git/info/exclude` — one managed block covering the full AI/agent footprint, never the machine-global excludes). See [Visibility contract](references/contracts.md#visibility-contract).
 3. **Choose conversational language — ASK the user explicitly and wait for the answer.** Which language should the agent *talk to them* in — questions, explanations, summaries, status updates? Offer the language they're already writing in as the default. Carry the answer into the `{{COMM_LANGUAGE}}` slot of the *Communication language* block when `AGENTS.md` is created (step 5). See [Communication contract](references/contracts.md#communication-contract). This sets the **dialogue** language only — never the files.
 4. **Choose agent attribution — ASK the user explicitly and wait for the answer.** May the agent attribute work to itself / to AI — `Co-Authored-By` trailers, "Generated with …" footers, "AI"/agent/model mentions in code, comments, commit messages, PR titles/bodies, or docs? **Default to `off`** (no agent/AI mention anywhere) unless they opt in — people are routinely surprised to find an AI listed as a repo contributor. Carry the answer into the `{{AGENT_ATTRIBUTION}}` slot of the *Attribution* block when `AGENTS.md` is created (step 5). **If `off` and the project uses Claude Code**, also set `"includeCoAuthoredBy": false` in the project's `.claude/settings.json` (create it if absent) — the trailer is added by the harness, so a doc directive alone won't stop it. See [Attribution contract](references/contracts.md#attribution-contract).
 5. **Entry-point doc.** If `AGENTS.md` / `CLAUDE.md` already exist (step-1 recon), do **not** overwrite — show the user and ask whether to merge or replace. Otherwise create `AGENTS.md` (the cross-agent standard — Codex / Cursor / Devin Desktop / Copilot read it natively) from `${CLAUDE_SKILL_DIR}/references/templates/AGENTS.md`, and symlink `CLAUDE.md -> AGENTS.md` (`ln -s AGENTS.md CLAUDE.md`) for Claude Code — single source, no duplication. For nested context, add a subdir `AGENTS.md` (+ a `CLAUDE.md` symlink beside it for Claude Code).
 6. **Deploy `docs/ai/`.** Create the 11 files + `pages/` from `${CLAUDE_SKILL_DIR}/references/templates/`. Keep each file's frontmatter (`type / lastUpdated / scope / staleAfter / owner / maxLines`).
 7. **Fill templates** per the table below.
 8. **Install enforcement (Node projects).** Copy `${CLAUDE_SKILL_DIR}/references/scripts/*.mjs` (+ `*.test.mjs`) into the project's `scripts/`. They self-configure (project name from `package.json`, hierarchical/on-demand sections auto-discovered). **If the project has no Node runtime** (step-1 recon), skip this step and the hook in step 9 — follow the cap/archive/index policy manually, or port the scripts to the project's language.
-9. **Wire / hide** per visibility (see contract). Install the pre-commit hook (Node projects): `node scripts/install-git-hooks.mjs`. If the installer reports a pre-existing non-marker hook, stop and ask the user to merge it manually rather than overwriting.
+9. **Wire / hide** per visibility (see [Visibility contract](references/contracts.md#visibility-contract)). Install the pre-commit hook (Node projects): `node scripts/install-git-hooks.mjs`. If the installer reports a pre-existing non-marker hook, stop and ask the user to merge it manually rather than overwriting.
+   - **visible** — wire the `package.json` scripts + add the minimal `.gitignore`. **Do not run the hide tool.**
+   - **hidden** — run the kit's hide writer (one managed block in the **project-local** `.git/info/exclude`, covering the kit's own artifacts **and** every known AI/agent tool's footprint — never the machine-global excludes): `node ${CLAUDE_SKILL_DIR}/tools/hide-footprint.mjs --dir <project> --dry-run` **first** (changes nothing, prints the plan), then the same without `--dry-run`. Handle what it surfaces, in plain language (never the tool's internal terms):
+     - A path it reports as **already committed** can't be hidden by ignoring it and is **never un-tracked silently** — show the user the printed `git rm --cached <path>`, let them decide, then opt it in with `--include=<path>`.
+     - A **present file with a generic name** it flags (e.g. `GEMINI.md`) → ask before `--include=<path>`.
+     - If it reports a **leftover machine-wide ignore block** from an older deployment, **ask before removing it** — it could affect another of the user's repos that relies on the same machine-wide rules; on a yes, re-run with `--remove-global` (prints a restorable backup). Otherwise it is kept (harmless — the project-local rules win).
+     - Report the result plainly (what is now hidden). **No Node on the agent host** → write the one managed block into `.git/info/exclude` by hand from the contract's path list, and report the manual step. **Windows is supported.**
+   - **Do not edit `package.json`** in hidden mode — a tracked change leaks the whole system.
 10. **Stamp the deployment lineage.** Write the **deployment-lineage head** into
     `docs/ai/.workflow-version` (one semver line). The lineage head is **`1.3.0`** — the shared
     `agent-workflow` deployment lineage, **NOT** this kit's npm package version (see
@@ -164,13 +183,21 @@ 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`.
-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 (slot reconcile) ran first and may have changed the file, so this is a proper exit report, not a no-op:
-   - **Report step 3's outcome in plain language** — the workflow-methodology pointer was *added*, was *already present* (nothing changed), or was *skipped because the entry point is over its line limit* (the cap-refusal soft-skip from step 3, with its reason). Plain wording only — never the reconcile/slot/anchor/marker terms (Gotcha: never leak kit internals).
+   (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:
+   - **Report step 3's outcome in plain language** — the workflow-methodology pointer was *added*, was *already present* (nothing changed), or was *skipped because the entry point is over its line limit* (the cap-refusal soft-skip from step 3, with its reason); and, for a hidden deployment, whether the hidden-mode footprint was *moved to project-local*, was *already project-local* (nothing changed), or needed a question (ambiguous visibility / a leftover machine-wide block). Plain wording only — never the reconcile/slot/anchor/marker terms (Gotcha: never leak kit internals).
    - **Print the one-line backend-status line** — the shared contract above (run `node ${CLAUDE_SKILL_DIR}/tools/detect-backends.mjs`; same format, invariants, and detector-unavailable skip-with-reason).
    - **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, say **"already up to date"** and still print the read-only backend line.
 5. Show the relevant `${CLAUDE_SKILL_DIR}/CHANGELOG.md` diff (entries newer than the project's stamp).
@@ -217,6 +244,7 @@ The non-obvious traps — scan these before bootstrapping or upgrading. Each is
 - **Source vs target directory.** Templates and scripts are read from the skill's own dir (`${CLAUDE_SKILL_DIR}/` in Claude Code, the `SKILL.md` folder elsewhere). The **working directory is the target project** — never write kernel files back into the skill.
 - **The `Co-Authored-By` trailer is added by the harness, not by prose.** When attribution is `off`, a doc directive alone won't stop it — for Claude Code you **must** also set `"includeCoAuthoredBy": false` in the project's `.claude/settings.json` (create it if absent). Other tools: disable their equivalent co-author/footer setting.
 - **Hidden mode must never touch `package.json`.** Editing it is a *tracked* change and leaks the whole system. Hidden mode wires nothing into `package.json`; the pre-commit hook (untracked in `.git/hooks/`) calls `node scripts/<x>.mjs` directly. After hiding, **verify `git status` shows the artifacts as ignored**.
+- **Hidden mode is project-local, and the hide tool owns the known footprint.** `tools/hide-footprint.mjs` writes **one managed block** in the **project-local `.git/info/exclude`** — never the machine-global `core.excludesFile` (which would silently affect every repo on the host; **AD-014** amends **AD-006**). It hides the kit's own artifacts **and** the known external AI/agent footprint (the `KNOWN_FOOTPRINT` table in [contracts](references/contracts.md#visibility-contract)). A **tracked** file is **never silently un-tracked** — the tool prints the `git rm --cached` it will not run. Never leak its internal marker / asks terms to the user; translate every outcome to plain language.
 - **`CLAUDE.md` is a symlink, not a copy.** `ln -s AGENTS.md CLAUDE.md` — single source, no duplication. A copy drifts; a symlink can't.
 - **Never overwrite an existing entry point or hook.** If `AGENTS.md` / `CLAUDE.md` already exist, or the installer reports a pre-existing non-marker git hook, **stop and ask** the user to merge vs replace — don't clobber.
 - **No Node runtime → skip enforcement.** If the project has no Node (recon step 1), skip bootstrap steps 8–9 (scripts + hook) and follow the cap/archive/index policy manually, or port the scripts to the project's language.
@@ -273,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), 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").