devflow-kit 3.3.0 → 3.5.0

package/dist/commands/plan.md

@@ -109,14 +109,25 @@ If the user says "skip" or "just proceed" — skip remaining questions, present
 
 #### Phase 2: Orient + Load Decisions
 
-**Produces:** SKIM_CONTEXT, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE
+**Produces:** SKIM_CONTEXT, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, FEATURE_KNOWLEDGE_RULES
 **Requires:** CONFIRMED_SCOPE
 
+**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 when the run has one worktree:
+
+```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> LEARNING=<on|off> KNOWLEDGE=<on|off>` — 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=on LEARNING=on KNOWLEDGE=off` instead.
+
+The accepted line is the only source of these values: the script alone folds the committed `.devflow/project.json`, the personal `.devflow/config.json` and the machine manifest.
+
 Spawn Skim agent for codebase context:
 
 ```
 Agent(subagent_type="Skim"):
 "Orient in codebase for design planning: {feature/issues}
+LEARNING: {LEARNING from the settings line}
 Run rskim on source directories (NOT repo root) to identify:
 - Existing patterns and conventions in the affected area
 - File structure and module boundaries
@@ -135,6 +146,8 @@ and using its one-line output. If the command fails (outside a git repository),
 
 ### Load DECISIONS_CONTEXT
 
+When the settings line says `LEARNING=off`, set `DECISIONS_CONTEXT` to `(none)` and skip this step, locating no ledger and reading no index.
+
 The decisions ledger belongs to the repository, not to one checkout: in a linked worktree it lives in the main worktree, and a session started in a subdirectory reads the copy at the repository root. Locate it with ONE git call, run from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`):
 
 ```bash
@@ -158,11 +171,11 @@ Attempt to read `{ledger}/.devflow/learning/index.md`.
 
 The index is one direct file read, written at render time by `render-decisions.cjs` alongside `decisions.md`/`pitfalls.md` — no `.cjs` script runs here, and the index's own footer names the files that hold each entry's full body.
 
-**Step 2 — Apply decisions using `devflow:apply-decisions`:**
+**Step 2 — Agents apply the decisions:**
 
-When `DECISIONS_CONTEXT` is not `(none)`, follow `devflow:apply-decisions` to scan the index, identify plausibly-relevant entries, Read full entry bodies on demand, and cite verbatim IDs in downstream agent prompts and reasoning.
+When `DECISIONS_CONTEXT` is not `(none)`, hand it only to the agents whose contract declares it. They follow `devflow:apply-decisions`: scan the index, identify plausibly-relevant entries, Read full entry bodies on demand, and cite verbatim IDs in their reasoning. A host that uses the index in its own thread says so in its own step.
 
-This produces a compact index of active ADR/PF entries. Pass Skim agent context and `DECISIONS_CONTEXT` to all subsequent agents — prior decisions constrain design, known pitfalls inform gap analysis. Agents use `devflow:apply-decisions` to Read full entry bodies on demand.
+This produces a compact index of active ADR/PF entries. Pass the Skim agent context to all subsequent agents. Pass `DECISIONS_CONTEXT` to the Design agents of the gap-analysis phase — prior decisions constrain design, known pitfalls inform gap analysis. Design agents use `devflow:apply-decisions` to Read full entry bodies on demand.
 
 ### Load Feature Knowledge
 
@@ -192,31 +205,41 @@ Glob `{worktree}/.devflow/features/*/KNOWLEDGE.md`. For each file found, read on
 
 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 selected KBs:**
+**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.
 
-For each selected entry, read `{worktree}/.devflow/features/{slug}/KNOWLEDGE.md` in full. When the KB content contradicts the current code you observe, **trust the code** — the code is the freshness mechanism; the KB may lag behind.
+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:**
+**Step 5 — Set FEATURE_KNOWLEDGE and FEATURE_KNOWLEDGE_RULES:**
 
-Concatenate the selected KNOWLEDGE.md files under slug headers:
+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} ---
-{full KNOWLEDGE.md content}
+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
 ```
 
-If no KBs exist, no KBs are relevant, or `.devflow/features/` is absent, set `FEATURE_KNOWLEDGE` to `(none)`.
+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 file reads — no `.cjs` script.** After resolving `{worktree}`, this step is 1 index read (or N frontmatter reads on fallback), bounded by KB count.
+**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` alongside `DECISIONS_CONTEXT` to Explore and Design agents.
+Pass `FEATURE_KNOWLEDGE` to Explore and Design agents. Pass `DECISIONS_CONTEXT` to Design agents only.
 
 #### Phase 3: Explore Requirements (Parallel)
 
 **Produces:** EXPLORE_OUTPUTS
-**Requires:** SKIM_CONTEXT, DECISIONS_CONTEXT
+**Requires:** SKIM_CONTEXT
 
-Spawn 4 Explore agents **in a single message**, each with Skim agent context, `DECISIONS_CONTEXT` (from Phase 2), and `FEATURE_KNOWLEDGE` (from Phase 2). Include instructions: "follow `devflow:apply-decisions` for DECISIONS_CONTEXT" and "The FEATURE_KNOWLEDGE is a baseline — VALIDATE, EXTEND, and CORRECT it, don't repeat it. Focus on areas the feature knowledge doesn't cover and changes since it was last updated." Ask each agent for a final report of at most about 1,500 tokens: findings with file:line references, not file dumps.
+Spawn 4 `Agent(subagent_type="Explore")` agents **in a single message**, each with Skim agent context and `FEATURE_KNOWLEDGE: {feature_knowledge}` (from Phase 2). Include the instruction: "The FEATURE_KNOWLEDGE is a baseline — VALIDATE, EXTEND, and CORRECT it. For anything it already covers, cite its KB IDs (`{slug} KB-AP-n`) instead of restating the text. Focus on areas the feature knowledge doesn't cover and changes since it was last updated." Ask each agent for a final report of at most about 1,500 tokens: findings with file:line references, not file dumps.
 
 | Focus | Thoroughness | Find |
 |-------|-------------|------|
@@ -249,17 +272,7 @@ Combine into: user needs, similar features, constraints, failure modes"
 **Produces:** GAP_OUTPUTS, COMPLIANCE_ACTIVE, COMPLIANCE_FRAMEWORKS
 **Requires:** EXPLORATION_SYNTHESIS, SKIM_CONTEXT, DECISIONS_CONTEXT
 
-**Resolve the compliance lens** for each worktree root, from its settings line (every framework reference is installed on every machine, so no file check decides it):
-
-**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 when the run has one worktree:
-
-```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> LEARNING=<on|off> KNOWLEDGE=<on|off>` — 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=on LEARNING=on KNOWLEDGE=off` instead.
-
-The accepted line is the only source of these values: the script alone folds the committed `.devflow/project.json`, the personal `.devflow/config.json` and the machine manifest.
+**Resolve the compliance lens** for each worktree root, from its settings line — the line resolved above for that root, by the settings block when this run has not yet resolved it (every framework reference is installed on every machine, so no file check decides it).
 
 **Set the compliance lens** from that line: `COMPLIANCE_FRAMEWORKS` is the settings line's `COMPLIANCE` with `generic` written `none`: `off`, `none`, or the framework ids the machine and this repository declare.
 
@@ -288,16 +301,21 @@ Each Design agent receives:
 - Exploration synthesis from Phase 4
 - Skim agent context from Phase 2
 - `DECISIONS_CONTEXT` (index from Phase 2)
-- `COMPLIANCE_FRAMEWORKS` (compliance focus only)
+- `COMPLIANCE_FOCUS_DIRECTIVE` (compliance focus only)
 - Multi-issue: all issue bodies
 
+**Set the compliance focus directive** from `COMPLIANCE_FRAMEWORKS`. `COMPLIANCE_FOCUS_DIRECTIVE` is this one line, with `<ids>` replaced by the value of `COMPLIANCE_FRAMEWORKS`; only the compliance focus's spawn carries it:
+
+> For this compliance focus, invoke Skill(skill="devflow:compliance") and load references/{id}.md only for the ids in <ids> (none: generic controls only); never fabricate guidance for a framework you were not given.
+
 ```
 Agent(subagent_type="Design"):
 "Mode: gap-analysis
 Focus: {completeness|architecture|security|performance|compliance|consistency|dependencies}
 DECISIONS_CONTEXT: {decisions_context}
 FEATURE_KNOWLEDGE: {feature_knowledge}
-COMPLIANCE_FRAMEWORKS: {COMPLIANCE_FRAMEWORKS}  (compliance focus only)
+{COMPLIANCE_FOCUS_DIRECTIVE}  (compliance focus only)
+Resolve `${CLAUDE_CONFIG_DIR:-$HOME/.claude}` in Bash, then Read `<that directory>/skills/devflow:gap-analysis/references/compliance.md` with the Read tool and apply it as your focus patterns.  (compliance focus only)
 Artifacts:
   Feature/Issues: {feature description or issue bodies}
   Exploration synthesis: {Phase 4 output}
@@ -359,7 +377,7 @@ User can:
 **Produces:** IMPL_EXPLORE_OUTPUTS
 **Requires:** SKIM_CONTEXT, ACCEPTED_SCOPE
 
-Spawn 4 Explore agents **in a single message**, each with Skim agent context + accepted scope. Ask each agent for a final report of at most about 1,500 tokens: findings with file:line references, not file dumps.
+Spawn 4 `Agent(subagent_type="Explore")` agents **in a single message**, each with Skim agent context + accepted scope. Ask each agent for a final report of at most about 1,500 tokens: findings with file:line references, not file dumps.
 
 | Focus | Thoroughness | Find |
 |-------|-------------|------|
@@ -386,7 +404,7 @@ Combine into: patterns to follow, integration points, reusable code, edge cases"
 #### Phase 10: Plan Implementation (Parallel)
 
 **Produces:** PLAN_OUTPUTS
-**Requires:** IMPL_EXPLORATION_SYNTHESIS, GAP_SYNTHESIS, DECISIONS_CONTEXT
+**Requires:** IMPL_EXPLORATION_SYNTHESIS, GAP_SYNTHESIS
 
 Spawn 3 Plan agents **in a single message**, each with implementation exploration synthesis. Ask each agent for a final report of at most about 1,500 tokens: the plan itself, not a restatement of the exploration.
 
@@ -483,8 +501,10 @@ User can:
 
 **Store design artifact:**
 
-**Pre-compute the artifact path** from the slug (it never changes after this):
-- If one issue: `{worktree}/.devflow/docs/design/{ISSUE_ID}-{topic-slug}.{YYYY-MM-DD_HHMM}.md` (the `docs-framework` skill's design-document pattern, e.g. `42-jwt-auth.2026-04-07_1430.md`)
+**Load `devflow:docs-framework`** — Load via Skill tool: `devflow:docs-framework`, here and not earlier, so a run that stops before this phase never pays for it. If it fails to load, continue with the paths below.
+
+**Pre-compute the artifact path** (it never changes after this) by the skill's rules: `{topic-slug}` is its topic slug of the feature title, the same value as the artifact's `slug:` frontmatter, and `{YYYY-MM-DD_HHMM}` is the local time, computed once:
+- If one issue: `{worktree}/.devflow/docs/design/{ISSUE_ID}-{topic-slug}.{YYYY-MM-DD_HHMM}.md` (e.g. `42-jwt-auth.2026-04-07_1430.md`)
 - If multi-issue: `{worktree}/.devflow/docs/design/multi-{topic-slug}.{YYYY-MM-DD_HHMM}.md`, frontmatter `issue: pending` — a batch fetch returns no issue ID to name it by
 - If no issue: `{worktree}/.devflow/docs/design/{topic-slug}.{YYYY-MM-DD_HHMM}.md`
 

package/dist/commands/release.md

@@ -40,8 +40,6 @@ Parse from `COMMAND_INPUT`:
 
 **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)
@@ -52,7 +50,19 @@ Read `.release/RELEASE-FLOW.md`:
 
 ### Phase 1b: Load Context
 
-**Produces:** DECISIONS_CONTEXT, FEATURE_KNOWLEDGE
+**Produces:** DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, FEATURE_KNOWLEDGE_RULES
+
+**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 when the run has one worktree:
+
+```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> LEARNING=<on|off> KNOWLEDGE=<on|off>` — 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=on LEARNING=on KNOWLEDGE=off` instead.
+
+The accepted line is the only source of these values: the script alone folds the committed `.devflow/project.json`, the personal `.devflow/config.json` and the machine manifest.
+
+When the settings line says `LEARNING=off`, set `DECISIONS_CONTEXT` to `(none)` and skip this step, locating no ledger and reading no index.
 
 The decisions ledger belongs to the repository, not to one checkout: in a linked worktree it lives in the main worktree, and a session started in a subdirectory reads the copy at the repository root. Locate it with ONE git call, run from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`):
 
@@ -70,9 +80,62 @@ This is the rule the learning hooks apply (D-LEDGER-MAIN-WORKTREE, D-PROMPT-ROOT
 
 Read `{ledger}/.devflow/learning/index.md`. If the file is absent or empty, set `DECISIONS_CONTEXT` to `(none)`; otherwise use the file content as `DECISIONS_CONTEXT`.
 
-Load feature knowledge: Attempt to read `.devflow/features/index.md` (the regenerable cache). If absent or empty, glob `.devflow/features/*/KNOWLEDGE.md` and read each file's YAML frontmatter (`name`, `description`, `directories`) as the relevance surface. Pick release-relevant KBs by matching their documented area against the release context. For each selected KB, read the full `KNOWLEDGE.md` — trust current code over KB content on any mismatch. Concatenate under slug headers and set `FEATURE_KNOWLEDGE` (or `(none)` if no KBs exist or none are relevant). No `index.json`, no subprocess, no `.cjs` script.
+### 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.
 
-Pass both to all subsequent agents via their input contracts.
+**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 `DECISIONS_CONTEXT` and `FEATURE_KNOWLEDGE` only to agents whose contract declares them; the Validate and Git agents this command spawns do not.
 
 ### Phase 1c: Resolve the Evidence Policy
 
@@ -191,6 +254,9 @@ Confirm with user via AskUserQuestion before executing:
 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)
+
+**Load Companion Skills** (D-RELEASE-GIT-LOAD-LATE) — Load via Skill tool: `devflow:git`, here and not earlier: steps 1–2 only write files and `--dry-run` halts after Phase 4, so neither carries the skill. A resume that skips step 3 loads it before its next main-thread git write. If a skill fails to load, continue without it.
+
 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
@@ -230,7 +296,7 @@ On completion:
 │  └─ Read .release/RELEASE-FLOW.md (learned) or proceed to detect (fresh)
 │
 ├─ Phase 1b: Load Context
-│  └─ Load DECISIONS_CONTEXT and FEATURE_KNOWLEDGE for downstream agents
+│  └─ Load DECISIONS_CONTEXT and FEATURE_KNOWLEDGE for the agents that declare them
 │
 ├─ Phase 2: Detect Release Process (first run only)
 │  └─ Tiered scan: package.json, CI workflows, git history

package/dist/commands/research.md

@@ -31,7 +31,7 @@ $ARGUMENTS
 
 ### Phase 1: Load Decisions (Orchestrator-Local)
 
-**Produces:** DECISIONS_CONTEXT, FEATURE_KNOWLEDGE
+**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
 
@@ -41,8 +41,20 @@ 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.
 
+**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 when the run has one worktree:
+
+```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> LEARNING=<on|off> KNOWLEDGE=<on|off>` — 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=on LEARNING=on KNOWLEDGE=off` instead.
+
+The accepted line is the only source of these values: the script alone folds the committed `.devflow/project.json`, the personal `.devflow/config.json` and the machine manifest.
+
 ### Load DECISIONS_CONTEXT
 
+When the settings line says `LEARNING=off`, set `DECISIONS_CONTEXT` to `(none)` and skip this step, locating no ledger and reading no index.
+
 The decisions ledger belongs to the repository, not to one checkout: in a linked worktree it lives in the main worktree, and a session started in a subdirectory reads the copy at the repository root. Locate it with ONE git call, run from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`):
 
 ```bash
@@ -66,9 +78,9 @@ Attempt to read `{ledger}/.devflow/learning/index.md`.
 
 The index is one direct file read, written at render time by `render-decisions.cjs` alongside `decisions.md`/`pitfalls.md` — no `.cjs` script runs here, and the index's own footer names the files that hold each entry's full body.
 
-**Step 2 — Apply decisions using `devflow:apply-decisions`:**
+**Step 2 — Agents apply the decisions:**
 
-When `DECISIONS_CONTEXT` is not `(none)`, follow `devflow:apply-decisions` to scan the index, identify plausibly-relevant entries, Read full entry bodies on demand, and cite verbatim IDs in downstream agent prompts and reasoning.
+When `DECISIONS_CONTEXT` is not `(none)`, hand it only to the agents whose contract declares it. They follow `devflow:apply-decisions`: scan the index, identify plausibly-relevant entries, Read full entry bodies on demand, and cite verbatim IDs in their reasoning. 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.
 
@@ -100,22 +112,32 @@ Glob `{worktree}/.devflow/features/*/KNOWLEDGE.md`. For each file found, read on
 
 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 selected KBs:**
+**Step 4 — Read each selected KB's Rules:**
+
+For each selected entry, `{kb}` is `{worktree}/.devflow/features/{slug}/KNOWLEDGE.md`:
 
-For each selected entry, read `{worktree}/.devflow/features/{slug}/KNOWLEDGE.md` in full. When the KB content contradicts the current code you observe, **trust the code** — the code is the freshness mechanism; the KB may lag behind.
+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.
 
-**Step 5 — Set FEATURE_KNOWLEDGE:**
+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.
 
-Concatenate the selected KNOWLEDGE.md files under slug headers:
+**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} ---
-{full KNOWLEDGE.md content}
+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
 ```
 
-If no KBs exist, no KBs are relevant, or `.devflow/features/` is absent, set `FEATURE_KNOWLEDGE` to `(none)`.
+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 file reads — no `.cjs` script.** After resolving `{worktree}`, this step is 1 index read (or N frontmatter reads on fallback), bounded by KB count.
+**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.
 
@@ -123,6 +145,10 @@ Use `FEATURE_KNOWLEDGE` **locally** for research framing. Pass to each Research
 
 **Produces:** RESEARCH_PLAN
 
+**Load `devflow:docs-framework`** — Load via Skill tool: `devflow:docs-framework`, here and not earlier, so a run that stops before this phase never pays for it. If it fails to load, continue with the rules below.
+
+Name the research directory by the skill's rules, once: `{topic-slug}` is its topic slug of the research question and `{YYYY-MM-DD_HHMM}` is the local time. When `{worktree}/.devflow/docs/research/{topic-slug}/{YYYY-MM-DD_HHMM}` already exists (a same-minute collision), the timestamp takes seconds instead, `YYYY-MM-DD_HHMMSS`. Every path of this run uses that one directory.
+
 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
@@ -130,15 +156,13 @@ Analyze the research question to infer research types needed (min 2, max 5). For
 
 **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.
+Spawn `Agent(subagent_type="Skim")` with `LEARNING` from the settings line, targeting codebase areas relevant to the research question.
 
 Skip and set ORIENT_OUTPUT = "(none)" if `codebase` type is not in RESEARCH_PLAN.
 
@@ -152,7 +176,7 @@ Spawn 2-5 `Agent(subagent_type="Research")` agents **in a single message** (para
 Each Research agent receives:
 - `RESEARCH_TYPE`, `RESEARCH_QUESTION`, `OUTPUT_PATH` from RESEARCH_PLAN
 - `DECISIONS_CONTEXT`: From Phase 1
-- `FEATURE_KNOWLEDGE`: From Phase 1
+- `FEATURE_KNOWLEDGE`: `{feature_knowledge}` from Phase 1
 - `ORIENT_OUTPUT`: Only for `codebase` type
 - `WORKTREE_PATH`: If in a worktree context
 
@@ -163,12 +187,17 @@ Each Research agent writes findings to disk at OUTPUT_PATH.
 **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
+Spawn `Agent(subagent_type="Synthesize")` in `research` mode. It reads the Research agent outputs from the `RESEARCH_OUTPUTS` paths, merges them with trust-aware aggregation, and writes `research-summary.md` into `RESEARCH_BASE_DIR` — the one directory of this run, which only this spawn names:
 
-Output path: `{worktree}/.devflow/docs/research/{topic-slug}/{timestamp}/research-summary.md`
+```
+Agent(subagent_type="Synthesize", run_in_background=false):
+"Mode: research
+WORKTREE_PATH: {WORKTREE_PATH}  (omit if none was provided)
+RESEARCH_OUTPUTS: {the OUTPUT_PATH of every Research agent that wrote its file}
+RESEARCH_BASE_DIR: {worktree}/.devflow/docs/research/{topic-slug}/{YYYY-MM-DD_HHMM}
+Merge findings with trust-aware aggregation.
+Output: {worktree}/.devflow/docs/research/{topic-slug}/{YYYY-MM-DD_HHMM}/research-summary.md"
+```
 
 ### Phase 6: Present
 
@@ -183,7 +212,7 @@ If external research was skipped due to tool unavailability: inform user.
 
 ### Phase 7: Feature Knowledge Creation (Conditional)
 
-**Requires:** RESEARCH_SUMMARY, DECISIONS_CONTEXT
+**Requires:** RESEARCH_SUMMARY
 **Produces:** FEATURE_KNOWLEDGE_STATUS (created | skipped)
 
 1. If `codebase` type was not in RESEARCH_PLAN → skip