@sabaiway/agent-workflow-kit 1.3.0 → 1.5.0

package/tools/detect-backends.test.mjs

@@ -0,0 +1,342 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, mkdtempSync, writeFileSync, symlinkSync, chmodSync, readFileSync, readdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  expandTilde,
+  resolveDir,
+  findOnPath,
+  probeCredential,
+  detectBackend,
+  detectBackends,
+  formatReport,
+  KNOWN_BACKENDS,
+} from './detect-backends.mjs';
+
+const REPO = fileURLToPath(new URL('../../', import.meta.url)); // …/agent-workflow-kit/tools/ → repo root
+const KIT = join(REPO, 'agent-workflow-kit');
+const FIX = join(KIT, 'tools', 'manifest', 'fixtures');
+const HOME = '/home/u';
+
+// An ENOENT-typed error, matching the shape Node's fs throws (used to drive the wrapped probes).
+const enoent = () => Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
+const eacces = () => Object.assign(new Error('EACCES'), { code: 'EACCES' });
+
+// ── pure helpers ─────────────────────────────────────────────────────────────
+
+describe('expandTilde', () => {
+  it('"~" → home', () => assert.equal(expandTilde('~', HOME), HOME));
+  it('"~/x" → home/x', () => assert.equal(expandTilde('~/x/y', HOME), join(HOME, 'x/y')));
+  it('absolute path untouched', () => assert.equal(expandTilde('/abs/path', HOME), '/abs/path'));
+  it('relative path untouched', () => assert.equal(expandTilde('rel/path', HOME), 'rel/path'));
+});
+
+describe('resolveDir', () => {
+  it('non-empty env wins, as-is', () => {
+    assert.equal(resolveDir({ env: 'D', default: '~/d' }, { D: '/from/env' }, HOME), '/from/env');
+  });
+  it('empty-string env → default', () => {
+    assert.equal(resolveDir({ env: 'D', default: '/d' }, { D: '' }, HOME), '/d');
+  });
+  it('null env name → default', () => {
+    assert.equal(resolveDir({ env: null, default: '/d' }, {}, HOME), '/d');
+  });
+  it('default is tilde-expanded', () => {
+    assert.equal(resolveDir({ env: 'D', default: '~/skills/x' }, {}, HOME), join(HOME, 'skills/x'));
+  });
+});
+
+describe('findOnPath', () => {
+  const linux = { platform: 'linux', getenv: { PATH: '/a:/b' }, realpath: (p) => p };
+
+  it('present via posix exec-bit', () => {
+    const r = findOnPath('codex', { ...linux, access: (p) => { if (p !== '/a/codex') throw enoent(); } });
+    assert.equal(r.state, 'present');
+    assert.equal(r.path, '/a/codex');
+  });
+
+  it('missing when absent everywhere', () => {
+    const r = findOnPath('codex', { ...linux, access: () => { throw enoent(); } });
+    assert.equal(r.state, 'missing');
+    assert.equal(r.path, null);
+  });
+
+  it('found in the 2nd PATH dir', () => {
+    const r = findOnPath('agy', { ...linux, access: (p) => { if (p !== '/b/agy') throw enoent(); } });
+    assert.equal(r.state, 'present');
+    assert.equal(r.path, '/b/agy');
+  });
+
+  it('Windows: matches via PATHEXT', () => {
+    const r = findOnPath('codex', {
+      platform: 'win32',
+      getenv: { PATH: 'C:\\bin', PATHEXT: '.COM;.EXE;.CMD' },
+      realpath: (p) => p,
+      access: (p) => { if (!p.endsWith('codex.EXE')) throw enoent(); },
+    });
+    assert.equal(r.state, 'present');
+    assert.ok(r.path.endsWith('codex.EXE'));
+  });
+
+  it('resolves a symlinked binary to its realpath (real fs)', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'awf-path-'));
+    const target = join(dir, 'real-tool');
+    const link = join(dir, 'linked-tool');
+    writeFileSync(target, '#!/bin/sh\n');
+    chmodSync(target, 0o755);
+    symlinkSync(target, link);
+    const r = findOnPath('linked-tool', { platform: 'linux', getenv: { PATH: dir } });
+    assert.equal(r.state, 'present');
+    assert.equal(r.path, target); // realpath followed the symlink
+  });
+
+  it('accessSync throwing EACCES → unknown (cannot confirm)', () => {
+    const r = findOnPath('codex', { ...linux, access: () => { throw eacces(); } });
+    assert.equal(r.state, 'unknown');
+  });
+});
+
+describe('probeCredential', () => {
+  const entry = (over = {}) => ({ credential: { env: 'CRED', default: '~/.codex', file: 'auth.json', ...over } });
+
+  it('present when the marker file is a real file (env override honoured)', () => {
+    const r = probeCredential(entry(), { getenv: { CRED: '/cdir' }, home: HOME, exists: () => true, stat: () => ({ isFile: () => true }) });
+    assert.equal(r.state, 'present');
+    assert.equal(r.path, '/cdir/auth.json');
+  });
+
+  it('absent → missing', () => {
+    const r = probeCredential(entry(), { getenv: {}, home: HOME, exists: () => false });
+    assert.equal(r.state, 'missing');
+    assert.equal(r.path, join(HOME, '.codex/auth.json')); // env unset → tilde default
+  });
+
+  it('statSync throwing a non-ENOENT error → unknown', () => {
+    const r = probeCredential(entry(), { getenv: {}, home: HOME, exists: () => true, stat: () => { throw eacces(); } });
+    assert.equal(r.state, 'unknown');
+  });
+
+  it('credential.env:null uses the (tilde-expanded) default', () => {
+    const r = probeCredential(entry({ env: null, default: '~/.gemini/antigravity-cli', file: 'tok' }), {
+      getenv: {}, home: HOME, exists: () => true, stat: () => ({ isFile: () => true }),
+    });
+    assert.equal(r.state, 'present');
+    assert.equal(r.path, join(HOME, '.gemini/antigravity-cli/tok'));
+  });
+
+  it('never counts a directory as a present credential', () => {
+    const r = probeCredential(entry(), { getenv: { CRED: '/cdir' }, home: HOME, exists: () => true, stat: () => ({ isFile: () => false }) });
+    assert.equal(r.state, 'missing');
+  });
+});
+
+// ── detectBackend: manifestState precedence ──────────────────────────────────
+
+// Build an entry whose installed-marker is `capability.json` so a fixture without a SKILL.md still
+// registers as "installed", letting the validator branch decide the state.
+const entryAt = (dir, over = {}) => ({
+  name: 'codex-cli-bridge',
+  installed: { env: 'X_DIR', default: dir, file: 'capability.json' },
+  bin: 'codex',
+  credential: { env: null, default: '/no/such/dir', file: 'auth.json' },
+  setupUrl: 'https://example.test/setup',
+  setupPathLocal: 'setup/README.md',
+  ...over,
+});
+
+// All readiness inputs present, so manifestState is the only variable under test.
+const allPresentDeps = {
+  getenv: {},
+  probeCli: () => ({ bin: 'codex', state: 'present', path: '/usr/bin/codex' }),
+  probeCredentials: () => ({ state: 'present', path: '/c/auth.json' }),
+  probeWrapper: (cmd) => ({ name: cmd, state: 'present' }),
+};
+
+describe('detectBackend — manifestState precedence', () => {
+  it('not-installed when the marker file is absent', () => {
+    const empty = mkdtempSync(join(tmpdir(), 'awf-empty-'));
+    const d = detectBackend(entryAt(empty), allPresentDeps);
+    assert.equal(d.manifestState, 'not-installed');
+    assert.equal(d.skillDir, null);
+    assert.equal(d.readiness, 'needs-skill');
+  });
+
+  it('unsupported-schema (fixtures/unknown-schema)', () => {
+    const d = detectBackend(entryAt(join(FIX, 'unknown-schema')), allPresentDeps);
+    assert.equal(d.manifestState, 'unsupported-schema');
+  });
+
+  it('invalid-manifest (fixtures/malformed-json)', () => {
+    const d = detectBackend(entryAt(join(FIX, 'malformed-json')), allPresentDeps);
+    assert.equal(d.manifestState, 'invalid-manifest');
+  });
+
+  it('stub (fixtures/stub — available:false)', () => {
+    const d = detectBackend(entryAt(join(FIX, 'stub')), allPresentDeps);
+    assert.equal(d.manifestState, 'stub');
+  });
+
+  it('foreign (valid, but a memory-substrate, not this backend)', () => {
+    const d = detectBackend(entryAt(join(REPO, 'agent-workflow-memory')), allPresentDeps);
+    assert.equal(d.manifestState, 'foreign');
+    assert.match(d.manifestReason, /memory-substrate/);
+  });
+
+  it('ok (the real codex-cli-bridge dir, marker = SKILL.md)', () => {
+    const d = detectBackend(
+      entryAt(join(REPO, 'codex-cli-bridge'), { installed: { env: 'X_DIR', default: join(REPO, 'codex-cli-bridge'), file: 'SKILL.md' } }),
+      allPresentDeps,
+    );
+    assert.equal(d.manifestState, 'ok');
+    assert.deepEqual(d.wrappers.map((w) => w.name).sort(), ['codex-exec', 'codex-review']);
+    assert.equal(d.setupHint.local, 'setup/README.md'); // installed AND setup/README.md exists
+  });
+});
+
+// ── detectBackend: readiness matrix (over an `ok` manifest) ───────────────────
+
+const okEntry = entryAt(join(REPO, 'codex-cli-bridge'), {
+  installed: { env: 'X_DIR', default: join(REPO, 'codex-cli-bridge'), file: 'SKILL.md' },
+});
+
+describe('detectBackend — readiness over an ok manifest', () => {
+  it('ready when cli + credentials + every wrapper present', () => {
+    assert.equal(detectBackend(okEntry, allPresentDeps).readiness, 'ready');
+  });
+
+  it('needs-cli when the CLI is missing', () => {
+    const d = detectBackend(okEntry, { ...allPresentDeps, probeCli: () => ({ bin: 'codex', state: 'missing', path: null }) });
+    assert.equal(d.readiness, 'needs-cli');
+  });
+
+  it('needs-cli when the CLI is unknown (unknown never counts as present)', () => {
+    const d = detectBackend(okEntry, { ...allPresentDeps, probeCli: () => ({ bin: 'codex', state: 'unknown', path: null }) });
+    assert.equal(d.readiness, 'needs-cli');
+  });
+
+  it('needs-credentials when the credential marker is missing', () => {
+    const d = detectBackend(okEntry, { ...allPresentDeps, probeCredentials: () => ({ state: 'missing', path: '/c/auth.json' }) });
+    assert.equal(d.readiness, 'needs-credentials');
+  });
+
+  it('degraded when a wrapper is missing from PATH', () => {
+    const d = detectBackend(okEntry, {
+      ...allPresentDeps,
+      probeWrapper: (cmd) => ({ name: cmd, state: cmd === 'codex-review' ? 'missing' : 'present' }),
+    });
+    assert.equal(d.readiness, 'degraded');
+  });
+
+  it('needs-skill dominates even when cli + credentials are present', () => {
+    const empty = mkdtempSync(join(tmpdir(), 'awf-empty2-'));
+    const d = detectBackend(entryAt(empty), allPresentDeps);
+    assert.equal(d.readiness, 'needs-skill');
+  });
+});
+
+// ── registry drift guard ─────────────────────────────────────────────────────
+
+const readManifest = (dir) => JSON.parse(readFileSync(join(dir, 'capability.json'), 'utf8'));
+
+// Every top-level in-repo dir with a kind:execution-backend manifest, discovered fresh from disk.
+const inRepoBackends = () =>
+  readdirSync(REPO, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && existsSync(join(REPO, e.name, 'capability.json')))
+    .filter((e) => readManifest(join(REPO, e.name)).kind === 'execution-backend')
+    .map((e) => e.name);
+
+describe('KNOWN_BACKENDS — drift guard against the in-repo manifests', () => {
+  it('set equality: registry names == in-repo execution-backend dirs', () => {
+    const onDisk = inRepoBackends().sort();
+    const registry = KNOWN_BACKENDS.map((b) => b.name).sort();
+    assert.deepEqual(registry, onDisk);
+  });
+
+  it('the methodology-engine is NOT counted as a backend', () => {
+    assert.ok(!KNOWN_BACKENDS.some((b) => b.name === 'agent-workflow-engine'));
+    assert.equal(readManifest(join(REPO, 'agent-workflow-engine')).kind, 'methodology-engine');
+  });
+
+  it('registry names are unique', () => {
+    const names = KNOWN_BACKENDS.map((b) => b.name);
+    assert.equal(new Set(names).size, names.length);
+  });
+
+  it('each entry.installed matches the real manifest detect.installed', () => {
+    for (const entry of KNOWN_BACKENDS) {
+      const real = readManifest(join(REPO, entry.name)).detect.installed;
+      assert.equal(entry.installed.env, real.env, `${entry.name} env`);
+      assert.equal(entry.installed.default, real.default, `${entry.name} default`);
+      assert.equal(entry.installed.file, real.file, `${entry.name} file`);
+    }
+  });
+
+  it('each entry.setupPathLocal exists in the repo', () => {
+    for (const entry of KNOWN_BACKENDS) {
+      assert.ok(existsSync(join(REPO, entry.name, entry.setupPathLocal)), `${entry.name}/${entry.setupPathLocal}`);
+    }
+  });
+});
+
+// ── formatReport ─────────────────────────────────────────────────────────────
+
+const readyStatus = {
+  name: 'codex-cli-bridge',
+  manifestState: 'ok',
+  manifestReason: 'ok',
+  skillDir: '/skills/codex-cli-bridge',
+  cli: { bin: 'codex', state: 'present', path: '/usr/bin/codex' },
+  credentials: { state: 'present', path: '/home/u/.codex/auth.json' },
+  wrappers: [{ name: 'codex-exec', state: 'present' }, { name: 'codex-review', state: 'present' }],
+  readiness: 'ready',
+  setupHint: { local: 'setup/README.md', url: 'https://example.test/codex' },
+};
+const needsSkillStatus = {
+  name: 'antigravity-cli-bridge',
+  manifestState: 'not-installed',
+  manifestReason: 'not installed',
+  skillDir: null,
+  cli: { bin: 'agy', state: 'present', path: '/home/u/.local/bin/agy' },
+  credentials: { state: 'present', path: '/home/u/.gemini/antigravity-cli/antigravity-oauth-token' },
+  wrappers: [],
+  readiness: 'needs-skill',
+  setupHint: { url: 'https://example.test/agy' },
+};
+
+describe('formatReport', () => {
+  const out = formatReport([readyStatus, needsSkillStatus]);
+
+  it('never says "authenticated" or "authed" (credentials = file presence, not a live login)', () => {
+    const low = out.toLowerCase();
+    assert.ok(!low.includes('authenticated'));
+    assert.ok(!low.includes('authed'));
+  });
+
+  it('uses the word "credentials"', () => assert.ok(out.toLowerCase().includes('credentials')));
+
+  it('shows the ready backend as ready', () => {
+    assert.match(out, /codex-cli-bridge.*ready/s);
+  });
+
+  it('a needs-skill backend (CLI + creds present) says install the bridge + points at the setup URL', () => {
+    assert.match(out, /needs-skill/);
+    assert.match(out, /install the bridge/);
+    assert.match(out, /https:\/\/example\.test\/agy/);
+  });
+});
+
+describe('detectBackends — live shape on this machine', () => {
+  it('returns one status per registry entry with all data-model keys', () => {
+    const statuses = detectBackends();
+    assert.equal(statuses.length, KNOWN_BACKENDS.length);
+    for (const s of statuses) {
+      for (const key of ['name', 'manifestState', 'manifestReason', 'cli', 'credentials', 'wrappers', 'readiness', 'setupHint']) {
+        assert.ok(key in s, `${s.name} missing ${key}`);
+      }
+      assert.ok(['present', 'missing', 'unknown'].includes(s.cli.state));
+      assert.ok(['present', 'missing', 'unknown'].includes(s.credentials.state));
+    }
+  });
+});

package/tools/inject-methodology.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// Methodology slot injection — the composition root's only mutation of memory's AGENTS.md.
+//
+// memory ships an EMPTY delimited slot in templates/AGENTS.md; the kit (which knows the whole
+// family) fills it. The engine only *provides* the methodology text — Plan 2 repoints the
+// source to it. Phase 1 source = the kit's bundled tools/methodology-slot.md (a BOUNDED summary
+// + pointer, NOT the full references/planning.md), so AGENTS.md stays under its line cap.
+//
+// Marker contract (shared with memory's upgrade extract-and-reinsert), strictly enforced:
+//   - exactly one ordered start→end pair  → replace only the bytes between them.
+//   - markers absent (legacy AGENTS.md)   → gracefully NO-OP (slot migration is Plan 2).
+//   - any malformed state (single, reversed, nested, duplicate) → NO-OP WITH AN ERROR; never edit.
+// Prefix/suffix bytes are preserved exactly. Re-running with the same fragment is idempotent.
+//
+// Pure string functions (testable with byte-preservation fixtures); dependency-free, Node >= 18.
+
+export const START_MARKER = '<!-- workflow:methodology:start -->';
+export const END_MARKER = '<!-- workflow:methodology:end -->';
+export const AGENTS_MD_CAP = 100; // the deployed AGENTS.md line budget (its own footer rule)
+
+const countOccurrences = (haystack, needle) => {
+  let count = 0;
+  let from = 0;
+  for (;;) {
+    const idx = haystack.indexOf(needle, from);
+    if (idx === -1) return count;
+    count += 1;
+    from = idx + needle.length;
+  }
+};
+
+// Classify the marker state of an AGENTS.md text. Pure; no fs.
+//   { state: 'ok',      startIdx, endIdx }   exactly one ordered pair
+//   { state: 'absent' }                      no markers at all → caller no-ops
+//   { state: 'malformed', reason }           anything else → caller no-ops WITH error
+export const findSlot = (text) => {
+  const starts = countOccurrences(text, START_MARKER);
+  const ends = countOccurrences(text, END_MARKER);
+  if (starts === 0 && ends === 0) return { state: 'absent' };
+  if (starts !== 1 || ends !== 1) {
+    return { state: 'malformed', reason: `expected exactly one start/end marker pair, found ${starts} start / ${ends} end` };
+  }
+  const startIdx = text.indexOf(START_MARKER);
+  const endIdx = text.indexOf(END_MARKER);
+  if (endIdx < startIdx) return { state: 'malformed', reason: 'end marker precedes start marker' };
+  return { state: 'ok', startIdx, endIdx };
+};
+
+// Inject `fragment` between the markers, replacing only the bytes between them.
+// Returns { status: 'injected' | 'noop-absent' | 'error', text, error? }. On absent/error the
+// returned text is the INPUT, byte-for-byte (never edit on a malformed slot). Pass
+// `{ maxLines }` to enforce the AGENTS.md line cap as a postcondition (refuse, don't bust it).
+export const injectMethodology = (text, fragment, { maxLines } = {}) => {
+  // A fragment that itself contains a marker would create a duplicate/nested slot — refuse.
+  if (fragment.includes(START_MARKER) || fragment.includes(END_MARKER)) {
+    return { status: 'error', text, error: 'fragment contains a methodology marker — refusing to inject (would create a duplicate/nested slot)' };
+  }
+  const slot = findSlot(text);
+  if (slot.state === 'absent') return { status: 'noop-absent', text };
+  if (slot.state === 'malformed') return { status: 'error', text, error: slot.reason };
+  const before = text.slice(0, slot.startIdx + START_MARKER.length);
+  const after = text.slice(slot.endIdx);
+  const out = `${before}\n${fragment.trim()}\n${after}`;
+  if (maxLines != null) {
+    const lines = out.split('\n').length - (out.endsWith('\n') ? 1 : 0);
+    if (lines > maxLines) {
+      return { status: 'error', text, error: `injection would push AGENTS.md to ${lines} lines (cap ${maxLines}) — trim the fragment or the file` };
+    }
+  }
+  return { status: 'injected', text: out };
+};
+
+// Inverse used by memory's upgrade: extract the current slot content (preserve-on-upgrade).
+// Returns the bytes strictly between the markers, or null on absent/malformed.
+export const extractSlot = (text) => {
+  const slot = findSlot(text);
+  if (slot.state !== 'ok') return null;
+  return text.slice(slot.startIdx + START_MARKER.length, slot.endIdx);
+};
+
+const main = async (argv) => {
+  const { readFile, writeFile, rename } = 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 agentsPath = argv[0];
+  if (!agentsPath) {
+    console.error('usage: inject-methodology.mjs <path/to/AGENTS.md> [fragment.md]');
+    process.exit(2);
+  }
+  const fragmentPath = argv[1] ? resolve(argv[1]) : resolve(here, 'methodology-slot.md');
+  const text = await readFile(resolve(agentsPath), 'utf8');
+  const fragment = await readFile(fragmentPath, 'utf8');
+  const result = injectMethodology(text, fragment, { maxLines: AGENTS_MD_CAP });
+  if (result.status === 'error') {
+    console.error(`[inject-methodology] malformed slot — refusing to edit: ${result.error}`);
+    process.exit(1);
+  }
+  if (result.status === 'noop-absent') {
+    console.log('[inject-methodology] no methodology markers found — nothing to inject (legacy AGENTS.md).');
+    return;
+  }
+  const tmp = join(dirname(resolve(agentsPath)), `.${basename(agentsPath)}.tmp-${process.pid}-${Date.now()}`);
+  await writeFile(tmp, result.text, 'utf8');
+  await rename(tmp, resolve(agentsPath));
+  console.log('[inject-methodology] injected the bounded methodology fragment into the slot.');
+};
+
+const { pathToFileURL } = await import('node:url');
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) await main(process.argv.slice(2));

package/tools/inject-methodology.test.mjs

@@ -0,0 +1,124 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  injectMethodology,
+  findSlot,
+  extractSlot,
+  START_MARKER,
+  END_MARKER,
+} from './inject-methodology.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const FRAGMENT = readFileSync(join(HERE, 'methodology-slot.md'), 'utf8');
+
+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`;
+
+describe('findSlot — marker classification', () => {
+  it('one ordered pair → ok', () => {
+    assert.equal(findSlot(wrap('\n')).state, 'ok');
+  });
+  it('no markers → absent', () => {
+    assert.equal(findSlot('# AGENTS.md\nno markers here\n').state, 'absent');
+  });
+  it('duplicate pair → malformed', () => {
+    const text = `${START_MARKER}\n${END_MARKER}\n${START_MARKER}\n${END_MARKER}\n`;
+    assert.equal(findSlot(text).state, 'malformed');
+  });
+  it('single start only → malformed', () => {
+    assert.equal(findSlot(`x\n${START_MARKER}\ny\n`).state, 'malformed');
+  });
+  it('single end only → malformed', () => {
+    assert.equal(findSlot(`x\n${END_MARKER}\ny\n`).state, 'malformed');
+  });
+  it('reversed (end before start) → malformed', () => {
+    assert.equal(findSlot(`${END_MARKER}\nmiddle\n${START_MARKER}\n`).state, 'malformed');
+  });
+});
+
+describe('injectMethodology — byte preservation', () => {
+  it('injects into an empty slot, preserving prefix/suffix exactly', () => {
+    const input = wrap('\n');
+    const out = injectMethodology(input, FRAGMENT);
+    assert.equal(out.status, 'injected');
+    assert.ok(out.text.startsWith('# AGENTS.md\n\nprefix bytes\n\n## Session Protocols\n\nintro line.\n\n'));
+    assert.ok(out.text.endsWith('\n\n## Hard Constraints\n\nsuffix bytes\n'));
+    assert.ok(out.text.includes(FRAGMENT.trim()));
+    // markers themselves are preserved
+    assert.equal((out.text.match(new RegExp(START_MARKER.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g')) || []).length, 1);
+  });
+
+  it('is idempotent — re-injecting the same fragment is stable', () => {
+    const once = injectMethodology(wrap('\n'), FRAGMENT).text;
+    const twice = injectMethodology(once, FRAGMENT).text;
+    assert.equal(twice, once);
+  });
+
+  it('overwrites a previously-filled slot (bootstrap composition), preserving outside bytes', () => {
+    const filled = wrap('\nstale content\n');
+    const out = injectMethodology(filled, FRAGMENT);
+    assert.equal(out.status, 'injected');
+    assert.ok(!out.text.includes('stale content'));
+    assert.ok(out.text.endsWith('\n\n## Hard Constraints\n\nsuffix bytes\n'));
+  });
+
+  it('rejects a fragment that itself contains a marker (would nest/duplicate the slot)', () => {
+    const out = injectMethodology(wrap('\n'), `bad ${START_MARKER} fragment`);
+    assert.equal(out.status, 'error');
+    assert.equal(out.text, wrap('\n'));
+  });
+
+  it('refuses to bust the line cap (maxLines) instead of silently overflowing it', () => {
+    const huge = Array.from({ length: 40 }, (_, i) => `methodology line ${i}`).join('\n');
+    const out = injectMethodology(wrap('\n'), huge, { maxLines: 20 });
+    assert.equal(out.status, 'error');
+    assert.match(out.error, /cap 20/);
+    assert.equal(out.text, wrap('\n')); // unchanged
+  });
+
+  it('absent markers → no-op, returns input byte-for-byte', () => {
+    const input = '# AGENTS.md\nlegacy file, no slot\n';
+    const out = injectMethodology(input, FRAGMENT);
+    assert.equal(out.status, 'noop-absent');
+    assert.equal(out.text, input);
+  });
+
+  for (const [label, input] of [
+    ['duplicate pair', `${START_MARKER}\n${END_MARKER}\n${START_MARKER}\n${END_MARKER}\n`],
+    ['single start', `head\n${START_MARKER}\ntail\n`],
+    ['single end', `head\n${END_MARKER}\ntail\n`],
+    ['reversed', `${END_MARKER}\nx\n${START_MARKER}\n`],
+  ]) {
+    it(`malformed (${label}) → error, returns input byte-for-byte`, () => {
+      const out = injectMethodology(input, FRAGMENT);
+      assert.equal(out.status, 'error');
+      assert.equal(out.text, input); // never edits a malformed slot
+    });
+  }
+});
+
+describe('extractSlot — preserve-on-upgrade inverse', () => {
+  it('returns the bytes strictly between the markers', () => {
+    assert.equal(extractSlot(wrap('\nkeep me\n')), '\nkeep me\n');
+  });
+  it('null on absent/malformed', () => {
+    assert.equal(extractSlot('no markers'), null);
+    assert.equal(extractSlot(`${START_MARKER}\n${START_MARKER}\n${END_MARKER}\n`), null);
+  });
+});
+
+describe('post-injection cap — AGENTS.md stays under its line budget', () => {
+  it('injecting the bounded fragment into the real memory template keeps AGENTS.md ≤ 100 lines', () => {
+    const template = readFileSync(
+      join(HERE, '..', '..', 'agent-workflow-memory', 'references', 'templates', 'AGENTS.md'),
+      'utf8',
+    );
+    const out = injectMethodology(template, FRAGMENT);
+    assert.equal(out.status, 'injected');
+    const lines = out.text.split('\n').length - (out.text.endsWith('\n') ? 1 : 0);
+    assert.ok(lines <= 100, `AGENTS.md would be ${lines} lines after injection (cap 100)`);
+  });
+});

package/tools/manifest/fixtures/bad-available/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: bad-available
+metadata:
+  version: '1.0.0'
+---
+
+# bad-available fixture — `available` is a string, not a boolean → invalid.

package/tools/manifest/fixtures/bad-available/capability.json

@@ -0,0 +1,10 @@
+{
+  "family": "agent-workflow",
+  "schema": 1,
+  "name": "bad-available",
+  "kind": "memory-substrate",
+  "version": "1.0.0",
+  "available": "yes",
+  "provides": [],
+  "roles": {}
+}

package/tools/manifest/fixtures/detect-array/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: detect-array
+metadata:
+  version: '1.0.0'
+---
+
+# detect-array fixture — `detect.installed` is an array, not an object.

package/tools/manifest/fixtures/detect-array/capability.json

@@ -0,0 +1,10 @@
+{
+  "family": "agent-workflow",
+  "schema": 1,
+  "name": "detect-array",
+  "kind": "memory-substrate",
+  "version": "1.0.0",
+  "provides": [],
+  "roles": {},
+  "detect": { "installed": [] }
+}

package/tools/manifest/fixtures/malformed-json/capability.json

@@ -0,0 +1 @@
+{ "family": "agent-workflow", "schema": 1, "name": "broken",

package/tools/manifest/fixtures/metadata-version/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: metadata-version
+version: '9.9.9'
+description: A decoy top-level `version:` that must NOT be read as the authoritative version.
+metadata:
+  version: '1.0.0'
+---
+
+# metadata-version fixture — authoritative version is `metadata.version` (1.0.0), not the
+# stray top-level `version: 9.9.9`. capability.json declares 1.0.0, so this is VALID.

package/tools/manifest/fixtures/metadata-version/capability.json

@@ -0,0 +1,9 @@
+{
+  "family": "agent-workflow",
+  "schema": 1,
+  "name": "metadata-version",
+  "kind": "memory-substrate",
+  "version": "1.0.0",
+  "provides": [],
+  "roles": {}
+}

package/tools/manifest/fixtures/missing-key/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: missing-key
+metadata:
+  version: '1.0.0'
+---
+
+# missing-key fixture — capability.json omits the required `name` key.

package/tools/manifest/fixtures/missing-key/capability.json

@@ -0,0 +1,8 @@
+{
+  "family": "agent-workflow",
+  "schema": 1,
+  "kind": "memory-substrate",
+  "version": "1.0.0",
+  "provides": [],
+  "roles": {}
+}

package/tools/manifest/fixtures/missing-source/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: missing-source
+metadata:
+  version: '1.0.0'
+---
+
+# missing-source fixture — `roles.review.source` points to a file that does not exist.