@sabaiway/agent-workflow-kit 1.16.0 → 1.18.0

package/tools/inject-methodology.mjs

@@ -18,6 +18,14 @@
 // STOP loudly (never a silent fallback) when the engine is needed but absent/invalid.
 //
 // Pure string functions (testable with byte-preservation fixtures); dependency-free, Node >= 18.
+//
+// Canonical-refresh (AD-025): a slot filled BEFORE a clause existed is normally preserved verbatim
+// (reconcile only fills an EMPTY slot). To push a NEW canonical clause to the EXISTING filled base
+// without clobbering a user's customization, reconcileMarkerSlot also REFRESHES a filled slot — but
+// ONLY when its content normalize-matches a KNOWN PRIOR canonical fragment (drift-guarded, append-only
+// per descriptor). A customized slot never matches → preserved verbatim + a read-only upgrade advisory.
+
+import { normalizeCanonical } from './orchestration-config.mjs';
 
 export const START_MARKER = '<!-- workflow:methodology:start -->';
 export const END_MARKER = '<!-- workflow:methodology:end -->';
@@ -57,11 +65,29 @@ export const ORCH_ANCHOR = new RegExp(`^.*${escapeRegExp(END_MARKER)}.*$`, 'm');
 export const EMPTY_SLOT = `${START_MARKER}\n${END_MARKER}`;
 export const ORCH_EMPTY_SLOT = `${ORCH_START_MARKER}\n${ORCH_END_MARKER}`;
 
+// ── known-prior canonical fragments (drift-guarded, APPEND-ONLY per slot) ───────
+// The EXACT content a PREVIOUS release's engine fragment shipped (what a filled slot would carry today).
+// reconcileMarkerSlot refreshes a filled slot to the current engine fragment IFF its content
+// normalize-matches one of these — so the install base gains a new clause without clobbering a
+// customization (which never matches). Any release that CHANGES an engine fragment must FIRST append the
+// OUTGOING content here, so the immediately-previous deployments still match (a drift-guard test pins
+// current-minus-one → new). NEVER edit an existing entry — only append.
+export const KNOWN_PRIOR_METHODOLOGY_SLOT = [
+  // v1.3.0 — pre-communication-contract methodology pointer (procedures route, no §1.9 clause).
+  '> **Workflow methodology** — plan → execute → review. Plans are ephemeral `docs/plans/*.md` (gitignored, **never committed**); every Plan ends with a mandatory **Phase: Cleanup**; series order lives in `docs/plans/queue.md`. Full vocabulary, lifecycle, and the plan-then-execute split live in the project\'s **planning skill** (it overrides the generic `writing-plans`); summary in `docs/ai/agent_rules.md` §5. Named activities (plan-authoring, plan-execution) have procedures — see `/agent-workflow-kit procedures <activity>` for the steps + resolved recipe.',
+];
+export const KNOWN_PRIOR_ORCH_SLOT = [
+  // v1.3.0 — pre-read-at-start orchestration pointer (recipes vocabulary, no orchestration.json clause).
+  '> **Orchestration recipes** — compose plan → execute → review with a named recipe: **Solo** (no backend), **Reviewed** (one backend reviews), **Council** (both review, you synthesize), **Delegated** (a backend executes a bounded sub-task); the orchestrator always commits, a backend is never autonomous. Pick + plan one for this environment with `/agent-workflow-kit recipes` (read-only); the deployed how/why lives in your `docs/ai/` workflow docs.',
+];
+
 // A slot descriptor bundles everything the generic engine needs to operate on ONE marker pair.
 // `leadingBlank` controls whether the inserted empty pair gets a blank separator line above it — the
 // methodology insert keeps it (readability), the orchestration insert omits it to save a cap line
-// (the pair already sits right under the methodology block).
-const METHODOLOGY_DESCRIPTOR = {
+// (the pair already sits right under the methodology block). `knownPriorCanonicals` drives the refresh;
+// `upgradeSignature` + `upgradeAdvice` drive the read-only advisory for a CUSTOMIZED (non-matching) slot
+// that predates the current clause.
+export const METHODOLOGY_DESCRIPTOR = {
   startMarker: START_MARKER,
   endMarker: END_MARKER,
   anchor: METHODOLOGY_ANCHOR,
@@ -69,6 +95,10 @@ const METHODOLOGY_DESCRIPTOR = {
   leadingBlank: true,
   markerName: 'methodology',
   anchorLabel: 'methodology anchor (the "Read it before any code change." Session-Protocols line)',
+  knownPriorCanonicals: KNOWN_PRIOR_METHODOLOGY_SLOT,
+  upgradeSignature: 'Communication',
+  upgradeAdvice:
+    'the workflow-methodology pointer predates the communication-contract clause (deliver the artifact inline, lead with the result) — refresh it to the current canon, or add the clause by hand; the contract still applies.',
 };
 export const ORCHESTRATION_DESCRIPTOR = {
   startMarker: ORCH_START_MARKER,
@@ -78,6 +108,10 @@ export const ORCHESTRATION_DESCRIPTOR = {
   leadingBlank: false,
   markerName: 'orchestration',
   anchorLabel: 'orchestration anchor (the methodology end-marker line)',
+  knownPriorCanonicals: KNOWN_PRIOR_ORCH_SLOT,
+  upgradeSignature: '/agent-workflow-kit set-recipe',
+  upgradeAdvice:
+    'the orchestration-recipes pointer predates the read-at-start clause — add "read `docs/ai/orchestration.json` at session start; set it with /agent-workflow-kit set-recipe", or set your preference now with /agent-workflow-kit set-recipe.',
 };
 
 // ── generic marker-slot engine (descriptor-parameterized) ──────────────────────
@@ -160,16 +194,27 @@ export const ensureMarkerSlot = (text, descriptor) => {
 // Bootstrap/upgrade reconciliation policy (pure): ensure the slot exists, then fill it ONLY IF it
 // is empty (a filled/customized slot is preserved verbatim), enforcing the line cap — all as one step
 // the CLI commits with a single atomic write. On ANY error the INPUT bytes are returned unchanged.
-//   reconciled-inserted — slot was absent, inserted at the anchor, then filled.
-//   reconciled-filled   — slot existed but was empty, now filled.
-//   present-filled      — slot already carried content → preserved verbatim.
-//   error               — malformed slot, 0/>1 anchors, or cap exceeded → input unchanged.
+//   reconciled-inserted  — slot was absent, inserted at the anchor, then filled.
+//   reconciled-filled    — slot existed but was empty, now filled.
+//   reconciled-refreshed — slot was filled with a KNOWN PRIOR canonical → replaced with `fragment`.
+//   present-filled       — slot already carried CUSTOM content → preserved verbatim.
+//   error                — malformed slot, 0/>1 anchors, or cap exceeded → input unchanged.
 export const reconcileMarkerSlot = (text, descriptor, fragment, { maxLines } = {}) => {
   const ensured = ensureMarkerSlot(text, descriptor);
   if (ensured.status === 'error') return { status: 'error', text, error: ensured.error };
   const current = extractMarkerSlot(ensured.text, descriptor);
   const isEmpty = current == null || current.trim() === '';
   if (!isEmpty) {
+    // Canonical-refresh: a slot whose content normalize-matches a known prior canonical is STALE — replace
+    // it with the current `fragment`. A customized slot never matches → preserved verbatim. (`fragment`
+    // is empty for a customized slot — main() only sources it when markerSlotNeedsFill is true.)
+    const priors = descriptor.knownPriorCanonicals ?? [];
+    const matchesPrior = fragment && fragment.trim() !== '' && priors.some((p) => normalizeCanonical(p) === normalizeCanonical(current));
+    if (matchesPrior) {
+      const injected = injectIntoSlot(ensured.text, descriptor, fragment, { maxLines });
+      if (injected.status !== 'injected') return { status: 'error', text, error: injected.error };
+      return { status: 'reconciled-refreshed', text: injected.text };
+    }
     if (maxLines != null && lineCount(ensured.text) > maxLines) {
       return { status: 'error', text, error: `AGENTS.md is ${lineCount(ensured.text)} lines (cap ${maxLines}) — trim the file (a customized ${descriptor.markerName} slot must still fit the cap)` };
     }
@@ -189,7 +234,11 @@ export const markerSlotNeedsFill = (text, descriptor) => {
   const ensured = ensureMarkerSlot(text, descriptor);
   if (ensured.status === 'error') return false;
   const current = extractMarkerSlot(ensured.text, descriptor);
-  return current == null || current.trim() === '';
+  if (current == null || current.trim() === '') return true; // empty → fill
+  // filled-but-STALE (content matches a known prior canonical) → needs a refresh, so main() must
+  // re-source the fragment. A customized slot doesn't match → no source needed (preserved verbatim).
+  const priors = descriptor.knownPriorCanonicals ?? [];
+  return priors.some((p) => normalizeCanonical(p) === normalizeCanonical(current));
 };
 
 // ── methodology-slot exports (delegate to the generic engine, byte-for-byte) ────
@@ -217,6 +266,19 @@ export const methodologyProceduresHint = (text) => {
   return `the methodology pointer has no procedures route — add "${PROCEDURES_POINTER} <activity>" for auto-discovery; the activity procedures are reachable now via ${PROCEDURES_POINTER}.`;
 };
 
+// Generic read-only upgrade advisory (AD-025; the §1.6a/§1.9 reach to CUSTOMIZED filled slots): a slot
+// that is present + FILLED but lacks the descriptor's current-canon `upgradeSignature` (and so could not
+// be canonical-refreshed — its content is customized) gets a one-line note the upgrade flow surfaces.
+// Returns null for an absent / empty / malformed slot, or one that already carries the signature. Pure;
+// never edits the file (a customization is never rewritten — only the user decides).
+export const markerSlotUpgradeHint = (text, descriptor) => {
+  if (!descriptor.upgradeSignature) return null;
+  const content = extractMarkerSlot(text, descriptor);
+  if (content == null || content.trim() === '') return null; // only a FILLED slot
+  if (content.includes(descriptor.upgradeSignature)) return null; // already carries the current clause
+  return descriptor.upgradeAdvice;
+};
+
 // 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.
@@ -317,18 +379,23 @@ const main = async (argv) => {
       console.error(`[inject-methodology] reconcile refused — ${methResult.error}`);
       process.exit(1);
     }
-    const afterMeth = methResult.text; // === text when the methodology slot was already filled
+    const afterMeth = methResult.text; // === text when the methodology slot was already filled (custom)
     const describeMeth = {
       'reconciled-inserted': 'inserted the workflow-methodology pointer at the Session-Protocols anchor and filled it',
       'reconciled-filled': 'filled the empty workflow-methodology pointer',
+      'reconciled-refreshed': 'refreshed the workflow-methodology pointer to the current canon',
       '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}`);
+    // Read-only upgrade advisories for a CUSTOMIZED methodology pointer that reconcile preserved verbatim
+    // (a refreshed/filled/inserted slot already carries the current canon, so it gets none): the AD-019
+    // procedures route AND the §1.9 communication-contract clause. No mutation — reported notes only.
+    const notes = [];
+    if (methResult.status === 'present-filled') {
+      const p = methodologyProceduresHint(afterMeth); if (p) notes.push(p);
+      const u = markerSlotUpgradeHint(afterMeth, METHODOLOGY_DESCRIPTOR); if (u) notes.push(u);
+    }
+    const reportNotes = () => {
+      for (const n of notes) console.log(`[inject-methodology] note: ${n}`);
     };
 
     // ── Explicit [fragment.md] binds methodology ONLY → skip the orchestration reconcile ──
@@ -374,8 +441,15 @@ const main = async (argv) => {
         describeOrch = {
           'reconciled-inserted': 'inserted the orchestration-recipes pointer below it and filled it',
           'reconciled-filled': 'filled the empty orchestration-recipes pointer',
+          'reconciled-refreshed': 'refreshed the orchestration-recipes pointer to the current canon',
           'present-filled': 'orchestration-recipes pointer already present',
         }[orchResult.status];
+        // §1.6a advisory: a CUSTOMIZED orchestration pointer preserved verbatim, lacking the read-at-start
+        // clause, gets a read-only nudge (a refreshed/filled slot already carries it).
+        if (orchResult.status === 'present-filled') {
+          const u = markerSlotUpgradeHint(finalText, ORCHESTRATION_DESCRIPTOR);
+          if (u) notes.push(u);
+        }
       }
     }
 
@@ -384,12 +458,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();
+      reportNotes();
       return;
     }
     await writeAtomic(finalText);
     console.log(`[inject-methodology] reconcile: ${describeMeth}; ${describeOrch}.`);
-    reportNote();
+    reportNotes();
     return;
   }
 

package/tools/orchestration-config.mjs

@@ -0,0 +1,297 @@
+#!/usr/bin/env node
+// orchestration-config.mjs — the schema / read / pure-transform core for the per-project
+// orchestration config (docs/ai/orchestration.json). It is the SINGLE source of the config contract:
+//
+//   loadConfig / validateConfig / CONFIG_REL   — the strict-JSON reader the READ-ONLY surfaces share
+//                                                (procedures.mjs re-exports CONFIG_REL; family-registry
+//                                                + procedures import loadConfig from here).
+//   parseOp / assertSlotRecipe                  — the TYPED op parser + the ONE slot/recipe validity
+//                                                table the set-recipe writer AND procedures --override
+//                                                both reuse (drift-guarded: one accept/reject table).
+//   applySetOps / serializeConfig               — the PURE merge + the canonical (2-space, _README-first)
+//                                                serializer the writer commits.
+//   normalizeCanonical / refreshIfCanonical     — the PURE "replace IFF it matches a known prior
+//                                                canonical, else preserve a customization" helper shared
+//                                                by the _README refresh and the injected-slot refresh.
+//
+// This module performs NO filesystem WRITES — only reads (loadConfig). The single fs-writer lives in
+// orchestration-write.mjs, which procedures.mjs never imports, so "procedures never reaches a writer"
+// is structurally true. Pure-where-possible (fs injectable), dependency-free, Node >= 18. No side
+// effects on import.
+
+import { readFileSync, lstatSync } from 'node:fs';
+import { join } from 'node:path';
+import { ACTIVITIES, SLOT_RECIPES } from './recipes.mjs';
+
+// The hand-editable / agent-writable, 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). Avoids
+// a class (project rule) while letting a CLI main() map a throw to the right code in one place. Shared
+// so procedures.mjs + set-recipe.mjs raise identically-typed errors.
+export const fail = (exitCode, message) => Object.assign(new Error(message), { exitCode });
+
+const KNOWN_ACTIVITIES = () => Object.keys(ACTIVITIES).join(', ');
+
+// ── the ONE slot/recipe validity table (shared accept/reject) ───────────────────────
+// Both the set-recipe op parser and the procedures --override parser route through these, so the
+// accept/reject decision can never drift between the two surfaces (one table, drift-guarded by tests).
+
+// True iff `recipe` is valid for the (activity, slot) pair. Pure predicate; throws nothing.
+export const recipeValidForSlot = (activity, slot, recipe) => {
+  const slotType = ACTIVITIES[activity]?.slots?.[slot];
+  if (!slotType) return false;
+  return (SLOT_RECIPES[slotType] ?? []).includes(recipe);
+};
+
+// Assert (activity, slot) is a known slot of a known activity; return its recipe-TYPE. Loud (exit 2)
+// on an unknown activity or an unknown slot — the shared "unknown slot" message both parsers emit.
+export const assertSlot = (activity, slot, exitCode = 2) => {
+  const activityDef = ACTIVITIES[activity];
+  if (!activityDef) throw fail(exitCode, `unknown activity "${activity}" (known: ${KNOWN_ACTIVITIES()})`);
+  const slotType = activityDef.slots[slot];
+  if (!slotType) {
+    throw fail(
+      exitCode,
+      `unknown slot "${slot}" for activity "${activity}" (${activity} slots: ${Object.keys(activityDef.slots).join(', ')})`,
+    );
+  }
+  return slotType;
+};
+
+// Assert (activity, slot, recipe) is valid — unknown activity/slot OR invalid-recipe-for-slot → loud.
+// Used by the set-recipe op parser AND the procedures --override parser, so they accept/reject in
+// lockstep. `exitCode` is 2 for both CLIs (usage error); validateConfig reuses it with exitCode 1.
+export const assertSlotRecipe = (activity, slot, recipe, exitCode = 2) => {
+  const slotType = assertSlot(activity, slot, exitCode);
+  if (!(SLOT_RECIPES[slotType] ?? []).includes(recipe)) {
+    throw fail(
+      exitCode,
+      `invalid recipe "${recipe}" for ${slotType} slot of "${activity}" (${slotType} accepts: ${SLOT_RECIPES[slotType].join(', ')})`,
+    );
+  }
+  return slotType;
+};
+
+// ── the typed op parser (usage errors → exit 2) ─────────────────────────────────────
+// The grammar is ALWAYS fully-qualified `<activity>.<slot>` — the writer never guesses an activity. A
+// bare `review=council` is rejected (name the activity). The kit performs no `all`-magic; the agent
+// expands plain language like "both review" into explicit per-activity ops (asking if scope is unclear).
+
+const parseQualified = (lhs, flag) => {
+  const dot = lhs.indexOf('.');
+  if (dot <= 0 || dot === lhs.length - 1) {
+    throw fail(
+      2,
+      `${flag} must be fully-qualified <activity>.<slot> (got "${lhs}") — name the activity, e.g. plan-authoring.review / plan-execution.review`,
+    );
+  }
+  return { activity: lhs.slice(0, dot), slot: lhs.slice(dot + 1) };
+};
+
+// parseOp(kind, token) → a typed record:
+//   kind 'set'   + token `<activity>.<slot>=<recipe>` → { kind:'set', activity, slot, recipe }
+//   kind 'unset' + token `<activity>.<slot>`          → { kind:'unset', activity, slot }
+// Every malformed token is a USAGE error (exit 2): a bare recipe (no activity), an unknown activity /
+// slot, an invalid recipe-for-slot, a missing recipe on --set, or a stray recipe on --unset.
+export const parseOp = (kind, token) => {
+  if (kind === 'set') {
+    const eq = token.indexOf('=');
+    if (eq <= 0) throw fail(2, `--set must be <activity>.<slot>=<recipe> (got "${token}")`);
+    const recipe = token.slice(eq + 1);
+    if (!recipe) throw fail(2, `--set must be <activity>.<slot>=<recipe> (got "${token}")`);
+    const { activity, slot } = parseQualified(token.slice(0, eq), '--set');
+    assertSlotRecipe(activity, slot, recipe);
+    return { kind: 'set', activity, slot, recipe };
+  }
+  if (token.includes('=')) throw fail(2, `--unset takes <activity>.<slot> without a recipe (got "${token}")`);
+  const { activity, slot } = parseQualified(token, '--unset');
+  assertSlot(activity, slot);
+  return { kind: 'unset', activity, slot };
+};
+
+// ── config validation (config errors → exit 1) ──────────────────────────────────────
+
+// Validate a parsed orchestration.json object against the 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` (exit 1). Returns the config on success.
+export 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;
+};
+
+// ── config IO (config errors → exit 1) ──────────────────────────────────────────────
+
+// 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 read-only status survey + procedures + the set-recipe writer all
+// reuse THIS reader — one strict-JSON + loud-on-malformed contract, no second drifting implementation.
+export 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 };
+};
+
+// ── pure merge + canonical serialization ────────────────────────────────────────────
+
+// A pure deep-equal over the JSON-ish config shape (plain objects + string values). Used only for the
+// "did anything actually change?" decision (no-op detection + seed-on-change), never for output.
+const deepEqual = (a, b) => {
+  if (a === b) return true;
+  if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false;
+  const ak = Object.keys(a);
+  const bk = Object.keys(b);
+  if (ak.length !== bk.length) return false;
+  return ak.every((k) => Object.prototype.hasOwnProperty.call(b, k) && deepEqual(a[k], b[k]));
+};
+
+// applySetOps(currentConfig, ops, { seedReadme }) → the merged config. PURE: deep-clones `current`
+// (or {}), applies each set/unset, preserves `_README` + every untouched activity/slot, drops an
+// activity that an unset empties (sparse), then re-runs validateConfig (loud on invalid — defensive;
+// the op parser pre-validates). When (and ONLY when) the merge CHANGES the config, `_README` is absent,
+// and `seedReadme` is supplied, the canonical note is seeded — so a no-op set never spuriously seeds it.
+export const applySetOps = (currentConfig, ops, { seedReadme = null } = {}) => {
+  const base = currentConfig == null ? {} : structuredClone(currentConfig);
+  const next = structuredClone(base);
+  for (const op of ops) {
+    if (op.kind === 'set') {
+      next[op.activity] = { ...(next[op.activity] ?? {}) };
+      next[op.activity][op.slot] = op.recipe;
+    } else {
+      if (next[op.activity] && op.slot in next[op.activity]) {
+        const rest = { ...next[op.activity] };
+        delete rest[op.slot];
+        if (Object.keys(rest).length === 0) delete next[op.activity];
+        else next[op.activity] = rest;
+      }
+    }
+  }
+  validateConfig(next);
+  const changed = !deepEqual(next, base);
+  if (changed && seedReadme != null && next._README === undefined) next._README = seedReadme;
+  return next;
+};
+
+// serializeConfig(config) → strict JSON, 2-space, trailing newline, `_README` FIRST (explicitly, so the
+// onboarding note never sinks below the activities). This is the canonical on-disk form: a touched
+// write normalizes to it (content-preserving, NOT byte-preserving of arbitrary hand-formatting).
+export const serializeConfig = (config) => {
+  const ordered = {};
+  if (config._README !== undefined) ordered._README = config._README;
+  for (const [k, v] of Object.entries(config)) {
+    if (k !== '_README') ordered[k] = v;
+  }
+  return `${JSON.stringify(ordered, null, 2)}\n`;
+};
+
+// ── canonical-refresh (shared by the _README refresh + the injected-slot refresh) ───
+// normalizeCanonical: trim + LF-normalize (handles the CRLF / trailing-whitespace trap) so a byte-noisy
+// copy of a canonical string still matches. refreshIfCanonical: replace `current` with `next` IFF it
+// normalize-equals ANY known prior canonical; otherwise return `current` UNCHANGED (preserve a
+// customization). Pure; no fs. Used for the orchestration `_README` and the two injected pointers.
+
+export const normalizeCanonical = (s) => String(s).replace(/\r\n/g, '\n').trim();
+
+export const refreshIfCanonical = (current, knownPriorCanonicals, next) => {
+  const cur = normalizeCanonical(current);
+  return knownPriorCanonicals.some((prior) => normalizeCanonical(prior) === cur) ? next : current;
+};
+
+// ── canonical `_README` (drift-guarded, append-only known-prior set) ─────────────────
+// CANON_README is the CURRENT onboarding note — what the templates ship + what a refresh installs. It
+// frames hand-edit as a still-available option AND points at the set-recipe writer (no "never written
+// for you"). KNOWN_PRIOR_README is the APPEND-ONLY set of every PREVIOUS canonical note: any release
+// that changes CANON_README must FIRST append the outgoing string here, so an immediately-previous
+// deployment still normalize-matches and gets refreshed (a customized note never matches → preserved).
+export const CANON_README =
+  "Per-project orchestration config: the recipe used at each step (slot) of each named activity. " +
+  "Easiest: tell the agent in plain language and run the `set-recipe` writer — it interprets your intent, " +
+  "previews the change, and writes valid JSON for you. You can still hand-edit this file directly whenever you " +
+  "prefer; that option never goes away. Each activity is configured independently (e.g. plan-authoring, " +
+  "plan-execution), and so is each slot within it. A slot's value is a recipe: a 'review' slot accepts " +
+  "solo | reviewed | council (you self-review / one backend reviews / both review and you synthesize); an " +
+  "'execute' slot accepts solo | delegated (you implement / a backend runs a bounded sub-task). The default " +
+  "below is 'solo' everywhere — no execution backend required. Raise a slot to reviewed or council for a second " +
+  "opinion, or to delegated to hand off execution; those need an execution backend set up first. Remove a slot's " +
+  "line (or run `set-recipe --unset <activity>.<slot>`) to fall back to the computed default (reviewed when a " +
+  "review backend is ready, otherwise solo). Run the read-only procedures advisor to see an activity's steps " +
+  "plus the recipe resolved for your environment. Strict JSON — no comments.";
+
+export const KNOWN_PRIOR_README = [
+  // v1 (pre-set-recipe) — the "Hand-edit this file — it is never written for you" note. APPEND-ONLY.
+  "Per-project orchestration config: the recipe used at each step (slot) of each named activity. Hand-edit this file — it is never written for you. Each activity is configured independently (e.g. plan-authoring, plan-execution), and so is each slot within it. A slot's value is a recipe: a 'review' slot accepts solo | reviewed | council (you self-review / one backend reviews / both review and you synthesize); an 'execute' slot accepts solo | delegated (you implement / a backend runs a bounded sub-task). The default below is 'solo' everywhere — no execution backend required. Raise a slot to reviewed or council for a second opinion, or to delegated to hand off execution; those need an execution backend set up first. Remove a slot's line to fall back to the computed default (reviewed when a review backend is ready, otherwise solo). Run the read-only procedures advisor to see an activity's steps plus the recipe resolved for your environment, and pass a per-run override to change one slot just once. Strict JSON — no comments.",
+];
+
+// refreshReadme(config) → { config, changed }: refresh ONLY the `_README` value when it normalize-
+// matches a known prior canonical (preserve a customized note untouched); seed it when absent. The
+// stamp-independent config-ensure (kit fallback + memory delegated upgrade paths) uses this so an
+// install-base deployment gains the new note without a migration file — never clobbering a customization.
+export const refreshReadme = (config) => {
+  if (config == null || typeof config !== 'object' || Array.isArray(config)) {
+    return { config, changed: false };
+  }
+  const had = config._README;
+  const nextReadme = had === undefined ? CANON_README : refreshIfCanonical(had, KNOWN_PRIOR_README, CANON_README);
+  if (nextReadme === had) return { config, changed: false };
+  const next = { _README: nextReadme };
+  for (const [k, v] of Object.entries(config)) {
+    if (k !== '_README') next[k] = v;
+  }
+  return { config: next, changed: true };
+};
+
+// The canonical seed file body (what `init` deploys + what serializeConfig round-trips byte-identically).
+export const SEED_CONFIG = { _README: CANON_README, 'plan-authoring': { review: 'solo' }, 'plan-execution': { execute: 'solo', review: 'solo' } };

package/tools/orchestration-write.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// orchestration-write.mjs — the ONLY filesystem WRITER for docs/ai/orchestration.json. It is imported
+// by the set-recipe writer alone; procedures.mjs never imports it, so "the read-only procedures advisor
+// can never reach a writer" is a STRUCTURAL invariant (an import-split test pins it), not just an
+// assertion. Splitting the writer out of the schema/read module keeps the read surface fs-write-free.
+//
+// writeConfig is hardened (mirrors the setup-backends posture):
+//   - DEPLOYMENT GATE first: refuse to scatter a config into a repo with no docs/ai/ — STOP loud,
+//     pointing at init/bootstrap (a config without a deployment is meaningless + surprising).
+//   - refuse a SYMLINKED leaf (orchestration.json itself a symlink) — a rename would silently replace
+//     the link target.
+//   - guard the dst + the tmp sibling with assertContainedRealPath (fs-safe) — refuses a symlinked
+//     docs/ or docs/ai/ PARENT, not just the leaf, and refuses any escape outside cwd.
+//   - atomic: write a UNIQUE *.json.<rand>.tmp opened EXCLUSIVE-CREATE (wx), then rename over the dst.
+//   - RE-CHECK the parent chain + the leaf immediately before the rename (TOCTOU).
+//   - LAST-WRITER-WINS: local, single-user; no cross-process lock (documented, not silently assumed).
+//
+// Dependency-free, Node >= 18. Every fs primitive is injectable (deps.*) so the guards are unit-testable.
+
+import { lstatSync, writeFileSync, renameSync, rmSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+import { assertContainedRealPath } from './fs-safe.mjs';
+import { CONFIG_REL, serializeConfig } from './orchestration-config.mjs';
+
+// A typed STOP — a deliberate refusal we surface (deployment gate / symlinked leaf), distinct from a
+// native fs error. `Object.assign(new Error(), { code })`, the codebase's typed-error idiom (no classes).
+export const ORCH_WRITE_STOP = 'ORCH_WRITE_STOP';
+const stop = (message) => Object.assign(new Error(`[agent-workflow-kit] ${message}`), { name: 'OrchWriteStop', code: ORCH_WRITE_STOP });
+
+// lstat without following symlinks; null when absent. A non-ENOENT error propagates (never fail open).
+const lstatNoFollow = (path, lstat) => {
+  try {
+    return lstat(path);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+};
+
+// writeConfig(cwd, config, deps) → { writtenPath } on success; THROWS a typed STOP (no deployment /
+// symlinked leaf) or a native fs error otherwise. The tmp is cleaned up on any failure after its
+// creation. config is serialized canonically (serializeConfig: 2-space, _README-first, trailing NL).
+export const writeConfig = (cwd, config, deps = {}) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const writeFile = deps.writeFile ?? writeFileSync;
+  const rename = deps.rename ?? renameSync;
+  const rm = deps.rm ?? ((p) => rmSync(p, { force: true }));
+  const rand = deps.rand ?? (() => randomBytes(6).toString('hex'));
+  const guard = (target) => assertContainedRealPath(cwd, target, { lstat });
+
+  // Deployment gate — never scatter a config into a non-deployed repo (mirror velocity / setup). lstat,
+  // NOT existsSync: existsSync FOLLOWS a symlink, so a DANGLING `docs/ai` symlink would read as "absent"
+  // and mislabel a broken/symlinked deployment as "no deployment". lstat the leaf instead: a true ENOENT
+  // → no deployment (STOP, run init); a symlink or non-directory → STOP loud (never write through it).
+  const docsAi = join(cwd, 'docs', 'ai');
+  const docsAiStat = lstatNoFollow(docsAi, lstat);
+  if (docsAiStat === null) {
+    throw stop(`no agent-workflow deployment here (docs/ai is absent) — run init/bootstrap before writing ${CONFIG_REL}`);
+  }
+  if (docsAiStat.isSymbolicLink()) {
+    throw stop(`docs/ai is a symlink — refusing to write a config through it (run init/bootstrap in a real deployment)`);
+  }
+  if (!docsAiStat.isDirectory()) {
+    throw stop(`docs/ai exists but is not a directory — refusing to write ${CONFIG_REL}`);
+  }
+
+  const dst = join(cwd, CONFIG_REL);
+  // Refuse a symlinked leaf with a CLEAR message before the generic traversal guard fires (a rename
+  // would silently replace the link rather than the file the user thinks they are editing).
+  const leaf = lstatNoFollow(dst, lstat);
+  if (leaf && leaf.isSymbolicLink()) {
+    throw stop(`${CONFIG_REL} is a symlink — refusing to replace it (a write would clobber the link target)`);
+  }
+  // Guard the dst + a unique tmp SIBLING: refuses a symlinked docs/ or docs/ai/ parent, and any escape.
+  guard(dst);
+  const tmp = `${dst}.${rand()}.tmp`;
+  guard(tmp);
+
+  const body = serializeConfig(config);
+  // Exclusive-create (wx): never clobber a leftover tmp (a stray collision is surfaced, not silently
+  // overwritten). The random suffix makes a collision effectively impossible; wx makes it impossible-loud.
+  writeFile(tmp, body, { encoding: 'utf8', flag: 'wx' });
+  try {
+    // TOCTOU re-check: the parent chain + the leaf may have changed since the pre-checks above.
+    guard(dst);
+    const leafAgain = lstatNoFollow(dst, lstat);
+    if (leafAgain && leafAgain.isSymbolicLink()) {
+      throw stop(`${CONFIG_REL} became a symlink — refusing to replace it`);
+    }
+    rename(tmp, dst);
+  } catch (err) {
+    rm(tmp); // never leave a temp file behind on failure
+    throw err;
+  }
+  return { writtenPath: CONFIG_REL };
+};