@mindrian_os/cli 2.0.0-beta.29 → 2.0.0-beta.31

package/lib/hmi/f1-pick-capture-cli.cjs

@@ -0,0 +1,131 @@
+'use strict';
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 159-01 Task 3 -- captureCliPick: the CLI F.1 pick-capture adapter (HOW-3).
+ * ================================================================================
+ * The Tri-Polar split (DCW-07): the consumer (lib/workflow/f1-pick-consumer.cjs)
+ * is the SHARED CORE; each surface supplies a thin capture adapter that turns the
+ * surface's turn input into the {pick} shape consumeF1Pick accepts. This is the
+ * CLI adapter: it maps an AskUserQuestion Shape F.1 answer into {pick, sentence?}.
+ * Desktop/Cowork adapters are documented seam contracts only (live capture
+ * deferred); CAPTURE_ADAPTER_CONTRACT names the signature they implement.
+ *
+ * On CLI the F.1 dial renders via the AskUserQuestion trailer (shape-f1-renderer
+ * exposes contract.verbs -- the option labels). The navigator's pick arrives as
+ * the next user turn's selected option + chosen outcome. captureCliPick:
+ *   - maps the selected option to the matching verb in priorPayload.verbs
+ *     DETERMINISTICALLY (HOW-2: the answer is a known enum from the rendered card,
+ *     NOT free prose); returns {pick:{verb, outcome}}.
+ *   - carries the raw answer text ONLY as the optional `sentence` field, destined
+ *     for the FIX-05 LOCAL lane (HOW-5 / Part 8): consumeF1Pick forwards it to
+ *     closeOffer({sentence}) where it is classified to a scalar at the write seam
+ *     and NEVER stored in a row body. The raw text is NEVER returned as a pick
+ *     value, NEVER an edge body, NEVER a Brain packet.
+ *
+ * Canon binding:
+ *   Part 7: the adapter is thin glue; it does NO persistence (it produces the
+ *           {pick} the shared-core consumer routes).
+ *   Part 8: the navigator's pick text rides the sentence (LOCAL lane) only; the
+ *           pick verb/outcome are deterministic enums. The Part 8 SECRETREASON159
+ *           tripwire in the suite proves a seeded marker never lands in a row.
+ *
+ * Framework: pure CJS, zero new dependencies (Phase 87 invariant). No em-dashes.
+ * No emoji. No Brain call.
+ *
+ * License: BSL 1.1.
+ */
+
+// The Free-Text escape (mirrors offer-closer FREE_TEXT). The escape routes to the
+// miss path and never carries a reach_id.
+const FREE_TEXT = 'Free-Text';
+
+// The four canonical dial outcomes. Mirrored locally to keep the adapter
+// decoupled from the consumer (no require cycle); the consumer is the gate of
+// record.
+const OUTCOMES = ['accept', 'defer', 'reject', 'Free-Text'];
+
+function _normalizeOutcome(raw) {
+  if (typeof raw !== 'string' || raw.length === 0) return null;
+  if (raw === 'Free-Text' || raw === 'free-text') return 'Free-Text';
+  const lower = raw.toLowerCase();
+  if (lower === 'accept' || lower === 'approve') return 'accept';
+  if (lower === 'defer') return 'defer';
+  if (lower === 'reject') return 'reject';
+  return null;
+}
+
+// Deterministic option -> verb match against the rendered card's verbs. The CLI
+// AskUserQuestion answer is a known enum (the option label IS a verb in
+// priorPayload.verbs), so this is a membership match, NOT fuzzy NLP.
+function _matchVerb(selectedOption, verbs) {
+  if (typeof selectedOption !== 'string' || selectedOption.length === 0) return null;
+  if (!Array.isArray(verbs)) return null;
+  return verbs.indexOf(selectedOption) !== -1 ? selectedOption : null;
+}
+
+// ---------------------------------------------------------------------------
+// captureCliPick(answer, priorPayload) -> { pick: { verb, outcome }, sentence? }
+//
+// answer: the AskUserQuestion F.1 answer
+//         { selectedOption: <verb label>, outcome?: <decision keyword>,
+//           text?: <raw navigator text> }.
+// priorPayload: the prior turn's f1_closer_payload ({ verbs:[...], ... }).
+//
+// Returns { pick: { verb, outcome } } where verb is the matched enum from the
+// rendered card and outcome is the chosen decision keyword. The raw answer text
+// rides the optional `sentence` (the FIX-05 LOCAL lane) ONLY. When the answer
+// does not match a rendered verb, returns { pick: { verb: null, outcome } } so
+// the shared-core consumer no-ops deterministically (DCW-04).
+// ---------------------------------------------------------------------------
+function captureCliPick(answer, priorPayload) {
+  const a = (answer && typeof answer === 'object') ? answer : {};
+  const payload = (priorPayload && typeof priorPayload === 'object') ? priorPayload : {};
+  const verbs = Array.isArray(payload.verbs) ? payload.verbs : [];
+
+  // The selected option label is the verb (or the Free-Text escape).
+  const matched = _matchVerb(a.selectedOption, verbs);
+
+  // The outcome is the navigator's chosen decision keyword. When the answer
+  // carries no explicit outcome and the matched verb is the escape, the outcome
+  // is Free-Text; otherwise it defers to the consumer's accept default.
+  let outcome = _normalizeOutcome(a.outcome);
+  if (matched === FREE_TEXT) {
+    outcome = FREE_TEXT;
+  }
+  if (outcome !== null && OUTCOMES.indexOf(outcome) === -1) {
+    outcome = null;
+  }
+
+  const pick = { verb: matched, outcome: outcome };
+
+  const out = { pick: pick };
+  // The raw answer text rides the LOCAL lane ONLY (FIX-05 / Part 8). Never a pick
+  // value, never an edge body. Carried as the optional sentence for the consumer
+  // to forward to closeOffer({sentence}).
+  if (typeof a.text === 'string' && a.text.length > 0) {
+    out.sentence = a.text;
+  }
+  return out;
+}
+
+// The Desktop/Cowork capture-adapter seam contract (DCW-07). Desktop/Cowork
+// LIVE conversational capture is OUT of this phase; this constant names the
+// signature + expected shape those adapters implement so the Wave-3 seam doc can
+// reference it. A surface adapter MUST return the same {pick:{verb, outcome},
+// sentence?} shape captureCliPick returns, with verb a deterministic enum from
+// the rendered card and the raw navigator text confined to the LOCAL sentence
+// lane (Part 8).
+const CAPTURE_ADAPTER_CONTRACT = Object.freeze({
+  signature: 'captureSurfacePick(surfaceAnswer, priorPayload) -> { pick: { verb, outcome }, sentence? }',
+  returns: '{ pick: { verb: <enum from priorPayload.verbs | null>, outcome: accept|defer|reject|Free-Text|null }, sentence?: <raw navigator text, LOCAL lane only> }',
+  surfaces: Object.freeze(['cli (live, this module)', 'desktop (seam only, deferred)', 'cowork (seam only, deferred)']),
+  part8_note: 'The raw navigator text rides ONLY the optional sentence (FIX-05 LOCAL lane). It is NEVER a pick value, an edge body, or a Brain packet. consumeF1Pick forwards it to closeOffer({sentence}) where it is classified to a scalar at the write seam and never stored.',
+  consumer: 'lib/workflow/f1-pick-consumer.cjs::consumeF1Pick({ priorPayload, pick, roomState })',
+});
+
+module.exports = {
+  captureCliPick: captureCliPick,
+  CAPTURE_ADAPTER_CONTRACT: CAPTURE_ADAPTER_CONTRACT,
+  FREE_TEXT: FREE_TEXT,
+};

package/lib/hmi/f3-depth-capture-cli.cjs

@@ -0,0 +1,77 @@
+'use strict';
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 188-04 (SFS-08) -- captureCliDepthPick: the CLI F.3 depth-pick capture
+ * adapter. Clones the f1-pick-capture-cli.cjs STRUCTURE (a thin surface adapter
+ * that maps a rendered-card answer into the {pick} shape the consumer accepts)
+ * MINUS the two-channel outcome/reach machinery -- F.3 is a single closed depth
+ * scalar, not a verb+outcome dial.
+ *
+ * Closed-vocab carve-out (research pitfall #4): F.3 has NO recommended marker and
+ * NO Free-Text. The adapter maps the selected option to one of the closed depth
+ * values by DETERMINISTIC MEMBERSHIP (clone of _matchVerb), NOT fuzzy NLP. An
+ * unknown answer yields { depth: null } so the consumer no-ops (T-188-04-01).
+ *
+ * Part 8: the navigator's raw answer text rides the optional `sentence` LOCAL
+ * lane ONLY. It is NEVER the pick value, an edge body, or a Brain packet.
+ *
+ * Pure CJS, node built-ins only, zero deps (Phase 87 invariant). No em-dashes.
+ *
+ * API: captureCliDepthPick(answer) -> { depth, sentence? }
+ */
+
+// The closed F.3 axis (renderer F3_OPTIONS). 'Back' is the control return: it
+// carries no depth and is surfaced as a { back:true } signal (no state write).
+const DEPTH_VALUES = ['Shallow', 'Medium', 'Deep', 'Extreme'];
+const BACK = 'Back';
+
+// Deterministic membership match against the closed depth axis (clone of the F.1
+// adapter's _matchVerb). The AskUserQuestion answer is a known enum from the
+// rendered F.3 card, so this is a membership match, NOT fuzzy NLP.
+function _matchDepth(selected) {
+  if (typeof selected !== 'string' || selected.length === 0) return null;
+  return DEPTH_VALUES.indexOf(selected) !== -1 ? selected : null;
+}
+
+// ---------------------------------------------------------------------------
+// captureCliDepthPick(answer) -> { depth, sentence?, back? }
+//
+// answer: the AskUserQuestion F.3 answer. Either a bare option label string
+//         ('Deep') or an object { answer|selectedOption: <label>, text?: <raw> }.
+//
+// Returns { depth } where depth is the matched closed value, or { depth: null }
+// on an unknown pick (deterministic no-op downstream). 'Back' returns
+// { depth: null, back: true } (return to previous shape, no state write). The
+// raw answer text rides the optional `sentence` LOCAL lane ONLY (Part 8).
+// ---------------------------------------------------------------------------
+function captureCliDepthPick(answer) {
+  let selected = null;
+  let rawText = null;
+  if (typeof answer === 'string') {
+    selected = answer;
+  } else if (answer && typeof answer === 'object') {
+    selected = (typeof answer.answer === 'string' && answer.answer.length > 0)
+      ? answer.answer
+      : (typeof answer.selectedOption === 'string' ? answer.selectedOption : null);
+    if (typeof answer.text === 'string' && answer.text.length > 0) rawText = answer.text;
+  }
+
+  if (selected === BACK) {
+    const backOut = { depth: null, back: true };
+    if (rawText) backOut.sentence = rawText;
+    return backOut;
+  }
+
+  const depth = _matchDepth(selected);
+  const out = { depth: depth };
+  // Part 8: raw navigator text on the LOCAL sentence lane ONLY.
+  if (rawText) out.sentence = rawText;
+  return out;
+}
+
+module.exports = {
+  captureCliDepthPick: captureCliDepthPick,
+  DEPTH_VALUES: DEPTH_VALUES.slice(),
+  BACK: BACK,
+};

package/lib/hmi/f4-scope-capture-cli.cjs

@@ -0,0 +1,86 @@
+'use strict';
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 188-04 (SFS-09) -- captureCliScopePick: the CLI F.4 scope-pick capture
+ * adapter. Clones the F.3 depth adapter (a thin surface adapter mapping a
+ * rendered-card answer into the {pick} shape the consumer accepts). F.4 is a
+ * progressive scope LADDER, not a single scalar: each rung ADDS to the prior
+ * accumulated scope (the consumer + state module own the accumulation; this
+ * adapter only maps one pick).
+ *
+ * Closed-vocab carve-out (research pitfall #4): F.4 has NO recommended marker and
+ * NO Free-Text. The adapter maps the selected option to a closed ladder rung by
+ * DETERMINISTIC MEMBERSHIP, NOT fuzzy NLP. An unknown answer yields
+ * { scope: null } so the consumer no-ops (T-188-04-01).
+ *
+ * Part 8: the navigator's raw answer text rides the optional `sentence` LOCAL
+ * lane ONLY. It is NEVER the pick value, an edge body, or a Brain packet.
+ *
+ * Pure CJS, node built-ins only, zero deps (Phase 87 invariant). No em-dashes.
+ *
+ * API: captureCliScopePick(answer) -> { scope, sentence?, terminal?, back? }
+ */
+
+// The closed F.4 progressive ladder rungs (accumulating).
+const SCOPE_RUNGS = ['Key insights', '+contradictions', '+actions'];
+// The terminal option: hand the accumulated scope to synthesis (not a rung).
+const CREATE_DRAFT = 'Create artifact draft';
+const BACK = 'Back';
+
+// Deterministic membership match against the closed ladder (clone of the F.3
+// adapter's _matchDepth). The answer is a known enum from the rendered F.4 card.
+function _matchRung(selected) {
+  if (typeof selected !== 'string' || selected.length === 0) return null;
+  return SCOPE_RUNGS.indexOf(selected) !== -1 ? selected : null;
+}
+
+// ---------------------------------------------------------------------------
+// captureCliScopePick(answer) -> { scope, sentence?, terminal?, back? }
+//
+// answer: the AskUserQuestion F.4 answer. Either a bare option label string
+//         ('Key insights') or an object
+//         { answer|selectedOption: <label>, text?: <raw> }.
+//
+// Returns { scope } where scope is the matched closed rung, or { scope: null }
+// on an unknown pick (deterministic no-op downstream). 'Create artifact draft'
+// returns { scope: null, terminal: true } (hand the accumulated scope to
+// synthesis). 'Back' returns { scope: null, back: true } (no state write). The
+// raw answer text rides the optional `sentence` LOCAL lane ONLY (Part 8).
+// ---------------------------------------------------------------------------
+function captureCliScopePick(answer) {
+  let selected = null;
+  let rawText = null;
+  if (typeof answer === 'string') {
+    selected = answer;
+  } else if (answer && typeof answer === 'object') {
+    selected = (typeof answer.answer === 'string' && answer.answer.length > 0)
+      ? answer.answer
+      : (typeof answer.selectedOption === 'string' ? answer.selectedOption : null);
+    if (typeof answer.text === 'string' && answer.text.length > 0) rawText = answer.text;
+  }
+
+  if (selected === BACK) {
+    const backOut = { scope: null, back: true };
+    if (rawText) backOut.sentence = rawText;
+    return backOut;
+  }
+  if (selected === CREATE_DRAFT) {
+    const draftOut = { scope: null, terminal: true };
+    if (rawText) draftOut.sentence = rawText;
+    return draftOut;
+  }
+
+  const rung = _matchRung(selected);
+  const out = { scope: rung };
+  // Part 8: raw navigator text on the LOCAL sentence lane ONLY.
+  if (rawText) out.sentence = rawText;
+  return out;
+}
+
+module.exports = {
+  captureCliScopePick: captureCliScopePick,
+  SCOPE_RUNGS: SCOPE_RUNGS.slice(),
+  CREATE_DRAFT: CREATE_DRAFT,
+  BACK: BACK,
+};

package/lib/hmi/f8-action-capture-cli.cjs

@@ -0,0 +1,145 @@
+'use strict';
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 188-06 -- captureCliActionSet: the CLI F.8 array-capture adapter (SFS-02).
+ * ================================================================================
+ * The Tri-Polar split (DCW-07, inherited from f1-pick-capture-cli.cjs): the fan-out
+ * consumer (lib/workflow/f8-fanout-consumer.cjs) is the SHARED CORE; each surface
+ * supplies a thin capture adapter that turns the surface's turn input into the
+ * {verb, outcome} picks the consumer accepts. F.1 captures ONE pick; F.8 captures
+ * an ARRAY -- the navigator toggled a SET on and confirmed ONCE.
+ *
+ * This is the CLI adapter. The AskUserQuestion F.8 answer carries
+ * `selectedOptions[]` (the CONFIRMED toggle set; a pre-checked-but-unconfirmed
+ * toggle is NOT a selection until confirm). captureCliActionSet:
+ *   - maps EACH selected option to its matching verb in priorPayload.verbs
+ *     DETERMINISTICALLY (reuse _matchVerb membership match, NOT fuzzy NLP);
+ *   - reuses the OUTCOMES enum + _normalizeOutcome (NO parallel enum); a bare
+ *     toggle defaults to `accept` (toggling an action ON = accept it), while a
+ *     per-element outcome (accept/defer/reject/Free-Text) is honored so the
+ *     two-channel split (outcome keyword vs reach verb) survives per element;
+ *   - carries the raw navigator text on the optional `sentence` LOCAL lane per
+ *     element ONLY (Part 8) -- never a pick value, an edge body, or a Brain packet.
+ *
+ * An unknown / unmatched option degrades to { verb: null, outcome } so the
+ * fan-out consumer no-ops that item deterministically (never a false match).
+ *
+ * Framework: pure CJS, zero new dependencies (Phase 87 invariant). No em-dashes.
+ * No emoji. No Brain call.
+ *
+ * License: BSL 1.1.
+ */
+
+const FREE_TEXT = 'Free-Text';
+
+// The four canonical dial outcomes. Mirrored locally to keep the adapter decoupled
+// from the consumer (no require cycle); the consumer is the gate of record. This is
+// the SAME enum f1-pick-capture-cli.cjs reuses -- NOT a parallel one.
+const OUTCOMES = ['accept', 'defer', 'reject', 'Free-Text'];
+
+function _normalizeOutcome(raw) {
+  if (typeof raw !== 'string' || raw.length === 0) return null;
+  if (raw === 'Free-Text' || raw === 'free-text') return 'Free-Text';
+  const lower = raw.toLowerCase();
+  if (lower === 'accept' || lower === 'approve') return 'accept';
+  if (lower === 'defer') return 'defer';
+  if (lower === 'reject') return 'reject';
+  return null;
+}
+
+// Deterministic option -> verb match against the rendered card's verbs. The CLI
+// AskUserQuestion answer is a known enum (the toggle label IS a verb in
+// priorPayload.verbs), so this is a membership match, NOT fuzzy NLP.
+function _matchVerb(selectedOption, verbs) {
+  if (typeof selectedOption !== 'string' || selectedOption.length === 0) return null;
+  if (!Array.isArray(verbs)) return null;
+  return verbs.indexOf(selectedOption) !== -1 ? selectedOption : null;
+}
+
+// Resolve a single selectedOptions[] element into { label, outcome, text }. The
+// element is either a bare label string (a toggled-on action, default accept) or
+// an object { label|selectedOption, outcome?, text? } carrying a per-element
+// outcome + optional raw navigator text.
+function _resolveElement(el) {
+  if (typeof el === 'string') {
+    return { label: el, outcome: null, text: null };
+  }
+  if (el && typeof el === 'object') {
+    const label = (typeof el.label === 'string' && el.label.length > 0)
+      ? el.label
+      : ((typeof el.selectedOption === 'string' && el.selectedOption.length > 0) ? el.selectedOption : null);
+    const outcome = _normalizeOutcome(el.outcome);
+    const text = (typeof el.text === 'string' && el.text.length > 0) ? el.text : null;
+    return { label: label, outcome: outcome, text: text };
+  }
+  return { label: null, outcome: null, text: null };
+}
+
+// ---------------------------------------------------------------------------
+// captureCliActionSet(answer, priorPayload) -> [ { verb, outcome, sentence? }, ... ]
+//
+// answer: the AskUserQuestion F.8 answer
+//         { selectedOptions: [ <verb label> | { label, outcome?, text? } ] }.
+// priorPayload: the prior turn's F.8 closer payload ({ verbs:[...], ... }).
+//
+// Returns an ARRAY of picks, one per CONFIRMED toggle, each { verb, outcome }
+// where verb is the matched enum from the rendered card (or null when unmatched,
+// so the consumer no-ops that item) and outcome is the per-element decision
+// keyword (default accept). The raw text rides the optional `sentence` LOCAL lane
+// per element ONLY. A non-array / empty answer yields [].
+// ---------------------------------------------------------------------------
+function captureCliActionSet(answer, priorPayload) {
+  const a = (answer && typeof answer === 'object') ? answer : {};
+  const payload = (priorPayload && typeof priorPayload === 'object') ? priorPayload : {};
+  const verbs = Array.isArray(payload.verbs) ? payload.verbs : [];
+  const selected = Array.isArray(a.selectedOptions) ? a.selectedOptions : [];
+
+  const picks = [];
+  for (const el of selected) {
+    const resolved = _resolveElement(el);
+    const matched = _matchVerb(resolved.label, verbs);
+
+    // Per-element outcome. The Free-Text escape is always its own outcome; a bare
+    // confirmed toggle with no explicit outcome is an accept (toggled ON = accept).
+    let outcome = resolved.outcome;
+    if (matched === FREE_TEXT) {
+      outcome = FREE_TEXT;
+    } else if (outcome === null) {
+      outcome = 'accept';
+    }
+    if (outcome !== null && OUTCOMES.indexOf(outcome) === -1) {
+      outcome = null;
+    }
+
+    const pick = { verb: matched, outcome: outcome };
+    // The raw navigator text rides the LOCAL lane ONLY (Part 8). Never a pick
+    // value, never an edge body, never a Brain packet.
+    if (resolved.text) {
+      pick.sentence = resolved.text;
+    }
+    picks.push(pick);
+  }
+  return picks;
+}
+
+// The Desktop/Cowork capture-adapter seam contract (DCW-07). Desktop/Cowork LIVE
+// conversational multi-select capture is OUT of this phase; this constant names the
+// signature + expected ARRAY shape those adapters implement so a later seam doc can
+// reference it. A surface adapter MUST return the same [{verb, outcome}, sentence?]
+// array captureCliActionSet returns, with verb a deterministic enum from the
+// rendered card and any raw navigator text confined to the LOCAL sentence lane.
+const CAPTURE_ADAPTER_CONTRACT = Object.freeze({
+  signature: 'captureSurfaceActionSet(surfaceAnswer, priorPayload) -> [ { verb, outcome }, sentence? ]',
+  returns: '[ { verb: <enum from priorPayload.verbs | null>, outcome: accept|defer|reject|Free-Text|null, sentence?: <raw navigator text, LOCAL lane only> }, ... ]',
+  surfaces: Object.freeze(['cli (live, this module)', 'desktop (seam only, deferred)', 'cowork (seam only, deferred)']),
+  part8_note: 'The raw navigator text rides ONLY the optional per-element sentence (LOCAL lane). It is NEVER a pick value, an edge body, or a Brain packet. The consumer forwards it to closeOffer({sentence}) where it is classified to a scalar at the write seam and never stored.',
+  consumer: 'lib/workflow/f8-fanout-consumer.cjs::consumeF8Fanout({ priorPayload, picks, roomState })',
+});
+
+module.exports = {
+  captureCliActionSet: captureCliActionSet,
+  CAPTURE_ADAPTER_CONTRACT: CAPTURE_ADAPTER_CONTRACT,
+  OUTCOMES: OUTCOMES.slice(),
+  FREE_TEXT: FREE_TEXT,
+};

package/lib/hmi/f8-capture.test.cjs

@@ -0,0 +1,77 @@
+'use strict';
+/*
+ * Phase 188-06 -- F.8 array-capture adapter behavior test (SFS-02).
+ * =========================================================================
+ * The CONTRACT for lib/hmi/f8-action-capture-cli.cjs, referenced by
+ * tests/run-all-188.sh (the "F.8 capture (array of N toggles)" leg). Fails
+ * LOUDLY on module-not-found -- never a silent skip.
+ *
+ * What the F.8 capture is: F.1 maps ONE AskUserQuestion answer -> ONE {verb,
+ * outcome} pick; F.8 maps the CONFIRMED `selectedOptions[]` toggle set -> an
+ * ARRAY of N {verb, outcome} picks, one per toggle. Each option is matched to a
+ * verb DETERMINISTICALLY (membership, not fuzzy NLP); the raw navigator text
+ * rides the optional per-element `sentence` LOCAL lane only (Part 8).
+ *
+ * House rule: hyphens only, no em-dashes. Node built-ins only, zero deps.
+ */
+
+const assert = require('node:assert');
+
+let pass = 0;
+function ok(name, cond) { assert.ok(cond, name); console.log('  ok - ' + name); pass++; }
+
+// RED-loud: the module must exist.
+const mod = require('./f8-action-capture-cli.cjs');
+ok('module exports captureCliActionSet', typeof mod.captureCliActionSet === 'function');
+ok('module reuses the OUTCOMES enum (no parallel enum)',
+  Array.isArray(mod.OUTCOMES)
+  && mod.OUTCOMES.indexOf('accept') !== -1
+  && mod.OUTCOMES.indexOf('defer') !== -1
+  && mod.OUTCOMES.indexOf('reject') !== -1
+  && mod.OUTCOMES.indexOf('Free-Text') !== -1);
+
+const priorPayload = { verbs: ['ship it', 'archive', 'escalate', 'Free-Text'] };
+
+// ---- N selectedOptions -> N deterministic {verb, outcome} picks ----
+const answer = {
+  selectedOptions: [
+    'ship it',                                   // bare toggle -> default accept
+    { label: 'archive', outcome: 'reject' },     // per-element outcome preserved
+    { label: 'escalate', outcome: 'defer' },
+  ],
+};
+const picks = mod.captureCliActionSet(answer, priorPayload);
+ok('returns an ARRAY', Array.isArray(picks));
+ok('N selectedOptions -> N picks', picks.length === 3);
+ok('each pick carries a matched verb + outcome',
+  picks.every((p) => typeof p.verb === 'string' && typeof p.outcome === 'string'));
+ok('a bare confirmed toggle defaults to accept', picks[0].verb === 'ship it' && picks[0].outcome === 'accept');
+ok('a per-element reject stays a reject (two-channel split preserved)',
+  picks[1].verb === 'archive' && picks[1].outcome === 'reject');
+ok('a per-element defer stays a defer', picks[2].verb === 'escalate' && picks[2].outcome === 'defer');
+
+// ---- Part 8: raw navigator text rides the per-element sentence LOCAL lane only ----
+const withText = {
+  selectedOptions: [{ label: 'ship it', outcome: 'accept', text: 'do this before the demo' }],
+};
+const textPicks = mod.captureCliActionSet(withText, priorPayload);
+ok('raw navigator text rides the sentence LOCAL lane per element',
+  textPicks[0].sentence === 'do this before the demo');
+ok('the sentence text is NEVER the pick verb (Part 8: not an edge body)',
+  textPicks[0].verb === 'ship it' && textPicks[0].verb !== textPicks[0].sentence);
+
+// ---- unknown option degrades (no false match) ----
+const withUnknown = { selectedOptions: ['ship it', 'NOT-A-RENDERED-VERB'] };
+const degraded = mod.captureCliActionSet(withUnknown, priorPayload);
+ok('an unknown option degrades to verb:null (deterministic, no false match)',
+  degraded.length === 2 && degraded[0].verb === 'ship it' && degraded[1].verb === null);
+
+// ---- a pre-checked-but-unconfirmed toggle is NOT a selection until confirm ----
+// (The adapter only ever sees the CONFIRMED selectedOptions[]; an empty confirm
+//  yields an empty pick set even if candidates were pre-checked at render time.)
+const noConfirm = mod.captureCliActionSet({ selectedOptions: [] }, priorPayload);
+ok('a pre-checked-but-unconfirmed toggle is NOT a selection until confirm',
+  Array.isArray(noConfirm) && noConfirm.length === 0);
+
+console.log('\nPASS f8-capture.test (' + pass + ' assertions)');
+console.log('>>> f8-capture.test.cjs: PASSED');

package/lib/hmi/f9-ordered-capture-cli.cjs

@@ -0,0 +1,138 @@
+'use strict';
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 188-07 -- captureCliOrderedGate: the CLI F.9 ordered-capture adapter (SFS-04).
+ * ================================================================================
+ * The Tri-Polar split (DCW-07, inherited from f8-action-capture-cli.cjs): the
+ * ordered consumer (lib/workflow/f9-ordered-consumer.cjs) is the SHARED CORE; each
+ * surface supplies a thin capture adapter that turns the surface's turn input into
+ * the ordered per-item picks the consumer accepts. F.8 captures an UNORDERED set;
+ * F.9 captures an ORDERED array -- POSITION IS PRESERVED (array order IS meaning),
+ * each element carrying { item_id, outcome }.
+ *
+ * This is the CLI adapter. The F.9 answer carries `orderedOutcomes[]` -- one
+ * per-item ordered decision, in the SAME order as the rendered cascade questions.
+ * captureCliOrderedGate:
+ *   - walks the answer IN ORDER, zipping each element to the matching question's
+ *     item_id from priorPayload.questions (position-matched, NOT fuzzy NLP);
+ *   - folds each ordered token onto the reused OUTCOMES enum via the same alias the
+ *     renderer uses (APPROVE->accept, REJECT->reject, DEFER->defer) so no parallel
+ *     enum is minted; the consumer keys on the canonical ordered token;
+ *   - carries any raw navigator text on the optional per-element `sentence` LOCAL
+ *     lane ONLY (Part 8) -- never a pick value, an edge body, or a Brain packet;
+ *   - carries the per-element `reason` for a REJECT (rejection is data, Decision 13).
+ *
+ * An unknown / unmatched ordered token degrades to { item_id, outcome: null } so the
+ * ordered consumer no-ops that item deterministically (never a false decision).
+ *
+ * Framework: pure CJS, zero new dependencies (Phase 87 invariant). No em-dashes.
+ * No emoji. No Brain call.
+ *
+ * License: BSL 1.1.
+ */
+
+// The closed ordered-outcome vocabulary (canon literal tokens). Mirrored locally
+// to keep the adapter decoupled from the consumer (no require cycle).
+const ORDERED_OUTCOMES = ['APPROVE', 'REJECT', 'DEFER'];
+
+// The reused four-outcome enum (accept==APPROVE). Mirrored locally; the consumer is
+// the gate of record. This is the SAME enum the F.8 machinery reuses.
+const OUTCOMES = ['accept', 'defer', 'reject', 'Free-Text'];
+
+// Normalize any ordered-token spelling onto the canonical closed set. Accepts the
+// literal APPROVE/REJECT/DEFER and the reused-enum spellings (accept/approve, etc).
+function _normalizeOrdered(raw) {
+  if (typeof raw !== 'string' || raw.length === 0) return null;
+  const lower = raw.toLowerCase();
+  if (lower === 'approve' || lower === 'accept') return 'APPROVE';
+  if (lower === 'reject') return 'REJECT';
+  if (lower === 'defer') return 'DEFER';
+  return null;
+}
+
+// Resolve one orderedOutcomes[] element into { outcome, text, reason }. The element
+// is either a bare token string OR an object { outcome|token, text?, reason? }.
+function _resolveElement(el) {
+  if (typeof el === 'string') {
+    return { outcome: _normalizeOrdered(el), text: null, reason: null };
+  }
+  if (el && typeof el === 'object') {
+    const token = (typeof el.outcome === 'string' && el.outcome.length > 0)
+      ? el.outcome
+      : ((typeof el.token === 'string' && el.token.length > 0) ? el.token : null);
+    const text = (typeof el.text === 'string' && el.text.length > 0) ? el.text : null;
+    const reason = (typeof el.reason === 'string' && el.reason.length > 0) ? el.reason : null;
+    return { outcome: _normalizeOrdered(token), text: text, reason: reason };
+  }
+  return { outcome: null, text: null, reason: null };
+}
+
+// The item_id for the question at POSITION i (order IS meaning). Falls back to a
+// synthetic id when the prior payload did not carry an explicit item_id.
+function _itemIdAt(questions, i) {
+  if (Array.isArray(questions) && questions[i] && typeof questions[i] === 'object') {
+    const q = questions[i];
+    if (typeof q.item_id === 'string' && q.item_id.length > 0) return q.item_id;
+    if (typeof q.id === 'string' && q.id.length > 0) return q.id;
+  }
+  return 'item:' + String(i);
+}
+
+// ---------------------------------------------------------------------------
+// captureCliOrderedGate(answer, priorPayload)
+//   -> [ { item_id, outcome, reason?, sentence? }, ... ]  (POSITION PRESERVED)
+//
+// answer: the F.9 answer { orderedOutcomes: [ <token> | { outcome, text?, reason? } ] }.
+// priorPayload: the prior turn's F.9 render contract ({ questions:[{item_id,...}] }).
+//
+// Returns an ARRAY of ordered picks in the SAME order as the answer, each keyed to
+// its position's item_id, outcome the canonical ordered token (or null when
+// unmatched so the consumer no-ops it). Raw text rides the optional per-element
+// `sentence` LOCAL lane; a REJECT reason rides `reason`. A non-array answer -> [].
+// ---------------------------------------------------------------------------
+function captureCliOrderedGate(answer, priorPayload) {
+  const a = (answer && typeof answer === 'object') ? answer : {};
+  const payload = (priorPayload && typeof priorPayload === 'object') ? priorPayload : {};
+  const questions = Array.isArray(payload.questions) ? payload.questions : [];
+  const ordered = Array.isArray(a.orderedOutcomes) ? a.orderedOutcomes : [];
+
+  const picks = [];
+  for (let i = 0; i < ordered.length; i++) {
+    const resolved = _resolveElement(ordered[i]);
+    const pick = {
+      item_id: _itemIdAt(questions, i),
+      outcome: resolved.outcome,
+    };
+    // Rejection is data (Decision 13): the REJECT reason survives as a per-element
+    // field the consumer records as a graph node.
+    if (resolved.outcome === 'REJECT' && resolved.reason) {
+      pick.reason = resolved.reason;
+    }
+    // The raw navigator text rides the LOCAL lane ONLY (Part 8). Never a pick value,
+    // never an edge body, never a Brain packet.
+    if (resolved.text) {
+      pick.sentence = resolved.text;
+    }
+    picks.push(pick);
+  }
+  return picks;
+}
+
+// The Desktop/Cowork capture-adapter seam contract (DCW-07). Desktop/Cowork LIVE
+// ordered capture is OUT of this phase; this constant names the signature + expected
+// POSITION-PRESERVED array those adapters implement.
+const CAPTURE_ADAPTER_CONTRACT = Object.freeze({
+  signature: 'captureSurfaceOrderedGate(surfaceAnswer, priorPayload) -> [ { item_id, outcome, reason?, sentence? }, ... ]',
+  returns: '[ { item_id: <from priorPayload.questions[i]>, outcome: APPROVE|REJECT|DEFER|null, reason?: <REJECT reason>, sentence?: <raw navigator text, LOCAL lane only> }, ... ]  POSITION PRESERVED',
+  surfaces: Object.freeze(['cli (live, this module)', 'desktop (seam only, deferred)', 'cowork (seam only, deferred)']),
+  part8_note: 'The raw navigator text rides ONLY the optional per-element sentence (LOCAL lane). It is NEVER a pick value, an edge body, or a Brain packet.',
+  consumer: 'lib/workflow/f9-ordered-consumer.cjs::consumeF9Ordered({ items, roomState })',
+});
+
+module.exports = {
+  captureCliOrderedGate: captureCliOrderedGate,
+  CAPTURE_ADAPTER_CONTRACT: CAPTURE_ADAPTER_CONTRACT,
+  ORDERED_OUTCOMES: ORDERED_OUTCOMES.slice(),
+  OUTCOMES: OUTCOMES.slice(),
+};