devflow-kit 3.11.0 → 3.12.1

package/dist/commands/explore.md

@@ -1,10 +1,8 @@
 ---
-description: Explore codebase with structured analysis and optional feature knowledge creation
+description: Explore codebase with structured analysis; optionally build feature knowledge
 ---
 # Explore Command
 
-Explore a codebase area by spawning parallel agents for flow tracing, dependency mapping, and pattern analysis. Findings are synthesized into structured output with file:line references, with optional feature knowledge created as a byproduct.
-
 ## Usage
 
 ```
@@ -21,10 +19,7 @@ What follows `/explore` is bound once, here. Every later step names it `COMMAND_
 $ARGUMENTS
 </command-input>
 
-`COMMAND_INPUT` is one of:
-- Area description: "how does the auth system work"
-- Flow question: "trace the request lifecycle"
-- Empty: use conversation context
+An empty `COMMAND_INPUT` means: use the conversation context.
 
 ## Phases
 
@@ -32,42 +27,33 @@ $ARGUMENTS
 
 **Produces:** DECISIONS_CONTEXT
 
-**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.
 
-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`):
+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.
+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.
 
-**Step 1 — Read the pre-rendered index:**
+**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)`.
 
-Attempt to read `{ledger}/.devflow/curation/index.md`.
-
-- 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)`.
-
-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:**
 
@@ -75,11 +61,9 @@ 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.
-
-The orchestrator uses `DECISIONS_CONTEXT` locally when framing exploration — prior decisions and pitfalls suggest specific areas to investigate. Follow `devflow:apply-decisions` to Read full entry bodies on demand. **Do NOT pass `DECISIONS_CONTEXT` to Explore sub-agents** — decisions context stays in the orchestrator, not in the investigation workers.
+Use `DECISIONS_CONTEXT` locally to frame the exploration. Follow `devflow:apply-decisions` to Read full entry bodies on demand. **Do NOT pass `DECISIONS_CONTEXT` to Explore sub-agents** — decisions context stays in the orchestrator, not in the investigation workers.
 
-**No up-front feature knowledge load** — explore investigation workers read code directly to avoid confirmation bias. Feature knowledge is only created as a write-back at the end, after exploration is complete.
+**No up-front feature knowledge load** — explore investigation workers read code directly to avoid confirmation bias.
 
 ### Phase 2: Orient
 
@@ -141,31 +125,30 @@ Present findings to user. Use AskUserQuestion to offer focused follow-up explora
 
 ### Feature Knowledge Write-Back (Conditional)
 
-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}`.
+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.
 
-**Step 1 — Check the opt-out gate, with `{root}` = `{worktree}`:** take the settings line resolved above for that root, resolving it with the settings block when this run has not yet.
+All paths below are relative to `{worktree}`.
 
-If the settings line says `KNOWLEDGE=off`, skip write-back entirely. The machine switch (`devflow knowledge --disable`), the repository and the personal settings can each turn knowledge off, and none can turn it back on (D-FEATURES-NARROW-ONLY). The fail-closed line says `KNOWLEDGE=off` too, so an unresolvable line skips write-back.
+**Step 1 — Check the opt-out gate, with `{root}` = `{worktree}`:** take the settings line resolved above for that root, resolving it with the settings block when this run has not yet.
 
-**Step 2 — Evaluate whether write-back is warranted:**
+If the settings line says `KNOWLEDGE=off`, skip write-back entirely. The fail-closed line says `KNOWLEDGE=off` too.
 
-Only proceed if **at least one** of these is true:
+**Step 2 — Write back only if at least one is true:**
 - This workflow changed files in a directory that is documented by an existing feature knowledge base (a documented area changed). Knowledge bases are written through at that point, never on a background schedule.
-- This workflow surfaced durable, cross-cutting knowledge about a codebase area that would help future agents working in the same area — patterns, anti-patterns, integration points, gotchas not visible from a single file read.
+- This workflow found durable, cross-cutting knowledge about a codebase area that future agents in that area need: patterns, anti-patterns, integration points, gotchas that a single file read does not show.
 
-**Never spawn unconditionally.** If neither condition is met, skip write-back silently.
+Otherwise skip write-back silently.
 
 **Step 3 — Spawn the Knowledge agent:**
 
-Spawn `Agent(subagent_type="Knowledge")` with the following context:
-
 ```
+Agent(subagent_type="Knowledge"):
 "WORKTREE_PATH: {worktree root}
 FEATURE_SLUG: {slug derived from primary changed directory, kebab-case}
 FEATURE_NAME: {human-readable name}
@@ -186,9 +169,9 @@ Then commit the two files as your Commit Protocol directs."
 
 **Step 4 — Surface an uncommitted knowledge base:**
 
-When the Knowledge agent reports `KB_COMMIT: skipped (detached HEAD)`, the files were written but deliberately not committed — a commit on a detached HEAD becomes unreachable once HEAD moves. Tell the user in the workflow's final report, in one line, that the knowledge base was written but not committed, and name the uncommitted paths the agent listed, so they can commit them on a branch before the worktree is removed. Never commit them yourself.
+When the Knowledge agent reports `KB_COMMIT: skipped (detached HEAD)`, tell the user in the workflow's final report, in one line, that the knowledge base was written but not committed, and name the uncommitted paths the agent listed, so they can commit them on a branch. Never commit them yourself.
 
-**Failure handling**: Non-blocking. If the Knowledge agent fails, log the failure and continue — the workflow outcome is not affected by write-back success.
+Non-blocking: if the Knowledge agent fails, log the failure and continue.
 
 Set FEATURE_KNOWLEDGE_STATUS = created (if agent spawned) or skipped.
 
@@ -196,7 +179,7 @@ Set FEATURE_KNOWLEDGE_STATUS = created (if agent spawned) or skipped.
 
 ## 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.
+If the orchestrator receives a `WORKTREE_PATH` context, pass it through to all spawned agents.
 
 ## Output
 
@@ -209,38 +192,12 @@ Structured exploration findings with concrete code references:
 - Patterns (recurring conventions, design decisions observed)
 - Key Insights (non-obvious findings, surprises, potential concerns)
 
-## Architecture
-
-```
-/explore (orchestrator)
-│
-├─ Phase 1: Load Decisions (Orchestrator-Local)
-│
-├─ Phase 2: Orient
-│  └─ Skim agent (codebase overview)
-│
-├─ Phase 3: Parallel exploration
-│  └─ 2-3 Explore agents (flow, dependency, pattern) in single message
-│
-├─ Phase 4: Synthesize
-│  └─ Synthesize agent aggregates findings in exploration mode
-│
-├─ Phase 5: Present findings with drill-down offer
-│
-└─ Phase 6: Suggest feature knowledge creation (conditional)
-   └─ Knowledge agent write-back (if user accepts and no existing feature knowledge)
-```
-
 ## Principles
 
 1. **Structure over browsing** - Every claim must cite file:line references
-2. **Parallel execution** - All explorers run simultaneously for speed
-3. **Knowledge-informed** - Prior decisions guide where to look; NO pre-loaded feature knowledge in sub-agents (avoids confirmation bias)
-4. **User-driven depth** - Present findings, then offer drill-down into specific areas
 
 ## Error Handling
 
 - If Skim agent returns no relevant files: report "No files found matching exploration scope"
 - If all explorers error: report partial findings from any that succeeded, note gaps
 - If an explorer errors: continue with remaining results, note the gap
-- If feature knowledge creation fails: log failure, report exploration results normally