@sabaiway/agent-workflow-kit 1.17.0 → 1.19.0

package/tools/labels.mjs

@@ -0,0 +1,81 @@
+// labels.mjs — the frozen vocabulary LEAF of the status surface (Plan: One-init-freshness §4.2 B1).
+//
+// This module owns the internal↔public token vocabulary that used to live inline in
+// family-registry.mjs: the manifestState constants, the internal→public state map, the visibility
+// map, the short display names, and the no-leak forbidden-term set. It is a LEAF — it imports
+// nothing from the family (only the language is here), so the import graph stays acyclic: nobody
+// imports family-registry for vocabulary, and family-registry imports + re-exports the public subset
+// it exported before (the 7 state constants + DISPLAY_NAMES), so every existing importer stays green.
+//
+// Pure data, no side effects, Node >= 18. Every export is frozen — this is a contract, not a mutable.
+
+// ── manifestState values (internal; the detect-backends precedence, generalized to any member) ──────
+// These are INTERNAL — they must never reach a user surface verbatim (mapped through STATE_PUBLIC
+// first). The two surfaces are pinned separately; the no-leak guard (INTERNAL_RENDER_FORBIDDEN) keeps
+// the internal literals out of the serialized envelope.
+export const NOT_INSTALLED = 'not-installed';
+export const UNSUPPORTED_SCHEMA = 'unsupported-schema';
+export const INVALID_MANIFEST = 'invalid-manifest';
+export const STUB = 'stub';
+export const FOREIGN = 'foreign';
+export const OK = 'ok';
+// The marker could not be probed (a non-ENOENT fs error — EACCES/EIO). Surfaced explicitly instead of
+// being masked as not-installed (no silent failure). NOTE: 'unknown' is ALSO a PUBLIC value — it is a
+// bridge wrappers[].state ("couldn't check"), so it is deliberately EXCLUDED from the no-leak set.
+export const UNKNOWN = 'unknown';
+
+// internal manifestState → a STABLE, user-safe token. SKILL.md owns the value→plain-language phrasing;
+// presentation.mjs owns the direct-CLI English phrasing. Deliberately NOT the internal literals
+// (foreign/stub/…): those must never leak past this boundary.
+export const STATE_PUBLIC = Object.freeze({
+  [OK]: 'installed',
+  [NOT_INSTALLED]: 'absent',
+  [FOREIGN]: 'other-tool',
+  [STUB]: 'placeholder',
+  [INVALID_MANIFEST]: 'invalid',
+  [UNSUPPORTED_SCHEMA]: 'unsupported',
+  [UNKNOWN]: 'uncheckable',
+});
+
+// visibility: the THREE honest states from inferVisibility → user-safe words. Never the internal
+// "hidden fence" / marker terms. ('hidden' here is the PUBLIC visibility word, not the internal fence.)
+export const VISIBILITY_PUBLIC = Object.freeze({ visible: 'visible', hidden: 'hidden', ambiguous: 'unclear' });
+
+// Short, user-facing labels for the version block (kit · memory · engine · codex-bridge · …), so the
+// render is deterministic and the agent never invents a label.
+export const DISPLAY_NAMES = Object.freeze({
+  'agent-workflow-kit': 'kit',
+  'agent-workflow-memory': 'memory',
+  'agent-workflow-engine': 'engine',
+  'codex-cli-bridge': 'codex-bridge',
+  'antigravity-cli-bridge': 'antigravity-bridge',
+});
+export const displayOf = (name) => DISPLAY_NAMES[name] ?? name;
+
+// ── the no-leak forbidden set (Plan §4.3 INV-4) ────────────────────────────────────────────────────
+// The terms that must NEVER appear in the serialized buildEnvelope output (the agent reads the JSON
+// directly, so the no-leak boundary is the envelope, not just the rendered text). The INV-4 test
+// iterates this set over JSON.stringify(envelope). Deliberately EXCLUDES:
+//   • 'unknown' — also a PUBLIC bridge wrappers[].state value (a `state:"unknown"` fixture must pass);
+//   • 'ok'      — too generic to forbid as a substring, and not sensitive (its public form is 'installed').
+// Sourced here as the ONE definition so the guard can't drift from a hand-copied list in the test.
+export const INTERNAL_RENDER_FORBIDDEN = Object.freeze([
+  // internal manifestState literals that must never reach a surface
+  NOT_INSTALLED,
+  UNSUPPORTED_SCHEMA,
+  INVALID_MANIFEST,
+  STUB,
+  FOREIGN,
+  // internal field names (the structural keys of the surveys, never the envelope)
+  'manifestState',
+  'hiddenFence',
+  // the hidden-mode marker / fence jargon (the SKILL communication firewall) — never the public
+  // visibility words ('hidden' / 'visible' / 'unclear'), only the internal compound terms + operations
+  'hidden fence',
+  'hidden-mode fence',
+  'reconcile',
+  'ensureSlot',
+  // raw deployment-stamp FILENAMES (the envelope exposes member/display/version, never the file)
+  '.workflow-version',
+  '.memory-version',
+]);

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 };
+};

package/tools/presentation.mjs

@@ -0,0 +1,55 @@
+// presentation.mjs — the frozen ENGLISH/neutral vocabulary the direct-CLI renderers use to draw the
+// four status blocks (members · bridges · project deploy/visibility · settings). Plan §4.2.
+//
+// This is the DIRECT-CLI surface only (`node tools/family-registry.mjs` in a terminal). The
+// agent-mediated surface (`/agent-workflow-kit status`) consumes the `--json` envelope and localizes
+// in the user's language per SKILL.md §4.4 — it never reads this file. Keeping the vocabulary here (a
+// frozen leaf) means the renderers carry no inline strings and the phrasing is pinned by tests.
+//
+// Pure data, no side effects, Node >= 18. Every export frozen.
+
+// public state token (STATE_PUBLIC value) → the direct-CLI English phrase. `installed` is null because
+// an installed member shows its VERSION, not a phrase (the renderer special-cases it). Mirrors the
+// SKILL.md value→plain-language map so the two surfaces stay semantically aligned.
+export const STATE_PHRASING = Object.freeze({
+  installed: null, // → show the version instead
+  absent: 'not installed',
+  'other-tool': 'a different tool occupies that skill slot',
+  placeholder: 'a placeholder, not a working install',
+  invalid: "installed but its manifest didn't validate",
+  unsupported: 'installed but its manifest schema is too new for this kit',
+  uncheckable: "couldn't be checked (a permission error)",
+});
+
+// public visibility (VISIBILITY_PUBLIC value) → phrase. Never the internal "fence"/marker terms.
+export const VISIBILITY_PHRASING = Object.freeze({
+  visible: 'visible (tracked)',
+  hidden: 'hidden (git-ignored, local-only)',
+  unclear: 'unclear (uncommitted or partially set up)',
+});
+
+// Block titles. `project` is a function of the resolved dir.
+export const BLOCK_TITLES = Object.freeze({
+  members: 'agent-workflow family — installed members (skill axis)',
+  bridges: 'execution backends (host)',
+  project: (dir) => `project deployment (${dir})`,
+  settings: 'settings',
+});
+
+// Per-area settings row labels (the left column of the settings block).
+export const SETTINGS_LABELS = Object.freeze({
+  recipes: 'recipes',
+  attribution: 'attribution',
+  velocity: 'velocity',
+});
+
+// Glyph sets — Unicode for a capable terminal, an ASCII fallback for a narrow / Windows-legacy one.
+// The renderer picks one set by the resolved surface's `ascii` flag (surface.mjs).
+export const GLYPHS = Object.freeze({
+  unicode: Object.freeze({ note: '↳', present: '✓', missing: '✗', unknown: '?', bullet: '•' }),
+  ascii: Object.freeze({ note: '->', present: '+', missing: 'x', unknown: '?', bullet: '*' }),
+});
+export const glyphsFor = (ascii) => (ascii ? GLYPHS.ascii : GLYPHS.unicode);
+
+// The "no deployment here" line for an undeployed project.
+export const NO_DEPLOYMENT = 'no agent-workflow deployment detected here (no docs/ai, no version stamp).';