docs(research): resolve deep-research-engine topic-1 (/deep-research trigging)

Operator reviewed the brief (S57) and approved as-is, then chose research-first
at the /trekplan research gate (option A: investigate only the genuinely-external
topic 1; fold local topics 2/3 into /trekplan exploration).

Topic 1 finding (validator-green; claude-code-guide + CC 2.1.196 binary + a real
local /deep-research run, all cited): /deep-research is a built-in *dynamic
workflow* (not a skill), outside the Skill-tool allowlist. Trigging is
prose-instruction only; the report lands inline in context with no on-disk
artifact (only the .js script is written). => the engine must be instruction-based
+ in-context transform, surface-only. Brief's v2.1.154+ / Pro-via-/config
constraints verified correct; SC3 ("dynamic workflows off -> fallback to swarm")
is correct as written (an earlier review note that called it a conflation rested
on a wrong premise and is retracted).

- docs/deep-research-engine-research.md: new, research-validator green strict.
- docs/deep-research-engine-brief.md: status draft->ready (operator-approved),
  research_status pending->complete (option-A decision recorded), Research Plan
  traceability note.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019ddpUq3MNQFoV5h3qYrVYj

docs/deep-research-engine-brief.md

@@ -4,10 +4,10 @@ brief_version: "2.2"
 task: "Opt-in /deep-research-motor for /trekresearch ekstern-fase"
 slug: deep-research-engine
 framing: refine
-status: draft
+status: ready
 brief_quality: complete
 research_topics: 3
-research_status: pending
+research_status: complete
 phase_signals_partial: true
 ---
 
@@ -51,6 +51,8 @@ phase_signals_partial: true
    `/trekresearch --project <dir> --local "Hva krever research-validator.mjs av research/NN-*.md?"`
 3. **Feature-deteksjon + fallback** — Hvordan oppdage om workflows er på, og hvor i fasen fallback-grenen bør sitte? Scope: local · Konfidens: middels · Kost: lav.
 
+> **Research-status (2026-06-30, operatør-beslutning «option A»):** Topic 1 (eneste ekte eksterne ukjente) er undersøkt → `docs/deep-research-engine-research.md` (validator-grønn). Funn: `/deep-research` er en innebygd **dynamic workflow** (ikke skill) → trigging KUN via prosa-instruksjon, output **inline i kontekst** (ingen on-disk-artefakt) → motoren må være instruksjons-basert + in-context transform. **SC3 er korrekt som skrevet** (`/deep-research` ER en dynamic workflow). Topic 2 (validator-skjema: `type/created/question` + `## Executive Summary`/`## Dimensions`, `dimensions ≥ 1`) og topic 3 (fallback-plassering) er lokale kode-spørsmål reklassifisert til `/trekplan`-utforskning. `research_status: complete` reflekterer denne beslutningen.
+
 ## Open Questions / Assumptions
 - Antar at `/deep-research`-rapporten kan reduseres til ≥ 1 dimensjon med per-påstand-sitater uten å bryte trianguleringen. Verifiseres i topic 2.
 - Uavklart om delegering skjer via instruksjon (trygt) eller programmatisk API (raskere) — topic 1 avgjør.

docs/deep-research-engine-research.md

@@ -0,0 +1,210 @@
+---
+type: trekresearch-brief
+created: 2026-06-30
+question: "Can a Claude Code plugin command programmatically trigger the built-in /deep-research workflow and capture its report, or must it instruct Claude to run it?"
+confidence: 0.85
+dimensions: 4
+mcp_servers_used: []
+local_agents_used: [claude-code-guide]
+external_agents_used: []
+slug: deep-research-engine
+feeds_brief: docs/deep-research-engine-brief.md
+research_topic: 1
+---
+
+# Research — Programmatic trigging of `/deep-research` from a plugin command
+
+> Targeted single-topic research for the `deep-research-engine` brief (Topic 1 of
+> the brief's Research Plan). Topics 2 & 3 are local Voyage-code questions folded
+> into `/trekplan` exploration; only Topic 1 was a genuine external unknown.
+> Method: `claude-code-guide` agent (Anthropic docs + CHANGELOG, cited) +
+> direct inspection of this machine (CC 2.1.196 binary, a real local `/deep-research`
+> run). Not run through the `/trekresearch` swarm — see brief reconcile note.
+
+## Research Question
+
+Can a Claude Code **plugin slash-command** (markdown under `commands/`)
+**programmatically** start the built-in `/deep-research` workflow and **capture its
+report artifact** for adaptation into the research-brief schema — or must the command
+instead **instruct** Claude (in prose) to run `/deep-research` and then transform the
+in-context result?
+
+## Executive Summary
+
+Programmatic trigger + file-based capture is **not feasible**: `/deep-research` is a
+built-in **dynamic workflow** (not a skill), deliberately outside the Skill-tool
+allowlist, and it returns its report **inline into conversation context with no
+documented on-disk report artifact**. The **only reliable path is instruction-based
+delegation** — the command's prose tells Claude to run `/deep-research <q>`, then
+transforms the in-context report in the same turn. Confidence **high** (Anthropic docs +
+CHANGELOG + local run), with one residual gap: there is no positive "is it enabled?"
+probe, so feature-detection must lean on the documented *disable* switches + version
+floor + a `swarm` default.
+
+## Dimensions
+
+### 1. Origin + gating -- Confidence: high
+
+**External findings:**
+- `/deep-research` is a **built-in dynamic workflow**, not a command and not a bundled
+  skill. `commands.md` marks the `/deep-research <question>` row as **[Workflow]**;
+  `workflows.md`: "Claude Code includes `/deep-research` as a built-in workflow."
+  [VERIFIED — code.claude.com/docs/en/commands.md, code.claude.com/docs/en/workflows.md]
+- Gating: available on **all paid plans** (pro/max/team/enterprise) + API/Bedrock/Vertex/
+  Foundry. **On Pro it must be turned on** in the *Dynamic workflows* row of `/config`.
+  Also requires the **WebSearch tool** to be available.
+  [VERIFIED — workflows.md, commands.md bundled-workflows row]
+- Version floor: dynamic workflows were **introduced in CC 2.1.154**; "Dynamic workflows
+  require Claude Code v2.1.154 or later." The brief's `v2.1.154+` + `(Pro: via /config)`
+  constraints are **both correct**. The exact version that first shipped the *named*
+  `/deep-research` workflow is **[NOT DOCUMENTED]** (only a 2.1.196 bugfix mentions it by
+  name) — treat 2.1.154 as the substrate floor, not a proven introduction point.
+  [VERIFIED — workflows.md + CHANGELOG 2.1.154]
+
+**Local findings:**
+- This machine runs **CC 2.1.196** (`claude --version`) — substrate floor satisfied.
+- The exact skill-description string lives **compiled into the binary**
+  (`/Users/ktg/.local/share/claude/versions/2.1.196`, Mach-O 235 MB); there is **no
+  `SKILL.md`** for it anywhere under `~/.claude` (system-wide `find`/`grep` — only hits
+  are this brief + unrelated harness notes). Confirms "Anthropic-bundled, not user skill."
+
+### 2. Invocation mechanism (programmatic vs instruction) -- Confidence: high
+
+**External findings:**
+- **Not** via the `Skill` tool. The Skill-tool built-in allowlist is closed: only
+  `/init`, `/review`, `/security-review` are reachable; "Other built-in commands such as
+  `/compact` are not." `/deep-research` is a Workflow and is not on that list.
+  [VERIFIED — code.claude.com/docs/en/skills.md]
+- **Instruction-based delegation is the documented mechanism.** Workflows launch when the
+  user types the command, or **when Claude is asked in natural language** ("use a
+  workflow" / "run a workflow") or via the `ultracode` keyword. A plugin command whose
+  markdown instructs Claude to run `/deep-research <q>` is therefore the supported path.
+  [VERIFIED — workflows.md "Have Claude write a workflow"]
+- **Approval gate caveat:** launching a workflow triggers a per-run approval prompt —
+  *every run* in default/acceptEdits; *first launch only* in auto; **never in `claude -p`
+  / Agent SDK / bypass-permissions** ("the run starts immediately"). Voyage's headless
+  surface (`claude -p`) thus delegates without an interactive gate; interactive sessions
+  hit a prompt. [VERIFIED — workflows.md "Behavior and limits"]
+- No documented blanket "commands/skills cannot nest" prohibition beyond the Skill-tool
+  allowlist + workflow runtime limits (no mid-run user input; 16 concurrent agents;
+  1000 agents/run). [VERIFIED — workflows.md; NOT DOCUMENTED for a general nesting ban]
+
+### 3. Output capture -- Confidence: high
+
+**External findings:**
+- "When the run finishes, **the report lands in your session**"; "Claude's context holds
+  only the final answer." The report is **in-context**, not a file.
+  [VERIFIED — workflows.md]
+- What *is* written to disk is the orchestration **script**, not the report: "Every run
+  writes its script to a file under your session's directory in `~/.claude/projects/`."
+  [VERIFIED — workflows.md "How a workflow runs"]
+
+**Local findings:**
+- A real `/deep-research` run on this machine left exactly one file —
+  `~/.claude/projects/<session>/workflows/scripts/deep-research-wf_<id>.js` — and **no
+  `.md` report** beside it. [VERIFIED — local filesystem inspection by claude-code-guide]
+- **Consequence:** a calling command cannot `grep` a results file off disk (none is
+  documented to exist). It can only consume the report **as it sits in conversation
+  context in the same turn** — Claude reads its own prior output and transforms it into
+  research-brief schema. [INFERENCE — file-based capture not feasible; in-context
+  transform is the only avenue]
+
+### 4. Feature detection + fallback -- Confidence: medium
+
+**External findings:**
+- **No positive enumeration / "is-enabled" API or flag is documented.** `claude --help`
+  exposes `--disable-slash-commands` but no "list skills/workflows" or "is-feature-on"
+  flag. [VERIFIED — local `claude --help`; NOT DOCUMENTED for any positive probe]
+- The documented signals are the **off-switches**, read defensively: `/config` Dynamic-
+  workflows off; `disableWorkflows: true` / `disableBundledSkills: true` in settings.json;
+  `CLAUDE_CODE_DISABLE_WORKFLOWS=1` / `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS=1`.
+  [VERIFIED — workflows.md "Turn workflows off"; CHANGELOG 2.1.x]
+- **The gap:** the Pro `/config` *on*-state is the very thing you most need to detect, and
+  only the *disable* keys are documented; the persisted key/value for the Pro enable-state
+  is **[NOT DOCUMENTED]**, so it cannot be reliably grepped. A failed/disabled
+  `/deep-research` is also **not documented** to raise a signal a sibling command can
+  catch. [VERIFIED gap]
+
+**Local findings:**
+- On this machine both disable keys are unset/absent — workflows are not disabled.
+
+## External Knowledge
+
+### Best Practice
+The "Have Claude write a workflow" + "Behavior and limits" sections of `workflows.md`
+establish that workflows are operator/Claude-launched, run isolated, and return one
+in-context report. The Skill-tool allowlist (`skills.md`) is the authoritative statement
+that only three built-ins are tool-invocable.
+
+### Known Issues
+Per-run approval prompts outside `-p`/SDK/bypass mean an interactive `/trekresearch
+--engine deep-research` will pause for operator approval on each launch — acceptable, but
+worth documenting in the command UX. The absence of a positive availability probe is the
+single biggest design constraint (see Dimension 4).
+
+## Synthesis
+
+Three cross-cutting insights that only emerge from combining the docs with Voyage's brief:
+
+1. **The brief's SC3 is correct as written — an earlier review note was wrong.** Because
+   `/deep-research` *is itself* a dynamic workflow, "med dynamic workflows avskrudd faller
+   `--engine deep-research` tilbake til swarm" is the right feature-detection axis. A
+   prior brief-review remark that SC3 "conflated `/deep-research` (skill) with dynamic
+   workflows" was based on a wrong premise (that `/deep-research` was a skill) and is
+   retracted. **No SC3 brief edit is needed.**
+
+2. **The engine must be instruction-based + in-context, never file-based.** Topic 1's
+   open question ("instruction (safe) vs. programmatic API (faster) — topic 1 decides")
+   resolves decisively to **instruction-based**: there is no programmatic API and no
+   on-disk report. The `deep-research` engine path in `commands/trekresearch.md` must
+   (a) instruct Claude to run `/deep-research <q>`, then (b) transform the in-context
+   report into the `research/NN-*.md` schema in the same turn. This is surface-only
+   (`commands/` prose), matching the brief's "ingen nye `lib/`-avhengigheter."
+
+3. **SC3's "ingen exception" cannot rest on runtime detection — pin it to a default.**
+   Since no positive availability probe exists, robust fallback = version-floor check
+   (≥ 2.1.154) + disable-key heuristic (`disableWorkflows` / env) + **`--engine` default
+   of `swarm`** (explicit opt-in). The fallback is "graceful degradation by design,"
+   not "catch an exception at runtime." This refines, but does not contradict, SC3.
+
+## Open Questions
+
+- **Adapter fidelity (brief Topic 2, partly answered locally):** `research-validator.mjs`
+  requires `type: trekresearch-brief` + `created` + `question`; validates `confidence ∈
+  [0,1]` and `dimensions ≥ 1` if present; body must carry `## Executive Summary` +
+  `## Dimensions`. So the `/deep-research` report **can** be reduced to ≥ 1 dimension with
+  per-claim citations and a confidence number — the brief's assumption holds. The
+  remaining open part (how cleanly the in-context report maps to per-dimension
+  local/external splits) is a `/trekplan` exploration concern, not an external unknown.
+- **Exact intro version of the *named* `/deep-research` workflow** — not documented; the
+  2.1.154 dynamic-workflows floor is the safe pin.
+
+## Recommendation
+
+Build the `deep-research` engine as **instruction-based delegation with in-context
+adaptation**, not a programmatic trigger:
+1. `--engine deep-research` makes `commands/trekresearch.md`'s external phase instruct
+   Claude to run `/deep-research <q>` and transform the returned in-context report into
+   `research/NN-*.md` (validator-conformant: `## Executive Summary` + `## Dimensions`,
+   `confidence`, `dimensions ≥ 1`).
+2. Feature-detect by **graceful degradation**: version floor + disable-key heuristic +
+   `--engine` default `swarm`. Do not depend on a positive availability probe (none
+   exists). Log the chosen engine. This satisfies SC3 without a runtime exception.
+3. Keep `swarm` the default (brief's Non-Goal: "ikke default-bytte"). Document the
+   per-run approval prompt for interactive (non-`-p`) sessions.
+
+Confidence in the recommendation: **high** for the mechanism (instruction-based +
+in-context), **medium** for the exact fallback-detection ergonomics (the one documented
+gap). This is sufficient to green-light `/trekplan` with Topic 1 resolved.
+
+## Sources
+
+| # | Source | Type | Quality | Used in |
+|---|--------|------|---------|---------|
+| 1 | code.claude.com/docs/en/workflows.md | official | high | Dim 1,2,3,4 + Synthesis |
+| 2 | code.claude.com/docs/en/commands.md | official | high | Dim 1 (Workflow classification, WebSearch req) |
+| 3 | code.claude.com/docs/en/skills.md | official | high | Dim 2 (Skill-tool allowlist) |
+| 4 | github.com/anthropics/claude-code CHANGELOG (2.1.154, 2.1.x, 2.1.196) | official | high | Dim 1,4 (version floor, disable keys) |
+| 5 | Local: CC 2.1.196 binary inspection (`find`/`grep`, `claude --version`) | codebase | high | Dim 1 (bundled, no SKILL.md) |
+| 6 | Local: real `/deep-research` run — only `.js` script written, no `.md` report | codebase | high | Dim 3 (no on-disk artifact) |
+| 7 | Local: `lib/validators/research-validator.mjs` schema | codebase | high | Open Questions (adapter feasibility / Topic 2) |