@sabaiway/agent-workflow-kit 1.7.0 → 1.8.1

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.8.1 — Fix: `npx … init` ran nothing (the installer's own run-guard mis-fired under npx)
+
+1.8.0 set out to fix "`npx <pkg> init` quietly did nothing" — and shipped a *second*, unrelated
+silent no-op in the same spot. The reported symptom: `npx @sabaiway/agent-workflow-kit@latest init`
+installs the package, prints the npx "Ok to proceed?" line, and then **prints nothing and does
+nothing** — none of 1.8.0's new DX messaging, no install, exit 0.
+
+Root cause: the bottom-of-file run-guard that gates `main()` so importing the module has no side
+effects:
+
+```js
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+```
+
+npx never runs `bin/install.mjs` by its real path — it runs the `node_modules/.bin/agent-workflow-kit`
+**symlink** to it. Node resolves `import.meta.url` to the real file but leaves `process.argv[1]` as the
+symlink path, so the string compare is always false, `main()` never runs, and the process exits 0
+without a word. (Running `node bin/install.mjs` directly — as the test suite did — has no symlink, which
+is why every test passed while real `npx` was broken.)
+
+- **Fix:** the guard now compares **real paths** (`realpathSync` on both sides), which collapses the
+  `.bin` symlink so direct and npx invocations both register as a direct run; it also holds under
+  `--preserve-symlinks`. Import-with-no-`argv[1]` and a missing file still fall through to `false`, so
+  importing the module continues to run nothing.
+- **Regression test:** a new case invokes the installer **through a symlink** (the exact `.bin` shim
+  npx uses) and asserts it both prints and writes the payload — the previous suite never exercised a
+  symlinked invocation, so the bug slipped through.
+
+Installer bugfix only — no `docs/ai` structural change, deployment-lineage head stays **`1.3.0`**, no
+migration.
+
+## 1.8.0 — Stale-version DX: `@latest` everywhere + a no-network never-downgrade gate
+
+A returning user ran the headline `npx @sabaiway/agent-workflow-kit init` and it quietly did nothing:
+a bare `npx <pkg> init` (no `@latest`) reuses the npx cache and re-runs an **older cached build** of
+the installer, which exits 0 and reports it "updated" — to the same stale version. This release makes
+that mistake hard to miss while **the installer itself stays 100% network-free** — the only thing
+that ever contacts npm is npx resolving `@latest`, exactly as it already does (the no-phone-home
+principle is preserved; see AD-012):
+
+- **`@latest` is the documented default everywhere.** Every prescribing surface (both READMEs, the
+  bridge `SKILL.md` files + their bundled mirrors, the installer `--help` / header) now shows
+  `npx @sabaiway/agent-workflow-kit@latest init`. A new drift guard
+  (`test/init-command-uses-latest.test.mjs`) fails the build if a bare form sneaks back in (historical
+  contexts — CHANGELOG / `releases/` / `migrations/` — are exempt).
+- **Never-downgrade gate (no network).** `init` reads the installed skill's version from
+  `SKILL.md` **before** writing; if the installed kit is **newer** than the version you ran (the exact
+  stale-cache signature), it **refuses** (nonzero) and points at `@latest`, rather than silently
+  overwriting a newer install with old code. `--force` overrides. A legacy install with no version
+  stamp still upgrades cleanly.
+- **No-op re-run hint.** When `init` refreshes the skill with the *same* version it already had, it
+  says so and points at `@latest` — the no-network signal that catches the reported scenario.
+- **In-agent skill** (`SKILL.md`): surfaces a one-line version status (project `docs/ai/.workflow-version`
+  vs the lineage head) + routes (bootstrap / upgrade / current), spells out the **two independent
+  version axes** (project deployment vs kit freshness — the latter is the npx installer's job, never
+  this skill's), and tells you to **restart the session** after refreshing the kit so the new skill
+  files load.
+
+New users are unaffected (an empty npx cache already fetches `latest`); this targets the returning-user
+trap. No `docs/ai` structural change → the deployment-lineage head stays **`1.3.0`**; no migration.
+
 ## 1.7.0 — Link-only backend auto-setup; bridges bundled in the tarball
 
 The optional execution-backend bridges (`codex-cli-bridge` → `codex`, `antigravity-cli-bridge` →

package/README.md

@@ -18,7 +18,7 @@ decisions. Works with Claude Code, Codex, Cursor, and any agent that reads `AGEN
 **One command to start:**
 
 ```bash
-npx @sabaiway/agent-workflow-kit init
+npx @sabaiway/agent-workflow-kit@latest init
 ```
 
 <sub>This installs the **global skill** — deploying into a project is a separate step ([below](#-install)).</sub>
@@ -134,7 +134,7 @@ Hidden changes how the files are *tracked*, not where agents find them.
 ### 1. Install the global skill — once per machine
 
 ```bash
-npx @sabaiway/agent-workflow-kit init
+npx @sabaiway/agent-workflow-kit@latest init
 ```
 
 `init` installs/refreshes the skill at `~/.claude/skills/agent-workflow-kit/` and wires launchers for

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.7.0'
+  version: '1.8.1'
 ---
 
 # agent-workflow-kit
@@ -85,6 +85,22 @@ Pick the mode from the user's invocation. Auto-detect an existing `docs/ai/` to
 - **`/agent-workflow-kit backends`** — read-only environment check: which optional **execution-backends** (the `codex` / `agy` bridges) are set up vs missing. Never writes, never commits, never runs a subscription CLI.
 - **`/agent-workflow-kit setup [backend]`** — the **link-only**, opt-in companion to `backends`: place the bundled bridge skill + link its wrappers onto `PATH`. **In-agent only** — `init` (npx) never places bridges. The binary install + the interactive subscription login stay **manual** (it prints the exact commands); idempotent; refuses to clobber a non-symlink; never commits, never runs a subscription CLI.
 
+### Version status & the two axes — surface this on every invocation
+
+Before acting, read `docs/ai/.workflow-version` (the project's stamp), state a one-line status, then route:
+
+- **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 > head / unparseable** → STOP — never-downgrade gate (see *Mode: upgrade* step 2).
+
+**Two independent version axes — never conflate them:**
+
+1. **Project deployment** — `docs/ai/.workflow-version` vs the lineage head (`1.3.0`). This is the **only** axis this skill compares.
+2. **Kit freshness** — this skill's own files vs the published npm package. That is the **npx installer's** job: `npx @sabaiway/agent-workflow-kit@latest init` (it refuses a stale-cache downgrade by comparing the version on disk — **no network**). This skill never checks npm, and the package version (e.g. `1.x`) is **not** the lineage head.
+
+**Refreshed the kit but nothing changed?** The skill you are running is whatever was on disk when the session started. After `npx @sabaiway/agent-workflow-kit@latest init` updates `~/.claude/skills/agent-workflow-kit/`, **restart the session** so the agent reloads the new skill files (the slash command + this `SKILL.md`).
+
 ### Mode: bootstrap
 
 > Bundled sources below (templates, scripts) live in **this skill's own directory** — `${CLAUDE_SKILL_DIR}/` in Claude Code, or the folder containing this `SKILL.md` in Codex / other agents. Use that as the copy/read source; the working directory is the **target project**, not the skill.

package/bin/install.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // One-shot installer for @sabaiway/agent-workflow-kit.
 //
-//   npx @sabaiway/agent-workflow-kit init
+//   npx @sabaiway/agent-workflow-kit@latest init
 //
 // Copies the kit into the canonical skill home (~/.claude/skills/agent-workflow-kit),
 // then runs the cross-agent launcher (auto-detects Codex / Devin Desktop — only touches tools
@@ -14,14 +14,18 @@
 // 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.
+// 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.
 //
 // Dependency-free, Node >= 18.
 
 import { readFile, mkdir } from 'node:fs/promises';
-import { existsSync, lstatSync } from 'node:fs';
+import { existsSync, lstatSync, realpathSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { copyTreeRefresh } from '../tools/fs-safe.mjs';
@@ -57,6 +61,58 @@ const readVersion = async () => {
   }
 };
 
+// Dependency-free semver: parse the leading `x.y.z` (prerelease/build ignored — kit versions are
+// plain). compareSemver returns -1 | 0 | 1, or null when either side is unparseable (legacy installs
+// predate any version stamp). No `let`: a small functional comparison (AGENTS.md §2.3).
+const parseSemver = (str) => {
+  const m = typeof str === 'string' ? str.trim().match(/^(\d+)\.(\d+)\.(\d+)/) : null;
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+};
+
+const compareSemver = (a, b) => {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (!pa || !pb) return null;
+  const firstDiff = [0, 1, 2].map((i) => (pa[i] === pb[i] ? 0 : pa[i] < pb[i] ? -1 : 1)).find((c) => c !== 0);
+  return firstDiff ?? 0;
+};
+
+// Extract the version that is a DIRECT child of the top-level `metadata:` key — never a top-level
+// or deeper-nested decoy `version:` (mirrors the manifest validator's rigor; the kit ships manifest
+// fixtures that probe exactly those decoys). Pure string walk over the frontmatter block, no deps.
+const metadataVersion = (frontmatter) => {
+  const lines = frontmatter.split(/\r?\n/);
+  const metaIdx = lines.findIndex((l) => /^metadata:[ \t]*$/.test(l));
+  if (metaIdx === -1) return null;
+  const after = lines.slice(metaIdx + 1);
+  const dedent = after.findIndex((l) => /^[^ \t]/.test(l)); // a column-0 line closes the metadata block
+  const block = dedent === -1 ? after : after.slice(0, dedent);
+  // Direct children share the first child's indent; a nested decoy is MORE indented, so a
+  // `<baseIndent>version:` prefix match excludes it. baseIndent is non-empty, so a top-level
+  // `version:` (column 0, and before `metadata:` anyway) is excluded too.
+  const baseIndent = block.length ? (block[0].match(/^[ \t]*/)?.[0] ?? '') : '';
+  const verLine = block.find((l) => l.startsWith(`${baseIndent}version:`));
+  return verLine?.match(/version:[ \t]*['"]?(\d+\.\d+\.\d+)['"]?/)?.[1] ?? null;
+};
+
+// The installed version is read from the target's SKILL.md frontmatter (`metadata.version`) — the
+// manifest's canonical `detect.installed.file`, present even on legacy installs that predate
+// capability.json. Returns the semver string, or null when ABSENT / has no parseable stamp (legacy
+// → no gate). A SKILL.md that EXISTS but cannot be read is NOT swallowed as "legacy": we fail closed
+// (throw) so the never-downgrade gate can never be silently bypassed (AGENTS.md: no silent failures).
+const readInstalledVersion = async (target) => {
+  const skill = resolve(target, 'SKILL.md');
+  if (!existsSync(skill)) return null; // absent → new/legacy install, nothing to compare
+  const text = await readFile(skill, 'utf8').catch((err) => {
+    throw new Error(
+      `[agent-workflow-kit] cannot read the installed SKILL.md (${tildify(skill)}): ${err.message}. ` +
+        `Refusing to install over an unreadable kit — fix permissions/contents or remove it, then re-run.`,
+    );
+  });
+  const fm = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  return fm ? metadataVersion(fm[1]) : null;
+};
+
 // lstat without following symlinks; null when absent. existsSync FOLLOWS symlinks (so a
 // *dangling* symlink reads as absent) — lstat is what lets the guard catch a dangling dest symlink.
 const lstatNoFollow = (path) => {
@@ -80,6 +136,7 @@ const parseArgs = (argv) => {
     version: argv.includes('--version') || argv.includes('-v'),
     noLaunchers: argv.includes('--no-launchers'),
     force: argv.includes('--force'),
+    allowDowngrade: argv.includes('--allow-downgrade'),
     dir: dirFlag >= 0 ? argv[dirFlag + 1] : undefined,
   };
 };
@@ -94,15 +151,20 @@ const printHelp = (version) => {
   console.log(`agent-workflow-kit ${version}
 
 Usage:
-  npx @sabaiway/agent-workflow-kit init [--dir <path>] [--no-launchers] [--force]
-  npx @sabaiway/agent-workflow-kit --version
-  npx @sabaiway/agent-workflow-kit --help
+  npx @sabaiway/agent-workflow-kit@latest init [--dir <path>] [--no-launchers] [--force] [--allow-downgrade]
+  npx @sabaiway/agent-workflow-kit@latest --version
+  npx @sabaiway/agent-workflow-kit@latest --help
+
+Use the @latest form: a bare \`npx … init\` (no @latest) can reuse an OLDER cached
+  build of this installer, so a returning user must bypass the npx cache to upgrade.
 
 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.
+  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
@@ -143,12 +205,46 @@ const main = async () => {
     console.error(`[agent-workflow-kit] target dir is a symlink — refusing to write through it: ${tildify(target)}`);
     process.exit(1);
   }
+
+  // Stale-cache defenses (no network — version already on disk vs this runner). Read BEFORE any
+  // write so a refusal touches nothing. cmp is null on a legacy/unparseable install → no gate.
+  const installedVersion = wasPresent ? await readInstalledVersion(target) : null;
+  const cmp = installedVersion ? compareSemver(installedVersion, version) : null;
+
+  // Never-downgrade gate: a bare `npx … init` can run an OLDER cached build of this installer, which
+  // would overwrite a NEWER installed skill with old code. Refuse loudly (nonzero) unless the
+  // dedicated --allow-downgrade override is passed — surfacing the cache trap instead of silently
+  // regressing the install (AGENTS.md: no silent failures). The override is its OWN flag, NOT --force:
+  // --force means "replace a foreign launcher file" and is forwarded to the launcher; conflating them
+  // would let someone clearing the version gate also clobber launchers by accident.
+  if (cmp === 1 && !args.allowDowngrade) {
+    console.error(
+      `[agent-workflow-kit] refusing to downgrade: the installed kit is v${installedVersion}, but this ` +
+        `runner is the OLDER v${version}.\n` +
+        `  This is the classic npx cache serving a stale build. To get the newest kit, bypass the cache:\n` +
+        `    npx @sabaiway/agent-workflow-kit@latest init\n` +
+        `  (or pass --allow-downgrade to overwrite the newer install with v${version} anyway).`,
+    );
+    process.exit(1);
+  }
+
   await mkdir(target, { recursive: true });
   for (const entry of PAYLOAD.filter((e) => existsSync(resolve(PKG_ROOT, e)))) {
     copyTreeRefresh(resolve(PKG_ROOT, entry), resolve(target, entry), target);
   }
   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
+  // user who ran `init` expecting an upgrade, that almost always means npx reused a cached build —
+  // say so explicitly and point at @latest (the no-network signal that catches the reported scenario).
+  if (cmp === 0) {
+    console.log(
+      `[agent-workflow-kit] note: no version change — the kit was already v${version}. If you expected ` +
+        `an update, npx likely served a cached build; re-run bypassing the cache:\n` +
+        `    npx @sabaiway/agent-workflow-kit@latest init`,
+    );
+  }
+
   // Wire non-Claude agents — best-effort; the launcher only touches tools you have.
   const launcher = resolve(target, 'launchers/install-launchers.sh');
   if (args.noLaunchers) {
@@ -178,7 +274,22 @@ To update the kit later, re-run:  npx @sabaiway/agent-workflow-kit@latest init`)
 
 // Run main() only when executed directly (npx / node bin/install.mjs), never on import — so tests
 // can import this module to assert it has no side effects. Same idiom as tools/detect-backends.mjs.
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+//
+// Compare by REAL path, not by URL string: npx invokes the bin through a symlink in node_modules/.bin,
+// so process.argv[1] is that symlink while import.meta.url is the resolved real file — a raw string
+// compare reads them as different, main() never runs, and `npx … init` exits silently (the reported
+// "nothing happens after install" bug). realpathSync collapses the symlink so both sides match; it also
+// holds under --preserve-symlinks. A bare `node -e` (no argv[1]) and a missing file (realpath throws)
+// both correctly fall through to false — importing the module still runs nothing.
+const isDirectRun = (() => {
+  const invoked = process.argv[1];
+  if (!invoked) return false;
+  try {
+    return realpathSync(invoked) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
 if (isDirectRun) {
   main().catch((err) => {
     console.error(err);

package/bin/install.test.mjs

@@ -1,7 +1,7 @@
 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 } from 'node:fs/promises';
+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';
@@ -9,9 +9,21 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 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.
-const runInstaller = (target) =>
-  spawnSync(process.execPath, [INSTALLER, '--dir', target, '--no-launchers'], { encoding: 'utf8' });
+// --no-launchers so the test never wires Codex/Devin on the host. `extra` appends flags (e.g. --force).
+const runInstaller = (target, extra = []) =>
+  spawnSync(process.execPath, [INSTALLER, '--dir', target, '--no-launchers', ...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;
@@ -66,6 +78,31 @@ describe('kit installer — payload + symlink-traversal hardening', () => {
   });
 });
 
+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'], { 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()
@@ -82,6 +119,98 @@ describe('kit installer — module hygiene', () => {
   });
 });
 
+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 — published tarball bundles the bridges', () => {
   it('npm pack ships bridges/<name>/ (the execution-backend skill mirrors)', () => {
     // The real `files` whitelist decides what publishes — assert against `npm pack`, not the source

package/bridges/antigravity-cli-bridge/SKILL.md

@@ -150,9 +150,9 @@ checklist, prompt templates, output handling). Essentials:
 - **`agent-workflow-memory`** (family **context provider**) — if the current project has **no**
   `AGENTS.md` + `docs/ai/`, `agy` has no per-workspace context to read. The memory substrate creates
   it. Soft-recommend it (only when the user wants the memory workflow):
-  `npx @sabaiway/agent-workflow-memory init`, then `/agent-workflow-memory` in the project — or
+  `npx @sabaiway/agent-workflow-memory@latest init`, then `/agent-workflow-memory` in the project — or
   bootstrap the whole family via the **`agent-workflow-kit`** orchestrator
-  (`npx @sabaiway/agent-workflow-kit init`), which delegates substrate deployment to memory. Never a
+  (`npx @sabaiway/agent-workflow-kit@latest init`), which delegates substrate deployment to memory. Never a
   prerequisite for using `agy`.
 - **`codex-cli-bridge`** (sibling backend, OpenAI Codex) — recommend **by actual presence**: if
   `~/.claude/skills/codex-cli-bridge/` exists you have a **second delegated engine** (Codex for

package/bridges/codex-cli-bridge/SKILL.md

@@ -129,8 +129,8 @@ The wrappers work in any git repo where `codex` is installed and authenticated.
 - **`agent-workflow-memory`** (family **context provider**) — if the target project has **no**
   `AGENTS.md` + `docs/ai/`, codex has no root context to read (and the wrappers' preflight will
   STOP). The memory substrate is what creates that context. Soft-recommend it (only when the user
-  wants the memory workflow): `npx @sabaiway/agent-workflow-memory init`, or bootstrap the whole
-  family via the **`agent-workflow-kit`** orchestrator (`npx @sabaiway/agent-workflow-kit init`),
+  wants the memory workflow): `npx @sabaiway/agent-workflow-memory@latest init`, or bootstrap the whole
+  family via the **`agent-workflow-kit`** orchestrator (`npx @sabaiway/agent-workflow-kit@latest init`),
   which delegates substrate deployment to memory and injects the workflow methodology. Never a
   prerequisite.
 

package/capability.json

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

package/package.json

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