devflow-kit 3.11.0 → 3.12.1

package/dist/commands/research.md

@@ -1,10 +1,8 @@
 ---
-description: Research a topic using parallel multi-type Research agents with trust-aware synthesis
+description: Research a topic with parallel multi-type Research agents and trust-aware synthesis
 ---
 # Research Command
 
-Research a topic by spawning parallel Research agents across multiple research types (codebase, external, market, competitor, technology). Findings are trust-annotated and synthesized into structured output.
-
 ## Usage
 
 ```
@@ -16,16 +14,13 @@ Research a topic by spawning parallel Research agents across multiple research t
 
 ## Input
 
-What follows `/research` is bound once, here. Every later step names it `COMMAND_INPUT` and never restates it:
+What follows `/research` is bound once, here. Every later step names it `COMMAND_INPUT`:
 
 <command-input>
 $ARGUMENTS
 </command-input>
 
-`COMMAND_INPUT` is one of:
-- Research question: "best caching strategies"
-- Comparison question: "compare React vs Svelte for our use case"
-- Empty: use conversation context
+An empty `COMMAND_INPUT` means: use the conversation context.
 
 ## Phases
 
@@ -33,50 +28,43 @@ $ARGUMENTS
 
 **Produces:** DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, FEATURE_KNOWLEDGE_RULES
 
-**Docs root (D-DOCS-ROOT).** Every `.devflow/docs/` path this command reads or writes lives at the checkout's toplevel, never under the directory the session started in. Resolve `{worktree}` from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`) — by running
+**Docs root (D-DOCS-ROOT).** Every `.devflow/docs/` path is `{worktree}/.devflow/docs/…`. A repo-relative docs path handed to an agent travels with a `WORKTREE_PATH` naming its checkout.
+
+Once per start directory (`WORKTREE_PATH` if provided, otherwise cwd), run from it:
 
 ```bash
-git -C "{start}" rev-parse --show-toplevel
+node "$HOME/.devflow/scripts/resolve-root.cjs" "{start}"; echo "exit=$?"
 ```
 
-and using its one-line output. If the command fails (outside a git repository), `{worktree}` is the start directory itself. Every docs path below is written `{worktree}/.devflow/docs/…`; a repo-relative docs path handed to an agent always travels with a `WORKTREE_PATH` naming the checkout it is relative to.
+Accept only the three lines `WORKTREE=<absolute path>`, `LEDGER=<absolute path>` and `exit=0`, which set `{worktree}` and `{ledger}`. Otherwise both are the start directory.
 
-**Resolve the settings line** once per worktree root, reusing a line this run already resolved for the same root. `{root}` is the worktree the values are for — the repository root in a one-worktree run:
+**Resolve the settings line** once per worktree root, reusing a line this run already resolved for the same root. `{root}` is the worktree the values are for:
 
 ```bash
 node "$HOME/.devflow/scripts/resolve-settings.cjs" "{root}" 2>/dev/null; echo "exit=$?"
 ```
 
-Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `TRACKER=<github|jira|linear> TRACKER_SOURCE=<project|personal|machine|default> TRACKER_WARN=<none|mismatch|invalid> SITE=<none|https://<host>> KEY=<none|<key>> REVIEW_PUBLICATION=<off|auto|full> COMPLIANCE=<off|generic|<id>[,<id>…]> MEMORY=<on|off> CURATION=<on|off> KNOWLEDGE=<on|off> GATE_LEVEL=<full|standard|lean>` — these fields, in this order, nothing else, where `<host>` is a lowercase dotted host name alone, `<key>` is 2–10 of `A-Z`, `0-9` and `_` starting with a letter, and each `<id>` is one of `gdpr`, `hipaa`, `pci-dss`, `soc2`, `iso-27001`, `sox`. **Anything else** (a non-zero exit, no line, extra text, or a missing, reordered or unlisted field or value) ⇒ use `TRACKER=github TRACKER_SOURCE=default TRACKER_WARN=invalid SITE=none KEY=none REVIEW_PUBLICATION=off COMPLIANCE=generic MEMORY=off CURATION=off KNOWLEDGE=off GATE_LEVEL=full` instead.
+Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `TRACKER=<github|jira|linear> TRACKER_SOURCE=<project|personal|machine|default> TRACKER_WARN=<none|mismatch|invalid> SITE=<none|https://<host>> KEY=<none|<key>> REVIEW_PUBLICATION=<off|auto|full> COMPLIANCE=<off|generic|<id>[,<id>…]> MEMORY=<on|off> CURATION=<on|off> KNOWLEDGE=<on|off> GATE_LEVEL=<full|standard|lean>` — these fields, in this order, nothing else, where `<host>` is a lowercase dotted host name alone, `<key>` is 2–10 of `A-Z`, `0-9` and `_` starting with a letter, and each `<id>` is one of `gdpr`, `hipaa`, `pci-dss`, `soc2`, `iso-27001`, `sox`. **Anything else** (including a script that cannot run) ⇒ use `TRACKER=github TRACKER_SOURCE=default TRACKER_WARN=invalid SITE=none KEY=none REVIEW_PUBLICATION=off COMPLIANCE=generic MEMORY=off CURATION=off KNOWLEDGE=off GATE_LEVEL=full` instead.
 
 The accepted line is the only source of these values.
 
 ### Load DECISIONS_CONTEXT
 
-When the settings line says `CURATION=off`, set `DECISIONS_CONTEXT` to `(none)` and skip this step, locating no ledger and reading no index.
+When the settings line says `CURATION=off`, set `DECISIONS_CONTEXT` to `(none)` and skip this step, reading no index.
 
-The decisions ledger belongs to the repository, not to one checkout: a linked worktree reads the main worktree's copy, a subdirectory session the repository root's. Locate it with ONE git call, run from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`):
+The decisions ledger belongs to the repository, not to one checkout: a linked worktree reads the main worktree's copy.
+
+Once per start directory (`WORKTREE_PATH` if provided, otherwise cwd), run from it:
 
 ```bash
-git -C "{start}" rev-parse --path-format=absolute --show-toplevel --git-common-dir
+node "$HOME/.devflow/scripts/resolve-root.cjs" "{start}"; echo "exit=$?"
 ```
 
-Line 1 is the checkout's toplevel, line 2 the common git directory. A git older than 2.31 echoes `--path-format=absolute` back as a line of its own first. `{ledger}` is the first that applies:
-
-1. **The main worktree** — line 2 without its trailing `/.git`, when the output is exactly two lines each beginning with `/`, line 2 ends in `/.git`, and the directory left once it is removed is not your home directory and contains a `.devflow/` directory.
-2. **The toplevel** — line 1, or on an older git the line after the echoed flag.
-3. **The start directory itself** — when the command failed or printed no absolute toplevel (outside a git repository).
-
-This is the rule the curation hooks apply, so you read the index the Curate agent writes.
-
-**Step 1 — Read the pre-rendered index:**
-
-Attempt to read `{ledger}/.devflow/curation/index.md`.
+Accept only the three lines `WORKTREE=<absolute path>`, `LEDGER=<absolute path>` and `exit=0`, which set `{worktree}` and `{ledger}`. Otherwise both are the start directory.
 
-- If the file exists and contains non-empty content: use that content as `DECISIONS_CONTEXT`.
-- If the file is absent or empty: set `DECISIONS_CONTEXT` to `(none)`.
+**Step 1 — Read the pre-rendered index** `{ledger}/.devflow/curation/index.md`. Its content is `DECISIONS_CONTEXT`; if it is absent or empty, `DECISIONS_CONTEXT` is `(none)`.
 
-The index is one direct file read, written at render time by `render-decisions.cjs` — no `.cjs` script runs here.
+The index is one direct file read.
 
 **Step 2 — Slice the index, then hand it on:**
 
@@ -84,51 +72,33 @@ When `DECISIONS_CONTEXT` is not `(none)`, hand it only to the agents whose contr
 
 Hand each agent that takes `DECISIONS_CONTEXT` a slice, not the whole index: the index lines whose title, scope or area touch the files and task it works on, verbatim, led by `(slice: N of M entries — full index: <absolute index path>)` and closed by the index footer. When unsure, include the line. Siblings over one diff share ONE slice.
 
-Those agents follow `devflow:apply-decisions`. A host that uses the index in its own thread says so in its own step.
-
-Use `DECISIONS_CONTEXT` locally when framing research — prior decisions and pitfalls suggest areas to investigate. Follow `devflow:apply-decisions` to Read full entry bodies on demand. Pass `DECISIONS_CONTEXT` to each Research agent in Phase 4 so their findings can account for relevant decisions.
+Use `DECISIONS_CONTEXT` locally to frame the research. Follow `devflow:apply-decisions` to Read full entry bodies on demand. Pass `DECISIONS_CONTEXT` to each Research agent in Phase 4.
 
 ### Load Feature Knowledge
 
-Resolve `{worktree}` as the checkout's toplevel, because feature knowledge bases are committed with the branch (D-PROMPT-ROOT): from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`) — run
+Once per start directory (`WORKTREE_PATH` if provided, otherwise cwd), run from it:
 
 ```bash
-git -C "{start}" rev-parse --show-toplevel
+node "$HOME/.devflow/scripts/resolve-root.cjs" "{start}"; echo "exit=$?"
 ```
 
-and use its one-line output. If the command fails (outside a git repository), `{worktree}` is the start directory itself. All paths below are relative to `{worktree}`.
-
-**Step 1 — Read the index cache:**
-
-Attempt to read `{worktree}/.devflow/features/index.md`. Each line follows the format:
-
-```
-- **{slug}** — {areas} — {Use-when description}
-```
+Accept only the three lines `WORKTREE=<absolute path>`, `LEDGER=<absolute path>` and `exit=0`, which set `{worktree}` and `{ledger}`. Otherwise both are the start directory.
 
-If `index.md` exists and contains at least one entry line, use it for relevance matching.
+All paths below are relative to `{worktree}`.
 
-**Step 2 — Fallback: glob frontmatter (if `index.md` is absent or empty):**
+**Step 1 — Read the index cache** `{worktree}/.devflow/features/index.md`. Each line has the form `- **{slug}** — {areas} — {Use-when description}`. If `index.md` is absent or has no entry line, glob `{worktree}/.devflow/features/*/KNOWLEDGE.md` and read only the YAML frontmatter of each file, in one turn.
 
-Glob `{worktree}/.devflow/features/*/KNOWLEDGE.md`. For each file found, read only its YAML frontmatter block (between the opening and closing `---` delimiters).
+**Step 2 — Pick relevant KBs:** select the entries whose documented area overlaps the current task (index line, or frontmatter `description` and `directories` on fallback). Prefer the most specific entries.
 
-**Step 3 — Pick relevant KBs:**
+**Step 3 — Read each selected KB's Rules.** `{kb}` is `{worktree}/.devflow/features/{slug}/KNOWLEDGE.md`:
 
-Match the current task area and description against each index line (or frontmatter `description` + `directories` on fallback). Select entries whose documented area overlaps the current task. This is a relevance judgment — prefer specificity over breadth.
+1. List the `##` headings with line numbers of all selected KBs in one Bash call: `command grep -n '^## ' "{kb}" …`. With two or more paths, each line starts with its `{kb}:` path. This only locates sections; the text of a KB comes from the Read view alone.
+2. Read the `## Rules` range (its line to the next heading) with the Read tool, using `offset` and `limit`, all selected KBs in one turn, and choose the one to three bullets most relevant to the task.
+3. If the KB has no `## Rules` section, choose one to three entries from its `## Anti-Patterns` or `## Gotchas` range the same way.
 
-**Step 4 — Read each selected KB's Rules:**
+When a KB contradicts the code, **trust the code**. A missing Rules section, a missing heading list and `(none)` are normal, not errors.
 
-For each selected entry, `{kb}` is `{worktree}/.devflow/features/{slug}/KNOWLEDGE.md`:
-
-1. List its `##` headings with line numbers through Bash: `command grep -n '^## ' "{kb}"`. This only locates sections; the text of a KB comes from the Read view alone.
-2. Read the `## Rules` range (its line to the next heading) with the Read tool, using `offset` and `limit`, and choose the one to three bullets most relevant to the current task. The choice is yours, made per KB.
-3. If the KB has no `## Rules` section, choose one to three entries from its `## Anti-Patterns` or `## Gotchas` range the same way, and label them by that section's name instead of an ID.
-
-When a KB contradicts the code you observe, **trust the code** — the code is the freshness mechanism; the KB may lag behind. A missing Rules section, a missing heading list and `(none)` are legitimate states, not errors.
-
-**Step 5 — Set FEATURE_KNOWLEDGE and FEATURE_KNOWLEDGE_RULES:**
-
-Write one block per selected KB. Paste each bullet verbatim from the Read view, never from a shell view. The path is relative to the checkout root; an agent resolves it under `WORKTREE_PATH` when one is provided.
+**Step 4 — Set FEATURE_KNOWLEDGE and FEATURE_KNOWLEDGE_RULES.** Write one block per selected KB. Paste each bullet verbatim from the Read view, never from a shell view. The path is relative to the checkout root; an agent resolves it under `WORKTREE_PATH` when one is provided.
 
 ```
 --- Feature knowledge: {slug} ---
@@ -139,11 +109,9 @@ Rules:
 Headings: L5 Rules · L40 Overview · L62 Anti-Patterns · L118 Key Files
 ```
 
-A KB with no Rules section labels its entries `Rules ({section name}):` and gives them no ID. `FEATURE_KNOWLEDGE` is these blocks; `FEATURE_KNOWLEDGE_RULES` is the same blocks without the `Headings:` line. Both come from this one selection, and each spawn names the variable its recipient takes. If no KBs exist, no KBs are relevant, or `.devflow/features/` is absent, set both to `(none)`.
-
-**One git call, then direct reads — no `.cjs` script.**
+A KB with no Rules section labels its entries `Rules ({section name}):` and gives them no ID. `FEATURE_KNOWLEDGE` is these blocks; `FEATURE_KNOWLEDGE_RULES` is the same blocks without the `Headings:` line. If no KBs exist, no KBs are relevant, or `.devflow/features/` is absent, set both to `(none)`.
 
-Use `FEATURE_KNOWLEDGE` **locally** for research framing. Pass to each Research agent in Phase 4.
+Use `FEATURE_KNOWLEDGE` locally for research framing. Pass to each Research agent in Phase 4.
 
 ### Phase 2: Requirements
 
@@ -158,7 +126,7 @@ Analyze the research question to infer research types needed (min 2, max 5). For
 - `RESEARCH_QUESTION`: Focused sub-question for this type
 - `OUTPUT_PATH`: `{worktree}/.devflow/docs/research/{topic-slug}/{YYYY-MM-DD_HHMM}/{type}.md`
 
-**Tool availability check**: If WebSearch/WebFetch are unavailable, restrict to `codebase` type only.
+**Tool availability check**: If WebSearch/WebFetch are unavailable, restrict to `codebase` type only, telling the user why.
 
 ### Phase 3: Orient (Conditional)
 
@@ -184,8 +152,6 @@ Each Research agent receives:
 - `ORIENT_OUTPUT`: Only for `codebase` type
 - `WORKTREE_PATH`: If in a worktree context
 
-Each Research agent writes findings to disk at OUTPUT_PATH.
-
 ### Phase 5: Synthesize
 
 **Produces:** RESEARCH_SUMMARY
@@ -208,6 +174,7 @@ Output: {worktree}/.devflow/docs/research/{topic-slug}/{YYYY-MM-DD_HHMM}/researc
 **Requires:** RESEARCH_SUMMARY
 
 Present findings to user with:
+- The research folder `{worktree}/.devflow/docs/research/{topic-slug}/{YYYY-MM-DD_HHMM}/`
 - Trust annotations per finding: (trusted) for codebase, (untrusted) for web, (mixed) for technology
 - Explicit conflicts between codebase and web findings
 - Drill-down offer via AskUserQuestion
@@ -229,49 +196,13 @@ If external research was skipped due to tool unavailability: inform user.
 
 ## Worktree Support
 
-If the orchestrator receives a `WORKTREE_PATH` context (e.g., from multi-worktree workflows), pass it through to all spawned agents. Each agent's "Worktree Support" section handles path resolution.
-
-## Output
-
-Research findings saved to `{worktree}/.devflow/docs/research/{topic-slug}/{YYYY-MM-DD_HHMM}/`:
-- `{type}.md` per research type (codebase.md, external.md, etc.)
-- `research-summary.md` — synthesized findings with trust annotations
-
-## Architecture
-
-```
-/research (orchestrator)
-│
-├─ Phase 1: Load Decisions (Orchestrator-Local)
-│
-├─ Phase 2: Requirements
-│  └─ Infer 2-5 research types from question
-│
-├─ Phase 3: Orient (conditional — codebase type only)
-│  └─ Skim agent (codebase overview)
-│
-├─ Phase 4: Parallel Research agents
-│  └─ 2-5 Research agents in single message (all types simultaneously)
-│
-├─ Phase 5: Synthesize
-│  └─ Synthesize agent merges findings with trust-aware aggregation
-│
-├─ Phase 6: Present findings with trust annotations and drill-down offer
-│
-└─ Phase 7: Suggest feature knowledge creation (conditional)
-   └─ Knowledge agent (if codebase type researched + user accepts)
-```
+If the orchestrator receives a `WORKTREE_PATH` context, pass it through to all spawned agents.
 
 ## Principles
 
-1. **Parallel perspectives** — Multiple research types converge on truth better than any single perspective
-2. **Trust transparency** — Every finding is labeled with its trust level (trusted/untrusted/mixed)
-3. **Conflict surfacing** — Contradictions between codebase and web findings are highlighted, not hidden
-4. **Evidence over opinion** — All claims require citations (file:line or URL)
+1. **Evidence over opinion** — All claims require citations (file:line or URL)
 
 ## Error Handling
 
-- If WebSearch/WebFetch unavailable: restrict to codebase type, inform user
 - If a Research agent fails: continue with remaining outputs, note gap in synthesis
 - If Synthesize agent fails: present individual Research agent outputs directly
-- If feature knowledge creation fails: log failure, report research results normally