@sabaiway/agent-workflow-kit 1.32.0 → 1.34.0

package/tools/commands.mjs

@@ -96,7 +96,7 @@ const CATALOG = [
     invocation: invocationOf('gates'),
     group: 'Inspect',
     kind: PROJECT_EXEC,
-    oneLine: 'Run the project’s own declared gate commands (docs/ai/gates.json) as one batch — a PASS/FAIL table, one summary line.',
+    oneLine: 'Run the project’s own declared gate commands (docs/ai/gates.json) as one batch — a PASS/FAIL table, one summary line. The mode itself writes nothing; a separate consent-gated seeder can propose entries from your project’s own scripts (preview first, written only on your yes).',
   },
   {
     key: 'setup',
@@ -212,6 +212,19 @@ const KIND_TAG = {
 };
 const pad = (s, n) => (s.length >= n ? s : s + ' '.repeat(n - s.length));
 
+// The "Tune" tail — the opt-in accelerator funnel, rendered AFTER the catalog groups. NOT a new
+// catalog key or mode (the frozen CATALOG + GROUP_ORDER stay; the router SKILL.md is untouched):
+// the same four entries the bootstrap accelerators block presents, one line of why each.
+const TUNE_TAIL = Object.freeze([
+  '',
+  'Tune — opt-in accelerators (consent-first: every writer previews before writing; nothing runs without your yes)',
+  `  ${BARE_INVOCATION} velocity      routine read-only commands stop prompting (incl. the --kit-tools tier for the kit's own read-only tools)`,
+  `  ${BARE_INVOCATION} agents        cheap-model subagents take the mechanical work (sweeps, changelog skeletons, gate triage)`,
+  `  ${BARE_INVOCATION} gates         run your declared gates (docs/ai/gates.json) as one batch; its guide also offers the consent-gated seeding preview — writes only on your yes`,
+  `  ${BARE_INVOCATION} hook          auto-approve exactly your declared gate commands (byte-exact matches only)`,
+  `  ${BARE_INVOCATION} set-recipe    put a ready review backend to work on plans and diffs`,
+]);
+
 // formatHelp() → the grouped, kind-tagged human index. Deterministic; groups in GROUP_ORDER, modes in
 // catalog order within each group. The header states the index itself is read-only.
 export const formatHelp = () => {
@@ -229,6 +242,7 @@ export const formatHelp = () => {
       lines.push(`  ${pad(c.invocation, invocWidth)}  ${KIND_TAG[c.kind] ?? c.kind}  ${c.oneLine}`);
     }
   }
+  lines.push(...TUNE_TAIL);
   return lines.join('\n');
 };
 

package/tools/delegation.mjs

@@ -83,7 +83,9 @@ export const handoffPlan = (delegate) =>
     ? {
         mode: 'delegate',
         memoryWrites: ['docs/ai/', 'AGENTS.md', 'docs/ai/.memory-version'],
-        kitWrites: ['AGENTS.md methodology slot', 'docs/ai/.workflow-version'],
+        // The lens region runs AFTER the substrate deploy (its own precondition: the file exists)
+        // — it converges a stale-memory seed to the installed engine's canon (AD-041).
+        kitWrites: ['AGENTS.md methodology slot', 'docs/ai/agent_rules.md lens region', 'docs/ai/.workflow-version'],
         stampsPresent: ['.memory-version', '.workflow-version'],
         memoryRaisesCommitGate: false,
         commitGate: 'kit-only-after-injection',
@@ -93,8 +95,9 @@ export const handoffPlan = (delegate) =>
         memoryWrites: [],
         // Fallback now ships the kit's OWN AGENTS.md carrying the EMPTY methodology slot (Plan 2);
         // the kit reconciles it (ensure-slot + inject-because-empty) exactly like the delegate
-        // path — so both paths end with a FILLED slot, not inline methodology.
-        kitWrites: ['docs/ai/', 'AGENTS.md', 'AGENTS.md methodology slot', 'docs/ai/.workflow-version'],
+        // path — so both paths end with a FILLED slot, not inline methodology. The lens region
+        // runs after the fallback-template copy of docs/ai (same reconcile, both paths — AD-041).
+        kitWrites: ['docs/ai/', 'AGENTS.md', 'AGENTS.md methodology slot', 'docs/ai/agent_rules.md lens region', 'docs/ai/.workflow-version'],
         stampsPresent: ['.workflow-version'],
         memoryRaisesCommitGate: false,
         commitGate: 'kit-only-after-injection',

package/tools/engine-source.mjs

@@ -31,6 +31,12 @@ export const ORCHESTRATION_FRAGMENT_REL = 'references/orchestration-slot.md';
 // CLI fail loudly on — an engine too old to ship it. readEngineFragment accepts an arbitrary `rel`
 // (no whitelist), so no further plumbing is needed beyond this constant.
 export const PROCEDURES_FRAGMENT_REL = 'references/procedures.md';
+// The agent-rules lens pair — the canonical lens block + its append-only prior store (engine
+// >= 1.13.0; an older engine ships neither). The kit's lens-region reconcile live-reads BOTH via
+// readEngineFragment({ rel }); detectEngine({ rel }) lets it soft-skip a too-old engine (and
+// `status` caveat it) instead of failing the whole reconcile.
+export const LENS_FRAGMENT_REL = 'references/agent-rules-lens.md';
+export const LENS_PRIORS_REL = 'references/agent-rules-lens-priors.md';
 const ENGINE_DEFAULT_REL = '.claude/skills/agent-workflow-engine';
 
 const defaultStatType = (path) => {

package/tools/family-registry.mjs

@@ -26,7 +26,7 @@ import { resolveDir, detectBackends, findOnPath } from './detect-backends.mjs';
 import { parseSemver, compareSemver } from './semver-lite.mjs';
 import { validateManifest, readAuthoritativeVersion, UNSUPPORTED, INVALID } from './manifest/validate.mjs';
 import { START_MARKER, excludePath, inferVisibility } from './hide-footprint.mjs';
-import { readEngineFragment, ORCHESTRATION_FRAGMENT_REL, PROCEDURES_FRAGMENT_REL } from './engine-source.mjs';
+import { readEngineFragment, ORCHESTRATION_FRAGMENT_REL, PROCEDURES_FRAGMENT_REL, LENS_FRAGMENT_REL, LENS_PRIORS_REL } from './engine-source.mjs';
 import { ACTIVITIES, resolveActivityRecipe } from './recipes.mjs';
 // The config reader lives in orchestration-config.mjs (the single config contract). The read-only status
 // settings-survey reuses THIS reader (one strict-JSON + loud-on-malformed contract), not a second copy.
@@ -47,7 +47,10 @@ import {
 // The gate-hook writer's own wired-detection + placed path — reused by the settings survey (one
 // implementation; gate-hook imports only node builtins + velocity-profile, so no cycle).
 import { HOOK_FILE_REL as GATE_HOOK_FILE_REL, isHookWired } from './gate-hook.mjs';
-import { GATES_REL } from './run-gates.mjs';
+import { GATES_REL, loadDeclaration } from './run-gates.mjs';
+// The cheap-agents writer's own bundle reader + placement planner — reused by the settings survey
+// (one implementation, never a drifting copy; cheap-agents imports only node builtins, no cycle).
+import { readBundledAgents, planPlacement } from './cheap-agents.mjs';
 // The status vocabulary (manifestState constants, internal→public maps, display names, the no-leak
 // forbidden set) lives in the frozen labels.mjs LEAF (Plan §4.2 B1) so the import graph is acyclic —
 // nothing imports family-registry for vocabulary. Imported here for internal use; the public subset is
@@ -171,9 +174,13 @@ export const classifyMember = (member, deps = {}) => {
 // the manifest AND reads the fragment — so an absent, non-file, OR present-but-unreadable fragment all
 // surface (status never claims "ok" for a fragment a reconcile / the procedures CLI would STOP on), and
 // a current, readable fragment never gets the caveat. Read-only, best-effort.
+// Each caveat names the rel(s) its consumer actually needs: the lens reconcile requires the
+// fragment AND its prior store as a PAIR (lens-region soft-skips when either is missing), so its
+// caveat keys on both — an engine missing only the prior store must never report healthy.
 const ENGINE_FRAGMENT_CAVEATS = [
-  { rel: ORCHESTRATION_FRAGMENT_REL, caveat: 'engine present but does not supply the recipes pointer (too old / incomplete) — run `npx @sabaiway/agent-workflow-engine@latest init`' },
-  { rel: PROCEDURES_FRAGMENT_REL, caveat: 'engine present but does not ship the activity-procedures canon (too old / incomplete) — run `npx @sabaiway/agent-workflow-engine@latest init`' },
+  { rels: [ORCHESTRATION_FRAGMENT_REL], caveat: 'engine present but does not supply the recipes pointer (too old / incomplete) — run `npx @sabaiway/agent-workflow-engine@latest init`' },
+  { rels: [PROCEDURES_FRAGMENT_REL], caveat: 'engine present but does not ship the activity-procedures canon (too old / incomplete) — run `npx @sabaiway/agent-workflow-engine@latest init`' },
+  { rels: [LENS_FRAGMENT_REL, LENS_PRIORS_REL], caveat: 'engine present but does not ship the agent-rules lens canon (the fragment + its prior store; too old / incomplete — engine >= 1.13.0) — run `npx @sabaiway/agent-workflow-engine@latest init`' },
 ];
 
 // The orchestration-config TEMPLATE a current memory ships (added in memory 1.2.0; absent in older
@@ -244,7 +251,7 @@ export const surveyFamily = (deps = {}) =>
           return false; // absent / non-file / unreadable fragment → the engine can't supply it
         }
       };
-      const caveats = ENGINE_FRAGMENT_CAVEATS.filter((f) => !fragmentUsable(f.rel)).map((f) => f.caveat);
+      const caveats = ENGINE_FRAGMENT_CAVEATS.filter((f) => !f.rels.every(fragmentUsable)).map((f) => f.caveat);
       if (caveats.length) row.caveats = caveats;
     }
     // Memory offline caveat (Step 2.2): a distinct probe — the orchestration TEMPLATE file's existence.
@@ -452,21 +459,50 @@ export const surveyGateHook = (dir, deps = {}) => {
     const exists = deps.exists ?? existsSync;
     const project = readSettingsFile(join(d, SETTINGS_FILE), { ...deps, cwd: d });
     const local = readSettingsFile(join(d, SETTINGS_LOCAL_FILE), { ...deps, cwd: d });
+    // How many gates are actually DECLARED — the welcome-mat hook rung keys on a non-empty
+    // declaration (a fresh bootstrap seeds gates.json EMPTY, so file presence alone would misfire).
+    // 0 = absent or empty list; null = present but unreadable/malformed (unknown — never a false
+    // count, and never an area-wide error: the wired/placed probes still report; the validation
+    // REASON is preserved beside the null so status never renders a bare question mark).
+    const declaration = (() => {
+      try {
+        const res = loadDeclaration(d, deps);
+        return { declaredGates: res.outcome === 'loaded' ? res.gates.length : 0 };
+      } catch (err) {
+        return { declaredGates: null, declarationError: localizeError(err) };
+      }
+    })();
     return {
       wired: isHookWired(project.data) || isHookWired(local.data),
       filePlaced: Boolean(exists(join(d, GATE_HOOK_FILE_REL))),
       declarationPresent: Boolean(exists(join(d, GATES_REL))),
+      ...declaration,
     };
   } catch (err) {
     return { error: localizeError(err) };
   }
 };
 
+// cheap agents: the kit-placed .claude/agents/ vehicles (Mode: agents) — how many of the bundled
+// cheap-lane definitions are present in the project. A customized copy counts as PLACED (it exists;
+// the writer preserves it) — the welcome-mat agents rung keys on zero placed. Read-only; REUSES the
+// writer's own bundle reader + placement planner (cheap-agents.mjs — one implementation).
+export const surveyCheapAgents = (dir, deps = {}) => {
+  try {
+    const templates = readBundledAgents(deps);
+    const plan = planPlacement(templates, resolve(dir), deps);
+    return { bundled: templates.length, placed: plan.filter((p) => p.action !== 'place').length };
+  } catch (err) {
+    return { error: localizeError(err) };
+  }
+};
+
 // the project-scoped settings survey (needs a project dir). Each area is independently localized-on-error.
 export const surveySettings = (dir, deps = {}) => ({
   recipes: surveyRecipes(dir, deps),
   attribution: surveyAttribution(dir, deps),
   velocity: surveyVelocity(dir, deps),
+  agents: surveyCheapAgents(dir, deps),
   hook: surveyGateHook(dir, deps),
 });
 

package/tools/lens-region.mjs

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+// Heading-anchored lens-region reconcile — the composition root's only mutation of a deployed
+// `docs/ai/agent_rules.md`. The planning/review/process-fidelity lens block (`### 2.x. Planning,
+// review & process-fidelity invariants`) has ONE canonical home — the installed engine's
+// `references/agent-rules-lens.md` — and every deployed/template copy is a RENDER of it (the
+// file's own section number substituted into the number-neutral heading). This tool refreshes a
+// deployed region to the current canon under the AD-025 discipline: refresh IFF the region's
+// normalized body matches the current fragment (already current → zero-diff) or a KNOWN PRIOR
+// canonical body (the engine's append-only `references/agent-rules-lens-priors.md`, read live
+// beside the fragment — no kit-side prior constants, so a canon wording change is an engine-only
+// release). Anything else is preserved byte-for-byte + a one-line advisory.
+//
+// The region has NO markers (unlike the AGENTS.md pointer slots): it is located by the heading
+// through the next structural boundary (`---` / `##` / `###`) or EOF — the extraction rule the
+// lens-mirror guard pioneered, promoted here as the shipped implementation. A user-renamed
+// heading is therefore a natural preserve+advise; bytes outside the region are never touched.
+//
+// The live read is lazy + fail-loud: the engine is consulted only when a present region must be
+// classified; a fully absent/invalid engine is a loud STOP (never a silent fallback), a valid
+// engine that merely predates the lens pair (<1.13.0) is a stated soft skip. Cap-guard: a refresh
+// that would push the file over its own frontmatter `maxLines` is a loud, non-fatal refusal —
+// never a silent truncate; a file without frontmatter/`maxLines` skips the guard with a stated
+// note (such a file is outside the docs cap gate anyway).
+//
+// Pure string functions (fs only in the CLI); dependency-free, Node >= 18.
+
+import { normalizeCanonical } from './orchestration-config.mjs';
+
+// The deployed-heading matcher (prefix, like the historical extractLensBlock: robust to a future
+// heading-tail tweak) and the number-neutral form the engine fragment carries.
+export const LENS_HEADING_RE = /^### 2\.(\d+)\. Planning, review & process-fidelity/;
+const NEUTRAL_HEADING_RE = /^### 2\.x\. Planning, review & process-fidelity/;
+const HEADING_LABEL = '### 2.x. Planning, review & process-fidelity invariants';
+
+const stripCr = (line) => (line.endsWith('\r') ? line.slice(0, -1) : line);
+const isBoundary = (bareLine) => bareLine === '---' || /^#{2,3} /.test(bareLine);
+
+// Count lines independent of a trailing newline (the inject-methodology contract).
+const lineCount = (text) => text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
+
+// ── the frozen prior-store format (documented in the store file's own header) ─────
+// A delimiter is a line that starts with `<!-- prior` and ends with `-->`; an entry body is
+// everything after it up to the next delimiter / EOF, trimmed. The pre-delimiter header is
+// ignored. APPEND-ONLY on the engine side — this parser must keep reading a newer engine's file.
+export const parseLensPriors = (text) => {
+  const entries = [];
+  let current = null;
+  for (const line of String(text).split('\n')) {
+    const bare = stripCr(line);
+    if (bare.startsWith('<!-- prior') && bare.endsWith('-->')) {
+      if (current) entries.push(current.join('\n'));
+      current = [];
+    } else if (current) current.push(line);
+  }
+  if (current) entries.push(current.join('\n'));
+  return entries.map((e) => normalizeCanonical(e)).filter((e) => e !== '');
+};
+
+// renderLens(fragment, number) → the number-neutral canonical block bound to the file's OWN
+// section number (memory-seeded files say 2.6, kit-fallback files 2.5 — the fragment never
+// hardcodes one). LF-canonical; the CLI converts to the document's EOL style on write.
+export const renderLens = (fragment, number) =>
+  normalizeCanonical(fragment).replace(NEUTRAL_HEADING_RE, (m) => m.replace('2.x', `2.${number}`));
+
+// normalizeLensBody(body) → the number-neutral, whitespace/EOL-normalized comparison form
+// (heading number → `2.x`, trim, CRLF→LF) every known-set match uses.
+export const normalizeLensBody = (body) =>
+  normalizeCanonical(String(body).replace(/^### 2\.\d+\./, '### 2.x.'));
+
+// extractLensRegion(text) → { found: false } | { found, start, end, number, body }.
+// `start`/`end` are line indices over text.split('\n') — heading line through (exclusive) the
+// next structural boundary; EOF is a valid region end (no following boundary required). `body`
+// is the CR-stripped block with trailing blank lines dropped (the comparison form); the raw
+// region lines (including trailing blanks) are what replaceLensRegion preserves around a render.
+export const extractLensRegion = (text) => {
+  const lines = String(text).split('\n');
+  const start = lines.findIndex((line) => LENS_HEADING_RE.test(stripCr(line)));
+  if (start === -1) return { found: false };
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (isBoundary(stripCr(lines[i]))) {
+      end = i;
+      break;
+    }
+  }
+  const number = stripCr(lines[start]).match(LENS_HEADING_RE)[1];
+  const regionLines = lines.slice(start, end);
+  let bodyEnd = regionLines.length;
+  while (bodyEnd > 0 && stripCr(regionLines[bodyEnd - 1]).trim() === '') bodyEnd -= 1;
+  const body = regionLines.slice(0, bodyEnd).map(stripCr).join('\n');
+  return { found: true, start, end, number, body };
+};
+
+// replaceLensRegion(text, region, renderedBody) → the document with ONLY the region's block
+// lines replaced; trailing blank lines inside the region and every byte outside it are
+// preserved verbatim. Output keeps the document's EOL style (CRLF documents stay CRLF).
+export const replaceLensRegion = (text, region, renderedBody) => {
+  const lines = String(text).split('\n');
+  const crlf = String(text).includes('\r\n');
+  const regionLines = lines.slice(region.start, region.end);
+  let bodyEnd = regionLines.length;
+  while (bodyEnd > 0 && stripCr(regionLines[bodyEnd - 1]).trim() === '') bodyEnd -= 1;
+  const trailing = regionLines.slice(bodyEnd); // preserved verbatim (their own CR bytes intact)
+  const newBody = renderedBody.split('\n').map((l) => (crlf ? `${l}\r` : l));
+  const out = [...lines.slice(0, region.start), ...newBody, ...trailing, ...lines.slice(region.end)];
+  // In a CRLF document, only a line FOLLOWED by another line carries the CR byte; when the new
+  // body's last line is the final line of the whole document (EOF region, no trailing newline),
+  // strip the CR we just added so no stray byte lands at EOF.
+  if (crlf && trailing.length === 0 && region.end === lines.length) {
+    out[out.length - 1] = stripCr(out[out.length - 1]);
+  }
+  return out.join('\n');
+};
+
+// reconcileLensText(text, fragment, priors) — the PURE policy decision:
+//   { status: 'no-region' }  — heading absent/renamed → preserve + advise (caller words it).
+//   { status: 'current' }    — the region already renders the current canon → zero-diff.
+//   { status: 'refreshed', text } — the region matched the canon or a known prior → re-rendered
+//                                   with the file's OWN number (cap-guard is the caller's, so the
+//                                   decision stays pure).
+//   { status: 'custom' }     — anything else → preserved byte-for-byte + advisory.
+export const reconcileLensText = (text, fragment, priors) => {
+  const region = extractLensRegion(text);
+  if (!region.found) return { status: 'no-region', text };
+  const current = normalizeLensBody(region.body);
+  const canon = normalizeLensBody(fragment);
+  if (current === canon) return { status: 'current', text };
+  const known = priors.map((p) => normalizeLensBody(p));
+  if (!known.includes(current)) return { status: 'custom', text };
+  return { status: 'refreshed', text: replaceLensRegion(text, region, renderLens(fragment, region.number)) };
+};
+
+// frontmatterMaxLines(text) → the file's own `maxLines:` frontmatter value, or null when the
+// file has no frontmatter block or the block carries no maxLines (→ the cap-guard is skipped
+// with a stated note, never a throw — such a file is outside the docs cap gate anyway).
+export const frontmatterMaxLines = (text) => {
+  const lines = String(text).split('\n').map(stripCr);
+  if (lines[0] !== '---') return null;
+  for (let i = 1; i < lines.length; i += 1) {
+    if (lines[i] === '---') return null;
+    const m = lines[i].match(/^maxLines:\s*(\d+)\s*$/);
+    if (m) return Number(m[1]);
+  }
+  return null;
+};
+
+// ── CLI: `lens-region.mjs reconcile <path/to/agent_rules.md>` ─────────────────────
+// Outcome lines are the contract the upgrade/bootstrap prose relays in plain language; exit 0 on
+// every classified outcome (including the soft skips and the cap refusal), exit 1 ONLY on the
+// hard engine STOP or an unexpected fs error, exit 2 on usage.
+export const runCli = async (argv, deps = {}) => {
+  const log = deps.log ?? console.log;
+  const logError = deps.logError ?? console.error;
+  const env = deps.env ?? process.env;
+  const fs = deps.fs ?? (await import('node:fs/promises'));
+  const { dirname, basename, join, resolve } = await import('node:path');
+  const { homedir } = await import('node:os');
+  const { resolveEngineDir, detectEngine, readEngineFragment, LENS_FRAGMENT_REL, LENS_PRIORS_REL } = await import('./engine-source.mjs');
+
+  if (argv[0] !== 'reconcile' || !argv[1] || argv.length > 2) {
+    logError('usage: lens-region.mjs reconcile <path/to/agent_rules.md>');
+    return 2;
+  }
+  const targetPath = resolve(argv[1]);
+
+  // 1. Absent file → a stated skip (the memory substrate owns seeding; nothing to reconcile).
+  const text = await (async () => {
+    try {
+      return await fs.readFile(targetPath, 'utf8');
+    } catch (err) {
+      if (err.code === 'ENOENT') return null;
+      throw err;
+    }
+  })();
+  if (text === null) {
+    log(`[lens-region] ${argv[1]} is absent — skipped (nothing to reconcile; the substrate seeds it at bootstrap).`);
+    return 0;
+  }
+
+  // 2. No matching heading → preserve + advise, engine never consulted (the outcome is preserve
+  //    regardless, so the lazy contract holds).
+  if (!extractLensRegion(text).found) {
+    log(`[lens-region] no "${HEADING_LABEL}" section in ${argv[1]} — left untouched.`);
+    log('[lens-region] note: the planning/review lens section is missing or renamed — it cannot be auto-refreshed; restore the canonical heading to re-enable refresh.');
+    return 0;
+  }
+
+  // 3. A present region must be classified → live-read the engine's fragment + prior store.
+  //    Fully absent/invalid engine → loud STOP; valid-but-pre-lens engine → stated soft skip.
+  const { dir, source } = resolveEngineDir({ env, home: deps.home ?? homedir() });
+  const lensPairPresent =
+    detectEngine(dir, { source, rel: LENS_FRAGMENT_REL }).ok && detectEngine(dir, { source, rel: LENS_PRIORS_REL }).ok;
+  if (!lensPairPresent) {
+    if (detectEngine(dir, { source }).ok) {
+      log('[lens-region] skipped — the installed engine is too old (or incomplete) to supply the lens canon; refresh it with `npx @sabaiway/agent-workflow-engine@latest init`, then re-run.');
+      return 0;
+    }
+    try {
+      readEngineFragment(dir, { source, rel: LENS_FRAGMENT_REL }); // throws the canonical install-me error
+      return 1; // defensive: the pair is unusable — never proceed to a read
+    } catch (err) {
+      logError(`[lens-region] reconcile STOP — ${err.message}`);
+      return 1;
+    }
+  }
+  // TOCTOU guard: a fragment that vanishes between detect and read is a corruption STOP, never a
+  // silent proceed — readEngineFragment's own throw carries the install command.
+  let fragment;
+  let priors;
+  try {
+    fragment = readEngineFragment(dir, { source, rel: LENS_FRAGMENT_REL });
+    priors = parseLensPriors(readEngineFragment(dir, { source, rel: LENS_PRIORS_REL }));
+  } catch (err) {
+    logError(`[lens-region] reconcile STOP — ${err.message}`);
+    return 1;
+  }
+
+  // 4. The pure decision + the cap-guard + one atomic write.
+  const result = reconcileLensText(text, fragment, priors);
+  if (result.status === 'current') {
+    log('[lens-region] lens section already current — nothing to do (zero-diff).');
+    return 0;
+  }
+  if (result.status === 'custom') {
+    log('[lens-region] lens section carries a custom edit — preserved verbatim.');
+    log('[lens-region] note: the canonical planning/review lens has changed since this section was edited — compare it with the project methodology canon when convenient; your wording is never overwritten.');
+    return 0;
+  }
+  // refreshed → cap-guard from the TARGET's own frontmatter, then atomic write.
+  const maxLines = frontmatterMaxLines(text);
+  if (maxLines === null) {
+    log('[lens-region] note: no `maxLines` frontmatter on the target — the line-cap guard is skipped.');
+  } else if (lineCount(result.text) > maxLines) {
+    log(`[lens-region] refused — refreshing would push ${argv[1]} to ${lineCount(result.text)} lines (cap ${maxLines}); trim the file and re-run. Nothing was changed.`);
+    return 0;
+  }
+  const tmp = join(dirname(targetPath), `.${basename(targetPath)}.tmp-${process.pid}-${Date.now()}`);
+  try {
+    await fs.writeFile(tmp, result.text, 'utf8');
+    await fs.rename(tmp, targetPath);
+  } catch (err) {
+    await fs.rm(tmp, { force: true }).catch(() => {});
+    throw err;
+  }
+  log('[lens-region] refreshed the planning/review lens section to the current canon.');
+  return 0;
+};
+
+const { pathToFileURL } = await import('node:url');
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) process.exitCode = await runCli(process.argv.slice(2));

package/tools/orchestration-write.mjs

@@ -4,94 +4,24 @@
 // 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).
+// The hardened write flow (deployment gate → symlink STOPs → containment guard → exclusive-create
+// tmp + rename with a TOCTOU re-check → tmp cleanup; LAST-WRITER-WINS, documented) lives in the
+// shared atomic-write core (tools/atomic-write.mjs, extracted from this module — AD-042) and is
+// consumed here with this module's own STOP identity, so the public API + error contract are
+// unchanged (this file's tests pin them, characterize-first).
 //
 // 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';
+import { writeDocsAiFileAtomic } from './atomic-write.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 };
-};
+export const writeConfig = (cwd, config, deps = {}) =>
+  writeDocsAiFileAtomic(cwd, CONFIG_REL, serializeConfig(config), deps, { stop, noun: 'a config' });

package/tools/presentation.mjs

@@ -41,6 +41,7 @@ export const SETTINGS_LABELS = Object.freeze({
   recipes: 'recipes',
   attribution: 'attribution',
   velocity: 'velocity',
+  agents: 'cheap agents',
   hook: 'gate hook',
 });
 

package/tools/renderers.mjs

@@ -101,11 +101,19 @@ const renderSettings = (vm, { color, glyph }) => {
   else if (s.velocity) {
     lines.push(`  ${pad(SETTINGS_LABELS.velocity, SETTINGS_COL)}defaultMode=${String(s.velocity.defaultMode)} · allow project/local=${s.velocity.allow.project}/${s.velocity.allow.local}`);
   }
-  // gate hook — the opt-in PreToolUse gate-approval hook: wired / file placed / declaration present.
+  // cheap agents — the kit-placed .claude/agents/ vehicles: placed count vs the bundle.
+  if (s.agents?.error) lines.push(`  ${pad(SETTINGS_LABELS.agents, SETTINGS_COL)}error: ${s.agents.error}`);
+  else if (s.agents) {
+    lines.push(`  ${pad(SETTINGS_LABELS.agents, SETTINGS_COL)}placed=${s.agents.placed}/${s.agents.bundled}`);
+  }
+  // gate hook — the opt-in PreToolUse gate-approval hook: wired / file placed / declaration present /
+  // declared gate count (null → '?' — unknown is shown as unknown, never as a number).
   if (s.hook?.error) lines.push(`  ${pad(SETTINGS_LABELS.hook, SETTINGS_COL)}error: ${s.hook.error}`);
   else if (s.hook) {
     const yn = (b) => (b ? 'yes' : 'no');
-    lines.push(`  ${pad(SETTINGS_LABELS.hook, SETTINGS_COL)}wired=${yn(s.hook.wired)} · file=${yn(s.hook.filePlaced)} · gates.json=${yn(s.hook.declarationPresent)}`);
+    // A null count carries its preserved validation reason — never a silent bare "?".
+    const declared = s.hook.declaredGates ?? (s.hook.declarationError ? `? (${s.hook.declarationError})` : '?');
+    lines.push(`  ${pad(SETTINGS_LABELS.hook, SETTINGS_COL)}wired=${yn(s.hook.wired)} · file=${yn(s.hook.filePlaced)} · gates.json=${yn(s.hook.declarationPresent)} · declared=${declared}`);
   }
   return lines;
 };

package/tools/review-state.mjs

@@ -5,7 +5,8 @@
 // resolves the effective `plan-execution.review` recipe (the advisor's single-source readers),
 // recomputes the CURRENT canonical uncommitted-state fingerprint, and reports — per recipe-named
 // backend — whether a FRESH, grounded, current-fingerprint receipt exists. `--check` turns the
-// report into a gate exit code (declare it in docs/ai/gates.json — by hand; never auto-seeded).
+// report into a gate exit code (declare it in docs/ai/gates.json — by hand OR via the
+// explicit-consent seeder, tools/seed-gates.mjs — never without consent, AD-021/AD-042).
 //
 // Normative `--check` exit contract (the single home of this list — SKILL.md points here):
 //   exit 0  when the resolved plan-execution.review recipe is solo (configured, or degraded there —
@@ -353,7 +354,8 @@ presence + verdict + grounding for the CURRENT tree. Plan/diff-mode receipts and
 --check exits 0/1 per the normative contract in the tool header: 0 for solo / no plan in flight /
 a clean tree / not-a-git-tree / all recipe-named backends receipted-current-and-grounded; 1 when a
 recipe-named backend is missing, stale (edited after review), or grounded:false under
-reviewed/council. Declare it as a project gate by hand (docs/ai/gates.json) — never auto-seeded.
+reviewed/council. Declare it as a project gate by hand (docs/ai/gates.json) or via the
+explicit-consent seeder (tools/seed-gates.mjs) — never without consent.
 
 Read-only: never writes, never commits, never runs a subscription CLI; spawns read-only git queries.
 Human residual: git commit --no-verify and receipt-file deletion remain possible — this is a