docs(trekresearch): document STORM mechanisms across four surfaces

tests/lib/doc-consistency.test.mjs

@@ -1117,6 +1117,61 @@ test('deep-research-engine: --engine is documented + consistent across surfaces'
   );
 });
 
+// ── STORM bounded loop — env-vars documented across the four surfaces ──────
+// Same cross-doc shape as the --engine pin above. An operator-facing switch
+// documented on one surface is a switch most operators never find; and the
+// three below decide cost, so they are the ones worth pinning.
+
+const STORM_SURFACES = ['docs/command-modes.md', 'CLAUDE.md', 'README.md', 'docs/architecture.md'];
+const STORM_ENV_VARS = ['VOYAGE_STORM_ENABLED', 'TREKRESEARCH_MAX_CONV_TURNS', 'VOYAGE_DISABLE_CAP_HOOK'];
+
+for (const envVar of STORM_ENV_VARS) {
+  test(`STORM: ${envVar} is documented on all four reference surfaces`, () => {
+    for (const f of STORM_SURFACES) {
+      assert.ok(read(f).includes(envVar), `${f} must document ${envVar} (STORM bounded-loop env-vars)`);
+    }
+  });
+}
+
+test('STORM: VOYAGE_STORM_ENABLED is documented WITH its default-off contract', () => {
+  // Naming a switch without its default is how a default-on mechanism ships by
+  // accident. Default-off is also the decline branch: declining costs nothing.
+  for (const f of STORM_SURFACES) {
+    const t = read(f);
+    const i = t.indexOf('VOYAGE_STORM_ENABLED');
+    const window = t.slice(Math.max(0, i - 400), i + 400);
+    assert.match(
+      window,
+      /default-off|default off|opt-in/i,
+      `${f}: VOYAGE_STORM_ENABLED must be documented together with its default-off contract`,
+    );
+  }
+});
+
+test('STORM: README research-dimension prose stays at the existing 3–8 ceiling', () => {
+  // Phase 4.5 discovers dimensions UNDER settings.json:16's maxDimensions: 8.
+  // Rewriting this prose upward would raise a ceiling the brief asked us to hold.
+  assert.ok(
+    read('README.md').includes('3–8 research dimensions'),
+    'README.md must keep the "3–8 research dimensions" prose — augmentation happens under the existing cap, it does not raise it',
+  );
+});
+
+test('STORM: no banned Sonnet-swarm phrase introduced on any STORM surface', () => {
+  const BANNED = [
+    'Sonnet exploration',
+    'Sonnet runs the exploration',
+    'front-loads cheap Sonnet',
+    'exploration agents stay on Sonnet',
+  ];
+  for (const f of STORM_SURFACES) {
+    const t = read(f);
+    for (const phrase of BANNED) {
+      assert.ok(!t.includes(phrase), `${f} must not claim "${phrase}" — sub-agents are opus-pinned`);
+    }
+  }
+});
+
 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.