@sabaiway/agent-workflow-kit 1.12.0 → 1.14.0

package/tools/inject-methodology.test.mjs

@@ -1,6 +1,6 @@
 import { describe, it, after } from 'node:test';
 import assert from 'node:assert/strict';
-import { readFileSync, writeFileSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, mkdtempSync, rmSync, chmodSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -17,8 +17,20 @@ import {
   AGENTS_MD_CAP,
   START_MARKER,
   END_MARKER,
+  ORCH_START_MARKER,
+  ORCH_END_MARKER,
+  ORCHESTRATION_DESCRIPTOR,
+  findMarkerSlot,
+  extractMarkerSlot,
+  reconcileMarkerSlot,
+  methodologyProceduresHint,
+  PROCEDURES_POINTER,
 } from './inject-methodology.mjs';
 
+// Read the orchestration slot's content from a reconciled entry point.
+const extractOrch = (text) => extractMarkerSlot(text, ORCHESTRATION_DESCRIPTOR);
+const hasOrchSlot = (text) => findMarkerSlot(text, ORCHESTRATION_DESCRIPTOR).state === 'ok';
+
 const HERE = dirname(fileURLToPath(import.meta.url));
 const SCRIPT = join(HERE, 'inject-methodology.mjs');
 
@@ -29,6 +41,9 @@ const SCRIPT = join(HERE, 'inject-methodology.mjs');
 // 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';
+// The SECOND bounded fragment (Plan 4) — distinct content so a test can tell which slot got which.
+const ORCH_FRAGMENT =
+  '> **Orchestration recipes (test fixture)** — Solo / Reviewed / Council / Delegated; pick one with `/agent-workflow-kit recipes`.\n';
 
 // Temp dirs created by the fixtures below — cleaned up once after the whole file.
 const tmpDirs = [];
@@ -36,8 +51,9 @@ 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') => {
+// package.json) + BOTH live fragments (methodology + orchestration). detectEngine accepts it; pass
+// `orchFragment = null` to model an OLDER engine (<1.2.0) that ships no orchestration fragment.
+const makeEngineFixture = (fragment = FRAGMENT, version = '1.0.0', orchFragment = ORCH_FRAGMENT) => {
   const dir = mkdtempSync(join(tmpdir(), 'engine-fixture-'));
   tmpDirs.push(dir);
   const manifest = {
@@ -54,6 +70,7 @@ const makeEngineFixture = (fragment = FRAGMENT, version = '1.0.0') => {
   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);
+  if (orchFragment != null) writeFileSync(join(dir, 'references', 'orchestration-slot.md'), orchFragment);
   return dir;
 };
 
@@ -66,6 +83,11 @@ const withEngine = (engineDir) => ({ ...process.env, AGENT_WORKFLOW_ENGINE_DIR:
 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`;
 
+// An entry point carrying BOTH reconciled slots (the orchestration pair sits right under the
+// methodology pair, as the descriptor anchors it) — the deployed shape after a dual-slot reconcile.
+const wrapDual = (methInner, orchInner) =>
+  `# AGENTS.md\n\nprefix bytes\n\n## Session Protocols\n\nintro line.\n\n${START_MARKER}${methInner}${END_MARKER}\n${ORCH_START_MARKER}${orchInner}${ORCH_END_MARKER}\n\n## Hard Constraints\n\nsuffix bytes\n`;
+
 // The exact Session-Protocols line both deployed templates carry — the slot anchor.
 const ANCHOR_LINE =
   'Start-of-session, during-work, and task-completion procedures live in [`docs/ai/agent_rules.md`](./docs/ai/agent_rules.md) §1. **Read it before any code change.**';
@@ -401,26 +423,32 @@ describe('reconcile CLI — atomic ensure+inject-if-empty+cap, reading the fragm
     }
   };
 
-  it('markerless legacy (with anchor) → slot inserted + filled from the live engine fragment (exit 0)', () => {
+  it('markerless legacy (with anchor) → BOTH slots inserted + filled from their own live engine fragments (exit 0)', () => {
     withTempAgents(legacyWithAnchor(), (agents) => {
       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());
+      assert.equal(extractSlot(out).trim(), FRAGMENT.trim(), 'methodology slot filled from the methodology fragment');
+      assert.ok(hasOrchSlot(out), 'the orchestration slot was inserted below the methodology pair');
+      assert.equal(extractOrch(out).trim(), ORCH_FRAGMENT.trim(), 'orchestration slot filled from the orchestration fragment');
     });
   });
 
-  it('present empty slot → filled from the live engine fragment (exit 0)', () => {
+  it('present empty methodology slot → BOTH slots filled; each from its OWN engine fragment (exit 0)', () => {
     withTempAgents(wrap('\n'), (agents) => {
       execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe', env: withEngine(ENGINE) });
-      assert.equal(extractSlot(readFileSync(agents, 'utf8')).trim(), FRAGMENT.trim());
+      const out = readFileSync(agents, 'utf8');
+      assert.equal(extractSlot(out).trim(), FRAGMENT.trim());
+      assert.equal(extractOrch(out).trim(), ORCH_FRAGMENT.trim());
+      // Per-slot fragment sourcing: the two slots carry DIFFERENT content (not both the methodology one).
+      assert.notEqual(extractSlot(out).trim(), extractOrch(out).trim());
     });
   });
 
-  it('filled/customized slot → zero-diff no-op WITHOUT consulting the engine (engine absent, exit 0)', () => {
-    const custom = wrap('\nuser notes\n');
+  it('BOTH slots already filled → zero-diff no-op WITHOUT consulting the engine (engine absent, exit 0)', () => {
+    const custom = wrapDual('\nuser meth notes\n', '\nuser orch notes\n');
     withTempAgents(custom, (agents) => {
-      // Engine pointed at a path that does not exist — a filled slot must NOT require it.
+      // Engine pointed at a path that does not exist — a fully-filled entry point must NOT require it.
       execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe', env: withEngine(NO_ENGINE) });
       assert.equal(readFileSync(agents, 'utf8'), custom);
     });
@@ -444,7 +472,7 @@ describe('reconcile CLI — atomic ensure+inject-if-empty+cap, reading the fragm
     });
   });
 
-  it('explicit [fragment.md] override fills from that file and skips engine resolution (engine absent)', () => {
+  it('explicit [fragment.md] override fills methodology ONLY and skips both engine + the orchestration slot', () => {
     const override = '> custom override fragment line\n';
     const fdir = mkdtempSync(join(tmpdir(), 'frag-'));
     tmpDirs.push(fdir);
@@ -452,7 +480,98 @@ describe('reconcile CLI — atomic ensure+inject-if-empty+cap, reading the fragm
     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());
+      const out = readFileSync(agents, 'utf8');
+      assert.equal(extractSlot(out).trim(), override.trim(), 'methodology filled from the explicit fragment');
+      assert.ok(!hasOrchSlot(out), 'an explicit single-file override binds methodology only — no orchestration slot added');
+    });
+  });
+
+  it('dual-block cap → orchestration pointer is SOFT-skipped (reported), the file is byte-unchanged (exit 0)', () => {
+    // A 100-line entry point with a FILLED methodology slot + an EMPTY orchestration slot: filling the
+    // orchestration slot would push it to 101 > 100, so it is skipped loudly while methodology stays.
+    const head = [
+      '# AGENTS.md',
+      '',
+      '## Session Protocols',
+      '',
+      'Read it before any code change.',
+      '',
+      START_MARKER,
+      FRAGMENT.trim(),
+      END_MARKER,
+      ORCH_START_MARKER,
+      ORCH_END_MARKER,
+    ];
+    const pad = Array.from({ length: AGENTS_MD_CAP - head.length }, (_, i) => `pad line ${i}`);
+    const atCap = [...head, ...pad].join('\n') + '\n';
+    withTempAgents(atCap, (agents) => {
+      const out = execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { encoding: 'utf8', env: withEngine(ENGINE) });
+      assert.match(out, /skipped/i, 'the orchestration cap-skip is reported, not silent');
+      assert.equal(readFileSync(agents, 'utf8'), atCap, 'file byte-unchanged — the orchestration pointer was withheld, methodology already present');
+    });
+  });
+
+  it('malformed orchestration pair → hard STOP (nonzero), file byte-unchanged (methodology fine)', () => {
+    const malformedOrch =
+      `# AGENTS.md\n\nintro line.\n\n${START_MARKER}\n${FRAGMENT.trim()}\n${END_MARKER}\n` +
+      `${ORCH_START_MARKER}\n${ORCH_END_MARKER}\n${ORCH_START_MARKER}\n${ORCH_END_MARKER}\n`;
+    withTempAgents(malformedOrch, (agents) => {
+      assert.throws(() =>
+        execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe', env: withEngine(ENGINE) }),
+      );
+      assert.equal(readFileSync(agents, 'utf8'), malformedOrch, 'no partial write on an orchestration STOP');
+    });
+  });
+
+  it('engine too old (no orchestration fragment) → methodology filled, orchestration SOFT-skipped (exit 0, not a regression)', () => {
+    // A VALID engine that ships methodology-slot.md but NOT orchestration-slot.md (i.e. <1.2.0). The
+    // methodology fill must NOT be discarded — only the recipes pointer is withheld, reported, exit 0.
+    const oldEngine = makeEngineFixture(FRAGMENT, '1.0.0', null);
+    withTempAgents(wrap('\n'), (agents) => {
+      const out = execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { encoding: 'utf8', env: withEngine(oldEngine) });
+      const text = readFileSync(agents, 'utf8');
+      assert.equal(extractSlot(text).trim(), FRAGMENT.trim(), 'methodology pointer filled (not discarded by the too-old engine)');
+      assert.match(out, /skipped/i, 'the orchestration skip is reported (not silent)');
+      assert.match(out, /too old/i, 'the skip names the too-old-engine reason');
+      assert.ok(!hasOrchSlot(text), 'a too-old engine adds no orchestration pointer');
+    });
+  });
+
+  it('orchestration fragment PRESENT but unreadable → hard STOP (a corrupt engine is NOT mislabeled "too old")', () => {
+    if (process.getuid && process.getuid() === 0) return; // root bypasses 0o000 perms — can't restrict
+    const corruptEngine = makeEngineFixture(FRAGMENT, '1.2.0', '> orchestration line\n'); // both fragments present
+    const orchPath = join(corruptEngine, 'references', 'orchestration-slot.md');
+    chmodSync(orchPath, 0o000);
+    let restricted = false;
+    try {
+      readFileSync(orchPath, 'utf8');
+    } catch {
+      restricted = true;
+    }
+    if (!restricted) {
+      chmodSync(orchPath, 0o644); // exotic FS / perms ignored → can't exercise this path here
+      return;
+    }
+    try {
+      withTempAgents(wrap('\n'), (agents) => {
+        assert.throws(() =>
+          execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe', env: withEngine(corruptEngine) }),
+        );
+        assert.equal(extractSlot(readFileSync(agents, 'utf8')).trim(), '', 'no partial write on a corrupt-fragment STOP');
+      });
+    } finally {
+      chmodSync(orchPath, 0o644); // restore so the after() cleanup can remove the fixture
+    }
+  });
+
+  it('fully absent engine + a fill needed → hard STOP (methodology fragment also unavailable)', () => {
+    // Distinct from the too-old case: a fully absent engine cannot supply EITHER fragment, so the
+    // methodology slot fill itself STOPs first — the dual-slot reconcile never silently no-ops.
+    withTempAgents(wrap('\n'), (agents) => {
+      assert.throws(() =>
+        execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe', env: withEngine(NO_ENGINE) }),
+      );
+      assert.equal(readFileSync(agents, 'utf8'), wrap('\n'), 'no partial write when the engine is fully absent');
     });
   });
 
@@ -498,3 +617,73 @@ describe('reconcile CLI — atomic ensure+inject-if-empty+cap, reading the fragm
     });
   });
 });
+
+// AD-019 §3.1a — the read-only upgrade advisory: a FILLED methodology pointer lacking the procedures
+// route gets a hint (it can't be auto-re-rendered, reconcile preserves a filled slot verbatim); a slot
+// that already routes to procedures, or an empty / absent / malformed slot, is silent. NO mutation.
+describe('methodologyProceduresHint — read-only upgrade advisory (§3.1a)', () => {
+  it('a filled methodology slot WITHOUT the procedures route → a hint naming the procedures command', () => {
+    const entry = wrap('\n> methodology notes the user wrote, no procedures route here\n');
+    const hint = methodologyProceduresHint(entry);
+    assert.ok(hint, 'a filled-without-clause slot yields a hint');
+    assert.match(hint, new RegExp(PROCEDURES_POINTER.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+  });
+
+  it('a filled methodology slot that ALREADY routes to procedures → silent (null)', () => {
+    const entry = wrap(`\n> methodology — see ${PROCEDURES_POINTER} <activity> for the steps\n`);
+    assert.equal(methodologyProceduresHint(entry), null);
+  });
+
+  it('an empty methodology slot → silent (null) — only a filled slot is advised', () => {
+    assert.equal(methodologyProceduresHint(wrap('\n')), null);
+  });
+
+  it('an absent / malformed methodology slot → silent (null)', () => {
+    assert.equal(methodologyProceduresHint('# AGENTS.md\n\nno slot here\n'), null);
+    assert.equal(methodologyProceduresHint(`${START_MARKER}\n${END_MARKER}\n${START_MARKER}\n${END_MARKER}\n`), null);
+  });
+
+  it('is read-only: a pre-filled-without-clause deployment is reported, not mutated, on reconcile (engine absent)', () => {
+    // A dual-filled entry point whose methodology lacks the procedures route: reconcile is a zero-diff
+    // no-op (filled slots preserved) yet still surfaces the hint on stdout — never rewrites the file.
+    const custom = wrapDual('\nuser meth notes, no procedures route\n', '\nuser orch notes\n');
+    const dir = mkdtempSync(join(tmpdir(), 'reconcile-hint-'));
+    tmpDirs.push(dir);
+    const agents = join(dir, 'AGENTS.md');
+    writeFileSync(agents, custom);
+    const out = execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { encoding: 'utf8', env: withEngine(NO_ENGINE) });
+    assert.equal(readFileSync(agents, 'utf8'), custom, 'the file is byte-unchanged (read-only advisory)');
+    assert.match(out, /note:.*procedures/i, 'the upgrade flow surfaces the procedures hint');
+  });
+});
+
+// §3.2 (kit) — the REAL extended engine fragments must keep the dual-fill ≤ 100 on BOTH deployed
+// templates. The methodology fragment grew a procedures clause (still ONE line, so no extra line), but
+// pin it against the REAL fragments + REAL templates so a future fragment edit that DID add a line is
+// caught here, not in the field.
+describe('real-fragment dual-fill ≤ cap on both deployed templates (§3.2)', () => {
+  const ENGINE_REFS = join(HERE, '..', '..', 'agent-workflow-engine', 'references');
+  const realMeth = readFileSync(join(ENGINE_REFS, 'methodology-slot.md'), 'utf8');
+  const realOrch = readFileSync(join(ENGINE_REFS, 'orchestration-slot.md'), 'utf8');
+  const lineCount = (t) => t.split('\n').length - (t.endsWith('\n') ? 1 : 0);
+  const TEMPLATES = {
+    kit: join(HERE, '..', 'references', 'templates', 'AGENTS.md'),
+    memory: join(HERE, '..', '..', 'agent-workflow-memory', 'references', 'templates', 'AGENTS.md'),
+  };
+
+  it('the real methodology fragment carries the procedures route (auto-discovery clause)', () => {
+    assert.match(realMeth, new RegExp(PROCEDURES_POINTER.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+    assert.equal(lineCount(realMeth), 1, 'the methodology fragment stays exactly one content line');
+  });
+
+  for (const [name, path] of Object.entries(TEMPLATES)) {
+    it(`${name} template: filling BOTH real fragments stays ≤ ${AGENTS_MD_CAP} lines`, () => {
+      const template = readFileSync(path, 'utf8');
+      const meth = reconcileSlot(template, realMeth, { maxLines: AGENTS_MD_CAP });
+      assert.equal(meth.status, 'reconciled-filled', `${name}: methodology slot fills`);
+      const both = reconcileMarkerSlot(meth.text, ORCHESTRATION_DESCRIPTOR, realOrch, { maxLines: AGENTS_MD_CAP });
+      assert.equal(both.status, 'reconciled-filled', `${name}: orchestration slot fills`);
+      assert.ok(lineCount(both.text) <= AGENTS_MD_CAP, `${name}: dual-filled entry point is ${lineCount(both.text)} lines (cap ${AGENTS_MD_CAP})`);
+    });
+  }
+});

package/tools/procedures.mjs

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+// Activity-procedures advisor — the read-only `/agent-workflow-kit procedures <activity>` surface.
+//
+// It composes the AD-018 orchestration recipes into NAMED activities: it reads the canonical procedure
+// steps LIVE from the installed agent-workflow-engine (references/procedures.md — AD-016 live read, no
+// bundled mirror), reads the per-project, hand-edited config (docs/ai/orchestration.json), runs the
+// read-only backend detector, and prints the activity's steps VERBATIM + the resolved effective recipe
+// per slot (default = Reviewed-when-a-backend-is-ready, Council on request, slot-aware incl. Delegated).
+//
+// Invariants (mirror recipes.mjs): pure-where-possible, READ-ONLY (never writes, never commits, never
+// runs a subscription CLI). The deterministic resolution lives in the kit (resolveActivityRecipe), not
+// in the agent. Dependency-free, Node >= 18.
+//
+// Exit codes: 0 success (an unsatisfiable explicit override degrades LOUDLY but still exits 0 — it is a
+// valid request that gracefully degraded); 2 usage (unknown <activity> / bad --override syntax);
+// 1 config error (malformed / schema-invalid / unreadable orchestration.json) or engine error (the
+// installed engine is absent / invalid / too old to ship references/procedures.md).
+
+import { readFileSync, lstatSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { pathToFileURL } from 'node:url';
+import { detectBackends } from './detect-backends.mjs';
+import { ACTIVITIES, SLOT_RECIPES, resolveActivityRecipe } from './recipes.mjs';
+import { resolveEngineDir, readEngineFragment, PROCEDURES_FRAGMENT_REL } from './engine-source.mjs';
+
+// The hand-edited, per-project config (strict JSON). cwd-relative — the error prefix uses this rel path
+// so a user sees a path they can open, never an absolute temp/host path.
+export const CONFIG_REL = 'docs/ai/orchestration.json';
+
+// A tagged failure: a plain Error carrying the intended process exit code (2 usage / 1 config|engine).
+// Avoids a class (project rule) while letting main() map a throw to the right code in one place.
+const fail = (exitCode, message) => Object.assign(new Error(message), { exitCode });
+
+// ── argument + override parsing (usage errors → exit 2) ─────────────────────────────
+
+// Parse the activity's --override <slot>=<recipe> tokens into a { slot: recipe } map, validating each
+// against the activity's slots + SLOT_RECIPES. Every malformed token is a USAGE error (exit 2): a bare
+// `<recipe>` (no slot), an unknown slot for the activity, an invalid recipe-for-slot, or a duplicate
+// slot. (An override naming a recipe whose backend merely is not `ready` is NOT a usage error — it
+// degrades loudly at resolution time, exit 0.)
+const parseOverrides = (tokens, activity, activityDef) => {
+  const overrides = {};
+  for (const tok of tokens) {
+    const eq = tok.indexOf('=');
+    if (eq <= 0) throw fail(2, `--override must be <slot>=<recipe> (got "${tok}")`);
+    const slot = tok.slice(0, eq);
+    const recipe = tok.slice(eq + 1);
+    const slotType = activityDef.slots[slot];
+    if (!slotType) {
+      throw fail(
+        2,
+        `--override: unknown slot "${slot}" for activity "${activity}" (${activity} slots: ${Object.keys(activityDef.slots).join(', ')})`,
+      );
+    }
+    if (!(SLOT_RECIPES[slotType] ?? []).includes(recipe)) {
+      throw fail(
+        2,
+        `--override: invalid recipe "${recipe}" for ${slotType} slot of "${activity}" (${slotType} accepts: ${SLOT_RECIPES[slotType].join(', ')})`,
+      );
+    }
+    if (slot in overrides) throw fail(2, `--override: duplicate override for slot "${slot}"`);
+    overrides[slot] = recipe;
+  }
+  return overrides;
+};
+
+const KNOWN_ACTIVITIES = () => Object.keys(ACTIVITIES).join(', ');
+
+// Parse argv → { activity, overrides, json }. Unknown activity / bad flags / bad --override → exit 2.
+const parseArgs = (argv) => {
+  let activity;
+  let json = false;
+  const overrideTokens = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--json') {
+      json = true;
+    } else if (a === '--override') {
+      const tok = argv[i + 1];
+      if (tok === undefined || tok.startsWith('--')) throw fail(2, '--override requires <slot>=<recipe>');
+      overrideTokens.push(tok);
+      i += 1;
+    } else if (a.startsWith('--override=')) {
+      overrideTokens.push(a.slice('--override='.length));
+    } else if (a.startsWith('-')) {
+      throw fail(2, `unknown flag: ${a}`);
+    } else if (activity === undefined) {
+      activity = a;
+    } else {
+      throw fail(2, `unexpected argument: ${a}`);
+    }
+  }
+  if (!activity) throw fail(2, `missing <activity> (known: ${KNOWN_ACTIVITIES()})`);
+  const activityDef = ACTIVITIES[activity];
+  if (!activityDef) throw fail(2, `unknown activity "${activity}" (known: ${KNOWN_ACTIVITIES()})`);
+  return { activity, overrides: parseOverrides(overrideTokens, activity, activityDef), json };
+};
+
+// ── config IO + validation (config errors → exit 1) ────────────────────────────────
+
+// Validate a parsed orchestration.json object against the §2.0 schema. Strict: an unknown top-level
+// activity, an unknown slot for an activity, or a recipe invalid-for-slot is an error. All slots are
+// optional. An optional "_README" string key is allowed + ignored (self-documentation). Never a silent
+// fallback — every rejection is a loud `path: reason`.
+const validateConfig = (config) => {
+  if (config === null || typeof config !== 'object' || Array.isArray(config)) {
+    throw fail(1, `${CONFIG_REL}: must be a JSON object of activity → { slot: recipe }`);
+  }
+  for (const [key, val] of Object.entries(config)) {
+    if (key === '_README') {
+      if (typeof val !== 'string') throw fail(1, `${CONFIG_REL}: "_README" must be a string`);
+      continue;
+    }
+    const activityDef = ACTIVITIES[key];
+    if (!activityDef) {
+      throw fail(1, `${CONFIG_REL}: unknown activity "${key}" (known: ${KNOWN_ACTIVITIES()})`);
+    }
+    if (val === null || typeof val !== 'object' || Array.isArray(val)) {
+      throw fail(1, `${CONFIG_REL}: activity "${key}" must be a JSON object of slot → recipe`);
+    }
+    for (const [slot, recipe] of Object.entries(val)) {
+      const slotType = activityDef.slots[slot];
+      if (!slotType) {
+        throw fail(
+          1,
+          `${CONFIG_REL}: unknown slot "${slot}" for activity "${key}" (${key} slots: ${Object.keys(activityDef.slots).join(', ')})`,
+        );
+      }
+      if (typeof recipe !== 'string' || !(SLOT_RECIPES[slotType] ?? []).includes(recipe)) {
+        throw fail(
+          1,
+          `${CONFIG_REL}: invalid recipe "${recipe}" for ${slotType} slot of "${key}" (${slotType} accepts: ${SLOT_RECIPES[slotType].join(', ')})`,
+        );
+      }
+    }
+  }
+  return config;
+};
+
+// Load + validate the config from <cwd>/docs/ai/orchestration.json. Absent FILE → computed defaults
+// (NOT an error): { config: null, source: 'none' }. Malformed JSON / schema-invalid / unreadable →
+// loud `path: reason` (exit 1). The resolver receives the parsed+validated object (§2.2 IO/resolver split).
+const loadConfig = (cwd, readFile = readFileSync, lstat = lstatSync) => {
+  const full = join(cwd, CONFIG_REL);
+  // Distinguish a TRULY-absent config (no entry at all → computed defaults) from a present-but-
+  // unreadable one (a directory, a DANGLING SYMLINK, a permission error → loud exit 1). lstat does NOT
+  // follow the link, so a dangling symlink reads as "present" here and its later read failure surfaces
+  // loudly — never silently treated as absent (no-silent-failures Hard Constraint).
+  try {
+    lstat(full);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { config: null, source: 'none' };
+    throw fail(1, `${CONFIG_REL}: unreadable (${(err && err.code) || (err && err.message) || err})`);
+  }
+  let raw;
+  try {
+    raw = readFile(full, 'utf8');
+  } catch (err) {
+    throw fail(1, `${CONFIG_REL}: unreadable (${(err && err.code) || (err && err.message) || err})`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw fail(1, `${CONFIG_REL}: malformed JSON (${err.message})`);
+  }
+  return { config: validateConfig(parsed), source: CONFIG_REL };
+};
+
+// ── engine canon: live read + per-activity section extraction (engine errors → exit 1) ──
+
+// Read the activity-procedures canon LIVE from the installed engine. A failure (engine absent / invalid
+// / too old to ship references/procedures.md) is surfaced loudly with the resolver's message + an
+// upgrade hint — never a cryptic fs error.
+const readProceduresCanon = (env, home) => {
+  const { dir, source } = resolveEngineDir({ env, home });
+  try {
+    return readEngineFragment(dir, { source, rel: PROCEDURES_FRAGMENT_REL });
+  } catch (err) {
+    throw fail(
+      1,
+      `${err.message}\n  (the activity-procedures canon needs agent-workflow-engine shipping references/procedures.md — upgrade the engine if it is installed but older.)`,
+    );
+  }
+};
+
+// Extract a `## <activity>` section (its heading → the next `## ` heading or EOF) and return it
+// VERBATIM (trailing blank lines trimmed). The kit prints this string; it never parses the steps.
+export const extractSection = (text, activity) => {
+  const lines = text.split('\n');
+  const start = lines.findIndex((l) => l.trim() === `## ${activity}`);
+  if (start === -1) {
+    throw fail(
+      1,
+      `the installed engine's procedures.md has no "## ${activity}" section — upgrade the engine (it predates this activity).`,
+    );
+  }
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (/^## /.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start, end).join('\n').replace(/[\r\n]+$/, ''); // trim trailing blank lines (LF or CRLF)
+};
+
+// ── resolution + rendering ─────────────────────────────────────────────────────────
+
+const resolveAllSlots = ({ activity, config, detection, overrides }) =>
+  Object.keys(ACTIVITIES[activity].slots).map((slot) => ({
+    slot,
+    ...resolveActivityRecipe({ config: config ?? {}, readiness: detection, activity, slot, override: overrides[slot] }),
+  }));
+
+// An unsatisfiable EXPLICIT override is the only "warning" (loud, flagged for the agent to relay). A
+// graceful config/default degradation is reported as a per-slot reason, not a warning.
+const collectWarnings = (slots) =>
+  slots
+    .filter((s) => s.overrideUnsatisfied)
+    .map(
+      (s) =>
+        `override "${s.slot}=${s.degradedFrom}" could not be satisfied here — degraded to ${s.recipe} (${s.reason}). Tell the user.`,
+    );
+
+const SOURCE_LABEL = {
+  default: 'computed default',
+  config: `from ${CONFIG_REL}`,
+  override: 'from --override',
+};
+
+const formatHuman = ({ activity, section, slots, warnings }) => {
+  const lines = [
+    section,
+    '',
+    `resolved recipes for "${activity}" (read-only — the orchestrator runs the recipe via the bridge skills and owns any commit; a backend never commits):`,
+  ];
+  for (const s of slots) {
+    const arrow = s.degradedFrom ? ` (requested ${s.degradedFrom} → degraded)` : '';
+    lines.push(`  ${s.slot}: ${s.recipe} — ${SOURCE_LABEL[s.source]}${arrow}`);
+    if (s.reason) lines.push(`      ↳ ${s.reason}`);
+  }
+  if (warnings.length) {
+    lines.push('', 'warnings:');
+    for (const w of warnings) lines.push(`  ⚠ ${w}`);
+  }
+  return lines.join('\n');
+};
+
+const buildJson = ({ activity, section, slots, configSource, warnings }) => ({
+  activity,
+  section,
+  slots: Object.fromEntries(
+    slots.map((s) => [s.slot, { recipe: s.recipe, source: s.source, degradedFrom: s.degradedFrom, reason: s.reason }]),
+  ),
+  configSource,
+  warnings,
+});
+
+const HELP = `procedures — read-only activity-procedures advisor for the agent-workflow family.
+
+Usage:
+  node procedures.mjs <activity> [--override <slot>=<recipe>]... [--json]
+
+Activities: ${Object.keys(ACTIVITIES).join(', ')}
+Slots:      plan-authoring → review;  plan-execution → execute, review
+Recipes:    review accepts solo|reviewed|council;  execute accepts solo|delegated
+
+Reads the activity's procedure steps LIVE from the installed agent-workflow-engine
+(references/procedures.md), resolves the effective recipe per slot from
+${CONFIG_REL} + the read-only backend detector, and prints both. A per-run
+--override <slot>=<recipe> (repeatable) overrides the configured/default recipe for that slot.
+Read-only: never writes, never commits, never runs a subscription CLI.
+
+Exit codes: 0 success (an unsatisfiable override degrades loudly, still 0);
+            2 usage (unknown activity / bad --override); 1 config or engine error.`;
+
+// ── main ───────────────────────────────────────────────────────────────────────────
+
+// main(argv, ctx) → { code, stdout, stderr }. Pure I/O at the edges (cwd / env / home / detect are
+// injectable for host-independent tests); never calls process.exit itself — the direct-run guard does.
+export const main = (argv, ctx = {}) => {
+  const cwd = ctx.cwd ?? process.cwd();
+  const env = ctx.env ?? process.env;
+  const home = ctx.home ?? homedir();
+  const detect = ctx.detect ?? detectBackends;
+  const readFile = ctx.readFileSync ?? readFileSync;
+  const lstat = ctx.lstatSync ?? lstatSync;
+  try {
+    if (argv.includes('--help') || argv.includes('-h')) return { code: 0, stdout: HELP, stderr: '' };
+    const { activity, overrides, json } = parseArgs(argv);
+    const { config, source: configSource } = loadConfig(cwd, readFile, lstat);
+    const section = extractSection(readProceduresCanon(env, home), activity);
+    // Backend detection is a SECONDARY input — it only refines the recipe. A corrupt / unreadable backend
+    // must NOT fail activity resolution as a config/engine error (exit 1, outside the contract): treat all
+    // backends as not-ready (resolution floors at Solo) and surface the failure as a loud warning, exit 0.
+    const detectWarnings = [];
+    let detection = [];
+    try {
+      detection = detect();
+    } catch (err) {
+      detectWarnings.push(
+        `backend detection failed (${(err && err.message) || err}) — treating all backends as not ready; recipes needing a backend degrade to solo.`,
+      );
+    }
+    const slots = resolveAllSlots({ activity, config, detection, overrides });
+    const warnings = [...detectWarnings, ...collectWarnings(slots)];
+    const stdout = json
+      ? JSON.stringify(buildJson({ activity, section, slots, configSource, warnings }), null, 2)
+      : formatHuman({ activity, section, slots, warnings });
+    return { code: 0, stdout, stderr: '' };
+  } catch (err) {
+    return { code: err.exitCode ?? 1, stdout: '', stderr: `procedures: ${err.message}` };
+  }
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) {
+  const r = main(process.argv.slice(2));
+  if (r.stdout) console.log(r.stdout);
+  if (r.stderr) console.error(r.stderr);
+  process.exit(r.code);
+}