@mindrian_os/cli 2.0.0-beta.3 → 2.0.0-beta.33

package/lib/mcp/gate-render.cjs

@@ -0,0 +1,483 @@
+'use strict';
+// Phase 198-05 (SPEC-4, Task 1) -- the Mindrian gate superset schema + the
+// three-rung renderer ladder.
+//
+// 307 files today assume the Claude Code AskUserQuestion card; no schema
+// exists independent of the host. This module defines ONE Mindrian superset
+// card (options + per-option descriptions + ranks + previews + single/multi-
+// select) and a 3-rung renderer ladder:
+//   (a) renderViaElicitation -- MCP elicitation, where the client declares the
+//       capability. LOSSY on the wire: the requestedSchema carries per-option
+//       `const` (option ids) plus `title` (labels) on both select modes, via
+//       the SDK's titled enum schemas (node_modules/@modelcontextprotocol/sdk
+//       /dist/cjs/types.js TitledSingleSelectEnumSchemaSchema and
+//       TitledMultiSelectEnumSchemaSchema) -- per-option descriptions/ranks/
+//       previews never leave the server on this rung (RESEARCH Pitfall 4;
+//       SDK 1.29.0 ElicitRequestFormParamsSchema has no per-option
+//       description field). Phase 265 ledger: RADAR-06 (265-02-PLAN.md).
+//   (b) renderViaAskUserQuestion -- composes the FULL card (through the
+//       shipped shape-f8-renderer.cjs toggle envelope + the selector-
+//       dispatcher's AskUserQuestion trailer, Canon Part 7 reuse) for the
+//       Claude Code thin adapter, enriched with the complete superset
+//       metadata (descriptions/ranks/previews) so the adapter can construct
+//       the real native AskUserQuestion call with full fidelity.
+//   (c) renderViaText -- a structured-text card + next-message fallback for
+//       headless clients that declare neither capability.
+//
+// The three rungs carry different wire fidelity, but they all normalize the
+// user's choice into ONE canonical gate_answer payload shape
+// `{ gate_id, chosen: [optionId...], verdict }` via normalizeGateAnswer --
+// SPEC-4's acceptance bar is that identity, not merely "each renderer works".
+//
+// D-04 (F.8 binding-card discipline): a gate of kind 'binding' fires ONCE per
+// session and ONLY on genuine ambiguity; a resolved/unambiguous context (or a
+// session that already saw its one binding card) returns no card at all.
+//
+// Canon Part 7: reuses lib/hmi/shape-f8-renderer.cjs (binding) +
+// lib/hmi/shape-f9-renderer.cjs (reconcile) + lib/hmi/selector-dispatcher.cjs
+// -- this module mints NO new card renderer.
+// Canon Part 8: zero Brain/network tokens; pure composition + normalization.
+// CJS only. No em-dashes.
+
+const crypto = require('node:crypto');
+
+const { renderShapeF8 } = require('../hmi/shape-f8-renderer.cjs');
+const { renderShapeF9 } = require('../hmi/shape-f9-renderer.cjs');
+const selectorDispatcher = require('../hmi/selector-dispatcher.cjs');
+
+const DEFAULT_VERDICT = 'approve';
+
+// quick task 260903-h27 (T-h27-03): the normalized card is retained in the
+// in-process gate ledger until consumed or TTL-expired, and the caller
+// supplying evidence_node_ids is the model itself (the ONLY entity that can
+// ever know these ids -- see the plan's objective). An unbounded caller-
+// controlled list is therefore caller-controlled retained memory. This cap
+// bounds it.
+const MAX_EVIDENCE_NODE_IDS = 64;
+
+// -----------------------------------------------------------------------
+// SUPERSET_SCHEMA -- Mindrian's OWN card superset (descriptive, not a zod
+// validator: the MCP tool layer, lib/mcp/tools/gate.cjs, owns the zod input
+// schema for the gate_render tool call itself). Every renderer normalizes
+// its raw card input against this shape before rendering.
+// -----------------------------------------------------------------------
+const SUPERSET_SCHEMA = Object.freeze({
+  schema: 'mindrian.gate.superset.v1',
+  fields: Object.freeze({
+    gate_id: 'string (minted if absent)',
+    header: 'string | null',
+    kind: "string (e.g. 'binding' for the F.8 once-per-session card, 'general' default)",
+    ambiguous: 'boolean (only relevant to kind: binding)',
+    selectMode: "'single' | 'multi'",
+    options: Object.freeze({
+      id: 'string (derived from label if absent)',
+      label: 'string',
+      description: 'string | null',
+      rank: 'number | null',
+      preview: 'string | null',
+    }),
+    // quick task 260903-h27 (T2 gate-card schema half): carryable-only
+    // fields. Accepted input keys: subject_node_id / subjectNodeId (snake_case
+    // wins when both are present). Normalized output: subjectNodeId. Nothing
+    // in this task READS these fields -- they exist so the write half
+    // (claim-node creation + provenance edges) can consume an
+    // already-populated card.
+    subjectNodeId: "string | null (default null; accepted input: subject_node_id, falls back to subjectNodeId)",
+    // Accepted input keys: evidence_node_ids / evidenceNodeIds (snake_case
+    // wins). Normalized output: evidenceNodeIds. Non-empty-string entries
+    // only, de-duped first-wins, capped at MAX_EVIDENCE_NODE_IDS (64).
+    evidenceNodeIds: "string[] (default []; accepted input: evidence_node_ids, falls back to evidenceNodeIds; capped at " + MAX_EVIDENCE_NODE_IDS + ")",
+  }),
+});
+
+// -----------------------------------------------------------------------
+// pickRenderer -- the ladder detection. elicitation-declared > insideClaude
+// Code > headless-text.
+// -----------------------------------------------------------------------
+function pickRenderer(capabilities) {
+  const caps = (capabilities && typeof capabilities === 'object') ? capabilities : {};
+  if (caps.elicitation === true) return 'elicitation';
+  if (caps.claudeCode === true) return 'askuserquestion';
+  return 'text';
+}
+
+// -----------------------------------------------------------------------
+// Card normalization
+// -----------------------------------------------------------------------
+function _slug(s) {
+  return String(s).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-+|-+$)/g, '') || 'opt';
+}
+
+function _normalizeOption(raw, index) {
+  if (raw === null || raw === undefined) return null;
+  const obj = (typeof raw === 'string') ? { label: raw } : ((raw && typeof raw === 'object') ? raw : null);
+  if (!obj || typeof obj.label !== 'string' || obj.label.length === 0) return null;
+  const id = (typeof obj.id === 'string' && obj.id.length > 0) ? obj.id : (_slug(obj.label) + '-' + index);
+  return {
+    id: id,
+    label: obj.label,
+    description: (typeof obj.description === 'string' && obj.description.length > 0) ? obj.description : null,
+    rank: (typeof obj.rank === 'number' && Number.isFinite(obj.rank)) ? obj.rank : null,
+    preview: (typeof obj.preview === 'string' && obj.preview.length > 0) ? obj.preview : null,
+  };
+}
+
+/**
+ * _normalizeNodeIds(raw) -> a FRESH string[], never throws. Non-array input
+ * returns []; otherwise filters to non-empty strings, drops duplicates
+ * first-wins via a Set (mirrors the option de-dup loop above), and truncates
+ * to MAX_EVIDENCE_NODE_IDS.
+ */
+function _normalizeNodeIds(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  const seen = new Set();
+  for (const v of raw) {
+    if (typeof v !== 'string' || v.length === 0) continue;
+    if (seen.has(v)) continue;
+    seen.add(v);
+    out.push(v);
+    if (out.length >= MAX_EVIDENCE_NODE_IDS) break;
+  }
+  return out;
+}
+
+/**
+ * normalizeCard(raw) -> canonical superset card (SUPERSET_SCHEMA shape).
+ * Never throws. Missing gate_id is minted; duplicate option ids are dropped
+ * (first wins, mirrors shape-f8-renderer's own de-dup discipline).
+ */
+function normalizeCard(raw) {
+  const opts = (raw && typeof raw === 'object') ? raw : {};
+  const gateId = (typeof opts.gate_id === 'string' && opts.gate_id.length > 0)
+    ? opts.gate_id
+    : ('gate-' + crypto.randomBytes(8).toString('hex'));
+  const rawOptions = Array.isArray(opts.options) ? opts.options : [];
+  const options = [];
+  const seenIds = new Set();
+  for (let i = 0; i < rawOptions.length; i += 1) {
+    const n = _normalizeOption(rawOptions[i], i);
+    if (!n) continue;
+    if (seenIds.has(n.id)) continue;
+    seenIds.add(n.id);
+    options.push(n);
+  }
+  // quick task 260903-h27: BOTH casings are read deliberately, not defensive
+  // noise. Live precedent this task must not repeat: `select_mode` is
+  // emitted by two internal card builders (chain.cjs's
+  // _buildMaterialStepCard, sensors.cjs's framework_run halt card) and
+  // silently dropped because normalizeCard reads only `selectMode` -- see
+  // this module's own selectMode line above. subject_node_id/evidence_node_
+  // ids are the design's declared WIRE key (snake_case, the MCP tool-param
+  // convention), so it wins when both casings are present; the camelCase
+  // fallback covers an internal caller (e.g. a future card builder) that
+  // constructs the card object in JS-native camelCase directly.
+  const rawSubjectNodeId = (opts.subject_node_id !== undefined) ? opts.subject_node_id : opts.subjectNodeId;
+  const subjectNodeId = (typeof rawSubjectNodeId === 'string' && rawSubjectNodeId.length > 0) ? rawSubjectNodeId : null;
+  const rawEvidenceNodeIds = (opts.evidence_node_ids !== undefined) ? opts.evidence_node_ids : opts.evidenceNodeIds;
+  const evidenceNodeIds = _normalizeNodeIds(rawEvidenceNodeIds);
+
+  return {
+    gate_id: gateId,
+    header: (typeof opts.header === 'string' && opts.header.length > 0) ? opts.header : null,
+    kind: (typeof opts.kind === 'string' && opts.kind.length > 0) ? opts.kind : 'general',
+    ambiguous: opts.ambiguous === true,
+    selectMode: opts.selectMode === 'multi' ? 'multi' : 'single',
+    options: options,
+    subjectNodeId: subjectNodeId,
+    evidenceNodeIds: evidenceNodeIds,
+  };
+}
+
+/**
+ * normalizeGateAnswer(gateId, chosenIds, verdict) -> the ONE canonical
+ * gate_answer payload shape every rung normalizes to. This is the SPEC-4
+ * acceptance bar: whatever wire format captured the user's choice, the same
+ * chosen option id + verdict always produces byte-identical output here.
+ */
+function normalizeGateAnswer(gateId, chosenIds, verdict) {
+  return {
+    gate_id: gateId,
+    chosen: Array.isArray(chosenIds) ? chosenIds.slice() : [],
+    verdict: (typeof verdict === 'string' && verdict.length > 0) ? verdict : DEFAULT_VERDICT,
+  };
+}
+
+// -----------------------------------------------------------------------
+// D-04: F.8 binding-card once-per-session-on-ambiguity discipline. A
+// resolved/unambiguous context NEVER fires; an ambiguous context fires
+// exactly once per session (subsequent calls for the SAME session return no
+// card). In-process, single-use-per-session ledger -- mirrors the T-198-10
+// live-gate ledger in lib/mcp/tools/gate.cjs (same "mint once, consume once"
+// shape, different concern).
+// -----------------------------------------------------------------------
+const _firedBindingSessions = new Set();
+
+function shouldFireBindingCard(sessionId, ambiguous) {
+  if (ambiguous !== true) return false; // unambiguous: never fires
+  const key = (typeof sessionId === 'string' && sessionId.length > 0) ? sessionId : '__no_session__';
+  if (_firedBindingSessions.has(key)) return false; // already fired once this session
+  _firedBindingSessions.add(key);
+  return true;
+}
+
+function _resetBindingFiredForTest() {
+  _firedBindingSessions.clear();
+}
+
+// -----------------------------------------------------------------------
+// Rung (a): MCP elicitation. LOSSY -- per-option const (ids) + title (labels)
+// on both select modes, via the SDK's titled enum schemas; no descriptions.
+// -----------------------------------------------------------------------
+function buildElicitRequestedSchema(card) {
+  if (card.selectMode === 'multi') {
+    return {
+      type: 'object',
+      properties: {
+        choices: {
+          type: 'array',
+          title: card.header || 'Choose options',
+          items: {
+            anyOf: card.options.map((o) => ({ const: o.id, title: o.label })),
+          },
+        },
+      },
+      required: ['choices'],
+    };
+  }
+  return {
+    type: 'object',
+    properties: {
+      choice: {
+        type: 'string',
+        title: card.header || 'Choose an option',
+        oneOf: card.options.map((o) => ({ const: o.id, title: o.label })),
+      },
+    },
+    required: ['choice'],
+  };
+}
+
+function extractElicitChoice(result) {
+  if (!result || typeof result !== 'object') return null;
+  if (result.action !== 'accept') return null;
+  const content = result.content;
+  if (!content || typeof content !== 'object') return null;
+  if (Array.isArray(content.choices)) {
+    const out = content.choices.filter((c) => typeof c === 'string');
+    return out.length > 0 ? out : null;
+  }
+  if (typeof content.choice === 'string' && content.choice.length > 0) return [content.choice];
+  return null;
+}
+
+async function renderViaElicitation(card, ctx) {
+  const requestedSchema = buildElicitRequestedSchema(card);
+  const message = card.header || ('mindrianOS gate: ' + card.gate_id);
+  const rendered = { requestedSchema: requestedSchema, message: message };
+
+  const elicitFn = (ctx && typeof ctx.elicitInput === 'function') ? ctx.elicitInput : null;
+  let answer = null;
+  if (elicitFn) {
+    const result = await elicitFn({ message: message, requestedSchema: requestedSchema });
+    const chosenIds = extractElicitChoice(result);
+    if (chosenIds && chosenIds.length > 0) {
+      const verdict = (ctx && typeof ctx.verdictFor === 'function') ? ctx.verdictFor(chosenIds) : DEFAULT_VERDICT;
+      answer = normalizeGateAnswer(card.gate_id, chosenIds, verdict);
+    }
+  }
+  return { renderer: 'elicitation', rendered: rendered, answer: answer };
+}
+
+// -----------------------------------------------------------------------
+// Rung (b): canUseTool/AskUserQuestion thin adapter inside Claude Code.
+// Composes from the SHIPPED shape-f8-renderer.cjs toggle envelope (Canon
+// Part 7 reuse -- this module never reinvents a card renderer), enriched with
+// the FULL superset metadata (id/description/rank/preview) so the thin
+// adapter can construct the real native AskUserQuestion call at full
+// fidelity. The AskUserQuestion trailer imperative is appended through the
+// shipped selector-dispatcher SEED-020 single door.
+// -----------------------------------------------------------------------
+/**
+ * validateChosenAgainstCard(card, chosen) -> the server-side allow-list
+ * check every gate ratification path needs (ASVS V5 Input Validation).
+ * Phase 238 (GATE-01 G-2): until this phase, gate_answer's and chain_run's
+ * ratification paths had no value-domain check at all -- the zod schema on
+ * gate_answer's tool input validated only the SHAPE of `chosen`
+ * (z.array(z.string().min(1)).min(1)), never that a submitted value was
+ * actually among the minted card's own options. This is that check,
+ * lifted from the AskUserQuestion rung's own resolver (below) so 238-03
+ * (gate.cjs) and 238-04 (chain.cjs) can both call the SAME implementation
+ * rather than growing a second copy.
+ *
+ * Returns an array of resolved option ids when at least one submitted
+ * value matches an option id or an option label; returns null when
+ * nothing survives (null means REJECT). Guards defensively: a null or
+ * malformed card, a card with no options array, or a non-array chosen all
+ * return null rather than throwing, because both new call sites run
+ * inside MCP tool handlers where a throw becomes an opaque tool error.
+ */
+function validateChosenAgainstCard(card, chosen) {
+  if (!Array.isArray(chosen)) return null;
+  const options = (card && Array.isArray(card.options)) ? card.options : null;
+  if (!options) return null;
+  const byId = new Set(options.map((o) => o.id));
+  const byLabel = new Map(options.map((o) => [o.label, o.id]));
+  const out = [];
+  for (const c of chosen) {
+    if (typeof c !== 'string') continue;
+    if (byId.has(c)) { out.push(c); continue; }
+    if (byLabel.has(c)) { out.push(byLabel.get(c)); continue; }
+  }
+  return out.length > 0 ? out : null;
+}
+
+/**
+ * _resolveChosenIds -- thin caller kept for the AskUserQuestion rung's own
+ * existing contract (its guard on `picked` is not part of
+ * validateChosenAgainstCard's own signature). Behavior is byte-stable:
+ * this is the rung's only current caller and its tests must not move.
+ */
+function _resolveChosenIds(picked, card) {
+  if (!picked || !Array.isArray(picked.chosen)) return null;
+  return validateChosenAgainstCard(card, picked.chosen);
+}
+
+async function renderViaAskUserQuestion(card, ctx) {
+  const base = renderShapeF8({
+    options: card.options.map((o) => ({ label: o.label, confidence: null })),
+    header: card.header || undefined,
+  });
+  // Reuse stops at the envelope shape; the superset's extra fidelity
+  // (descriptions/ranks/previews, and the true single/multi mode -- F.8's own
+  // renderer always sets multiSelect:true) is folded on top, not reinvented.
+  base.contract.multiSelect = card.selectMode === 'multi';
+  base.contract.superset_options = card.options.map((o) => ({
+    id: o.id,
+    label: o.label,
+    description: o.description,
+    rank: o.rank,
+    preview: o.preview,
+  }));
+  selectorDispatcher.appendAskUserQuestionTrailer(base, base.contract.shape || 'F.8');
+
+  let answer = null;
+  const responder = (ctx && typeof ctx.simulateAskUserQuestion === 'function') ? ctx.simulateAskUserQuestion : null;
+  if (responder) {
+    const picked = await responder(base);
+    const chosenIds = _resolveChosenIds(picked, card);
+    if (chosenIds) {
+      const verdict = (picked && typeof picked.verdict === 'string')
+        ? picked.verdict
+        : ((ctx && typeof ctx.verdictFor === 'function') ? ctx.verdictFor(chosenIds) : DEFAULT_VERDICT);
+      answer = normalizeGateAnswer(card.gate_id, chosenIds, verdict);
+    }
+  }
+  return { renderer: 'askuserquestion', rendered: base, answer: answer };
+}
+
+// -----------------------------------------------------------------------
+// Rung (c): structured-text fallback for headless clients.
+// -----------------------------------------------------------------------
+function parseTextReply(text, card) {
+  if (typeof text !== 'string' || text.length === 0) return null;
+  const tokens = text.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+  const out = [];
+  for (const t of tokens) {
+    const idx = parseInt(t, 10);
+    if (Number.isInteger(idx) && String(idx) === t && idx >= 1 && idx <= card.options.length) {
+      out.push(card.options[idx - 1].id);
+      continue;
+    }
+    const byId = card.options.find((o) => o.id === t);
+    if (byId) { out.push(byId.id); continue; }
+  }
+  return out.length > 0 ? out : null;
+}
+
+async function renderViaText(card, ctx) {
+  const lines = card.options.map((o, i) => {
+    let line = (i + 1) + '. ' + o.label + ' [' + o.id + ']';
+    if (o.description) line += ' - ' + o.description;
+    return line;
+  });
+  const rendered = {
+    zones: {
+      header: card.header || '-- mindrianOS -- gate --',
+      body: lines.join('\n'),
+      signals: '',
+      footer: 'Reply with the option number or id' + (card.selectMode === 'multi' ? 's (comma-separated)' : '') + ' to answer.',
+    },
+    contract: {
+      shape: 'text',
+      keyboard: 'next-message',
+      multiSelect: card.selectMode === 'multi',
+      recommended: null,
+      freeTextOffered: false,
+      options: card.options.map((o) => o.id),
+    },
+  };
+
+  let answer = null;
+  const responder = (ctx && typeof ctx.simulateTextReply === 'function') ? ctx.simulateTextReply : null;
+  if (responder) {
+    const replyText = await responder(rendered);
+    const chosenIds = parseTextReply(replyText, card);
+    if (chosenIds) {
+      const verdict = (ctx && typeof ctx.verdictFor === 'function') ? ctx.verdictFor(chosenIds) : DEFAULT_VERDICT;
+      answer = normalizeGateAnswer(card.gate_id, chosenIds, verdict);
+    }
+  }
+  return { renderer: 'text', rendered: rendered, answer: answer };
+}
+
+// -----------------------------------------------------------------------
+// renderGate -- the single entry point. Dispatches by pickRenderer(ctx.
+// capabilities); every rung normalizes its answer to the SAME gate_answer
+// shape (SPEC-4 acceptance). Applies the D-04 F.8 binding-card discipline
+// BEFORE dispatch: a suppressed binding card never reaches a renderer.
+// -----------------------------------------------------------------------
+async function renderGate(card, ctx) {
+  const normalized = normalizeCard(card);
+  const context = (ctx && typeof ctx === 'object') ? ctx : {};
+
+  if (normalized.kind === 'binding' && !shouldFireBindingCard(context.sessionId, normalized.ambiguous)) {
+    return { renderer: 'none', card: normalized, rendered: null, answer: null, suppressed: true };
+  }
+
+  const renderer = pickRenderer(context.capabilities);
+  let result;
+  if (renderer === 'elicitation') {
+    result = await renderViaElicitation(normalized, context);
+  } else if (renderer === 'askuserquestion') {
+    result = await renderViaAskUserQuestion(normalized, context);
+  } else {
+    result = await renderViaText(normalized, context);
+  }
+  return Object.assign({ card: normalized, suppressed: false }, result);
+}
+
+module.exports = {
+  SUPERSET_SCHEMA: SUPERSET_SCHEMA,
+  pickRenderer: pickRenderer,
+  renderGate: renderGate,
+  normalizeCard: normalizeCard,
+  // normalizeGateAnswer is the shared normalization every rung (and the
+  // gate_answer MCP tool, lib/mcp/tools/gate.cjs) funnels through -- the
+  // { gate_id, chosen, verdict } shape gate_answer ratifies.
+  normalizeGateAnswer: normalizeGateAnswer,
+  // validateChosenAgainstCard is the public contract 238-03 (gate.cjs) and
+  // 238-04 (chain.cjs) call to reject an out-of-card gate_answer before
+  // ratification (GATE-01 G-2).
+  validateChosenAgainstCard: validateChosenAgainstCard,
+  shouldFireBindingCard: shouldFireBindingCard,
+  _resetBindingFiredForTest: _resetBindingFiredForTest,
+  _internal: {
+    renderViaElicitation: renderViaElicitation,
+    renderViaAskUserQuestion: renderViaAskUserQuestion,
+    renderViaText: renderViaText,
+    buildElicitRequestedSchema: buildElicitRequestedSchema,
+    extractElicitChoice: extractElicitChoice,
+    parseTextReply: parseTextReply,
+  },
+};

package/lib/mcp/hook-adapter-audit.cjs

@@ -0,0 +1,199 @@
+'use strict';
+// Phase 198-08 (SPEC-5, D-06) -- hook-adapter-audit: the measured
+// "adapter-only" budget for MIGRATED hook scripts (enumerated from
+// hooks/hooks.json's _mcpFirst198Migrated marker, Task 1). Two checks:
+//   1. IMPORT AUDIT -- a migrated hook script's own require() calls (after
+//      comment-stripping, so a header/doc comment naming lib/core does not
+//      self-invalidate the gate) never reach into lib/core, lib/workflow, or
+//      lib/memory (the business-module directories D-06 forbids from a hook
+//      script's own text -- lib/mcp/* adapter plumbing, e.g. adapter-
+//      client.cjs's own daemon-lifecycle.cjs require, is allowed; the audit
+//      targets hook scripts, not lib/mcp/adapter-client.cjs itself).
+//   2. LINE-COUNT BUDGET -- each migrated script stays under a measured
+//      per-file ceiling (baseline + a small margin), so a future change
+//      cannot silently re-fatten a thin adapter back into a business-logic
+//      script without this test failing.
+//
+// Scope: ONLY the surfaces hooks.json's own migration marker names (D-05:
+// statusline + SessionStart THIS plan; Stop-gate scripts are Plan 09's
+// concern and are never enumerated here -- enumeration comes from the
+// marker, not a hand-maintained list, so Plan 09 adding its own marker
+// entries later does not require touching this file).
+//
+// No em-dashes. CJS only.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const HOOKS_JSON_PATH = path.join(REPO_ROOT, 'hooks', 'hooks.json');
+
+// Measured baseline + a small margin (D-06: "set the budget from the thin
+// post-migration line counts with a small margin; record the exact numbers
+// in the test and the SUMMARY"). This is the single source of truth for
+// all three numbers; 198-08-SUMMARY.md and 198-09-SUMMARY.md cite these same
+// figures.
+//
+// (measured via src.split('\n').length, the same measure lineCountBudget()
+// uses below -- one more than a bare `wc -l` on a file with a trailing
+// newline, since split() counts the trailing empty segment)
+//
+//   scripts/statusline-mos-dispatch:      128 measured lines -> 150 budget (+22 margin)
+//   scripts/sessionstart-coordinator.cjs: 250 measured lines -> 280 budget (+30 margin;
+//     the flag-OFF legacy runAll()/11-contributor dispatch table stays inline
+//     BY DESIGN for byte-identical legacy behavior -- SPEC-7 -- so this
+//     budget is intentionally larger than statusline's; the NEW flag-ON
+//     runThinAdapter() path itself is under 40 lines)
+//   scripts/on-stop:                      547 measured lines -> 570 budget (+23 margin;
+//     Phase 198-09, D-05 final wave. The flag-OFF legacy body -- the full
+//     Phase 84/88/88.1 close-out orchestration -- stays inline BY DESIGN for
+//     byte-identical legacy behavior (SPEC-7); this generic whole-file line
+//     count is therefore intentionally as large as the pre-198-09 file plus
+//     the new flag-ON adapter branch alone (~80 lines). This budget is a
+//     secondary signal for on-stop -- the REAL D-06 protection for this BASH
+//     surface is tests/test-198-adapter-budget.test.cjs's own bespoke
+//     flag-ON-branch text audit (a `require(...)`-shaped import audit does
+//     not apply to bash; see that test file's own header comment).
+const LINE_BUDGETS = {
+  'scripts/statusline-mos-dispatch': 150,
+  'scripts/sessionstart-coordinator.cjs': 280,
+  'scripts/on-stop': 570,
+};
+
+// The SAME pattern shape Task 1's own acceptance criteria grep used
+// (`require(.*lib/core|require(.*lib/workflow|require(.*lib/memory`), so the
+// audit module and the plan's own literal acceptance check agree on what
+// counts as a forbidden business import -- including a require() reached via
+// path.join(...) rather than only a directly-quoted relative path.
+const FORBIDDEN_IMPORT_PATTERN = /require\(.*lib\/core|require\(.*lib\/workflow|require\(.*lib\/memory/;
+
+/**
+ * migratedSurfaces() -- read hooks.json's _mcpFirst198Migrated.surfaces
+ * marker (Task 1) and return the list of migrated script paths (repo-root
+ * relative). Never throws; a missing/malformed marker returns [].
+ *
+ * @returns {string[]}
+ */
+function migratedSurfaces() {
+  try {
+    const raw = fs.readFileSync(HOOKS_JSON_PATH, 'utf8');
+    const parsed = JSON.parse(raw);
+    const marker = parsed && parsed._mcpFirst198Migrated;
+    const surfaces = marker && Array.isArray(marker.surfaces) ? marker.surfaces : [];
+    return surfaces
+      .map((s) => s && s.script)
+      .filter((s) => typeof s === 'string' && s.length > 0);
+  } catch (_e) {
+    return [];
+  }
+}
+
+/**
+ * stripComments(src) -- drop any line whose first non-whitespace characters
+ * are `#` (bash) or `//` (js), so a header/doc comment naming lib/core does
+ * not self-invalidate the import-audit gate. Does not attempt to strip
+ * inline trailing comments or block comments -- the migrated scripts in
+ * scope never wrap a require() call inside one, so a line-anchored strip is
+ * sufficient and avoids needing a full parser.
+ *
+ * @param {string} src
+ * @returns {string}
+ */
+function stripComments(src) {
+  return src
+    .split('\n')
+    .filter((line) => {
+      const trimmed = line.trim();
+      return !(trimmed.startsWith('#') || trimmed.startsWith('//') || trimmed.startsWith('*'));
+    })
+    .join('\n');
+}
+
+/**
+ * auditHookScripts(opts) -- run the import audit over every migrated
+ * surface. Returns a per-file result plus an overall pass boolean. Never
+ * throws.
+ *
+ * @param {{surfaces?: string[], root?: string}} [opts] - override the
+ *   enumerated surfaces and/or the root dir scripts resolve against (test
+ *   seam -- lets a test point at a hermetic fixture copy without touching
+ *   the real tracked file)
+ * @returns {{pass: boolean, files: Array<{script: string, pass: boolean, violation: string|null}>}}
+ */
+function auditHookScripts(opts) {
+  const options = opts || {};
+  const root = options.root || REPO_ROOT;
+  const surfaces = options.surfaces || migratedSurfaces();
+  const files = surfaces.map((script) => {
+    const abs = path.isAbsolute(script) ? script : path.join(root, script);
+    let src;
+    try {
+      src = fs.readFileSync(abs, 'utf8');
+    } catch (e) {
+      return { script, pass: false, violation: 'file not readable: ' + (e && e.message) };
+    }
+    const stripped = stripComments(src);
+    const match = stripped.match(FORBIDDEN_IMPORT_PATTERN);
+    if (match) {
+      return { script, pass: false, violation: 'forbidden business import: ' + match[0] };
+    }
+    return { script, pass: true, violation: null };
+  });
+  return { pass: files.every((f) => f.pass), files };
+}
+
+/**
+ * lineCountBudget(opts) -- run the line-count budget check over every
+ * migrated surface, against the measured LINE_BUDGETS ceiling. A surface
+ * with no recorded budget fails closed (never silently unbudgeted).
+ *
+ * @param {{surfaces?: string[], root?: string}} [opts]
+ * @returns {{pass: boolean, files: Array<{script: string, lines: number, budget: number|null, pass: boolean}>}}
+ */
+function lineCountBudget(opts) {
+  const options = opts || {};
+  const root = options.root || REPO_ROOT;
+  const surfaces = options.surfaces || migratedSurfaces();
+  const files = surfaces.map((script) => {
+    const abs = path.isAbsolute(script) ? script : path.join(root, script);
+    let lines;
+    try {
+      const src = fs.readFileSync(abs, 'utf8');
+      lines = src.split('\n').length;
+    } catch (_e) {
+      lines = Infinity;
+    }
+    const budget = Object.prototype.hasOwnProperty.call(LINE_BUDGETS, script)
+      ? LINE_BUDGETS[script]
+      : null;
+    const pass = typeof budget === 'number' && lines <= budget;
+    return { script, lines, budget, pass };
+  });
+  return { pass: files.every((f) => f.pass), files };
+}
+
+/**
+ * checkAdapterBudget(opts) -- the combined D-06 gate: import audit AND
+ * line-count budget must both pass for every migrated surface.
+ *
+ * @param {{surfaces?: string[]}} [opts]
+ * @returns {{pass: boolean, importAudit: object, lineBudget: object}}
+ */
+function checkAdapterBudget(opts) {
+  const importAudit = auditHookScripts(opts);
+  const lineBudget = lineCountBudget(opts);
+  return {
+    pass: importAudit.pass && lineBudget.pass,
+    importAudit,
+    lineBudget,
+  };
+}
+
+module.exports = {
+  migratedSurfaces,
+  auditHookScripts,
+  lineCountBudget,
+  checkAdapterBudget,
+  LINE_BUDGETS,
+  FORBIDDEN_IMPORT_PATTERN,
+};