session-orchestrator 3.16.0

package/scripts/lib/config/custom-phases.mjs

@@ -0,0 +1,213 @@
+import { matchBlockHeader } from './block-header.mjs';
+
+/**
+ * custom-phases.mjs — Parser for the `custom-phases:` Session Config block (#637).
+ *
+ * Lets a repo declare opt-in deterministic phases that run during session close
+ * (and/or housekeeping) as a CONTRACT: each phase has a name, a `when` trigger,
+ * a shell `command`, a `mode` (warn|hard|off) that gates the close, and an
+ * optional `review` file the coordinator reads after the command.
+ *
+ * Exports:
+ *   _parseCustomPhases(content) — PURE, no side effects beyond a stderr WARN when
+ *                                 a record is dropped for failing validation.
+ *                                 Returns [] when the block is absent/empty.
+ *
+ * Block shape:
+ *   custom-phases:
+ *     - name: eval-learn-aggregate     # required, non-empty, SAFE slug
+ *       when: housekeeping              # housekeeping | session-end | both (default: session-end)
+ *       command: npm run eval:aggregate # required; NO interpolation from records
+ *       mode: hard                      # warn | hard | off (default: warn)
+ *       review: docs/eval/last-run.md   # optional; SAFE_PATH_RE-validated; default null
+ *
+ * Modelled on cross-repo.mjs (per-entry SAFE_PATH_RE validation, drop-with-warn)
+ * and gitlab-portfolio.mjs (nested list/column-0 block scan). Enum fallbacks are
+ * SILENT to the default per block-parser convention (vault-sync.mjs precedent).
+ *
+ * NOTE on the mode enum: it is ['warn','hard','off'] — `hard` is the correct
+ * blocking value for THIS new key. Do NOT copy vault-sync's ['strict','warn','off']
+ * (see #217 regression: `hard` was a silent-default bug THERE, intentional HERE).
+ */
+
+/** Per-phase defaults. */
+export const CUSTOM_PHASE_DEFAULTS = Object.freeze({
+  when: 'session-end',
+  mode: 'warn',
+  review: null,
+});
+
+const VALID_WHEN = new Set(['housekeeping', 'session-end', 'both']);
+const VALID_MODE = new Set(['warn', 'hard', 'off']);
+
+// Allowlist: a phase `name` is a SAFE slug — lowercase/uppercase letters, digits,
+// hyphen, underscore, dot. No spaces, no shell metacharacters.
+const SAFE_NAME_RE = /^[A-Za-z0-9._-]+$/;
+
+// Allowlist for `command` and `review`: rejects shell metacharacters (; $ ` | & > <
+// ( ) newline) that would break the exit-code-gated execution / file-read contract.
+// `command` legitimately contains spaces, slashes, colons (e.g. "npm run eval:aggregate"),
+// so the allowlist is broader than SAFE_NAME_RE but still excludes injection vectors.
+const SAFE_COMMAND_RE = /^[A-Za-z0-9._\-/: =]+$/;
+
+// `review` is a repo-relative or absolute file path — no spaces, no metacharacters.
+const SAFE_PATH_RE = /^[A-Za-z0-9._~/-]+$/;
+
+/**
+ * Parse the top-level `custom-phases:` YAML list block from markdown content.
+ *
+ * Each list item is a record. Records are validated per-entry; a record missing
+ * a required field (`name`, `command`) or carrying a shell-metacharacter in
+ * `command`/`review`/`name` is DROPPED with a stderr WARN. Invalid `when`/`mode`
+ * enum values fall back SILENTLY to their defaults.
+ *
+ * @param {string} content — full CLAUDE.md / AGENTS.md file content
+ * @returns {Array<{name: string, when: string, command: string, mode: string, review: string|null}>}
+ */
+export function _parseCustomPhases(content) {
+  const lines = content.split(/\r?\n/);
+  let inBlock = false;
+  const blockLines = [];
+
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/\r$/, '');
+
+    if (!inBlock) {
+      // Detect `custom-phases:` at column 0 with optional trailing spaces.
+      if (matchBlockHeader(line, 'custom-phases')) inBlock = true;
+      continue;
+    }
+
+    // Block terminates at the first non-indented, non-empty line (next top-level key).
+    if (line.length > 0 && !/^\s/.test(line)) break;
+
+    blockLines.push(line);
+  }
+
+  if (blockLines.length === 0) return [];
+
+  /** @type {Array<{name: string, when: string, command: string, mode: string, review: string|null}>} */
+  const records = [];
+  /** @type {Record<string, string>|null} */
+  let current = null;
+
+  const flush = () => {
+    if (current === null) return;
+    const rec = _validateRecord(current);
+    if (rec !== null) records.push(rec);
+    current = null;
+  };
+
+  for (const rawLine of blockLines) {
+    // Strip inline comments + trailing whitespace, preserve leading indent.
+    const clean = rawLine.replace(/\s*#.*$/, '').replace(/\s+$/, '');
+    if (!clean.trim()) continue;
+
+    // A new list item starts with a dash. The first key may sit on the dash line:
+    //   - name: foo
+    const dashMatch = clean.match(/^\s*-\s+(.*)$/);
+    if (dashMatch) {
+      flush();
+      current = {};
+      const inlineKv = dashMatch[1].match(/^([a-zA-Z][a-zA-Z0-9_-]*):\s*(.*)$/);
+      if (inlineKv) {
+        _assignKv(current, inlineKv[1], inlineKv[2]);
+      }
+      continue;
+    }
+
+    // Continuation key for the current record (deeper indent, no dash).
+    const kvMatch = clean.match(/^\s+([a-zA-Z][a-zA-Z0-9_-]*):\s*(.*)$/);
+    if (kvMatch && current !== null) {
+      _assignKv(current, kvMatch[1], kvMatch[2]);
+    }
+  }
+
+  flush();
+
+  return records;
+}
+
+/**
+ * Assign a raw key/value onto a record being built, stripping surrounding quotes.
+ * Only known keys are stored; unknown keys are silently ignored (additive-friendly).
+ *
+ * @param {Record<string, string>} record
+ * @param {string} key
+ * @param {string} rawValue
+ */
+function _assignKv(record, key, rawValue) {
+  let v = rawValue.trim();
+  if (v.startsWith('"') && v.endsWith('"') && v.length >= 2) v = v.slice(1, -1);
+  else if (v.startsWith("'") && v.endsWith("'") && v.length >= 2) v = v.slice(1, -1);
+
+  switch (key) {
+    case 'name':
+    case 'when':
+    case 'command':
+    case 'mode':
+    case 'review':
+      record[key] = v;
+      break;
+    default:
+      // Unknown keys are silently ignored — additive-friendly.
+      break;
+  }
+}
+
+/**
+ * Validate + normalise a raw record. Returns the fully-defaulted record, or null
+ * (with a stderr WARN) when a required field is missing or a SAFE-regex fails.
+ *
+ * @param {Record<string, string>} raw
+ * @returns {{name: string, when: string, command: string, mode: string, review: string|null}|null}
+ */
+function _validateRecord(raw) {
+  const name = (raw.name ?? '').trim();
+  if (name === '') {
+    process.stderr.write('custom-phases: dropped record missing required field: name\n');
+    return null;
+  }
+  if (!SAFE_NAME_RE.test(name)) {
+    process.stderr.write(
+      `custom-phases: dropped record with unsafe name: ${JSON.stringify(name)}\n`,
+    );
+    return null;
+  }
+
+  const command = (raw.command ?? '').trim();
+  if (command === '') {
+    process.stderr.write(
+      `custom-phases: dropped record '${name}' missing required field: command\n`,
+    );
+    return null;
+  }
+  if (!SAFE_COMMAND_RE.test(command)) {
+    process.stderr.write(
+      `custom-phases: dropped record '${name}' with shell metacharacter in command: ${JSON.stringify(command)}\n`,
+    );
+    return null;
+  }
+
+  // when: enum fallback SILENT to default.
+  const when = VALID_WHEN.has(raw.when) ? raw.when : CUSTOM_PHASE_DEFAULTS.when;
+
+  // mode: enum fallback SILENT to default.
+  const mode = VALID_MODE.has(raw.mode) ? raw.mode : CUSTOM_PHASE_DEFAULTS.mode;
+
+  // review: optional; validated against SAFE_PATH_RE. An unsafe path DROPS the
+  // whole record (it is a security-relevant field the coordinator will read).
+  let review = CUSTOM_PHASE_DEFAULTS.review;
+  const rawReview = (raw.review ?? '').trim();
+  if (rawReview !== '' && rawReview !== 'null' && rawReview !== 'none') {
+    if (!SAFE_PATH_RE.test(rawReview)) {
+      process.stderr.write(
+        `custom-phases: dropped record '${name}' with shell metacharacter in review path: ${JSON.stringify(rawReview)}\n`,
+      );
+      return null;
+    }
+    review = rawReview;
+  }
+
+  return { name, when, command, mode, review };
+}

package/scripts/lib/config/dialectic.mjs

@@ -0,0 +1,92 @@
+import { matchBlockHeader } from './block-header.mjs';
+
+/**
+ * dialectic.mjs — Parser for top-level `dialectic:` YAML block (#506).
+ *
+ * Drives the Dialectic-Deriver via /evolve --dialectic and session-end Phase 3.6.7.
+ * Returns { cadence, model, "budget-tokens" }.
+ * Fail-fast on unknown model value (per #506 EARS unwanted-behaviour);
+ * silent fallback for out-of-range integers (matches cold-start.mjs precedent).
+ *
+ * Consumer: skills/evolve/SKILL.md Phase 6, skills/session-end/SKILL.md Phase 3.6.7.
+ */
+
+const ALLOWED_MODELS = new Set(['haiku', 'sonnet', 'opus']);
+
+/**
+ * Parse the top-level `dialectic:` YAML block from markdown content.
+ * Independent of the `## Session Config` section boundary.
+ *
+ * Defaults:
+ *   cadence:       5 (integer ≥ 0 — session count between auto-runs; 0 = disabled)
+ *   model:         'haiku'
+ *   budget-tokens: 8000 (integer ≥ 0)
+ *
+ * Throws if `model` is present but not one of haiku|sonnet|opus.
+ *
+ * @param {string} content — full file contents
+ * @returns {{ cadence: number, model: string, "budget-tokens": number }}
+ */
+export function _parseDialectic(content) {
+  const defaults = { cadence: 5, model: 'haiku', 'budget-tokens': 8000 };
+
+  const lines = content.split(/\r?\n/);
+  let inBlock = false;
+  const blockLines = [];
+
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/\r$/, '');
+    if (!inBlock) {
+      if (matchBlockHeader(line, 'dialectic')) inBlock = true;
+      continue;
+    }
+    if (line.length > 0 && !/^\s/.test(line)) break;
+    blockLines.push(line);
+  }
+
+  if (blockLines.length === 0) return defaults;
+
+  let cadence = 5;
+  let model = 'haiku';
+  let budgetTokens = 8000;
+
+  for (const rawLine of blockLines) {
+    const clean = rawLine.replace(/\s*#.*$/, '').replace(/\s+$/, '');
+    if (!clean.trim()) continue;
+
+    const kvMatch = clean.match(/^\s+([a-zA-Z_-]+):\s*(.*)/);
+    if (!kvMatch) continue;
+
+    const k = kvMatch[1];
+    let v = kvMatch[2].trim();
+    if (v.startsWith('"') && v.endsWith('"') && v.length >= 2) v = v.slice(1, -1);
+    else if (v.startsWith("'") && v.endsWith("'") && v.length >= 2) v = v.slice(1, -1);
+
+    switch (k) {
+      case 'cadence': {
+        if (/^\d+$/.test(v)) {
+          const n = parseInt(v, 10);
+          if (n >= 0) cadence = n;
+        }
+        break;
+      }
+      case 'model': {
+        const lower = v.toLowerCase();
+        if (!ALLOWED_MODELS.has(lower)) {
+          throw new Error(`dialectic.model must be haiku|sonnet|opus, got '${v}'`);
+        }
+        model = lower;
+        break;
+      }
+      case 'budget-tokens': {
+        if (/^\d+$/.test(v)) {
+          const n = parseInt(v, 10);
+          if (n >= 0) budgetTokens = n;
+        }
+        break;
+      }
+    }
+  }
+
+  return { cadence, model, 'budget-tokens': budgetTokens };
+}

package/scripts/lib/config/discovery-validator.mjs

@@ -0,0 +1,75 @@
+import { matchBlockHeader } from './block-header.mjs';
+
+/**
+ * discovery-validator.mjs — Parser for the top-level `discovery-validator:`
+ * YAML block (PSA-006 mechanical enforcement / issue #567).
+ *
+ * Drives the non-blocking SubagentStop hook that flags distributional
+ * claims ("N of M", "100% of", "all N", "no remaining", "every X", "none of")
+ * in a subagent's transcript tail that lack an adjacent fenced grep/rg/find
+ * transcript. v1 is log+warn only (events.jsonl + stderr WARN); exit 2
+ * (blocking) is reserved for a future hard-gate.
+ *
+ * Returns `{ enabled }`.
+ * Tolerant parser: malformed values silently fall back to defaults.
+ *
+ * Consumer: `hooks/post-subagent-discovery-validator.mjs`.
+ */
+
+/**
+ * Parse the top-level `discovery-validator:` YAML block from markdown content.
+ * Independent of the `## Session Config` section boundary.
+ *
+ * Defaults:
+ *   enabled: true
+ *
+ * @param {string} content — full file contents
+ * @returns {{ enabled: boolean }}
+ */
+export function _parseDiscoveryValidator(content) {
+  const defaults = {
+    enabled: true,
+  };
+
+  const lines = content.split(/\r?\n/);
+  let inBlock = false;
+  const blockLines = [];
+
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/\r$/, '');
+    if (!inBlock) {
+      if (matchBlockHeader(line, 'discovery-validator')) inBlock = true;
+      continue;
+    }
+    if (line.length > 0 && !/^\s/.test(line)) break;
+    blockLines.push(line);
+  }
+
+  if (blockLines.length === 0) return defaults;
+
+  let dvEnabled = false;
+
+  for (const rawLine of blockLines) {
+    const clean = rawLine.replace(/\s*#.*$/, '').replace(/\s+$/, '');
+    if (!clean.trim()) continue;
+
+    const kvMatch = clean.match(/^\s+([a-zA-Z_-]+):\s*(.*)/);
+    if (!kvMatch) continue;
+
+    const k = kvMatch[1];
+    let v = kvMatch[2].trim();
+    if (v.startsWith('"') && v.endsWith('"') && v.length >= 2) v = v.slice(1, -1);
+    else if (v.startsWith("'") && v.endsWith("'") && v.length >= 2) v = v.slice(1, -1);
+
+    switch (k) {
+      case 'enabled':
+        // Only literal "true" (case-insensitive) flips enabled; any other value → false
+        dvEnabled = v.toLowerCase() === 'true';
+        break;
+    }
+  }
+
+  return {
+    enabled: dvEnabled,
+  };
+}

package/scripts/lib/config/dispatcher-autonomy-capture.mjs

@@ -0,0 +1,240 @@
+/**
+ * dispatcher-autonomy-capture.mjs — One-time per-repo capture of the
+ * `dispatcher-autonomy:` preference (Epic #673 / issue #681).
+ *
+ * The committed `dispatcher-autonomy:` block is asked EXACTLY ONCE per repo at
+ * two triggers:
+ *   (a) bootstrap   — new project, block always absent → always asks.
+ *   (b) migration   — first session-start after this feature ships, when the
+ *                     committed block is still absent.
+ *
+ * The guard is the RAW PRESENCE of the committed block, not the RESOLVED value:
+ * `_parseDispatcherAutonomy()` returns `autonomy: 'off'` for BOTH "block absent"
+ * AND "block present with autonomy: off" — so the resolved value cannot
+ * distinguish first-run from a deliberate `off`. This module therefore detects
+ * presence via the shared bold-tolerant `hasBlockHeader()` helper
+ * (block-header.mjs) — the same matcher the parser now uses (#830).
+ * Block presence IS the never-re-ask marker — there is no separate state file.
+ *
+ * The committed instruction file is `CLAUDE.md` on Claude Code / Cursor IDE and
+ * `AGENTS.md` on Codex CLI — transparent aliases (see
+ * `skills/_shared/instruction-file-resolution.md`); every reference to `CLAUDE.md`
+ * below resolves to `AGENTS.md` on those platforms.
+ *
+ * The writer writes ONLY the committed default (autonomy enum + confidence-floor).
+ * Host-local overrides (env `SO_DISPATCHER_AUTONOMY`, owner.yaml
+ * `dispatcher.autonomy`) NEVER land in CLAUDE.md / AGENTS.md — they stay host-local
+ * so a machine may differ from the committed default. See
+ * `scripts/lib/config/dispatcher-autonomy.mjs` `resolveDispatcherAutonomy()`.
+ *
+ * Pure, no-throw, zero-coupling helpers. The coordinator drives the
+ * AskUserQuestion call; this module only provides the question definition,
+ * the presence guard, the block renderer, and the idempotent writer.
+ *
+ * Consumers:
+ *   - `skills/bootstrap/SKILL.md`      (Phase 3.5.1 — new-project capture)
+ *   - `skills/session-start/SKILL.md`  (Phase 1.1  — migration capture)
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs';
+
+import { hasBlockHeader } from './block-header.mjs';
+
+const ALLOWED_AUTONOMY = ['off', 'advisory', 'autonomous-gated'];
+const DEFAULT_CONFIDENCE_FLOOR = 0.5;
+
+/**
+ * Coordinator-facing AUQ question definition for the one-time capture.
+ * Mirrors the shape of `getInterviewQuestions()` entries in owner-interview.mjs:
+ *   { question, header, options: [{ label, description }], multiSelect }
+ *
+ * Option labels match the ALLOWED_AUTONOMY enum so the selected label maps
+ * directly to the `autonomy` value passed to writeDispatcherAutonomyBlock().
+ * Option 1 (`off`) is the recommended, fail-closed default.
+ *
+ * @returns {{ question: string, header: string, options: Array<{ label: string, description: string }>, multiSelect: boolean }}
+ */
+export function getDispatcherAutonomyQuestion() {
+  return {
+    question:
+      'Cross-repo dispatcher autonomy: how should this repo participate when the free-repo dispatcher routes work to it?',
+    header: 'Dispatcher Autonomy (one-time)',
+    options: [
+      {
+        label: 'off',
+        description:
+          '(Recommended) Fail-closed. The dispatcher never routes work to this repo automatically. No behaviour change.',
+      },
+      {
+        label: 'advisory',
+        description:
+          'The dispatcher surfaces ranked free-repo candidates for operator review — no automated dispatch.',
+      },
+      {
+        label: 'autonomous-gated',
+        description:
+          'A deterministic confidence gate is checked first; only dispatches that clear the confidence-floor route automatically.',
+      },
+    ],
+    multiSelect: false,
+  };
+}
+
+/**
+ * Detect whether the committed `dispatcher-autonomy:` block is present in the
+ * given CLAUDE.md / AGENTS.md content. This is the one-time-capture guard:
+ * absent → ask, present → never re-ask.
+ *
+ * SOURCE-OF-TRUTH ALIGNMENT: this guard mirrors the block-header detection of
+ * `_parseDispatcherAutonomy()` in dispatcher-autonomy.mjs EXACTLY — both now call
+ * the shared `matchBlockHeader()` matcher (block-header.mjs). `hasBlockHeader()`
+ * splits on `/\r?\n/` and tests each line, so `\r` and trailing whitespace are
+ * eaten by the `\s*$` tail and the identical set of inputs matches.
+ * Verified-equivalent edge cases:
+ *   - CRLF line endings (`dispatcher-autonomy:\r\n`) → PRESENT (`\s*$` eats the `\r`).
+ *   - Trailing spaces / tabs on the header line → PRESENT (`\s*$`).
+ *   - Header glued to a leading BOM (a U+FEFF byte-order-mark immediately
+ *     preceding `dispatcher-autonomy:`) → ABSENT, because `^...` requires column-0
+ *     and the BOM occupies it — IDENTICAL to the parser, which also rejects it.
+ *     (A BOM at file START with the header on a
+ *     LATER line is unaffected; the block is always appended to the end of an
+ *     existing file, so the BOM never touches the header in practice.)
+ *   - Header inside a ``` fenced code block → PRESENT. This is DELIBERATE: the
+ *     parser does not track fences and would treat such a header as a real block,
+ *     so the guard must agree. The never-re-ask marker is "the parser would see a
+ *     block", not "a human would call it config". If the parser is ever taught to
+ *     skip fences, update this guard in lock-step.
+ *   - Header present but BODY malformed (garbage non-yaml lines) → PRESENT. A
+ *     malformed block is the operator's to fix, never a re-prompt trigger — the
+ *     parser tolerantly falls back to defaults, and capture must not re-ask.
+ *
+ * No-throw: null / non-string / empty → false.
+ *
+ * @param {unknown} claudeMdContent — full CLAUDE.md / AGENTS.md file contents
+ * @returns {boolean}
+ */
+export function isDispatcherAutonomyBlockPresent(claudeMdContent) {
+  if (typeof claudeMdContent !== 'string' || claudeMdContent.length === 0) return false;
+  return hasBlockHeader(claudeMdContent, 'dispatcher-autonomy');
+}
+
+/**
+ * Coerce a candidate autonomy value to a valid lowercase enum, falling back to
+ * 'off' when unset/empty/whitespace/invalid (fail-closed). Mirrors the
+ * fail-closed posture of resolveDispatcherAutonomy().
+ *
+ * @param {unknown} value
+ * @returns {string} one of ALLOWED_AUTONOMY
+ */
+function coerceAutonomy(value) {
+  if (value === null || value === undefined) return 'off';
+  const normalized = String(value).toLowerCase().trim();
+  return ALLOWED_AUTONOMY.includes(normalized) ? normalized : 'off';
+}
+
+/**
+ * Clamp a candidate confidence-floor to the closed interval [0.0, 1.0],
+ * falling back to the default when unset/non-finite.
+ *
+ * @param {unknown} value
+ * @returns {number} float in [0.0, 1.0]
+ */
+function clampConfidenceFloor(value) {
+  if (value === null || value === undefined || value === '') return DEFAULT_CONFIDENCE_FLOOR;
+  const f = Number(value);
+  if (!Number.isFinite(f)) return DEFAULT_CONFIDENCE_FLOOR;
+  if (f < 0) return 0;
+  if (f > 1) return 1;
+  return f;
+}
+
+/**
+ * Render the canonical standalone `## Dispatcher Autonomy` H2 block + fenced
+ * yaml. The standalone-H2 placement is MANDATORY: it keeps
+ * claude-md-drift-check Check-6 (Session-Config-parity) green. Promoting the
+ * block into `## Session Config` would hard-fail drift-check on every repo
+ * lacking the key.
+ *
+ * Validates `autonomy` against the enum (fall back to 'off') and clamps
+ * `confidenceFloor` to [0, 1]. Writes ONLY the committed default — never the
+ * host-local override.
+ *
+ * @param {{ autonomy?: unknown, confidenceFloor?: unknown }} [opts]
+ * @returns {string} the rendered block (leading newline, trailing newline)
+ */
+export function renderDispatcherAutonomyBlock({ autonomy, confidenceFloor = DEFAULT_CONFIDENCE_FLOOR } = {}) {
+  const safeAutonomy = coerceAutonomy(autonomy);
+  const safeFloor = clampConfidenceFloor(confidenceFloor);
+
+  return [
+    '',
+    '## Dispatcher Autonomy',
+    '',
+    '> **Parity-exempt section.** This H2 is intentionally placed outside the `## Session Config` block so that the `claude-md-drift-check` Check-6 parity scanner (which extracts only column-0 keys inside the `## Session Config` block) does not flag repos that have not yet adopted this feature. Issue #679 / #681.',
+    '',
+    'Opt-in configuration for the cross-repo free-repo dispatcher autonomy gate (Epic #673). The default is `off` — fail-closed. The effective `autonomy` resolves with host-local precedence `SO_DISPATCHER_AUTONOMY` env > `owner.yaml` `dispatcher.autonomy` > committed > `off` (#653 pattern).',
+    '',
+    '```yaml',
+    'dispatcher-autonomy:',
+    `  autonomy: ${safeAutonomy}            # off | advisory | autonomous-gated — default off (fail-closed)`,
+    `  confidence-floor: ${safeFloor}    # float 0.0..1.0`,
+    '```',
+    '',
+    'Read by: `scripts/lib/config/dispatcher-autonomy.mjs` (parser + resolver), `skills/dispatcher/SKILL.md` (cross-repo dispatch flow). Issue: #681.',
+    '',
+  ].join('\n');
+}
+
+/**
+ * Idempotently append the committed `dispatcher-autonomy:` block to CLAUDE.md.
+ *
+ * Behaviour:
+ *   - block ABSENT  → append the rendered block → { written: true, path }.
+ *   - block PRESENT → no-op → { written: false, reason: 'already-present' }.
+ *   - IO failure    → { written: false, error: <message> } (no-throw).
+ *
+ * Block presence IS the never-re-ask marker, so a second invocation after a
+ * successful write is a safe no-op. A defensive double-write guard re-checks
+ * absence against the freshly-read file content immediately before writing (the
+ * content read here is the source of truth, not a stale caller-supplied value).
+ * This guard fires for a PARTIAL/MALFORMED existing block too: if a (even
+ * garbage-bodied) `dispatcher-autonomy:` header already exists, the writer
+ * returns `already-present` and never appends a second block — a malformed block
+ * is the operator's to repair, not ours to duplicate. The no-op is therefore
+ * idempotent against concurrent sessions (parallel writers) AND against
+ * hand-edited malformed blocks.
+ *
+ * @param {{ claudeMdPath: string, autonomy?: unknown, confidenceFloor?: unknown }} opts
+ * @returns {{ written: boolean, path?: string, reason?: string, error?: string }}
+ */
+export function writeDispatcherAutonomyBlock({ claudeMdPath, autonomy, confidenceFloor } = {}) {
+  if (typeof claudeMdPath !== 'string' || claudeMdPath.length === 0) {
+    return { written: false, error: 'writeDispatcherAutonomyBlock requires a claudeMdPath' };
+  }
+
+  let content;
+  try {
+    content = readFileSync(claudeMdPath, 'utf8');
+  } catch (err) {
+    return { written: false, error: `read failed: ${err && err.message ? err.message : String(err)}` };
+  }
+
+  // Defensive double-write guard: re-check absence against the freshly-read
+  // content before writing.
+  if (isDispatcherAutonomyBlockPresent(content)) {
+    return { written: false, reason: 'already-present' };
+  }
+
+  const block = renderDispatcherAutonomyBlock({ autonomy, confidenceFloor });
+  // Ensure exactly one separating newline between existing content and the block.
+  const separator = content.endsWith('\n') ? '' : '\n';
+  const next = `${content}${separator}${block}`;
+
+  try {
+    writeFileSync(claudeMdPath, next, 'utf8');
+  } catch (err) {
+    return { written: false, error: `write failed: ${err && err.message ? err.message : String(err)}` };
+  }
+
+  return { written: true, path: claudeMdPath };
+}