devflow-kit 3.3.0 → 3.4.0

package/dist/learning-off/commands/release.md

@@ -0,0 +1,310 @@
+---
+description: Release project using adaptive learned configuration
+---
+
+# Release Command
+
+Release the project using adaptive learned configuration. On first run, scans the codebase to detect the release process and stores it in `.release/RELEASE-FLOW.md`. Subsequent releases use the stored config, skipping discovery.
+
+## Usage
+
+```
+/release v1.2.3          (explicit version)
+/release patch           (bump type: patch | minor | major)
+/release --dry-run       (simulate release, show plan without executing)
+/release                 (interactive: ask for version)
+```
+
+## Input
+
+What follows `/release` is bound once, here. Every later step names it `COMMAND_INPUT` and never restates it:
+
+<command-input>
+$ARGUMENTS
+</command-input>
+
+`COMMAND_INPUT` is one of:
+- Explicit version: `v1.2.3` or `1.2.3`
+- Bump type: `patch`, `minor`, `major`
+- Flag: `--dry-run`
+- Empty: interactive mode (will ask for version)
+
+Parse from `COMMAND_INPUT`:
+- `VERSION`: explicit version string if present (strip leading `v`)
+- `BUMP_TYPE`: `patch | minor | major` if bump type provided
+- `DRY_RUN`: true if `--dry-run` present, false otherwise
+
+## Phases
+
+### Phase 1: Load Config
+
+**Produces:** RELEASE_CONFIG, CONFIG_STATE (`learned` | `fresh`)
+
+**Load Companion Skills** — Load via Skill tool: `devflow:git`. If a skill fails to load, continue without it.
+
+**Continuation detection**: Check `.release/.progress.json`. If exists, an interrupted release is in progress. Offer user:
+- **Resume**: continue from last checkpoint (skip phases already completed)
+- **Restart**: clean start (delete `.release/.progress.json` and begin from Phase 1)
+
+Read `.release/RELEASE-FLOW.md`:
+- If exists → parse as structured config, set CONFIG_STATE = learned, skip to Phase 4
+- If missing → set CONFIG_STATE = fresh, continue to Phase 2
+
+### Phase 1b: Load Context
+
+**Produces:** FEATURE_KNOWLEDGE, FEATURE_KNOWLEDGE_RULES
+
+### 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
+
+```bash
+git -C "{start}" rev-parse --show-toplevel
+```
+
+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}
+```
+
+If `index.md` exists and contains at least one entry line, use it for relevance matching.
+
+**Step 2 — Fallback: glob frontmatter (if `index.md` is absent or empty):**
+
+Glob `{worktree}/.devflow/features/*/KNOWLEDGE.md`. For each file found, read only its YAML frontmatter block (between the opening and closing `---` delimiters). The frontmatter fields `name`, `description`, and `directories` are the authoritative relevance surface — `index.md` is only a cache.
+
+**Step 3 — Pick relevant KBs:**
+
+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.
+
+**Step 4 — Read each selected KB's Rules:**
+
+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.
+
+```
+--- Feature knowledge: {slug} ---
+KB: .devflow/features/{slug}/KNOWLEDGE.md
+Rules:
+- **KB-AP-2** {bullet text, verbatim}
+- **KB-INV-1** {bullet text, verbatim}
+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.** After resolving `{worktree}`, this step is 1 index read (or N frontmatter reads on fallback), plus one heading listing and one Rules read per selected KB, bounded by KB count.
+
+Pass `FEATURE_KNOWLEDGE` only to agents whose contract declares it; the Validate and Git agents this command spawns do not.
+
+### Phase 1c: Resolve the Evidence Policy
+
+**Produces:** EVIDENCE_POLICY, ISSUE_REQUIRED, APPLY_CONVENTIONS, REQUIRE_NON_AUTHOR_APPROVAL
+
+**Resolve the evidence policy once per run**, from the repository root, before any step reads the values:
+
+```bash
+node "$HOME/.devflow/scripts/resolve-evidence-policy.cjs" 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 `EVIDENCE_POLICY=<required|standard> SOURCE=<file|worktree|default|invalid|error> REF=<branch|none>[ WARN=<remote-unavailable|invalid-file|raised-by-compliance|pr-changes-policy>[,…]] ISSUE_REQUIRED=<true|false> APPLY_CONVENTIONS=<true|false> REQUIRE_NON_AUTHOR_APPROVAL=<true|false>` — these fields, in this order, nothing else, where `<branch>` is a branch name such as `main`. **Anything else** (a non-zero exit, no line, extra text, or a missing, reordered or unlisted field or value) ⇒ use `EVIDENCE_POLICY=required SOURCE=error REF=none ISSUE_REQUIRED=true APPLY_CONVENTIONS=true REQUIRE_NON_AUTHOR_APPROVAL=true` instead.
+
+Set `EVIDENCE_POLICY`, `ISSUE_REQUIRED`, `APPLY_CONVENTIONS` and `REQUIRE_NON_AUTHOR_APPROVAL` from the accepted line. Pass agents only the three mechanism inputs, never `EVIDENCE_POLICY`. Report `Evidence policy: {EVIDENCE_POLICY} (source: {SOURCE})`, plus any `WARN` tokens as advisory, once in the final report.
+
+Reuse this result for all subsequent phases: it decides whether a real release gathers and traces its evidence (Phases 4–5), passes it to the release notes (step 4), and back-links shipped issues and associates them with the release (steps 4b–4c).
+
+### Phase 2: Detect Release Process (First Run Only)
+
+**Produces:** RELEASE_SIGNALS
+**Requires:** CONFIG_STATE = fresh
+
+Tiered codebase scan to detect the project's release process:
+
+**Tier 1** — Read these if they exist: `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `Dockerfile`, `.github/workflows/*.yml`, `CHANGELOG.md`
+
+**Tier 2** — Broaden: monorepo indicators (`lerna.json`, `pnpm-workspace.yaml`, `turbo.json`), release tool configs (`.releaserc`, `.changeset/`, `release-please-config.json`)
+
+**Tier 3** — Git history: `git tag -l` for tag format, `git log --oneline -20` for conventions
+
+Skip credential files (`.env*`, `*credentials*`, `*secret*`, `*.key`). Max 20 files total.
+
+### Phase 3: Build Config (First Run Only)
+
+**Produces:** RELEASE_CONFIG (written to disk)
+**Requires:** RELEASE_SIGNALS
+
+Map RELEASE_SIGNALS to `.release/RELEASE-FLOW.md` with sections: Packages, Pre-release Checks, Changelog, Build & Test, Publish, Post-release.
+
+**Conventions naming:** Consult `.devflow/conventions.md` (the naming authority written by the Git `learn-conventions` operation) for version/tag/version-PR title conventions. When the branching model uses version PRs, follow the Version PR Titles convention recorded there; compliance defaults when the file is absent. When the repo uses a main+integration branching model, ship via a version PR per the recorded convention. Re-learn by deleting `.devflow/conventions.md` — the next Git `learn-conventions` call rewrites it.
+
+Use AskUserQuestion for any gaps that cannot be inferred.
+
+Lazy-init `.release/` directory. Create `.release/.gitignore` with `.progress.json` and `.lock/`.
+
+### Phase 4: Pre-release Checks
+
+**Produces:** PRE_RELEASE_RESULT, VERSION, RELEASE_EVIDENCE
+**Requires:** RELEASE_CONFIG, EVIDENCE_POLICY
+
+**Version determination** (in order):
+1. Explicit version from args → use directly
+2. Bump type from args → compute from current version
+3. `semver-auto` strategy → analyze commits since the last release tag: the tag that `node "$HOME/.devflow/scripts/release-trace.cjs" last-tag`, run from the repository root, prints as `LAST_TAG <tag>` (`LAST_TAG none` ⇒ the initial commit) — never `git describe`, which can return a local marker tag
+4. None → use AskUserQuestion
+
+Pre-release checks:
+- Clean working directory (`git status --porcelain`)
+- Tag does not already exist
+- Custom checks from RELEASE_CONFIG
+
+Spawn `Agent(subagent_type="Validate")` for build + test.
+
+**Gather release evidence** — under either policy when `DRY_RUN` is true, otherwise only when `EVIDENCE_POLICY` is `required`: spawn `Agent(subagent_type="Git")` with `gather-release-evidence` operation; pass `WORKTREE_PATH` if provided. Keep `COMMIT_LIST`, `SHIPPED_ISSUES`, `### TRACE_MAP` and `### Status:` as RELEASE_EVIDENCE. The Git agent applies its own bounds (≤100 commits, ≤50 issues, 500 traced commits) and degrades gracefully per D4.
+
+Unless `DRY_RUN` is true, write `.release/.progress.json` checkpoint, with RELEASE_EVIDENCE when it was gathered — a dry run leaves nothing to resume.
+
+`--dry-run`: report what would happen and, when evidence was gathered, the Phase 5 traceability arms, the untraced list and the exempt counts — never asking — then **halt after this phase**.
+
+### Phase 5: Build Release Plan
+
+**Produces:** RELEASE_PLAN, TRACEABILITY_EXCEPTIONS
+**Requires:** PRE_RELEASE_RESULT, RELEASE_CONFIG, VERSION, RELEASE_EVIDENCE
+
+**Traceability** (only when `EVIDENCE_POLICY` is `required`), before the confirm below. Classify RELEASE_EVIDENCE by its `### Status:` value — `READY`, `PARTIAL`, `TRUNCATED`, `DEGRADED` or `INDETERMINATE` — and by the first `### TRACE_MAP` line, `TRACE from:<ref> scanned:<n> traced:<n> untraced:<n> exempt:<n> unmatched:<n> bound:<ok|hit>`. Let *u* be its `untraced` count, and re-check traced + untraced + exempt = scanned yourself. Every arm that matches applies:
+
+1. **Coverage unknown** — no gather ran, its output is missing or unparseable, there is no `TRACE` line, the sum does not hold, `bound:hit`, status `INDETERMINATE`, or a status that is none of the five.
+2. **Untraced** — *u* > 0.
+3. **Partial** — status `PARTIAL`, `TRUNCATED` or `DEGRADED`: warn and continue; this arm never blocks on its own. A tracker with no closing-reference capability always lands here.
+4. **Clean** — status `READY` and *u* = 0, and no arm above.
+
+Arm 1 or 2 ⇒ first show the attestation list, copied from `### TRACE_MAP`: every listed `untraced` line's `<sha12>` and author (≤100), the `…and <n> more` line that closes the untraced list when there is one, and each exempt kind's count with every listed exempt SHA — the commits **Record** attests to, and those the `Exempt` line prints.
+
+Arm 1 or 2 ⇒ ask once, via AskUserQuestion: "{u} untraced commits{, coverage unknown: {cause}}. Record self-attested traceability exceptions, or halt?", with exactly two options:
+- **Record** — ask for the reason in the user's own words; if it renders empty, ask once more, then halt. Compose `TRACEABILITY_EXCEPTIONS` below and add it to `.release/.progress.json`.
+- **Halt** — stop now: nothing has been committed, tagged or published.
+
+`TRACEABILITY_EXCEPTIONS` is this block, and no commit subject is ever written into it:
+
+```markdown
+## Traceability exceptions
+- `untraced` <sha12> (<author>) self-attested by @<login> at <utc>: <reason>
+- `coverage` <bound-hit|trace-unavailable|gather-indeterminate|untraced-beyond-list> self-attested by @<login> at <utc>: <reason>
+Exempt (not attested): release <n> · revert <n> · bot <n> — <sha12>, …
+```
+
+- One `untraced` line per listed untraced commit (≤100), its `<sha12>` and `<author>` copied from that `### TRACE_MAP` line. One `coverage` line per arm-1 cause — `bound-hit` for `bound:hit`, `gather-indeterminate` for status `INDETERMINATE` or none of the five, `trace-unavailable` for any other — plus `untraced-beyond-list` when an `…and <n> more` line closes the untraced list. The `Exempt` line counts each exempt kind (its listed lines plus its `…and <n> more`) and names every listed exempt SHA.
+- `@<login>` is `@` followed by the output of `gh api user --jq .login` when that output matches `^[A-Za-z0-9][A-Za-z0-9-]{0,38}$`. On any other output, or a failed call, it is `(login unavailable)` instead, with no `@`.
+- `<utc>` is the output of `date -u +%Y-%m-%dT%H:%M:%SZ`.
+- `<reason>` is the user's own words, made inert: replace every character outside printable ASCII (newlines and tabs included) with a space, remove every `<`, `>`, `` ` ``, `[`, `]`, `\`, `/`, `#`, `@`, `&` and `$`, collapse runs of spaces, trim, keep the first 200 characters, and trim again. A reason that is empty after this is no reason.
+
+No ask, but the trace lists an exempt commit ⇒ `TRACEABILITY_EXCEPTIONS` is the heading and the `Exempt` line alone, added to `.release/.progress.json` the same way: an exemption is self-asserted, so it is printed, never hidden.
+
+Build ordered execution plan from RELEASE_CONFIG. For monorepo: respect dependency ordering, present package selection to user.
+
+Confirm with user via AskUserQuestion before executing:
+"Ready to release v{VERSION}. Plan: {steps summary}. Proceed?"
+
+`--dry-run`: should already be halted from Phase 4.
+
+### Phase 6: Execute Release
+
+**Produces:** RELEASE_RESULT
+**Requires:** RELEASE_PLAN, VERSION, EVIDENCE_POLICY, RELEASE_EVIDENCE, TRACEABILITY_EXCEPTIONS
+
+Sequential execution with progress checkpoints:
+1. **Version bumps** — write new version to configured files
+2. **Changelog update** — move Unreleased section to versioned entry (if configured)
+3. **Release commit** — `chore(release): v{VERSION}` (conventional commit)
+4. **Tag and GitHub Release** — spawn `Agent(subagent_type="Git")` with `create-release` operation (the agent reads `.devflow/conventions.md` for tag format and release title conventions; compliance defaults when absent); only when `EVIDENCE_POLICY` is `required`, also pass `COMMIT_LIST` and `SHIPPED_ISSUES` from RELEASE_EVIDENCE, and `TRACEABILITY_EXCEPTIONS` when composed (Record, or the no-ask exempt rule), as inputs so the agent includes them in the release notes body.
+4b. **Back-link shipped issues** (only when `EVIDENCE_POLICY` is `required`) — spawn `Agent(subagent_type="Git")` with `backlink-shipped-issues` operation, passing `VERSION` and `SHIPPED_ISSUES`; posts a marker-deduped comment on each issue (bounds and throttle enforced by the operation); degrade gracefully (D4) on any API failure — never block the release
+4c. **Associate shipped issues with the release** (only when `EVIDENCE_POLICY` is `required` and `SHIPPED_ISSUES` is non-empty) — spawn `Agent(subagent_type="Git")` with `associate-release` operation, passing `VERSION` and `SHIPPED_ISSUES`; it adds each issue to the release's tracker marker and never replaces another; degrade gracefully (D4) — never block the release
+5. **Publish** — CI-driven (report) or manual (provide instructions)
+6. **Post-release steps** — version bump to next dev
+
+**Resume:** a checkpoint missing the RELEASE_EVIDENCE its Phase 4 gate called for is gathered again, with Phase 5's traceability step re-run, only before step 4; after step 4, report `evidence lost on resume` and continue — never block.
+
+Delete `.release/.progress.json` on success.
+
+### Phase 7: Suggest Improvements
+
+**Requires:** RELEASE_RESULT
+
+Post-release analysis for improvement opportunities. Present as suggested diffs to RELEASE-FLOW.md. Never auto-apply. Fire-and-forget.
+
+## Worktree Support
+
+If the orchestrator receives a `WORKTREE_PATH` context, pass it through to all spawned agents. Each agent's "Worktree Support" section handles path resolution.
+
+## Output
+
+On completion:
+- Git tag created: `v{VERSION}` (or configured tag format)
+- GitHub Release created with release notes — `## Traceability exceptions` last, when composed (Record, or the no-ask exempt rule)
+- Changelog updated (if configured)
+- Version files bumped
+- `.release/RELEASE-FLOW.md` created (first run only)
+
+## Architecture
+
+```
+/release (orchestrator)
+│
+├─ Phase 1: Load Config
+│  └─ Read .release/RELEASE-FLOW.md (learned) or proceed to detect (fresh)
+│
+├─ Phase 1b: Load Context
+│  └─ Load FEATURE_KNOWLEDGE for the agents that declare it
+│
+├─ Phase 2: Detect Release Process (first run only)
+│  └─ Tiered scan: package.json, CI workflows, git history
+│
+├─ Phase 3: Build Config (first run only)
+│  └─ Write .release/RELEASE-FLOW.md
+│
+├─ Phase 4: Pre-release Checks
+│  ├─ Validate agent (build + test)
+│  ├─ Git agent: gather release evidence + trace map (dry run, or evidence policy required)
+│  └─ Write progress checkpoint
+│
+├─ Phase 5: Build Release Plan
+│  ├─ Traceability: classify the trace map; record exceptions or halt (evidence policy required)
+│  └─ Confirm with user before executing
+│
+├─ Phase 6: Execute Release
+│  ├─ Version bumps → Changelog → Commit → Git agent (tag + release) → Back-link → Associate → Publish → Post-release
+│  └─ Progress checkpoints between each step
+│
+└─ Phase 7: Suggest Improvements
+   └─ Suggested diffs to RELEASE-FLOW.md (never auto-applied)
+```
+
+## Principles
+
+1. **Learn once, reuse always** — discovery happens on first run; subsequent releases skip it
+2. **Config is data, not code** — structured config fields map to pre-defined operations, never raw shell commands
+3. **Checkpoint-resume** — progress file enables safe resume of interrupted releases
+4. **User confirms before execution** — release plan is presented for approval before any tags or commits
+
+## Error Handling
+
+- Validate agent fails (build/test): halt, report failures, do not proceed
+- User declines release plan: halt gracefully
+- User halts at the traceability question: stop — nothing has been committed, tagged or published
+- Git agent reports DEGRADED while gathering, back-linking or associating: warn and continue — never halt the release
+- Git agent fails (tag/release): halt, report error, suggest manual steps
+- Mid-release failure: progress checkpoint enables resume on next run
+- Version file not found: halt, report which file is missing, ask user to update RELEASE-FLOW.md

package/dist/learning-off/commands/research.md

@@ -0,0 +1,222 @@
+---
+description: Research a topic using parallel multi-type Research agents with 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
+
+```
+/research "best caching strategies"
+/research "compare React vs Svelte for our use case"
+/research "what open-source competitors exist"
+/research "how does our auth system work and what are the industry alternatives"
+```
+
+## Input
+
+What follows `/research` is bound once, here. Every later step names it `COMMAND_INPUT` and never restates it:
+
+<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
+
+## Phases
+
+### Phase 1: Load Context (Orchestrator-Local)
+
+**Produces:** 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
+
+```bash
+git -C "{start}" rev-parse --show-toplevel
+```
+
+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.
+
+### 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
+
+```bash
+git -C "{start}" rev-parse --show-toplevel
+```
+
+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}
+```
+
+If `index.md` exists and contains at least one entry line, use it for relevance matching.
+
+**Step 2 — Fallback: glob frontmatter (if `index.md` is absent or empty):**
+
+Glob `{worktree}/.devflow/features/*/KNOWLEDGE.md`. For each file found, read only its YAML frontmatter block (between the opening and closing `---` delimiters). The frontmatter fields `name`, `description`, and `directories` are the authoritative relevance surface — `index.md` is only a cache.
+
+**Step 3 — Pick relevant KBs:**
+
+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.
+
+**Step 4 — Read each selected KB's Rules:**
+
+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.
+
+```
+--- Feature knowledge: {slug} ---
+KB: .devflow/features/{slug}/KNOWLEDGE.md
+Rules:
+- **KB-AP-2** {bullet text, verbatim}
+- **KB-INV-1** {bullet text, verbatim}
+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.** After resolving `{worktree}`, this step is 1 index read (or N frontmatter reads on fallback), plus one heading listing and one Rules read per selected KB, bounded by KB count.
+
+Use `FEATURE_KNOWLEDGE` **locally** for research framing. Pass to each Research agent in Phase 4.
+
+### Phase 2: Requirements
+
+**Produces:** RESEARCH_PLAN
+
+Analyze the research question to infer research types needed (min 2, max 5). For each type:
+- `RESEARCH_TYPE`: `codebase | external | market | competitor | technology`
+- `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.
+
+Generate topic slug from the research question (kebab-case, lowercase, no articles).
+
+### Phase 3: Orient (Conditional)
+
+**Produces:** ORIENT_OUTPUT
+
+Only if `codebase` type is in RESEARCH_PLAN.
+
+Spawn `Agent(subagent_type="Skim")` targeting codebase areas relevant to the research question.
+
+Skip and set ORIENT_OUTPUT = "(none)" if `codebase` type is not in RESEARCH_PLAN.
+
+### Phase 4: Parallel Research agents
+
+**Produces:** RESEARCH_OUTPUTS
+**Requires:** RESEARCH_PLAN, ORIENT_OUTPUT (optional)
+
+Spawn 2-5 `Agent(subagent_type="Research")` agents **in a single message** (parallel execution).
+
+Each Research agent receives:
+- `RESEARCH_TYPE`, `RESEARCH_QUESTION`, `OUTPUT_PATH` from RESEARCH_PLAN
+- `FEATURE_KNOWLEDGE`: `{feature_knowledge}` from Phase 1
+- `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
+**Requires:** RESEARCH_OUTPUTS
+
+Spawn `Agent(subagent_type="Synthesize")` in `research` mode:
+- Reads Research agent outputs from RESEARCH_OUTPUTS paths
+- Merges findings with trust-aware aggregation
+- Writes `research-summary.md` to the same timestamped directory
+
+Output path: `{worktree}/.devflow/docs/research/{topic-slug}/{timestamp}/research-summary.md`
+
+### Phase 6: Present
+
+**Requires:** RESEARCH_SUMMARY
+
+Present findings to user with:
+- 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
+
+If external research was skipped due to tool unavailability: inform user.
+
+### Phase 7: Feature Knowledge Creation (Conditional)
+
+**Requires:** RESEARCH_SUMMARY
+**Produces:** FEATURE_KNOWLEDGE_STATUS (created | skipped)
+
+1. If `codebase` type was not in RESEARCH_PLAN → skip
+2. Check if matching feature knowledge already exists by reading `{worktree}/.devflow/features/index.md` (or globbing frontmatter if absent). If covered → skip
+3. Use AskUserQuestion: "No feature knowledge exists for {researched area}. Create one?"
+4. If user accepts: spawn `Agent(subagent_type="Knowledge")` with researched area context + worktree root, instructing it to write `KNOWLEDGE.md` and update `index.md` directly
+5. Set FEATURE_KNOWLEDGE_STATUS = created or skipped
+
+**Failure handling**: Non-blocking. If Knowledge agent fails, log and continue.
+
+## 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 Context (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)
+```
+
+## 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)
+
+## 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