@sabaiway/agent-workflow-kit 1.15.0 → 1.15.2

package/CHANGELOG.md

@@ -4,6 +4,49 @@ 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.15.2 — Strip the package's own tests + fixtures from the npm tarball (kit)
+
+Packaging only — no API/behaviour change; removed the package's own colocated tests + fixtures from
+the published tarball, deploy/mirror payload tests retained. The deployment-lineage head stays
+**`1.3.0`** (no `docs/ai` structural change, no migration file). The kit **package** version is a
+separate axis.
+
+- **`files[]` scoped negation.** Appended `!bin/*.test.mjs`, `!tools/**/*.test.mjs`, and
+  `!tools/manifest/fixtures/**` to the package allowlist (npm ignores a root `.npmignore` when
+  `files[]` is present, so negation entries in `files[]` are the mechanism). Tarball **115 → 69
+  files**: 18 of the package's own colocated tests + 28 manifest fixtures no longer ship.
+- **Deploy/mirror payload tests retained.** `references/scripts/*.test.mjs` (deployed into a
+  consumer repo's `scripts/` with the docs-rotation scripts) and
+  `bridges/antigravity-cli-bridge/bin/agy.test.mjs` (part of the byte-identical bridge mirror the
+  installed kit links from) still ship — a blanket `!**/*.test.mjs` would have silently broken
+  installs, so the negation is deliberately scoped. **Never broaden it to `!references/**` or
+  `!bridges/**`.**
+- **New tarball guard.** `test/package-content.test.mjs` (dev-only; outside `files[]`, never ships)
+  pins the exact shape via `npm pack --dry-run --json`: no own-test/fixture leak, payload tests +
+  runtime files present, exact file count `=== 69`.
+- Test files stay on disk; the gate + publish CI run them from the checkout, unchanged. This is a
+  tarball-only exclusion.
+
+## 1.15.1 — Version-axis clarity, hidden-mode invariant, lineage-head drift guard (kit)
+
+Patch: documentation + a regression guard; no behaviour change to shipped tooling, and the
+deployment-lineage head stays **`1.3.0`** (no `docs/ai` structural change, no migration file). The
+kit **package** version is a separate axis.
+
+- **`upgrade` now names the version axis in its report.** Steps 4 (equal-head exit) and 8 (re-stamp)
+  state that a project's stamp tracks the **deployment-lineage head** (`1.3.0`) — a separate axis from
+  the kit **package** version on npm/GitHub — so an equal-head report is no longer mistaken for a
+  stale deployment when GitHub shows a higher package number. A packaging-only release bumps the
+  package without moving the head; the head advances only when the deployed `docs/ai` structure does.
+- **Hidden-mode maintenance invariant made explicit (Visibility contract).** Hidden mode changes only
+  what *git* sees — never the agent's duty to read/maintain `docs/ai`. "Git-ignored / `git status`
+  clean" is **not** "optional to update"; those updates simply live on disk and never enter a commit.
+- **New cross-package drift guard** (`test/lineage-head-drift.test.mjs`): asserts the kit's
+  `EXPECTED_WORKFLOW_VERSION` equals the canonical `LINEAGE_HEAD` in `agent-workflow-memory`, so a
+  future head bump can't silently desync the two duplicated literals (which would make
+  `velocity --apply` reject a correctly-upgraded project). Runs in the gate; lives outside the package
+  `files` whitelist, so it is never shipped.
+
 ## 1.15.0 — Velocity-profile onboarding (kit)
 
 An opt-in **`/agent-workflow-kit velocity`** mode seeds a fixed, audited **read-only** Claude Code

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.15.0'
+  version: '1.15.2'
 ---
 
 # agent-workflow-kit
@@ -219,12 +219,13 @@ Fill strategy:
    **Orchestration config ensure — stamp-independent, same gate, BEFORE the equal-head short-circuit.** Ensure `docs/ai/orchestration.json` exists: **create it if missing**, **preserve it byte-for-byte if it already exists** (a user may have edited it — never clobber it). In the **delegated** path memory does this from its own template (memory upgrade step 2); in the **fallback** path the kit seeds it from `${CLAUDE_SKILL_DIR}/references/templates/orchestration.json`. Like the pointer slots + the footprint reconcile, this lets an equal-head (`1.3.0`) deployment gain the config seed **without a lineage-head bump or a migration file** (it is a `.json`, inherently outside the docs cap-validator). Report it in the step 4 / step 8 success report (config *seeded* vs *already present*).
 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** — for **each** pointer (workflow-methodology and orchestration-recipes) whether it 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); whether the `docs/ai/orchestration.json` config was *seeded* or was *already present* (a user edit is preserved); 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).
+   - **Name the version axis so the package number isn't mistaken for a newer release.** When you state the deployment is up to date, say it is current at the **deployment-lineage head** (`1.3.0`) and add one plain line: this head versions the deployed `docs/ai` structure and is a **separate axis** from the kit **package** version published on npm/GitHub (the larger number users see on the repo/npm page). A packaging-only release can bump that package version **without** moving the head — the head advances only when the deployed `docs/ai` structure changes — so an equal-head report is **not** a stale deployment even though GitHub shows a higher package number. (This is the only place the two axes meet the user in `upgrade`; surfacing it here prevents the recurring "but GitHub shows a higher version" confusion.)
    - **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).
 6. Apply `${CLAUDE_SKILL_DIR}/migrations/<version>-<slug>.md` in **semver order**, only those newer than the project's stamp. Migrations are **idempotent** — safe to re-run.
 7. Reconcile drift: add any kernel files/scripts the project is missing; never clobber project-authored content (their `decisions.md`, `known_issues.md`, page specs stay). Any user question a migration raises follows the same rule as bootstrap — **structured multiple-choice where supported** (`AskUserQuestion` in Claude Code), otherwise prose. If `AGENTS.md` has no *Communication language* block (pre-1.1.0 deployment), **ask the user their conversational language** and insert the block — see `migrations/1.1.0-communication-language.md`. If it has no *Attribution* block (pre-1.2.0 deployment), **ask whether the agent may attribute work to itself / AI** and insert the block (defaulting to `off`) — see `migrations/1.2.0-agent-attribution.md`.
-8. Re-stamp `docs/ai/.workflow-version` to the **deployment-lineage head** (`1.3.0`, not the package version). Report changes, then **print the one-line backend-status line** (the shared contract above — same detector, format, invariants, and detector-unavailable skip-with-reason). Then **ask before committing**.
+8. Re-stamp `docs/ai/.workflow-version` to the **deployment-lineage head** (`1.3.0`, not the package version). Report changes — and when you report the stamp, **name the axis**: the head versions the deployed `docs/ai` structure and is a separate axis from the kit **package** version on npm/GitHub (the larger number users see there), so the user doesn't read the bigger package number as a newer deployment (same framing as the step 4 equal-head exit). Then **print the one-line backend-status line** (the shared contract above — same detector, format, invariants, and detector-unavailable skip-with-reason). Then **ask before committing**.
 
 ### Mode: backends
 

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.15.0",
+  "version": "1.15.2",
   "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",
@@ -50,7 +50,10 @@
     "launchers/",
     "migrations/",
     "tools/",
-    "bridges/"
+    "bridges/",
+    "!bin/*.test.mjs",
+    "!tools/**/*.test.mjs",
+    "!tools/manifest/fixtures/**"
   ],
   "engines": {
     "node": ">=18"

package/references/contracts.md

@@ -19,6 +19,8 @@ diverge:
 - **visible** — artifacts are committed. Wire the project's `package.json` scripts (`docs:check` / `docs:index` / `docs:index:check` / `docs:archive` / `docs:archive:check` / `docs:archive:issues` / `docs:archive:issues:check` / `prepare: node scripts/install-git-hooks.mjs`) and add a minimal `.gitignore` (`docs/plans/`, `.claude/settings.local.json`). This is the canonical model.
 - **hidden** (in-tree) — same files on disk, but the repo "looks normal": the AI/agent footprint is git-ignored via **one managed block in the project-local `.git/info/exclude`** (resolved with `git rev-parse --git-path info/exclude` — never the machine-global `core.excludesFile`, which would affect every repo on the host; **AD-014** amends **AD-006**). The kit's `tools/hide-footprint.mjs` is the single writer: it covers `KIT_OWN_PATHS ∪ the present subset of KNOWN_FOOTPRINT` (the full footprint table below — the kit's own artifacts **and** every other AI/agent tool's files). Per path: a **tracked** file → **ASK** (an exclude does nothing for it; only `git rm --cached` un-tracks it — the tool prints that command and never runs it); an untracked path already covered by a **tracked `.gitignore`** → dropped (redundant); a **present** file whose name is generic enough to be ambiguous (`falsePositiveRisk`) → **ASK**; everything else → **hidden**. `asks` are excluded from the block unless explicitly opted in. **Verify** treats a path as hidden only when it is **untracked AND ignored by our project-local block** (or a tracked `.gitignore`) — being ignored by the global excludes does **not** count. Re-running re-derives the block wholesale (sorted/deduped) → a clean re-run is a **zero-diff** no-op. On an existing global-excludes deployment the tool **detects + reports the residual legacy machine-global block and keeps it by default** (a harmless double-ignore; the local block wins precedence); removal is the explicit `--remove-global` (it prints the removed lines as a restorable backup), which **the agent only runs after asking** — another of the user's hidden repos on the same host may rely on the same root-anchored global lines. **Do not edit `package.json`** — that is a tracked change and would leak; the pre-commit hook (always untracked in `.git/hooks/`) calls the scripts via `node scripts/<x>.mjs` directly. Windows is supported (text edit, no symlinks; CRLF preserved).
 
+**Visibility changes what git sees — never how the agent works (the load-bearing invariant).** Both modes carry the **same** working memory and run the **same** session protocol: `docs/ai` and the deployed workflow artifacts (`AGENTS.md`, the added `scripts/`) are read at session start and maintained on task completion **identically** whether visible or hidden. (Hidden mode git-ignores a *wider* footprint — other AI/agent tools' files too — but that is only a **visibility** surface; the working memory the agent actually reads and maintains is `docs/ai` plus those artifacts.) Hidden mode only makes the repo *look* normal to git; it is **never** a license to skip, defer, or down-prioritise a doc/state update. The single difference is the destination: in hidden mode those updates live on disk and never enter a commit (the footprint is excluded), so a commit there carries only the project's own tracked files while `docs/ai` is still kept current locally — **git-ignored ≠ optional-to-maintain**. An agent that reads "git-ignored / `git status` clean" and infers the working memory is optional has the model backwards. (This is why bootstrap/upgrade never wire hidden-mode docs into a commit, yet the session protocol still mandates maintaining them.)
+
 **Known AI/agent footprint** (the `KNOWN_FOOTPRINT` registry in `tools/known-footprint.mjs`; this table is its human mirror, kept in sync by review — D11):
 
 | Pattern | Owner | Kind | Commit-risk name? | Note |

package/bin/install.test.mjs

@@ -1,347 +0,0 @@
-import { describe, it, beforeEach, afterEach } from 'node:test';
-import assert from 'node:assert/strict';
-import { spawnSync } from 'node:child_process';
-import { mkdtemp, rm, mkdir, symlink, readdir, readFile, writeFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-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; --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', '--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.
-const setInstalledVersion = async (target, v) => {
-  const p = join(target, 'SKILL.md');
-  const text = await readFile(p, 'utf8');
-  await writeFile(p, text.replace(/version:\s*['"]?\d+\.\d+\.\d+['"]?/, `version: '${v}'`));
-};
-const getInstalledVersion = async (target) =>
-  (await readFile(join(target, 'SKILL.md'), 'utf8')).match(/version:\s*['"]?(\d+\.\d+\.\d+)['"]?/)?.[1] ?? null;
-const pkgVersion = async () =>
-  JSON.parse(await readFile(join(KIT_ROOT, 'package.json'), 'utf8')).version;
-
-describe('kit installer — payload + symlink-traversal hardening', () => {
-  let dir;
-  beforeEach(async () => {
-    dir = await mkdtemp(join(tmpdir(), 'aw-kit-install-'));
-  });
-  afterEach(async () => {
-    await rm(dir, { recursive: true, force: true });
-  });
-
-  it('installs the critical payload (capability.json + tools/ + references/) and not the npm wrapper', () => {
-    const target = join(dir, 'agent-workflow-kit');
-    const res = runInstaller(target);
-    assert.equal(res.status, 0, res.stderr);
-    for (const f of ['SKILL.md', 'capability.json', 'tools/manifest/validate.mjs', 'tools/delegation.mjs', 'references']) {
-      assert.ok(existsSync(join(target, f)), `missing installed entry: ${f}`);
-    }
-    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');
-    await mkdir(target, { recursive: true });
-    await mkdir(evil, { recursive: true });
-    await symlink(evil, join(target, 'references'));
-    const res = runInstaller(target);
-    assert.notEqual(res.status, 0);
-    assert.match(res.stderr, /symlink/i);
-    assert.deepEqual(await readdir(evil), []);
-  });
-
-  it('refuses a DANGLING destination symlink', async () => {
-    const target = join(dir, 'target');
-    await mkdir(target, { recursive: true });
-    await symlink(join(dir, 'nowhere'), join(target, 'references'));
-    const res = runInstaller(target);
-    assert.notEqual(res.status, 0);
-    assert.match(res.stderr, /symlink/i);
-    assert.equal(existsSync(join(dir, 'nowhere')), false);
-  });
-
-  it('refuses a symlinked TARGET root (no leak)', async () => {
-    const real = join(dir, 'real');
-    const root = join(dir, 'root');
-    await mkdir(real, { recursive: true });
-    await symlink(real, root);
-    const res = runInstaller(root);
-    assert.notEqual(res.status, 0);
-    assert.match(res.stderr, /symlink/i);
-    assert.deepEqual(await readdir(real), []);
-  });
-});
-
-describe('kit installer — runs through the npx bin symlink', () => {
-  let dir;
-  beforeEach(async () => {
-    dir = await mkdtemp(join(tmpdir(), 'aw-kit-symlink-'));
-  });
-  afterEach(async () => {
-    await rm(dir, { recursive: true, force: true });
-  });
-
-  it('main() runs when invoked through a symlink (the node_modules/.bin shim npx uses)', async () => {
-    // npx never runs bin/install.mjs by its real path — it runs node_modules/.bin/agent-workflow-kit,
-    // a symlink to it. Node resolves import.meta.url to the REAL file but leaves argv[1] as the symlink,
-    // so a string compare of the two makes isDirectRun false and main() silently no-ops. Reproduce that
-    // exact invocation: run the installer via a symlink and assert it actually installed (visible output
-    // + payload on disk). A regression here means `npx … init` goes quiet again.
-    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', '--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');
-  });
-});
-
-describe('kit installer — module hygiene', () => {
-  it('importing install.mjs runs nothing (main() is guarded by isDirectRun)', () => {
-    // `node -e` has no argv[1], so isDirectRun is false → importing must not run main()
-    // (no FS writes, no exit). A child process keeps the assertion off the test runner's own state.
-    const url = JSON.stringify(pathToFileURL(INSTALLER).href);
-    const res = spawnSync(
-      process.execPath,
-      ['--input-type=module', '-e', `import(${url}).then(() => console.log('IMPORT_OK'));`],
-      { encoding: 'utf8' },
-    );
-    assert.equal(res.status, 0, res.stderr);
-    assert.match(res.stdout, /IMPORT_OK/);
-    assert.doesNotMatch(res.stdout, /installed v|updated the kit/);
-  });
-});
-
-describe('kit installer — stale-cache defenses (no network)', () => {
-  let dir;
-  beforeEach(async () => {
-    dir = await mkdtemp(join(tmpdir(), 'aw-kit-stale-'));
-  });
-  afterEach(async () => {
-    await rm(dir, { recursive: true, force: true });
-  });
-
-  it('a no-op re-run (same version) flags the likely npx cache and points at @latest', async () => {
-    const target = join(dir, 'agent-workflow-kit');
-    assert.equal(runInstaller(target).status, 0); // first install
-    const again = runInstaller(target); // second run: installed == running
-    assert.equal(again.status, 0, again.stderr);
-    assert.match(again.stdout, /no version change/i);
-    assert.match(again.stdout, /cache/i);
-    assert.match(again.stdout, /@latest/);
-  });
-
-  it('refuses to downgrade when the installed kit is NEWER, and writes nothing', async () => {
-    const target = join(dir, 'agent-workflow-kit');
-    assert.equal(runInstaller(target).status, 0);
-    await setInstalledVersion(target, '99.0.0'); // pretend a newer kit is already installed
-    const res = runInstaller(target); // running version < installed → downgrade
-    assert.notEqual(res.status, 0);
-    assert.match(res.stderr, /downgrade/i);
-    assert.match(res.stderr, /@latest/);
-    assert.equal(await getInstalledVersion(target), '99.0.0', 'newer install must be left untouched');
-  });
-
-  it('--allow-downgrade overrides the refusal and overwrites with the runner version', async () => {
-    const target = join(dir, 'agent-workflow-kit');
-    assert.equal(runInstaller(target).status, 0);
-    await setInstalledVersion(target, '99.0.0');
-    const res = runInstaller(target, ['--allow-downgrade']);
-    assert.equal(res.status, 0, res.stderr);
-    assert.equal(await getInstalledVersion(target), await pkgVersion());
-  });
-
-  it('--force alone does NOT override the downgrade gate (the override is its own flag)', async () => {
-    const target = join(dir, 'agent-workflow-kit');
-    assert.equal(runInstaller(target).status, 0);
-    await setInstalledVersion(target, '99.0.0');
-    const res = runInstaller(target, ['--force']); // launcher-clobber flag, not the gate override
-    assert.notEqual(res.status, 0, 'launcher --force must not silently clear the version gate');
-    assert.equal(await getInstalledVersion(target), '99.0.0', 'newer install must be left untouched');
-  });
-
-  it('reads the version under `metadata:`, never a top-level / nested decoy `version:`', async () => {
-    // A crafted SKILL.md whose REAL metadata.version (0.0.1) is OLDER than the runner, but with decoy
-    // `version:` lines that are NEWER. A naive "first version: in frontmatter" read would see 99.0.0
-    // and wrongly refuse; the correct read sees 0.0.1 → a normal upgrade (exit 0).
-    const target = join(dir, 'agent-workflow-kit');
-    await mkdir(target, { recursive: true });
-    const decoy = [
-      '---',
-      "version: '99.0.0'", // top-level decoy (column 0)
-      'name: agent-workflow-kit',
-      'metadata:',
-      '  nested:',
-      "    version: '98.0.0'", // deeper-nested decoy
-      "  version: '0.0.1'", // the authoritative direct child
-      '---',
-      '# decoy',
-      '',
-    ].join('\n');
-    await writeFile(join(target, 'SKILL.md'), decoy);
-    const res = runInstaller(target);
-    assert.equal(res.status, 0, `expected a normal upgrade (read 0.0.1), got: ${res.stderr}`);
-    assert.match(res.stdout, /updated the kit to/);
-  });
-
-  it('fails closed (does not silently treat as legacy) when an existing SKILL.md cannot be read', async () => {
-    // SKILL.md present but unreadable (a directory → EISDIR on read). The gate must NOT be bypassed:
-    // we refuse rather than overwrite a kit whose version we could not determine (no silent failure).
-    const target = join(dir, 'agent-workflow-kit');
-    await mkdir(join(target, 'SKILL.md'), { recursive: true });
-    const res = runInstaller(target);
-    assert.notEqual(res.status, 0);
-    assert.match(res.stderr, /cannot read the installed SKILL\.md/i);
-  });
-
-  it('a legacy install with no version stamp still upgrades (no false downgrade, no crash)', async () => {
-    const target = join(dir, 'agent-workflow-kit');
-    await mkdir(target, { recursive: true });
-    await writeFile(join(target, 'SKILL.md'), '---\nname: agent-workflow-kit\n---\n# legacy stub\n');
-    const res = runInstaller(target);
-    assert.equal(res.status, 0, res.stderr);
-    assert.match(res.stdout, /updated the kit to/);
-  });
-});
-
-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' });
-    assert.equal(res.status, 0, res.stderr || res.error?.message);
-    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/tools/delegation.test.mjs

@@ -1,116 +0,0 @@
-import { describe, it } from 'node:test';
-import assert from 'node:assert/strict';
-import { detectMemory, handoffPlan, REQUIRED_MEMORY_ASSETS } from './delegation.mjs';
-
-// Inject a fake validator + fs so the decision matrix is tested independent of real files/agents.
-const fakeValidate = (over = {}) => () => ({
-  result: 'valid',
-  kind: 'memory-substrate',
-  name: 'agent-workflow-memory',
-  available: true,
-  errors: [],
-  ...over,
-});
-const ASSET_TYPE = {
-  'references/templates': 'dir',
-  'references/contracts.md': 'file',
-  'references/scripts': 'dir',
-  'scripts/stamp-takeover.mjs': 'file',
-  migrations: 'dir',
-  'capability.json': 'file',
-};
-const typeFor = (p) => {
-  for (const [k, t] of Object.entries(ASSET_TYPE)) if (p.endsWith(k)) return t;
-  return 'file';
-};
-const allPresent = (p) => typeFor(p);
-const missing = (absent) => (p) => (absent.some((a) => p.endsWith(a)) ? null : typeFor(p));
-const wrongType = (paths) => (p) => {
-  for (const [k, t] of Object.entries(ASSET_TYPE)) {
-    if (p.endsWith(k)) return paths.includes(k) ? (t === 'dir' ? 'file' : 'dir') : t;
-  }
-  return 'file';
-};
-
-describe('detectMemory — decision matrix', () => {
-  it('valid + memory-substrate + right name + available + all assets → delegate', () => {
-    const d = detectMemory('/m', { validate: fakeValidate(), statType: allPresent });
-    assert.equal(d.delegate, true);
-  });
-
-  it('invalid manifest → fallback', () => {
-    const d = detectMemory('/m', { validate: fakeValidate({ result: 'invalid' }), statType: allPresent });
-    assert.equal(d.delegate, false);
-    assert.match(d.reason, /invalid/);
-  });
-
-  it('unsupported schema → fallback (treated like invalid)', () => {
-    const d = detectMemory('/m', { validate: fakeValidate({ result: 'unsupported' }), statType: allPresent });
-    assert.equal(d.delegate, false);
-  });
-
-  it('wrong kind → fallback', () => {
-    const d = detectMemory('/m', { validate: fakeValidate({ kind: 'composition-root' }), statType: allPresent });
-    assert.equal(d.delegate, false);
-    assert.match(d.reason, /not memory-substrate/);
-  });
-
-  it('wrong name → fallback (even if kind + assets are right)', () => {
-    const d = detectMemory('/m', { validate: fakeValidate({ name: 'evil-substrate' }), statType: allPresent });
-    assert.equal(d.delegate, false);
-    assert.match(d.reason, /name/);
-  });
-
-  it('available:false stub → fallback', () => {
-    const d = detectMemory('/m', { validate: fakeValidate({ available: false }), statType: allPresent });
-    assert.equal(d.delegate, false);
-    assert.match(d.reason, /stub/);
-  });
-
-  it('partial install (missing stamp-takeover) → fallback', () => {
-    const d = detectMemory('/m', {
-      validate: fakeValidate(),
-      statType: missing(['scripts/stamp-takeover.mjs']),
-    });
-    assert.equal(d.delegate, false);
-    assert.match(d.reason, /stamp-takeover/);
-  });
-
-  it('wrong-type asset (templates is a file, not a dir) → fallback', () => {
-    const d = detectMemory('/m', { validate: fakeValidate(), statType: wrongType(['references/templates']) });
-    assert.equal(d.delegate, false);
-    assert.match(d.reason, /references\/templates/);
-  });
-
-  it('required assets use real (references/) paths', () => {
-    const paths = REQUIRED_MEMORY_ASSETS.map((a) => a.path);
-    assert.ok(paths.includes('references/templates'));
-    assert.ok(paths.includes('references/contracts.md'));
-  });
-});
-
-describe('handoffPlan — stamp sets + single commit gate', () => {
-  it('delegate → both stamps present; memory never raises its own commit gate', () => {
-    const p = handoffPlan(true);
-    assert.deepEqual(p.stampsPresent, ['.memory-version', '.workflow-version']);
-    assert.equal(p.memoryRaisesCommitGate, false);
-    assert.equal(p.commitGate, 'kit-only-after-injection');
-    assert.ok(p.memoryWrites.includes('docs/ai/.memory-version'));
-    // Delegate is the ONLY branch with a real slot (memory ships it empty; the kit injects).
-    assert.ok(p.kitWrites.some((w) => w.includes('slot')), 'delegate kitWrites should name the methodology slot');
-  });
-
-  it('fallback → only .workflow-version; kit writes everything; one kit gate', () => {
-    const p = handoffPlan(false);
-    assert.deepEqual(p.stampsPresent, ['.workflow-version']);
-    assert.deepEqual(p.memoryWrites, []);
-    assert.equal(p.memoryRaisesCommitGate, false);
-    assert.equal(p.commitGate, 'kit-only-after-injection');
-    // Fallback now ships the kit's own AGENTS.md with the EMPTY methodology slot, which the kit
-    // reconciles + fills — the same slot mechanism as the delegate path (Plan 2).
-    assert.ok(
-      p.kitWrites.some((w) => w.includes('slot')) && !p.kitWrites.some((w) => w.includes('inline')),
-      'fallback kitWrites should describe the methodology slot, not inline methodology',
-    );
-  });
-});