test(trekresearch): pin --engine doc-consistency across surfaces

tests/lib/doc-consistency.test.mjs

@@ -1065,6 +1065,32 @@ test('S18: --min-brief-version is documented at the trekplan + trekresearch boun
   }
 });
 
+test('deep-research-engine: --engine is documented + consistent across surfaces', () => {
+  // Cross-doc pin mirroring S18 (:1057). The opt-in external-research engine flag
+  // must be discoverable wherever /trekresearch flags live: the command itself
+  // plus the three reference surfaces.
+  for (const f of ['commands/trekresearch.md', 'docs/command-modes.md', 'CLAUDE.md', 'README.md']) {
+    assert.ok(
+      read(f).includes('--engine'),
+      `${f} must document the --engine flag (deep-research-engine)`,
+    );
+  }
+  // README documents it specifically as an **Engine** mode-table row.
+  assert.ok(
+    /\*\*Engine\*\*/.test(read('README.md')),
+    'README.md must document --engine as an **Engine** mode row',
+  );
+  // The command prose must name both engine values and the swarm fallback, so the
+  // opt-in + graceful-degradation contract is pinned — not merely the flag string.
+  const research = read('commands/trekresearch.md');
+  assert.ok(/\bswarm\b/.test(research), 'trekresearch.md must name the swarm engine value');
+  assert.ok(/\bdeep-research\b/.test(research), 'trekresearch.md must name the deep-research engine value');
+  assert.ok(
+    /fall back|falls back/.test(research),
+    'trekresearch.md must document the swarm fallback (graceful degradation)',
+  );
+});
+
 test('S18: HANDOVER-CONTRACTS documents the pre-2.2 zero-framing-enforcement hole', () => {
   // The framing defense is producer-elective: a brief declaring ≤ 2.1 sidesteps
   // it entirely. Handover 1 (PUBLIC CONTRACT) must disclose this and name the remedy.