feat(trekresearch): add deep-research engine-selection fork

commands/trekresearch.md

@@ -305,6 +305,63 @@ For each local agent, prompt with the research question, NOT a task description:
 - convention-scanner: "Discover coding conventions relevant to evaluating {question}.
   What patterns would a solution need to follow?"
 
+### Engine selection (scope = both or external)
+
+`--engine` affects ONLY the external portion of research. The local agents
+(`### Local agents` above) and Phases 6–7 (triangulation, synthesis, brief
+writing) are **engine-agnostic** — they run identically regardless of engine.
+
+`--engine` is **moot** (treated as `swarm`) whenever the external phase does not
+run at all: `--local`, `--quick`, `effort == 'low'`, or a profile with
+`external_research_enabled == false` (the `economy`/`balanced` auto-disable — see
+Profile below). The profile's on/off switch wins. Initialize
+`effective_engine = {requested engine}`.
+
+**engine = swarm (default):** run the `### External agents` + `### Bridge agent`
+blocks below unchanged. This is byte-for-byte the current path, so `--engine swarm`
+changes nothing (SC1). Keep the native-swarm anchors intact ("in parallel",
+"single message", `model: "opus"`).
+
+**engine = deep-research:**
+
+1. **Coarse pre-gate (best-effort, NOT a trust signal).** `Bash: claude --version`;
+   parse the leading `X.Y.Z` (e.g. from `2.1.196 (Claude Code)`) and compare
+   numerically against `2.1.154` — split each on `.` and compare major, then minor,
+   then patch as integers (do NOT string-compare; lexical comparison mis-orders
+   multi-digit patch numbers). If the version is `< 2.1.154`, OR if
+   `disableWorkflows: true` / `CLAUDE_CODE_DISABLE_WORKFLOWS=1` is set, skip to the
+   fallback (step 4). **If `claude` is not on PATH inside the Bash tool (possible
+   under `claude -p`) or the version cannot be parsed, treat the pre-gate as
+   *indeterminate* and proceed to step 2 — do NOT hard-fail.** There is no positive
+   availability probe (research Dim 4), so a passing pre-gate does not guarantee the
+   workflow runs; the post-hoc check (step 3) is the authoritative guard.
+
+2. **Run.** Instruct Claude (in prose, this turn) to run
+   `/deep-research <research question>` and request per-claim citations. Note:
+   interactive default/acceptEdits triggers a per-run approval prompt; `claude -p` /
+   SDK / bypass runs immediately.
+
+3. **Post-hoc presence + provenance check (the real guard).** Verify a real, cited
+   `/deep-research` report actually landed in context — substantive findings with
+   citations, not an empty/denied/errored turn and not bare error text. This check
+   must be **robust to all failure manifestations** (workflow disabled, approval
+   denied, runtime error, empty output), because the disabled-headless behavior is
+   undocumented: no recognizable cited report in context → fall back, regardless of
+   how the failure surfaces.
+
+4. **On no real report (fallback):** set `effective_engine = swarm`, run the swarm
+   blocks below, and **log the fallback at this decision point** — print
+   `Engine: deep-research → swarm (fallback: <reason>)` and carry the reason into the
+   Phase-8 Present summary and the brief's `## Executive Summary`. **NEVER fabricate
+   or synthesize a substitute report** — a structurally-valid-but-invented brief
+   passes the structure-only validator and silently poisons `/trekplan`; that is the
+   worst outcome of this feature.
+
+5. **On a real report:** keep `effective_engine = deep-research`, log
+   `Engine: deep-research (active)`, and carry the report into Phase 6 triangulation
+   as the external-findings input (adapted in Phase 7 — see the Deep-research engine
+   adapter below).
+
 ### External agents (scope = both or external)
 
 Launch the new research-specialized agents:
@@ -397,6 +454,7 @@ Present a summary to the user:
 **Mode:** {default | quick}, Scope: {both | local | external}
 **Brief:** {brief_destination}
 **Project:** {project_dir or "-"}
+**Engine (effective):** {swarm | deep-research}{, with fallback reason if it fell back}
 **Confidence:** {overall confidence 0.0-1.0}
 **Dimensions:** {N} researched
 **Agents:** {N} local + {N} external + {gemini: used | unavailable | skipped}