@sabaiway/agent-workflow-kit 1.12.0 → 1.14.0

package/tools/engine-source.test.mjs

@@ -8,6 +8,8 @@ import {
   ENGINE_ENV,
   EXPECTED_ENGINE_NAME,
   ENGINE_FRAGMENT_REL,
+  ORCHESTRATION_FRAGMENT_REL,
+  PROCEDURES_FRAGMENT_REL,
 } from './engine-source.mjs';
 
 // A valid engine dir = it exists (dir), the fragment file exists, and the validator reports a
@@ -180,3 +182,99 @@ describe('readEngineFragment — live read or loud throw', () => {
     );
   });
 });
+
+// The orchestration fragment is a SECOND bounded fragment (Plan 4), selected via deps.rel /
+// detectEngine({ rel }) — non-breaking: the default rel stays the methodology fragment so every
+// existing methodology call site is unchanged.
+describe('detectEngine / readEngineFragment — orchestration fragment via rel', () => {
+  // statType that knows both fragments live in the engine (a current >=1.2.0 engine).
+  const bothPresent = (path) =>
+    path === ENGINE_DIR
+      ? 'dir'
+      : path === join(ENGINE_DIR, ENGINE_FRAGMENT_REL) || path === join(ENGINE_DIR, ORCHESTRATION_FRAGMENT_REL)
+        ? 'file'
+        : null;
+
+  it('verifies the orchestration fragment when rel is the orchestration path', () => {
+    const out = detectEngine(ENGINE_DIR, { source: 'default', rel: ORCHESTRATION_FRAGMENT_REL }, deps({ statType: bothPresent }));
+    assert.equal(out.ok, true);
+  });
+
+  it('an older engine (no orchestration fragment) → detect not-ok, the reason names that fragment', () => {
+    const out = detectEngine(ENGINE_DIR, { source: 'default', rel: ORCHESTRATION_FRAGMENT_REL }, deps()); // okStatType: only the methodology fragment is a file
+    assert.equal(out.ok, false);
+    assert.match(out.reason, /orchestration-slot\.md/);
+  });
+
+  it('the methodology read is unaffected by the new rel default (back-compat)', () => {
+    const out = detectEngine(ENGINE_DIR, { source: 'default' }, deps({ statType: bothPresent }));
+    assert.equal(out.ok, true);
+  });
+
+  it('readEngineFragment reads the orchestration fragment bytes when deps.rel is set', () => {
+    const out = readEngineFragment(
+      ENGINE_DIR,
+      deps({ source: 'default', rel: ORCHESTRATION_FRAGMENT_REL, statType: bothPresent, readFileSync: () => 'ORCH BODY' }),
+    );
+    assert.equal(out, 'ORCH BODY');
+  });
+
+  it('readEngineFragment STOPs loudly when the orchestration fragment is absent (older engine)', () => {
+    assert.throws(
+      () => readEngineFragment(ENGINE_DIR, deps({ source: 'default', rel: ORCHESTRATION_FRAGMENT_REL })),
+      (err) => {
+        assert.match(err.message, /methodology engine not found\/invalid/);
+        assert.match(err.message, /orchestration-slot\.md/);
+        assert.match(err.message, /npx @sabaiway\/agent-workflow-engine@latest init/);
+        return true;
+      },
+    );
+  });
+});
+
+// The activity-procedures canon is a THIRD live-read fragment (engine >= 1.3.0), selected the same way
+// (deps.rel / detectEngine({ rel })). An engine too old to ship it must read as not-ok naming the
+// fragment, and readEngineFragment must STOP loudly — the procedures CLI maps that to a clean exit 1.
+describe('detectEngine / readEngineFragment — procedures fragment via rel', () => {
+  const proceduresPresent = (path) =>
+    path === ENGINE_DIR
+      ? 'dir'
+      : path === join(ENGINE_DIR, ENGINE_FRAGMENT_REL) || path === join(ENGINE_DIR, PROCEDURES_FRAGMENT_REL)
+        ? 'file'
+        : null;
+
+  it('exposes the procedures fragment rel constant', () => {
+    assert.equal(PROCEDURES_FRAGMENT_REL, 'references/procedures.md');
+  });
+
+  it('verifies the procedures fragment when rel is the procedures path', () => {
+    const out = detectEngine(ENGINE_DIR, { source: 'default', rel: PROCEDURES_FRAGMENT_REL }, deps({ statType: proceduresPresent }));
+    assert.equal(out.ok, true);
+  });
+
+  it('an older engine (no procedures fragment) → detect not-ok, the reason names that fragment', () => {
+    const out = detectEngine(ENGINE_DIR, { source: 'default', rel: PROCEDURES_FRAGMENT_REL }, deps()); // okStatType: only the methodology fragment is a file
+    assert.equal(out.ok, false);
+    assert.match(out.reason, /procedures\.md/);
+  });
+
+  it('readEngineFragment reads the procedures fragment bytes when deps.rel is set', () => {
+    const out = readEngineFragment(
+      ENGINE_DIR,
+      deps({ source: 'default', rel: PROCEDURES_FRAGMENT_REL, statType: proceduresPresent, readFileSync: () => 'PROCEDURES BODY' }),
+    );
+    assert.equal(out, 'PROCEDURES BODY');
+  });
+
+  it('readEngineFragment STOPs loudly when the procedures fragment is absent (engine < 1.3.0)', () => {
+    assert.throws(
+      () => readEngineFragment(ENGINE_DIR, deps({ source: 'default', rel: PROCEDURES_FRAGMENT_REL })),
+      (err) => {
+        assert.match(err.message, /methodology engine not found\/invalid/);
+        assert.match(err.message, /procedures\.md/);
+        assert.match(err.message, /npx @sabaiway\/agent-workflow-engine@latest init/);
+        return true;
+      },
+    );
+  });
+});

package/tools/family-registry.mjs

@@ -23,6 +23,7 @@ import os from 'node:os';
 import { resolveDir } from './detect-backends.mjs';
 import { validateManifest, readAuthoritativeVersion, UNSUPPORTED, INVALID } from './manifest/validate.mjs';
 import { START_MARKER, excludePath } from './hide-footprint.mjs';
+import { readEngineFragment, ORCHESTRATION_FRAGMENT_REL, PROCEDURES_FRAGMENT_REL } from './engine-source.mjs';
 
 // ── manifestState values (the detect-backends precedence, generalized to any member kind) ──────────
 export const NOT_INSTALLED = 'not-installed';
@@ -143,7 +144,37 @@ export const classifyMember = (member, deps = {}) => {
   return { name: member.name, kind: member.kind, installed, skillDir: installed ? skillDir : null, manifestState, version };
 };
 
-export const surveyFamily = (deps = {}) => FAMILY_MEMBERS.map((member) => classifyMember(member, deps));
+// An installed engine may be a VALID methodology-engine yet too old (or incomplete) to ship one of the
+// kit's live-read fragments: `references/orchestration-slot.md` (the recipes pointer, engine >= 1.2.0)
+// and `references/procedures.md` (the activity-procedures canon, engine >= 1.3.0). Each missing
+// fragment is a DISTINCT, plain-language caveat. They are collected into `row.caveats` (an ARRAY) so an
+// engine missing BOTH surfaces both — a single `row.caveat` would overwrite one with the other. The
+// check mirrors what each consumer actually does — `readEngineFragment(..., { rel })` validates
+// the manifest AND reads the fragment — so an absent, non-file, OR present-but-unreadable fragment all
+// surface (status never claims "ok" for a fragment a reconcile / the procedures CLI would STOP on), and
+// a current, readable fragment never gets the caveat. Read-only, best-effort.
+const ENGINE_FRAGMENT_CAVEATS = [
+  { rel: ORCHESTRATION_FRAGMENT_REL, caveat: 'engine present but does not supply the recipes pointer (too old / incomplete) — run `npx @sabaiway/agent-workflow-engine@latest init`' },
+  { rel: PROCEDURES_FRAGMENT_REL, caveat: 'engine present but does not ship the activity-procedures canon (too old / incomplete) — run `npx @sabaiway/agent-workflow-engine@latest init`' },
+];
+
+export const surveyFamily = (deps = {}) =>
+  FAMILY_MEMBERS.map((member) => {
+    const row = classifyMember(member, deps);
+    if (row.kind === 'methodology-engine' && row.manifestState === OK && row.skillDir) {
+      const fragmentUsable = (rel) => {
+        try {
+          readEngineFragment(row.skillDir, { source: 'default', rel, ...deps });
+          return true;
+        } catch {
+          return false; // absent / non-file / unreadable fragment → the engine can't supply it
+        }
+      };
+      const caveats = ENGINE_FRAGMENT_CAVEATS.filter((f) => !fragmentUsable(f.rel)).map((f) => f.caveat);
+      if (caveats.length) row.caveats = caveats;
+    }
+    return row;
+  });
 
 // ── the DEPLOY axis ──────────────────────────────────────────────────────────────
 // Read a one-line semver stamp (docs/ai/.workflow-version etc.). Returns the trimmed version or null.
@@ -208,6 +239,7 @@ export const formatStatus = (family, project = null) => {
   for (const m of family) {
     const ver = m.version ? `v${m.version}` : '—';
     lines.push(`  ${pad(m.name, 26)}[${pad(m.manifestState, 16)}] ${pad(ver, 10)} ${m.kind}`);
+    for (const c of m.caveats ?? []) lines.push(`      ↳ ${c}`);
   }
   if (project) {
     lines.push('', `project deployment (${project.dir})`, '');

package/tools/family-registry.test.mjs

@@ -18,6 +18,7 @@ import {
 } from './family-registry.mjs';
 import { VALID, INVALID, UNSUPPORTED } from './manifest/validate.mjs';
 import { START_MARKER } from './hide-footprint.mjs';
+import { ORCHESTRATION_FRAGMENT_REL, PROCEDURES_FRAGMENT_REL } from './engine-source.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = resolve(__dirname, '../..'); // agent-workflow-kit/tools → repo root
@@ -102,6 +103,95 @@ describe('surveyFamily', () => {
     assert.equal(rows.length, FAMILY_MEMBERS.length);
     assert.ok(rows.every((r) => r.manifestState === NOT_INSTALLED));
   });
+
+  // Only the engine member validates as ok (its name+kind match); the others go FOREIGN under this
+  // shared validate stub — so only the engine row is eligible for the orchestration-fragment caveat.
+  const engineValidate = (dir) =>
+    String(dir).includes('agent-workflow-engine')
+      ? { result: VALID, name: 'agent-workflow-engine', kind: 'methodology-engine', available: true }
+      : { result: VALID, name: 'x', kind: 'x', available: true };
+
+  // The caveats mirror the consumers: each reads a live engine fragment (readEngineFragment) — the
+  // recipes pointer (orchestration-slot.md, engine >= 1.2.0) AND the activity-procedures canon
+  // (procedures.md, engine >= 1.3.0). An absent / non-file / unreadable fragment surfaces as a DISTINCT
+  // caveat in `row.caveats` (an array, so missing BOTH surfaces BOTH); a current readable
+  // fragment never gets one. Helpers below model each fragment's on-disk state independently.
+  const engineDeps = (over) => ({
+    exists: () => true, // SKILL.md marker present (classifyMember)
+    stat: () => ({ isFile: () => true }),
+    getenv: {},
+    home: '/home/test',
+    validate: engineValidate,
+    readVersion: () => ({ version: '1.3.0' }),
+    ...over,
+  });
+  // statType where each fragment is independently a readable file ('file') or absent (null); the engine
+  // dir + everything else is a 'dir'. readFileSync returns content for a present fragment.
+  // Pin the mock to the AUTHORITATIVE engine-source constants (mirrors engine-source.test.mjs), so a
+  // fragment-path rename follows here instead of silently passing against the old basename.
+  const fragmentStat = ({ orch = 'file', proc = 'file' }) => (p) => {
+    const s = String(p);
+    if (s.endsWith(ORCHESTRATION_FRAGMENT_REL)) return orch;
+    if (s.endsWith(PROCEDURES_FRAGMENT_REL)) return proc;
+    return 'dir';
+  };
+  const caveatsOf = (rows) => rows.find((r) => r.kind === 'methodology-engine').caveats ?? [];
+
+  it('a current engine WITH BOTH fragments readable carries NO caveat', () => {
+    const rows = surveyFamily(engineDeps({ statType: fragmentStat({}), readFileSync: () => '> a bounded fragment' }));
+    const engine = rows.find((r) => r.kind === 'methodology-engine');
+    assert.equal(engine.manifestState, OK);
+    assert.equal(engine.caveats, undefined, 'no caveats when both live fragments are present + readable');
+  });
+
+  it('an OK engine MISSING the orchestration fragment gets the recipes caveat (only)', () => {
+    const rows = surveyFamily(engineDeps({
+      readVersion: () => ({ version: '1.2.0' }),
+      statType: fragmentStat({ orch: null }), // recipes fragment ABSENT, procedures present
+      readFileSync: () => '> a bounded fragment',
+    }));
+    const caveats = caveatsOf(rows);
+    assert.equal(caveats.length, 1);
+    assert.match(caveats[0], /recipes pointer/i);
+  });
+
+  it('an OK engine MISSING the procedures canon gets the activity-procedures caveat (only)', () => {
+    // The realistic post-release case: an engine at 1.2.0 ships the recipes pointer but not procedures.md.
+    const rows = surveyFamily(engineDeps({
+      readVersion: () => ({ version: '1.2.0' }),
+      statType: fragmentStat({ proc: null }), // procedures canon ABSENT, recipes present
+      readFileSync: () => '> a bounded fragment',
+    }));
+    const caveats = caveatsOf(rows);
+    assert.equal(caveats.length, 1);
+    assert.match(caveats[0], /activity-procedures|procedures canon/i);
+  });
+
+  it('an engine MISSING BOTH fragments surfaces BOTH caveats (neither overwrites the other)', () => {
+    const rows = surveyFamily(engineDeps({
+      readVersion: () => ({ version: '1.1.0' }),
+      statType: fragmentStat({ orch: null, proc: null }),
+    }));
+    const caveats = caveatsOf(rows);
+    assert.equal(caveats.length, 2, 'both missing fragments are reported');
+    assert.ok(caveats.some((c) => /recipes pointer/i.test(c)));
+    assert.ok(caveats.some((c) => /activity-procedures|procedures canon/i.test(c)));
+  });
+
+  it('a broken engine whose fragments are DIRECTORIES is NOT a false "ok"', () => {
+    const rows = surveyFamily(engineDeps({ statType: () => 'dir' })); // every fragment path is a dir
+    assert.equal(caveatsOf(rows).length, 2, 'non-file fragments are caveated');
+  });
+
+  it('a fragment PRESENT but UNREADABLE is NOT a false "ok" (mirrors the consumer STOP)', () => {
+    const rows = surveyFamily(engineDeps({
+      statType: fragmentStat({}), // both present as files
+      readFileSync: () => {
+        throw Object.assign(new Error('EACCES'), { code: 'EACCES' }); // but unreadable
+      },
+    }));
+    assert.equal(caveatsOf(rows).length, 2, 'unreadable fragments are caveated, not reported clean');
+  });
 });
 
 // ── surveyProject ────────────────────────────────────────────────────────────────