@sabaiway/agent-workflow-engine 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to the methodology engine. Versions are this **package's** n
 they are distinct from the **deployment-lineage** stamp written into a project's `docs/ai/`
 (which tracks the shared `agent-workflow` lineage, head `1.3.0`).
 
+## 1.1.0 — Live-read ready: never-downgrade gate + installer hardening
+
+The kit now reads this canon **live from the installed engine** and has retired its bundled mirror
+(see the kit's 1.11.0 / **AD-016**). This release hardens the engine's own installer to match — so an
+engine placed by `npx … kit init` (or by hand) is safe to refresh.
+
+### Added
+- **Never-downgrade gate** (cloned from the kit, AD-012): a bare `npx … init` that npx serves from an
+  **older cached build** can no longer overwrite a **newer** installed canon — `init` compares the
+  on-disk version (no network) and refuses loudly unless you pass `--allow-downgrade`. A same-version
+  re-run prints a cache hint and points at `@latest`. An existing but **unreadable** `SKILL.md` fails
+  closed (the gate is never silently bypassed).
+
+### Fixed
+- Containment check now accepts a legitimately-contained child literally named `..foo` (it wrongly
+  rejected anything starting with `..` before); `tildify` collapses only a **leading** `$HOME`, never
+  a mid-path occurrence (**Issue-004**, fixed in lockstep with the memory installer).
+
+### Changed
+- The installer is importable without side effects (the `isDirectRun` guard) and exports its
+  path/format helpers for in-process tests. The installer's own bare `npx … init` strings now use
+  `@latest`.
+
 ## 1.0.0
 
 First publish. The canonical home of the `agent-workflow` planning methodology is now an

package/README.md

@@ -10,9 +10,10 @@ This is the **methodology engine** of the `agent-workflow` family — the canoni
 rest of the family builds on. It is **content**, not a runtime: it reads nothing, writes
 nothing, and mutates no project file. It deliberately **knows nobody else** in the family —
 it only *provides* the methodology; the family composition root (`agent-workflow-kit`) is the
-one that injects it. The kit currently consumes a **byte-identical, drift-guarded mirror** of
-this canon bundled inside the kit; the live `kit → engine` read (and retiring that mirror)
-lands in the next slice.
+one that injects it. The kit reads **this canon live from the installed engine** and injects the
+bounded slot from it — **one source of truth, no bundled mirror** (Plan 3D / AD-016).
+`npx @sabaiway/agent-workflow-kit@latest init` installs the engine as a core part of the kit; if a
+slot fill is needed but the engine is absent, the kit's reconcile **fails loudly**.
 
 ## Install
 

package/SKILL.md

@@ -1,19 +1,20 @@
 ---
 name: agent-workflow-engine
-description: Canonical home of the agent-workflow planning methodology — the Plan→Phase→Step→Substep vocabulary, plan lifecycle, queue.md series index, mandatory Cleanup phase, and the bounded methodology slot fragment. A published, installable npm package (available:true) that *provides* the methodology text; it mutates nothing. The composition root (agent-workflow-kit) currently keeps byte-identical mirror copies of this text (drift-guarded) and injects the slot from its mirror; the live kit → engine read + mirror retirement land in the next slice.
+description: Canonical home of the agent-workflow planning methodology — the Plan→Phase→Step→Substep vocabulary, plan lifecycle, queue.md series index, mandatory Cleanup phase, and the bounded methodology slot fragment. A published, installable npm package (available:true) that *provides* the methodology text; it mutates nothing. The composition root (agent-workflow-kit) reads this canon LIVE from the installed engine and injects the bounded slot from it — one source of truth, no bundled mirror; `npx @sabaiway/agent-workflow-kit@latest init` installs the engine.
 disable-model-invocation: true
 metadata:
-  version: '1.0.0'
+  version: '1.1.0'
 ---
 
 # agent-workflow-engine
 
 The **canonical source of truth** for the `agent-workflow` planning methodology. It is a
 **published, installable npm package** (`capability.json` → `available:true`): it holds the
-methodology text and **provides** it, but it ships no runtime and mutates no files. The kit
-currently keeps **byte-identical mirror copies** of these files so the live injection + fallback
-keep working with no new dependency; a drift-guard test pins the mirrors to this canon. The live
-`kit → engine` read (and retiring the mirror) lands in the next slice.
+methodology text and **provides** it, but it ships no runtime and mutates no files. The kit reads
+**this canon live from the installed engine** (resolved via the family `detect.installed` pattern)
+and injects the bounded slot fragment from it — **one source of truth, no bundled mirror**.
+`npx @sabaiway/agent-workflow-kit@latest init` installs the engine as a core part of the kit; when a
+slot fill is needed but the engine is absent, the kit's reconcile **fails loudly** (never silently).
 
 ## What it provides (`provides: ["plan"]`)
 
@@ -36,9 +37,8 @@ no outbound edges.
 ## Status & roadmap
 
 The engine is **no longer a stub**: it is a published, `available:true`, installable npm package
-(`@sabaiway/agent-workflow-engine`). The kit currently keeps **byte-identical mirror copies** of
-this canon (drift-guarded), so the live injection + fallback keep working with no new dependency.
-The live `kit → engine` read (the kit reading this canon from the installed engine instead of its
-bundled mirror) and **retiring that mirror** land in the next slice. See the kit's
-`tools/inject-methodology.mjs` for the marker contract and the slot reconciliation the kit runs on
-bootstrap + upgrade.
+(`@sabaiway/agent-workflow-engine`). The kit reads **this canon live from the installed engine** and
+injects the methodology slot from it — the old bundled mirror is **retired** (Plan 3D / AD-016):
+**one source of truth**. `npx @sabaiway/agent-workflow-kit@latest init` installs the engine as a core
+part of the kit. See the kit's `tools/inject-methodology.mjs` (the marker contract + slot
+reconciliation) and `tools/engine-source.mjs` (the live read + fail-loud resolver).

package/bin/install.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // One-shot installer for @sabaiway/agent-workflow-engine.
 //
-//   npx @sabaiway/agent-workflow-engine init
+//   npx @sabaiway/agent-workflow-engine@latest init
 //
 // Copies the methodology canon into the canonical skill home
 // (~/.claude/skills/agent-workflow-engine, override with --dir or
@@ -17,7 +17,7 @@
 // No telemetry, no phone-home. Dependency-free, Node >= 18.
 
 import { readFile, mkdir, readdir, copyFile, lstat, readlink, symlink } from 'node:fs/promises';
-import { existsSync, lstatSync } from 'node:fs';
+import { existsSync, lstatSync, realpathSync } from 'node:fs';
 import { dirname, join, resolve, relative, sep, isAbsolute } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
@@ -37,7 +37,11 @@ const PAYLOAD = [
   'references',
 ];
 
-const tildify = (path) => path.replace(homedir(), '~');
+// Collapse only a LEADING homedir() to "~" — anchored at the string start (boundary-checked with
+// `sep`), never a mid-path occurrence. A naive `path.replace(homedir(), '~')` would rewrite the
+// first match anywhere in the path (Issue-004). Exported so the regression can pin it in-process.
+export const tildify = (path) =>
+  path === homedir() ? '~' : path.startsWith(homedir() + sep) ? `~${path.slice(homedir().length)}` : path;
 
 const readVersion = async () => {
   try {
@@ -48,6 +52,54 @@ const readVersion = async () => {
   }
 };
 
+// Never-downgrade gate helpers (D3 / AD-012) — cloned from the kit installer so a bare `npx … init`
+// serving an OLDER cached build cannot overwrite a NEWER installed canon. Dependency-free semver:
+// parse the leading x.y.z (prerelease/build ignored). compareSemver → -1 | 0 | 1, or null when
+// either side is unparseable (a legacy install predating any stamp → no gate).
+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 + the kit installer). Pure walk.
+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);
+  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 engine's
+// detect.installed.file). Returns the semver string, or null when ABSENT / unstamped (legacy → no
+// gate). A SKILL.md that EXISTS but cannot be read is NOT swallowed as "legacy": fail closed (throw)
+// so the 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-engine] cannot read the installed SKILL.md (${tildify(skill)}): ${err.message}. ` +
+        `Refusing to install over an unreadable canon — 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 the path does not exist. Using lstat (not
 // existsSync, which FOLLOWS symlinks and so reports a *dangling* symlink as absent) is what
 // makes the guard below catch a dangling destination symlink too.
@@ -64,9 +116,12 @@ const lstatNoFollow = (path) => {
 // within `root`. Walks `root` plus each existing path component down to `dest`; if the
 // root, an intermediate dir, or the leaf is a symlink (including a dangling one), a copy
 // could escape the target — STOP rather than follow it. Also refuses a dest outside `root`.
-const assertContainedRealPath = (root, dest) => {
+export const assertContainedRealPath = (root, dest) => {
   const rel = relative(root, dest);
-  if (rel.startsWith('..') || isAbsolute(rel)) {
+  // A true escape is `..` exactly or a `..`-prefixed PATH SEGMENT (`../x`) — NOT any string starting
+  // with the two chars "..": a legitimately-contained child literally named `..foo` has rel `..foo`,
+  // which the old `rel.startsWith('..')` wrongly rejected (Issue-004).
+  if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
     throw new Error(`[agent-workflow-engine] refusing to write outside the target dir: ${dest}`);
   }
   if (lstatNoFollow(root)?.isSymbolicLink()) {
@@ -106,6 +161,7 @@ const parseArgs = (argv) => {
   return {
     help: argv.includes('--help') || argv.includes('-h'),
     version: argv.includes('--version') || argv.includes('-v'),
+    allowDowngrade: argv.includes('--allow-downgrade'),
     dir: dirFlag >= 0 ? argv[dirFlag + 1] : undefined,
   };
 };
@@ -120,13 +176,15 @@ const printHelp = (version) => {
   console.log(`agent-workflow-engine ${version}
 
 Usage:
-  npx @sabaiway/agent-workflow-engine init [--dir <path>]
+  npx @sabaiway/agent-workflow-engine@latest init [--dir <path>] [--allow-downgrade]
   npx @sabaiway/agent-workflow-engine --version
   npx @sabaiway/agent-workflow-engine --help
 
 Installs/refreshes the methodology canon at ~/.claude/skills/agent-workflow-engine
   (override with --dir <path> or AGENT_WORKFLOW_ENGINE_DIR). init is additive —
-  it never deletes your files and never writes through a symlink.
+  it never deletes your files and never writes through a symlink. If the installed
+  canon 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.
 
 The engine is the methodology canon the family kit builds on — it is content, not a
 project deploy and not a model-invoked skill, so there is nothing to run inside an agent.
@@ -159,6 +217,26 @@ const main = async () => {
     console.error(`[agent-workflow-engine] 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 (D3 / AD-012): a bare `npx … init` can run an OLDER cached build, which
+  // would overwrite a NEWER installed canon with old text. Refuse loudly (nonzero) unless
+  // --allow-downgrade — surfacing the cache trap instead of silently regressing (no silent failures).
+  if (cmp === 1 && !args.allowDowngrade) {
+    console.error(
+      `[agent-workflow-engine] refusing to downgrade: the installed canon 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 canon, bypass the cache:\n` +
+        `    npx @sabaiway/agent-workflow-engine@latest init\n` +
+        `  (or pass --allow-downgrade to overwrite the newer install with v${version} anyway).`,
+    );
+    process.exit(1);
+  }
+
   await mkdir(target, { recursive: true });
   await Promise.all(
     PAYLOAD.map((entry) => copyRecursive(resolve(PKG_ROOT, entry), resolve(target, entry), target)),
@@ -167,13 +245,38 @@ const main = async () => {
     `[agent-workflow-engine] ${wasPresent ? 'updated the canon to' : 'installed'} v${version} -> ${tildify(target)}`,
   );
 
+  // No-op re-run (same version) → almost always npx served a cached build; say so + point at @latest.
+  if (cmp === 0) {
+    console.log(
+      `[agent-workflow-engine] note: no version change — the canon 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-engine@latest init`,
+    );
+  }
+
   console.log(`
 This installed the methodology canon at ${tildify(target)}. The engine is content the
 family kit builds on — there is nothing to run inside an agent.
 To update it later, re-run:  npx @sabaiway/agent-workflow-engine@latest init`);
 };
 
-main().catch((err) => {
-  console.error(err);
-  process.exit(1);
-});
+// Run main() only when executed directly (npx / node bin/install.mjs), never on import — so tests can
+// import this module to unit-test its exported helpers with no side effects. Compare by REAL path:
+// npx invokes the bin through a node_modules/.bin symlink, so process.argv[1] is that symlink while
+// import.meta.url is the resolved real file — a raw string compare reads them as different and main()
+// never runs. realpathSync collapses the symlink so both sides match. (Same idiom as the kit.)
+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);
+    process.exit(1);
+  });
+}

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-engine",
   "kind": "methodology-engine",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "available": true,
   "provides": ["plan"],
   "roles": {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-engine",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Canonical home of the agent-workflow planning methodology — the Plan→Phase→Step vocabulary, plan lifecycle, queue.md series index, and mandatory Cleanup phase, consumed by the kit (composition root). The methodology engine of the agent-workflow family.",
   "keywords": [
     "ai-agents",