@sabaiway/agent-workflow-kit 1.13.0 → 1.15.0

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
@@ -110,55 +111,86 @@ describe('surveyFamily', () => {
       ? { result: VALID, name: 'agent-workflow-engine', kind: 'methodology-engine', available: true }
       : { result: VALID, name: 'x', kind: 'x', available: true };
 
-  // The caveat mirrors the reconcile: it reads the orchestration fragment (readEngineFragment), so an
-  // absent / non-file / unreadable fragment all surface; a current readable fragment does not.
+  // 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.2.0' }),
+    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('an OK engine MISSING the orchestration fragment gets a plain caveat', () => {
-    const rows = surveyFamily(engineDeps({
-      readVersion: () => ({ version: '1.1.0' }),
-      statType: (p) => (String(p).endsWith('orchestration-slot.md') ? null : 'dir'), // fragment ABSENT
-    }));
+  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.ok(engine.caveat, 'an engine without the recipes fragment carries a caveat');
-    assert.match(engine.caveat, /recipes pointer|too old|incomplete/i);
+    assert.equal(engine.caveats, undefined, 'no caveats when both live fragments are present + readable');
   });
 
-  it('a current engine WITH a readable orchestration fragment carries NO caveat', () => {
+  it('an OK engine MISSING the orchestration fragment gets the recipes caveat (only)', () => {
     const rows = surveyFamily(engineDeps({
-      statType: (p) => (String(p).endsWith('orchestration-slot.md') ? 'file' : 'dir'),
-      readFileSync: () => '> orchestration recipes pointer', // present + readable
+      readVersion: () => ({ version: '1.2.0' }),
+      statType: fragmentStat({ orch: null }), // recipes fragment ABSENT, procedures present
+      readFileSync: () => '> a bounded fragment',
     }));
-    const engine = rows.find((r) => r.kind === 'methodology-engine');
-    assert.equal(engine.manifestState, OK);
-    assert.ok(!engine.caveat);
+    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('a broken engine whose orchestration "fragment" is a DIRECTORY is NOT a false "ok"', () => {
+  it('an engine MISSING BOTH fragments surfaces BOTH caveats (neither overwrites the other)', () => {
     const rows = surveyFamily(engineDeps({
-      statType: () => 'dir', // orchestration path is a directory, not a file
+      readVersion: () => ({ version: '1.1.0' }),
+      statType: fragmentStat({ orch: null, proc: null }),
     }));
-    assert.ok(rows.find((r) => r.kind === 'methodology-engine').caveat, 'a non-file fragment is caveated');
+    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 current engine whose orchestration fragment is PRESENT but UNREADABLE is NOT a false "ok"', () => {
+  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: (p) => (String(p).endsWith('orchestration-slot.md') ? 'file' : 'dir'), // present as a file
+      statType: fragmentStat({}), // both present as files
       readFileSync: () => {
         throw Object.assign(new Error('EACCES'), { code: 'EACCES' }); // but unreadable
       },
     }));
-    const engine = rows.find((r) => r.kind === 'methodology-engine');
-    assert.ok(engine.caveat, 'an unreadable fragment is caveated (mirrors the reconcile STOP), not reported clean');
+    assert.equal(caveatsOf(rows).length, 2, 'unreadable fragments are caveated, not reported clean');
   });
 });
 

package/tools/inject-methodology.mjs

@@ -201,6 +201,22 @@ export const ensureSlot = (text) => ensureMarkerSlot(text, METHODOLOGY_DESCRIPTO
 export const reconcileSlot = (text, fragment, opts) => reconcileMarkerSlot(text, METHODOLOGY_DESCRIPTOR, fragment, opts);
 export const slotNeedsFill = (text) => markerSlotNeedsFill(text, METHODOLOGY_DESCRIPTOR);
 
+// The routing token the methodology pointer should carry so NL like "write a plan" auto-discovers the
+// activity procedures. A deployment whose methodology slot was filled (legacy / customized) BEFORE this
+// clause existed will NOT auto-receive it — reconcile preserves a filled slot verbatim (AD-019 §3.1a).
+export const PROCEDURES_POINTER = '/agent-workflow-kit procedures';
+
+// Read-only upgrade advisory (NO mutation): when the methodology slot is present + FILLED but lacks the
+// procedures route, return a one-line note the upgrade flow surfaces — add it for auto-discovery; the
+// feature is reachable now via the explicit command. Returns null for an absent / empty / malformed slot
+// or one that already routes to procedures. Pure; never edits the file.
+export const methodologyProceduresHint = (text) => {
+  const content = extractSlot(text);
+  if (content == null || content.trim() === '') return null; // only a FILLED methodology slot
+  if (content.includes(PROCEDURES_POINTER)) return null; // already routes to the procedures advisor
+  return `the methodology pointer has no procedures route — add "${PROCEDURES_POINTER} <activity>" for auto-discovery; the activity procedures are reachable now via ${PROCEDURES_POINTER}.`;
+};
+
 // A cap-refusal is a SOFT, reported skip (distinct from a malformed/anchor STOP) — keyed off the
 // stable "(cap N)" substring both cap messages carry, so the dual-slot reconcile can skip the
 // orchestration pointer (loud) while keeping the methodology fill, instead of aborting both.
@@ -307,6 +323,13 @@ const main = async (argv) => {
       'reconciled-filled': 'filled the empty workflow-methodology pointer',
       'present-filled': 'workflow-methodology pointer already present',
     }[methResult.status];
+    // Read-only upgrade advisory (AD-019 §3.1a): a pre-existing FILLED methodology pointer that predates
+    // the procedures clause won't be re-rendered (reconcile preserves it verbatim), so surface a hint to
+    // add the procedures route. No mutation — purely a reported note appended to the success report.
+    const proceduresNote = methResult.status === 'present-filled' ? methodologyProceduresHint(afterMeth) : null;
+    const reportNote = () => {
+      if (proceduresNote) console.log(`[inject-methodology] note: ${proceduresNote}`);
+    };
 
     // ── Explicit [fragment.md] binds methodology ONLY → skip the orchestration reconcile ──
     if (explicitFragmentArg) {
@@ -361,10 +384,12 @@ const main = async (argv) => {
       // Byte-unchanged. Still report a cap-skip (it is not "nothing to do" — a pointer was withheld).
       if (orchSkipped) console.log(`[inject-methodology] reconcile: ${describeMeth}; ${describeOrch}.`);
       else console.log('[inject-methodology] reconcile: both pointers already present and filled — nothing to do (zero-diff).');
+      reportNote();
       return;
     }
     await writeAtomic(finalText);
     console.log(`[inject-methodology] reconcile: ${describeMeth}; ${describeOrch}.`);
+    reportNote();
     return;
   }
 

package/tools/inject-methodology.test.mjs

@@ -22,6 +22,9 @@ import {
   ORCHESTRATION_DESCRIPTOR,
   findMarkerSlot,
   extractMarkerSlot,
+  reconcileMarkerSlot,
+  methodologyProceduresHint,
+  PROCEDURES_POINTER,
 } from './inject-methodology.mjs';
 
 // Read the orchestration slot's content from a reconciled entry point.
@@ -614,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);
+}