@sabaiway/agent-workflow-kit 1.10.0 → 1.11.0

package/tools/engine-source.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+// Live methodology-engine source resolution — the kit reads the bounded methodology fragment
+// LIVE from the installed agent-workflow-engine (the family's one source of truth), via the same
+// `detect.installed` idiom the kit already uses to find memory (detectMemory in delegation.mjs),
+// NOT an npm `dependencies` edge (the family DAG: the kit DETECTS siblings, it never imports them).
+//
+//   resolveEngineDir({ env, home }) → { dir, source }   env override vs the ~/.claude default
+//   detectEngine(dir, { source })   → { ok, reason, dir }   runs the kit's OWN validator
+//   readEngineFragment(dir, { source }) → fragment string, or THROWS a loud install-me error
+//
+// Fail-closed: readEngineFragment never falls back to a bundled copy (there is none after the
+// mirror retirement) — when the engine is needed but absent/invalid it throws with the exact
+// remediation, so the reconcile STOPs loudly rather than silently dropping the slot (AGENTS.md:
+// no silent failures). Pure-where-possible (fs + validator injectable for tests), Node >= 18.
+
+import { statSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { validateManifest, VALID } from './manifest/validate.mjs';
+
+// The engine's detect.installed contract (agent-workflow-engine/capability.json): the env override,
+// the ~/.claude default home, the declared skill name, and the in-skill path of the live fragment.
+export const ENGINE_ENV = 'AGENT_WORKFLOW_ENGINE_DIR';
+export const EXPECTED_ENGINE_NAME = 'agent-workflow-engine';
+export const ENGINE_FRAGMENT_REL = 'references/methodology-slot.md';
+const ENGINE_DEFAULT_REL = '.claude/skills/agent-workflow-engine';
+
+const defaultStatType = (path) => {
+  try {
+    const s = statSync(path);
+    return s.isDirectory() ? 'dir' : s.isFile() ? 'file' : 'other';
+  } catch {
+    return null;
+  }
+};
+
+// Resolve the installed engine dir from the env override (if set) or the ~/.claude default,
+// mirroring the engine's `detect.installed`. `source` is load-bearing: a missing dir is reported as
+// `env-set-but-missing` ONLY when source === 'env' (the user pointed us somewhere that is not there),
+// which cannot be derived from `dir` alone.
+export const resolveEngineDir = ({ env = {}, home = '' } = {}) => {
+  const fromEnv = env[ENGINE_ENV];
+  if (typeof fromEnv === 'string' && fromEnv) return { dir: fromEnv, source: 'env' };
+  return { dir: join(home, ENGINE_DEFAULT_REL), source: 'default' };
+};
+
+// Decide whether the resolved dir is a usable methodology engine. Runs the kit's OWN validator
+// (never a candidate-shipped one), and clones detectMemory's reason ladder so each failure has a
+// distinct, actionable reason. ok only on: a dir that exists + VALID manifest + kind
+// methodology-engine + the right name + available + the live fragment file present.
+export const detectEngine = (engineDir, { source } = {}, deps = {}) => {
+  const validate = deps.validate ?? validateManifest;
+  const statType = deps.statType ?? defaultStatType;
+
+  // The dir itself must exist first — this is what lets an env-pointed-but-absent dir read as the
+  // distinct `env-set-but-missing` (validateManifest would only say "capability.json not found").
+  if (statType(engineDir) !== 'dir') {
+    const reason =
+      source === 'env'
+        ? `engine dir from ${ENGINE_ENV} is missing or not a directory (env-set-but-missing): ${engineDir}`
+        : `engine not installed at ${engineDir}`;
+    return { ok: false, reason, dir: engineDir };
+  }
+
+  // The validator does an UNGUARDED read of the candidate's SKILL.md for its version source, so a
+  // corrupt engine (e.g. SKILL.md is a directory → EISDIR) makes validateManifest THROW. Treat any
+  // validator throw as `invalid` so the failure still flows through readEngineFragment's stable
+  // "methodology engine not found/invalid" message + install command — never a raw fs error.
+  const report = (() => {
+    try {
+      return validate(engineDir);
+    } catch (err) {
+      return { result: 'invalid', errors: [`validator threw: ${err?.message ?? err}`] };
+    }
+  })();
+  const fragmentPresent = statType(join(engineDir, ENGINE_FRAGMENT_REL)) === 'file';
+  const ok =
+    report.result === VALID &&
+    report.kind === 'methodology-engine' &&
+    report.name === EXPECTED_ENGINE_NAME &&
+    report.available !== false &&
+    fragmentPresent;
+  const reason = ok
+    ? 'engine manifest valid (kind: methodology-engine) and the live fragment is present'
+    : report.result !== VALID
+      ? `engine manifest ${report.result} at ${engineDir}`
+      : report.kind !== 'methodology-engine'
+        ? `engine manifest kind "${report.kind}" is not methodology-engine`
+        : report.name !== EXPECTED_ENGINE_NAME
+          ? `engine manifest name "${report.name}" is not "${EXPECTED_ENGINE_NAME}"`
+          : report.available === false
+            ? 'engine manifest is a declared stub (available:false)'
+            : `engine fragment missing (${ENGINE_FRAGMENT_REL})`;
+  return { ok, reason, dir: engineDir };
+};
+
+// Read the bounded methodology fragment LIVE from the installed engine. Returns the fragment string
+// on the happy path; THROWS a loud Error naming the resolved dir + the reason + the exact
+// remediation on absent/invalid/unreadable — never a fallback (fail-closed). The "methodology engine
+// not found/invalid" prefix is a stable contract: the agent classifies the reconcile STOP by it
+// (distinct from the cap-skip message), so do not reword it without updating SKILL.md.
+export const readEngineFragment = (engineDir, deps = {}) => {
+  const detection = detectEngine(engineDir, { source: deps.source }, deps);
+  const installHint = `npx @sabaiway/agent-workflow-engine@latest init  (or set ${ENGINE_ENV})`;
+  if (!detection.ok) {
+    throw new Error(`methodology engine not found/invalid at ${engineDir} (${detection.reason}) — install it: ${installHint}`);
+  }
+  const read = deps.readFileSync ?? readFileSync;
+  try {
+    return read(join(engineDir, ENGINE_FRAGMENT_REL), 'utf8');
+  } catch (err) {
+    throw new Error(
+      `methodology engine not found/invalid at ${engineDir} (fragment unreadable: ${err.message}) — install it: ${installHint}`,
+    );
+  }
+};

package/tools/engine-source.test.mjs

@@ -0,0 +1,182 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { join } from 'node:path';
+import {
+  resolveEngineDir,
+  detectEngine,
+  readEngineFragment,
+  ENGINE_ENV,
+  EXPECTED_ENGINE_NAME,
+  ENGINE_FRAGMENT_REL,
+} from './engine-source.mjs';
+
+// A valid engine dir = it exists (dir), the fragment file exists, and the validator reports a
+// VALID methodology-engine with the right name. The deps below let every branch be exercised
+// in-process without touching the real filesystem.
+const ENGINE_DIR = '/home/u/.claude/skills/agent-workflow-engine';
+
+// statType stub: ENGINE_DIR → 'dir', the fragment → 'file', everything else → null.
+const okStatType = (path) =>
+  path === ENGINE_DIR ? 'dir' : path === join(ENGINE_DIR, ENGINE_FRAGMENT_REL) ? 'file' : null;
+
+const okReport = {
+  result: 'valid',
+  kind: 'methodology-engine',
+  name: EXPECTED_ENGINE_NAME,
+  available: true,
+};
+
+const deps = (overrides = {}) => ({
+  validate: () => okReport,
+  statType: okStatType,
+  ...overrides,
+});
+
+describe('resolveEngineDir — env override vs the ~/.claude default', () => {
+  it('uses AGENT_WORKFLOW_ENGINE_DIR when set, tagging source=env', () => {
+    const out = resolveEngineDir({ env: { [ENGINE_ENV]: '/custom/engine' }, home: '/home/u' });
+    assert.deepEqual(out, { dir: '/custom/engine', source: 'env' });
+  });
+  it('falls back to ~/.claude/skills/agent-workflow-engine, tagging source=default', () => {
+    const out = resolveEngineDir({ env: {}, home: '/home/u' });
+    assert.equal(out.source, 'default');
+    assert.equal(out.dir, join('/home/u', '.claude/skills/agent-workflow-engine'));
+  });
+  it('treats an empty env value as unset (source=default)', () => {
+    const out = resolveEngineDir({ env: { [ENGINE_ENV]: '' }, home: '/home/u' });
+    assert.equal(out.source, 'default');
+  });
+});
+
+describe('detectEngine — happy path + each distinct failure reason', () => {
+  it('ok when dir exists, manifest VALID methodology-engine, right name, fragment present', () => {
+    const out = detectEngine(ENGINE_DIR, { source: 'default' }, deps());
+    assert.equal(out.ok, true);
+    assert.equal(out.dir, ENGINE_DIR);
+    assert.match(out.reason, /methodology-engine/);
+  });
+
+  it('env-set-but-missing: dir absent AND source=env → distinct reason', () => {
+    const out = detectEngine(ENGINE_DIR, { source: 'env' }, deps({ statType: () => null }));
+    assert.equal(out.ok, false);
+    assert.match(out.reason, /env-set-but-missing/);
+  });
+
+  it('not-installed: dir absent AND source=default → not an env-set reason', () => {
+    const out = detectEngine(ENGINE_DIR, { source: 'default' }, deps({ statType: () => null }));
+    assert.equal(out.ok, false);
+    assert.match(out.reason, /not installed/i);
+    assert.doesNotMatch(out.reason, /env-set-but-missing/);
+  });
+
+  it('invalid manifest → reason names the validator result', () => {
+    const out = detectEngine(ENGINE_DIR, { source: 'default' }, deps({ validate: () => ({ ...okReport, result: 'invalid' }) }));
+    assert.equal(out.ok, false);
+    assert.match(out.reason, /invalid/);
+  });
+
+  it('wrong kind → reason names the kind', () => {
+    const out = detectEngine(ENGINE_DIR, { source: 'default' }, deps({ validate: () => ({ ...okReport, kind: 'memory-substrate' }) }));
+    assert.equal(out.ok, false);
+    assert.match(out.reason, /kind/);
+  });
+
+  it('wrong name → reason names the name mismatch', () => {
+    const out = detectEngine(ENGINE_DIR, { source: 'default' }, deps({ validate: () => ({ ...okReport, name: 'something-else' }) }));
+    assert.equal(out.ok, false);
+    assert.match(out.reason, /name/);
+  });
+
+  it('declared stub (available:false) → reason names the stub', () => {
+    const out = detectEngine(ENGINE_DIR, { source: 'default' }, deps({ validate: () => ({ ...okReport, available: false }) }));
+    assert.equal(out.ok, false);
+    assert.match(out.reason, /stub|available:false/);
+  });
+
+  it('missing fragment → reason names the fragment path', () => {
+    const out = detectEngine(ENGINE_DIR, { source: 'default' }, deps({ statType: (p) => (p === ENGINE_DIR ? 'dir' : null) }));
+    assert.equal(out.ok, false);
+    assert.match(out.reason, /fragment/);
+  });
+
+  it('a validator that THROWS (corrupt engine, e.g. EISDIR) → ok:false, no raw error escapes', () => {
+    const out = detectEngine(
+      ENGINE_DIR,
+      { source: 'default' },
+      deps({
+        validate: () => {
+          throw new Error('EISDIR: illegal operation on a directory, read');
+        },
+      }),
+    );
+    assert.equal(out.ok, false);
+    assert.match(out.reason, /invalid/);
+  });
+});
+
+describe('readEngineFragment — live read or loud throw', () => {
+  it('returns the fragment bytes on the happy path', () => {
+    const out = readEngineFragment(ENGINE_DIR, deps({ source: 'default', readFileSync: () => 'FRAGMENT BODY' }));
+    assert.equal(out, 'FRAGMENT BODY');
+  });
+
+  it('throws naming the dir + the exact install command when the engine is absent', () => {
+    assert.throws(
+      () => readEngineFragment(ENGINE_DIR, deps({ source: 'env', statType: () => null })),
+      (err) => {
+        assert.match(err.message, /methodology engine not found\/invalid/);
+        assert.match(err.message, new RegExp(ENGINE_DIR.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+        assert.match(err.message, /npx @sabaiway\/agent-workflow-engine@latest init/);
+        assert.match(err.message, new RegExp(ENGINE_ENV));
+        return true;
+      },
+    );
+  });
+
+  it('throws when the manifest is invalid (never falls back)', () => {
+    assert.throws(
+      () => readEngineFragment(ENGINE_DIR, deps({ source: 'default', validate: () => ({ ...okReport, result: 'invalid' }) })),
+      /methodology engine not found\/invalid/,
+    );
+  });
+
+  it('a THROWING validator still yields the stable install message (no raw fs error escapes)', () => {
+    assert.throws(
+      () =>
+        readEngineFragment(
+          ENGINE_DIR,
+          deps({
+            source: 'default',
+            validate: () => {
+              throw new Error('EISDIR: illegal operation on a directory, read');
+            },
+          }),
+        ),
+      (err) => {
+        assert.match(err.message, /methodology engine not found\/invalid/);
+        assert.match(err.message, /npx @sabaiway\/agent-workflow-engine@latest init/);
+        return true;
+      },
+    );
+  });
+
+  it('throws with the install command when the fragment file is unreadable', () => {
+    assert.throws(
+      () =>
+        readEngineFragment(
+          ENGINE_DIR,
+          deps({
+            source: 'default',
+            readFileSync: () => {
+              throw new Error('EISDIR');
+            },
+          }),
+        ),
+      (err) => {
+        assert.match(err.message, /fragment unreadable: EISDIR/);
+        assert.match(err.message, /npx @sabaiway\/agent-workflow-engine@latest init/);
+        return true;
+      },
+    );
+  });
+});

package/tools/fs-safe.mjs

@@ -44,7 +44,10 @@ export const assertContainedRealPath = (root, dest, deps = {}) => {
   const lstat = deps.lstat ?? lstatSync;
   const ln = (p) => lstatNoFollow(p, lstat);
   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 — same fix as the engine/memory installers).
+  if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
     throw new Error(`[agent-workflow-kit] refusing to write outside the target dir: ${dest}`);
   }
   if (ln(root)?.isSymbolicLink()) {

package/tools/fs-safe.test.mjs

@@ -30,6 +30,12 @@ describe('assertContainedRealPath', () => {
     assert.throws(() => assertContainedRealPath('/root', '/etc/passwd'), /outside/);
   });
 
+  it('Issue-004: accepts a contained child literally named "..foo", still rejects a true ".." segment', () => {
+    // rel "..foo" is a real child, NOT a "../" escape — the old `rel.startsWith('..')` wrongly rejected it.
+    assert.doesNotThrow(() => assertContainedRealPath(dir, join(dir, '..foo')));
+    assert.throws(() => assertContainedRealPath(dir, join(dir, '..', 'escape')), /outside/);
+  });
+
   it('rejects writing INTO a symlinked root', () => {
     const real = join(dir, 'real');
     const root = join(dir, 'root');

package/tools/inject-methodology.mjs

@@ -3,9 +3,12 @@
 // deployed AGENTS.md.
 //
 // Both templates (memory's + the kit fallback) ship an EMPTY delimited slot; the kit (which knows
-// the whole family) fills it. The bounded fragment (tools/methodology-slot.md) is a BOUNDED summary
-// + pointer, NOT the full references/planning.md, so AGENTS.md stays under its line cap; it is a
-// byte-identical MIRROR of the canonical text in agent-workflow-engine (drift-guarded).
+// the whole family) fills it. The bounded fragment is a BOUNDED summary + pointer (NOT the full
+// references/planning.md), so AGENTS.md stays under its line cap. It is read LIVE from the installed
+// agent-workflow-engine (references/methodology-slot.md) via engine-source.mjs — the family's one
+// source of truth; there is no bundled mirror (retired in Plan 3D, AD-016). The live read is lazy +
+// fail-loud: resolve+read the engine ONLY when a fill is actually needed, and STOP loudly (never a
+// silent fallback) when the engine is needed but absent/invalid.
 //
 // Two layers over one marker parser:
 //   - injectMethodology — fill an EXISTING slot. Marker contract, strictly enforced:
@@ -152,11 +155,24 @@ export const reconcileSlot = (text, fragment, { maxLines } = {}) => {
   return { status, text: injected.text };
 };
 
+// Pure predicate (no fs): does this AGENTS.md actually need the methodology fragment? True only when
+// the slot can be ensured (present or insertable) AND is empty — i.e. when reconcileSlot would
+// inject. False when the slot is already filled (preserve-verbatim, no fragment read) OR when the
+// slot/anchor is malformed (so reconcileSlot's own precise error path still fires). It reuses the
+// SAME primitives as reconcileSlot (ensureSlot + extractSlot), so the lazy "read the engine only
+// when needed" guard in main() cannot diverge from the actual fill decision.
+export const slotNeedsFill = (text) => {
+  const ensured = ensureSlot(text);
+  if (ensured.status === 'error') return false;
+  const current = extractSlot(ensured.text);
+  return current == null || current.trim() === '';
+};
+
 const main = async (argv) => {
   const { readFile, writeFile, rename, rm } = await import('node:fs/promises');
   const { dirname, basename, join, resolve } = await import('node:path');
-  const { fileURLToPath } = await import('node:url');
-  const here = dirname(fileURLToPath(import.meta.url));
+  const { homedir } = await import('node:os');
+  const { resolveEngineDir, readEngineFragment } = await import('./engine-source.mjs');
 
   // `reconcile <AGENTS.md> [fragment.md]` = ensure-slot + inject-if-empty + cap (bootstrap/upgrade);
   // `<AGENTS.md> [fragment.md]` = the legacy inject-into-existing-slot mode.
@@ -167,9 +183,29 @@ const main = async (argv) => {
     console.error('usage: inject-methodology.mjs [reconcile] <path/to/AGENTS.md> [fragment.md]');
     process.exit(2);
   }
-  const fragmentPath = rest[1] ? resolve(rest[1]) : resolve(here, 'methodology-slot.md');
+  const explicitFragmentArg = rest[1];
   const text = await readFile(resolve(agentsPath), 'utf8');
-  const fragment = await readFile(fragmentPath, 'utf8');
+
+  // Source the bounded fragment LAZILY. An explicit [fragment.md] arg (tests + manual) wins and skips
+  // engine resolution entirely. Otherwise read it LIVE from the installed engine — there is no
+  // bundled mirror. readEngineFragment THROWS (never falls back) when the engine is needed but
+  // absent/invalid; sourceFragmentOrStop turns that into a hard, loud STOP carrying the install
+  // command. The caller only invokes this when a fill is actually needed (the laziness).
+  const sourceFragment = async () => {
+    if (explicitFragmentArg) return readFile(resolve(explicitFragmentArg), 'utf8');
+    const { dir, source } = resolveEngineDir({ env: process.env, home: homedir() });
+    return readEngineFragment(dir, { source }); // sync; throws loudly when the engine is absent/invalid
+  };
+  const sourceFragmentOrStop = async (label) => {
+    try {
+      return await sourceFragment();
+    } catch (err) {
+      // Engine needed-but-absent → a hard STOP, distinct from the soft cap-skip. The
+      // "methodology engine not found/invalid" prefix lets the agent classify this exit (SKILL.md).
+      console.error(`[inject-methodology] ${label} — ${err.message}`);
+      process.exit(1);
+    }
+  };
 
   const writeAtomic = async (out) => {
     const tmp = join(dirname(resolve(agentsPath)), `.${basename(agentsPath)}.tmp-${process.pid}-${Date.now()}`);
@@ -183,6 +219,10 @@ const main = async (argv) => {
   };
 
   if (mode === 'reconcile') {
+    // Read the engine only when the slot actually needs filling (lazy). slotNeedsFill reuses the same
+    // primitives reconcileSlot does, so it cannot disagree with the fill decision below — a filled
+    // slot reconciles to a zero-diff no-op WITHOUT consulting the engine.
+    const fragment = slotNeedsFill(text) ? await sourceFragmentOrStop('reconcile STOP') : '';
     const result = reconcileSlot(text, fragment, { maxLines: AGENTS_MD_CAP });
     if (result.status === 'error') {
       console.error(`[inject-methodology] reconcile refused — ${result.error}`);
@@ -201,6 +241,10 @@ const main = async (argv) => {
     return;
   }
 
+  // Legacy inject-into-existing-slot mode. injectMethodology no-ops on absent markers and errors on a
+  // malformed slot WITHOUT reading the fragment, so resolve+read the engine only when there is a
+  // present (ok) slot to fill — a markerless legacy AGENTS.md stays a no-op without the engine.
+  const fragment = findSlot(text).state === 'ok' ? await sourceFragmentOrStop('STOP') : '';
   const result = injectMethodology(text, fragment, { maxLines: AGENTS_MD_CAP });
   if (result.status === 'error') {
     console.error(`[inject-methodology] malformed slot — refusing to edit: ${result.error}`);

package/tools/inject-methodology.test.mjs

@@ -1,6 +1,6 @@
-import { describe, it } from 'node:test';
+import { describe, it, after } from 'node:test';
 import assert from 'node:assert/strict';
-import { readFileSync, writeFileSync, mkdtempSync, rmSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -11,6 +11,7 @@ import {
   extractSlot,
   ensureSlot,
   reconcileSlot,
+  slotNeedsFill,
   METHODOLOGY_ANCHOR,
   EMPTY_SLOT,
   AGENTS_MD_CAP,
@@ -20,7 +21,47 @@ import {
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const SCRIPT = join(HERE, 'inject-methodology.mjs');
-const FRAGMENT = readFileSync(join(HERE, 'methodology-slot.md'), 'utf8');
+
+// The bounded methodology fragment is read LIVE from the installed engine now (the kit mirror is
+// retired in Plan 3D), so this suite no longer reads a bundled methodology-slot.md. Tests use an
+// inline fragment and, for the live-read CLI cases, an on-the-fly engine fixture that ships exactly
+// this fragment — keeping the kit suite decoupled from the sibling engine's on-disk presence.
+// Single-line (like the canonical fragment) so byte-equality holds in both LF and CRLF documents.
+const FRAGMENT =
+  '> **Workflow methodology (test fixture)** — plan → execute → review. Plans are ephemeral, gitignored, never committed; every Plan ends with a mandatory **Phase: Cleanup**.\n';
+
+// Temp dirs created by the fixtures below — cleaned up once after the whole file.
+const tmpDirs = [];
+after(() => tmpDirs.forEach((d) => rmSync(d, { recursive: true, force: true })));
+
+// A minimal but VALID installed-engine fixture: a methodology-engine capability.json + a SKILL.md
+// whose metadata.version matches it (the validator's authoritative version source when there is no
+// package.json) + the live fragment at references/methodology-slot.md. detectEngine accepts it.
+const makeEngineFixture = (fragment = FRAGMENT, version = '1.0.0') => {
+  const dir = mkdtempSync(join(tmpdir(), 'engine-fixture-'));
+  tmpDirs.push(dir);
+  const manifest = {
+    family: 'agent-workflow',
+    schema: 1,
+    name: 'agent-workflow-engine',
+    kind: 'methodology-engine',
+    version,
+    available: true,
+    provides: ['plan'],
+    roles: {},
+  };
+  writeFileSync(join(dir, 'capability.json'), JSON.stringify(manifest, null, 2));
+  writeFileSync(join(dir, 'SKILL.md'), `---\nname: agent-workflow-engine\nmetadata:\n  version: '${version}'\n---\n# engine\n`);
+  mkdirSync(join(dir, 'references'), { recursive: true });
+  writeFileSync(join(dir, 'references', 'methodology-slot.md'), fragment);
+  return dir;
+};
+
+const ENGINE = makeEngineFixture();
+// A path that is guaranteed NOT to be a valid engine — proves the no-op / explicit-override paths
+// never consult the engine, and drives the fail-loud STOP.
+const NO_ENGINE = join(tmpdir(), `definitely-no-engine-${process.pid}`);
+const withEngine = (engineDir) => ({ ...process.env, AGENT_WORKFLOW_ENGINE_DIR: engineDir });
 
 const wrap = (inner) =>
   `# AGENTS.md\n\nprefix bytes\n\n## Session Protocols\n\nintro line.\n\n${START_MARKER}${inner}${END_MARKER}\n\n## Hard Constraints\n\nsuffix bytes\n`;
@@ -309,7 +350,46 @@ describe('reconcileSlot — ensure + inject-if-empty + cap, as one atomic policy
   });
 });
 
-describe('reconcile CLI — atomic ensure+inject-if-empty+cap on the real filesystem', () => {
+describe('slotNeedsFill — lazy-read predicate (matches reconcileSlot fill decision)', () => {
+  it('present empty slot → true', () => {
+    assert.equal(slotNeedsFill(wrap('\n')), true);
+  });
+  it('markerless legacy with one anchor (insertable empty slot) → true', () => {
+    assert.equal(slotNeedsFill(legacyWithAnchor()), true);
+  });
+  it('present filled/customized slot → false (fragment not needed)', () => {
+    assert.equal(slotNeedsFill(wrap('\nuser notes\n')), false);
+  });
+  it('malformed slot → false (reconcileSlot error path fires, not a fill)', () => {
+    assert.equal(slotNeedsFill(`${START_MARKER}\n${END_MARKER}\n${START_MARKER}\n${END_MARKER}\n`), false);
+  });
+  it('markerless with no anchor → false (cannot insert; reconcile errors without the engine)', () => {
+    assert.equal(slotNeedsFill('# AGENTS.md\n\nno anchor here\n'), false);
+  });
+
+  // slotNeedsFill and reconcileSlot share the SAME emptiness primitives (ensureSlot + extractSlot), so
+  // the lazy "read the engine only when needed" guard cannot disagree with reconcileSlot's actual fill
+  // decision. Pin that equivalence across representative inputs: needsFill === true  IFF reconcile fills
+  // (reconciled-filled / reconciled-inserted); needsFill === false IFF reconcile does NOT fill
+  // (present-filled / error). This forecloses any future divergence that could silently drop a slot.
+  it('agrees with reconcileSlot across every slot state (no divergence → no silent drop)', () => {
+    const cases = [
+      wrap('\n'), // present empty slot → fill
+      legacyWithAnchor(), // markerless + anchor → insert + fill
+      wrap('\nuser notes\n'), // filled slot → no fill
+      `${START_MARKER}\n${END_MARKER}\n${START_MARKER}\n${END_MARKER}\n`, // malformed → no fill (error)
+      '# AGENTS.md\n\nno anchor here\n', // no anchor → no fill (error)
+    ];
+    for (const text of cases) {
+      const needs = slotNeedsFill(text);
+      const result = reconcileSlot(text, FRAGMENT, { maxLines: AGENTS_MD_CAP });
+      const filled = result.status === 'reconciled-filled' || result.status === 'reconciled-inserted';
+      assert.equal(needs, filled, `slotNeedsFill (${needs}) must match whether reconcile fills (${result.status})`);
+    }
+  });
+});
+
+describe('reconcile CLI — atomic ensure+inject-if-empty+cap, reading the fragment LIVE from the engine', () => {
   const withTempAgents = (contents, run) => {
     const dir = mkdtempSync(join(tmpdir(), 'reconcile-cli-'));
     const agents = join(dir, 'AGENTS.md');
@@ -321,35 +401,100 @@ describe('reconcile CLI — atomic ensure+inject-if-empty+cap on the real filesy
     }
   };
 
-  it('markerless legacy (with anchor) → slot inserted and filled (exit 0)', () => {
+  it('markerless legacy (with anchor) → slot inserted + filled from the live engine fragment (exit 0)', () => {
     withTempAgents(legacyWithAnchor(), (agents) => {
-      execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe' });
+      execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe', env: withEngine(ENGINE) });
       const out = readFileSync(agents, 'utf8');
       assert.equal(findSlot(out).state, 'ok');
       assert.equal(extractSlot(out).trim(), FRAGMENT.trim());
     });
   });
 
-  it('present empty slot → slot filled (exit 0)', () => {
+  it('present empty slot → filled from the live engine fragment (exit 0)', () => {
     withTempAgents(wrap('\n'), (agents) => {
-      execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe' });
+      execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe', env: withEngine(ENGINE) });
       assert.equal(extractSlot(readFileSync(agents, 'utf8')).trim(), FRAGMENT.trim());
     });
   });
 
-  it('filled/customized slot → file left byte-for-byte untouched', () => {
+  it('filled/customized slot → zero-diff no-op WITHOUT consulting the engine (engine absent, exit 0)', () => {
     const custom = wrap('\nuser notes\n');
     withTempAgents(custom, (agents) => {
-      execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe' });
+      // Engine pointed at a path that does not exist — a filled slot must NOT require it.
+      execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe', env: withEngine(NO_ENGINE) });
       assert.equal(readFileSync(agents, 'utf8'), custom);
     });
   });
 
-  it('malformed slot → STOP with non-zero exit, file byte-unchanged', () => {
+  it('present empty slot + engine ABSENT → hard STOP (nonzero) printing the install command, file unchanged', () => {
+    withTempAgents(wrap('\n'), (agents) => {
+      const err = (() => {
+        try {
+          execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe', env: withEngine(NO_ENGINE) });
+          return null;
+        } catch (e) {
+          return e;
+        }
+      })();
+      assert.ok(err, 'expected a non-zero exit when a fill is needed but the engine is absent');
+      const stderr = String(err.stderr);
+      assert.match(stderr, /methodology engine not found\/invalid/);
+      assert.match(stderr, /npx @sabaiway\/agent-workflow-engine@latest init/);
+      assert.equal(readFileSync(agents, 'utf8'), wrap('\n'), 'no partial write on STOP');
+    });
+  });
+
+  it('explicit [fragment.md] override fills from that file and skips engine resolution (engine absent)', () => {
+    const override = '> custom override fragment line\n';
+    const fdir = mkdtempSync(join(tmpdir(), 'frag-'));
+    tmpDirs.push(fdir);
+    const fpath = join(fdir, 'frag.md');
+    writeFileSync(fpath, override);
+    withTempAgents(wrap('\n'), (agents) => {
+      execFileSync(process.execPath, [SCRIPT, 'reconcile', agents, fpath], { stdio: 'pipe', env: withEngine(NO_ENGINE) });
+      assert.equal(extractSlot(readFileSync(agents, 'utf8')).trim(), override.trim());
+    });
+  });
+
+  it('malformed slot → STOP with non-zero exit, file byte-unchanged (engine never consulted)', () => {
     const malformed = `${START_MARKER}\n${END_MARKER}\n${START_MARKER}\n${END_MARKER}\n`;
     withTempAgents(malformed, (agents) => {
-      assert.throws(() => execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe' }));
+      assert.throws(() =>
+        execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe', env: withEngine(NO_ENGINE) }),
+      );
       assert.equal(readFileSync(agents, 'utf8'), malformed);
     });
   });
+
+  it('legacy inject mode: markerless AGENTS.md → no-op WITHOUT the engine (exit 0)', () => {
+    const markerless = '# AGENTS.md\n\nlegacy, no slot\n';
+    withTempAgents(markerless, (agents) => {
+      execFileSync(process.execPath, [SCRIPT, agents], { stdio: 'pipe', env: withEngine(NO_ENGINE) });
+      assert.equal(readFileSync(agents, 'utf8'), markerless);
+    });
+  });
+
+  // Legacy `inject` mode FORCE-OVERWRITES any present (ok) slot — filled or empty — unlike `reconcile`,
+  // which preserves a filled slot. So for an ok slot it genuinely NEEDS the fragment and reads the
+  // engine; the read-on-`state==='ok'` guard is correct (reading only an EMPTY ok slot would inject ''
+  // and WIPE a filled slot). These two tests pin that contract.
+  it('legacy inject mode: a FILLED slot is OVERWRITTEN from the live engine (engine present, exit 0)', () => {
+    const filled = wrap('\nstale user content\n');
+    withTempAgents(filled, (agents) => {
+      execFileSync(process.execPath, [SCRIPT, agents], { stdio: 'pipe', env: withEngine(ENGINE) });
+      const out = readFileSync(agents, 'utf8');
+      assert.equal(extractSlot(out).trim(), FRAGMENT.trim(), 'slot overwritten with the live fragment');
+      assert.ok(!out.includes('stale user content'), 'prior slot content replaced');
+    });
+  });
+
+  it('legacy inject mode: a present (ok) slot + engine ABSENT → hard STOP, file unchanged', () => {
+    const filled = wrap('\nstale user content\n');
+    withTempAgents(filled, (agents) => {
+      assert.throws(() =>
+        execFileSync(process.execPath, [SCRIPT, agents], { stdio: 'pipe', env: withEngine(NO_ENGINE) }),
+      );
+      assert.equal(readFileSync(agents, 'utf8'), filled, 'no partial write on STOP');
+    });
+  });
 });