devflow-kit 3.3.0 → 3.5.0

package/src/assets/commands/plan.mds

@@ -5,10 +5,11 @@ output-dir: dist/commands
 @import { knowledge_load } from "./_partials/_knowledge.mds"
 @import { decisions_load } from "./_partials/_decisions.mds"
 @import { docs_root } from "./_partials/_docs_root.mds"
-@import { compliance_gate } from "./_partials/_compliance.mds"
+@import { compliance_gate, compliance_focus_inject } from "./_partials/_compliance.mds"
 @import { evidence_policy } from "./_partials/_evidence_policy.mds"
 @import { test_plan_line } from "./_partials/_plan_contract.mds"
 @import { issue_ref_grammar, issue_capture_contract } from "./_partials/_tracker.mds"
+@import "./_partials/_settings.mds" as settings
 # Plan Command
 
 Orchestrate design planning from requirements discovery through gap analysis to implementation design. Produces a machine-readable design artifact consumed by `/implement`.
@@ -107,16 +108,29 @@ If the user says "skip" or "just proceed" — skip remaining questions, present
 
 **MANDATORY**: Do not spawn any agents until Gate 0 is confirmed — the Step 0 issue fetch (if applicable) is the sole exception; it precedes and informs Gate 0 and must complete before Gate 0 begins.
 
+<!-- learning:on -->
 #### Phase 2: Orient + Load Decisions
-
-**Produces:** SKIM_CONTEXT, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE
+<!-- learning:off -->
+#### Phase 2: Orient
+<!-- learning:end -->
+
+<!-- learning:on -->
+**Produces:** SKIM_CONTEXT, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, FEATURE_KNOWLEDGE_RULES
+<!-- learning:off -->
+**Produces:** SKIM_CONTEXT, FEATURE_KNOWLEDGE, FEATURE_KNOWLEDGE_RULES
+<!-- learning:end -->
 **Requires:** CONFIRMED_SCOPE
 
+{{settings.settings_resolve()}}
+
 Spawn Skim agent for codebase context:
 
 ```
 Agent(subagent_type="Skim"):
 "Orient in codebase for design planning: {feature/issues}
+<!-- learning:on -->
+LEARNING: {LEARNING from the settings line}
+<!-- learning:end -->
 Run rskim on source directories (NOT repo root) to identify:
 - Existing patterns and conventions in the affected area
 - File structure and module boundaries
@@ -128,19 +142,24 @@ Return codebase context for requirements analysis."
 {{docs_root()}}
 
 {{decisions_load()}}
+<!-- learning:on -->
+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.
 
-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.
-
+<!-- learning:end -->
 {{knowledge_load()}}
 
-Pass `FEATURE_KNOWLEDGE` alongside `DECISIONS_CONTEXT` to Explore and Design agents.
+<!-- learning:on -->
+Pass `FEATURE_KNOWLEDGE` to Explore and Design agents. Pass `DECISIONS_CONTEXT` to Design agents only.
+<!-- learning:off -->
+Pass `FEATURE_KNOWLEDGE` to Explore and Design agents.
+<!-- learning:end -->
 
 #### 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 |
 |-------|-------------|------|
@@ -171,7 +190,11 @@ Combine into: user needs, similar features, constraints, failure modes"
 #### Phase 5: Gap Analysis (Parallel)
 
 **Produces:** GAP_OUTPUTS, COMPLIANCE_ACTIVE, COMPLIANCE_FRAMEWORKS
+<!-- learning:on -->
 **Requires:** EXPLORATION_SYNTHESIS, SKIM_CONTEXT, DECISIONS_CONTEXT
+<!-- learning:off -->
+**Requires:** EXPLORATION_SYNTHESIS, SKIM_CONTEXT
+<!-- learning:end -->
 
 {{compliance_gate()}}
 
@@ -197,22 +220,33 @@ Each Design agent receives:
 - Focus: (their assigned focus from table)
 - Exploration synthesis from Phase 4
 - Skim agent context from Phase 2
+<!-- learning:on -->
 - `DECISIONS_CONTEXT` (index from Phase 2)
-- `COMPLIANCE_FRAMEWORKS` (compliance focus only)
+<!-- learning:end -->
+- `COMPLIANCE_FOCUS_DIRECTIVE` (compliance focus only)
 - Multi-issue: all issue bodies
 
+{{compliance_focus_inject()}}
+
 ```
 Agent(subagent_type="Design"):
 "Mode: gap-analysis
 Focus: {completeness|architecture|security|performance|compliance|consistency|dependencies}
+<!-- learning:on -->
 DECISIONS_CONTEXT: {decisions_context}
+<!-- learning:end -->
 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}
   Codebase context: {Phase 2 output}
+<!-- learning:on -->
 Analyze only your assigned focus area. Follow devflow:apply-decisions for DECISIONS_CONTEXT.
+<!-- learning:off -->
+Analyze only your assigned focus area.
+<!-- learning:end -->
 Cite evidence from provided artifacts."
 ```
 
@@ -269,7 +303,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 |
 |-------|-------------|------|
@@ -296,7 +330,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.
 
@@ -388,8 +422,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`
 
@@ -511,9 +547,17 @@ Display completion summary:
 ├─ Block 1: Requirements Discovery
 │  ├─ Phase 1: GATE 0 - Requirements Discovery ⛔ MANDATORY
 │  │  └─ AskUserQuestion: Validate interpretation
+<!-- learning:on -->
 │  ├─ Phase 2: Orient + Load Decisions
+<!-- learning:off -->
+│  ├─ Phase 2: Orient
+<!-- learning:end -->
+<!-- learning:on -->
 │  │  ├─ Skim agent (codebase context)
 │  │  └─ Read index.md → DECISIONS_CONTEXT
+<!-- learning:off -->
+│  │  └─ Skim agent (codebase context)
+<!-- learning:end -->
 │  ├─ Phase 3: Explore Requirements (PARALLEL)
 │  │  ├─ Explore: User perspective
 │  │  ├─ Explore: Similar features

package/src/assets/commands/{release.md → release.mds}

@@ -1,6 +1,11 @@
 ---
 description: Release project using adaptive learned configuration
+output-dir: dist/commands
 ---
+@import { evidence_policy } from "./_partials/_evidence_policy.mds"
+@import { decisions_gate, decisions_locate } from "./_partials/_decisions.mds"
+@import { knowledge_load } from "./_partials/_knowledge.mds"
+@import "./_partials/_settings.mds" as settings
 
 # Release Command
 
@@ -40,8 +45,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,41 +55,35 @@ Read `.release/RELEASE-FLOW.md`:
 
 ### Phase 1b: Load Context
 
-**Produces:** DECISIONS_CONTEXT, FEATURE_KNOWLEDGE
-
-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`):
+<!-- learning:on -->
+**Produces:** DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, FEATURE_KNOWLEDGE_RULES
+<!-- learning:off -->
+**Produces:** FEATURE_KNOWLEDGE, FEATURE_KNOWLEDGE_RULES
+<!-- learning:end -->
 
-```bash
-git -C "{start}" rev-parse --path-format=absolute --show-toplevel --git-common-dir
-```
+<!-- learning:on -->
+{{settings.settings_resolve()}}
 
-Line 1 is the checkout's toplevel, line 2 the repository's 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 of these that applies:
+{{decisions_gate()}}
 
-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 learning hooks apply (D-LEDGER-MAIN-WORKTREE, D-PROMPT-ROOT), so you read the index the Learning agent writes.
+{{decisions_locate()}}
 
 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.
+<!-- learning:end -->
+{{knowledge_load()}}
 
-Pass both to all subsequent agents via their input contracts.
+<!-- learning:on -->
+Pass `DECISIONS_CONTEXT` and `FEATURE_KNOWLEDGE` only to agents whose contract declares them; the Validate and Git agents this command spawns do not.
+<!-- learning:off -->
+Pass `FEATURE_KNOWLEDGE` only to agents whose contract declares it; the Validate and Git agents this command spawns do not.
+<!-- learning:end -->
 
 ### 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.
+{{evidence_policy()}}
 
 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).
 
@@ -191,6 +188,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 +230,11 @@ 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
+<!-- learning:on -->
+│  └─ Load DECISIONS_CONTEXT and FEATURE_KNOWLEDGE for the agents that declare them
+<!-- learning:off -->
+│  └─ Load FEATURE_KNOWLEDGE for the agents that declare it
+<!-- learning:end -->
 │
 ├─ Phase 2: Detect Release Process (first run only)
 │  └─ Tiered scan: package.json, CI workflows, git history

package/src/assets/commands/research.mds

@@ -5,6 +5,7 @@ output-dir: dist/commands
 @import { knowledge_load } from "./_partials/_knowledge.mds"
 @import { decisions_load } from "./_partials/_decisions.mds"
 @import { docs_root } from "./_partials/_docs_root.mds"
+@import "./_partials/_settings.mds" as settings
 # 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.
@@ -33,16 +34,29 @@ $ARGUMENTS
 
 ## Phases
 
+<!-- learning:on -->
 ### Phase 1: Load Decisions (Orchestrator-Local)
+<!-- learning:off -->
+### Phase 1: Load Context (Orchestrator-Local)
+<!-- learning:end -->
 
-**Produces:** DECISIONS_CONTEXT, FEATURE_KNOWLEDGE
+<!-- learning:on -->
+**Produces:** DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, FEATURE_KNOWLEDGE_RULES
+<!-- learning:off -->
+**Produces:** FEATURE_KNOWLEDGE, FEATURE_KNOWLEDGE_RULES
+<!-- learning:end -->
 
 {{docs_root()}}
 
-{{decisions_load()}}
+<!-- learning:on -->
+{{settings.settings_resolve()}}
 
+<!-- learning:end -->
+{{decisions_load()}}
+<!-- learning:on -->
 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.
 
+<!-- learning:end -->
 {{knowledge_load()}}
 
 Use `FEATURE_KNOWLEDGE` **locally** for research framing. Pass to each Research agent in Phase 4.
@@ -51,6 +65,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
@@ -58,15 +76,17 @@ 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.
 
+<!-- learning:on -->
+Spawn `Agent(subagent_type="Skim")` with `LEARNING` from the settings line, targeting codebase areas relevant to the research question.
+<!-- learning:off -->
 Spawn `Agent(subagent_type="Skim")` targeting codebase areas relevant to the research question.
+<!-- learning:end -->
 
 Skip and set ORIENT_OUTPUT = "(none)" if `codebase` type is not in RESEARCH_PLAN.
 
@@ -79,8 +99,10 @@ 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
+<!-- learning:on -->
 - `DECISIONS_CONTEXT`: From Phase 1
-- `FEATURE_KNOWLEDGE`: From Phase 1
+<!-- learning:end -->
+- `FEATURE_KNOWLEDGE`: `{feature_knowledge}` from Phase 1
 - `ORIENT_OUTPUT`: Only for `codebase` type
 - `WORKTREE_PATH`: If in a worktree context
 
@@ -91,12 +113,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
 
@@ -111,7 +138,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
@@ -137,7 +164,11 @@ Research findings saved to `{worktree}/.devflow/docs/research/{topic-slug}/{YYYY
 ```
 /research (orchestrator)
 │
+<!-- learning:on -->
 ├─ Phase 1: Load Decisions (Orchestrator-Local)
+<!-- learning:off -->
+├─ Phase 1: Load Context (Orchestrator-Local)
+<!-- learning:end -->
 │
 ├─ Phase 2: Requirements
 │  └─ Infer 2-5 research types from question

package/src/assets/commands/resolve.mds

@@ -7,6 +7,7 @@ output-dir: dist/commands
 @import { evidence_policy } from "./_partials/_evidence_policy.mds"
 @import { publication_gate } from "./_partials/_publication.mds"
 @import "./_partials/_compliance.mds" as compliance
+@import "./_partials/_settings.mds" as settings
 # Resolve Command
 
 Process issues from code review reports: triage every issue through the blast-radius disposition matrix, fix FIX_NOW items with Code agents, verify fixes with a Validate agent gate, and track FIX_SEPARATE/TECH_DEBT items as manage-debt tickets. Defaults to the latest timestamped review directory. Supports multi-worktree auto-discovery.
@@ -28,9 +29,10 @@ Process issues from code review reports: triage every issue through the blast-ra
 
 **Produces:** WORKTREES
 
-1. **Discover resolvable worktrees** using the `devflow:worktree-support` skill discovery algorithm:
-   - Run `git worktree list --porcelain` → parse, filter (skip protected/detached/mid-rebase), dedup by branch, sort by recent commit
-   - Invoke the `devflow:worktree-support` skill, then Read its `references/discovery.md` from the skill's base directory for the full 7-step algorithm; the canonical protected branch list stays in the skill
+1. **Discover resolvable worktrees**:
+   - Run `git worktree list --porcelain` and count the worktrees it lists
+   - **More than one listed:** Invoke the `devflow:worktree-support` skill, then Read its `references/discovery.md` from the skill's base directory for the full 7-step algorithm; the canonical protected branch list stays in the skill. Parse the list, filter (skip protected/detached/mid-rebase), dedup by branch, sort by recent commit
+   - **Exactly one listed:** load neither the skill nor the reference — that worktree is the only candidate, and Step 0b's Git agent validates its branch
    - Additional filter: must have unresolved reviews (latest review directory has no `resolution-summary.md`)
 2. **If `--path` flag provided:** use only that worktree, skip discovery
    **`--path` validation**: Before proceeding, verify the path exists as a directory and appears in `git worktree list` output. If not: report error and stop.
@@ -89,14 +91,25 @@ For each worktree:
 
 Set `TARGET_DIR` to the selected review or bug-analysis directory path, and `TARGET_DIR_REL` to the same directory relative to the worktree root (`.devflow/docs/reviews/…` or `.devflow/docs/bug-analysis/…`) — the only form of it that may reach a PR comment.
 
+<!-- learning:on -->
 #### Step 0d: Load Project Decisions
+<!-- learning:off -->
+#### Step 0d: Load Project Context
+<!-- learning:end -->
 
-**Produces:** DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, EVIDENCE_POLICY, ISSUE_REQUIRED, APPLY_CONVENTIONS, REQUIRE_NON_AUTHOR_APPROVAL, REVIEW_PUBLICATION, RESOLUTION_TS
+<!-- learning:on -->
+**Produces:** DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, FEATURE_KNOWLEDGE_RULES, EVIDENCE_POLICY, ISSUE_REQUIRED, APPLY_CONVENTIONS, REQUIRE_NON_AUTHOR_APPROVAL, REVIEW_PUBLICATION, RESOLUTION_TS
+<!-- learning:off -->
+**Produces:** FEATURE_KNOWLEDGE, FEATURE_KNOWLEDGE_RULES, EVIDENCE_POLICY, ISSUE_REQUIRED, APPLY_CONVENTIONS, REQUIRE_NON_AUTHOR_APPROVAL, REVIEW_PUBLICATION, RESOLUTION_TS
+<!-- learning:end -->
 
-{{decisions_load()}}
+{{settings.settings_resolve()}}
 
+{{decisions_load()}}
+<!-- learning:on -->
 This produces a compact index of active ADR/PF entries written at render time — Deprecated/Superseded entries are already stripped. Pass `DECISIONS_CONTEXT` to the Triage agent in Phase 2 and to Code agents in Phase 4.
 
+<!-- learning:end -->
 {{knowledge_load()}}
 
 Pass `FEATURE_KNOWLEDGE` to the Triage agent in Phase 2.
@@ -107,6 +120,10 @@ Reuse this result for every worktree.
 {{publication_gate()}}
 Resolve this per worktree — unlike the evidence policy above, the settings line is per worktree root. From the same line: {{compliance.compliance_frameworks()}}
 
+{{compliance.compliance_inject()}}
+
+Set it per worktree, from that worktree's lens, and pass that worktree's `COMPLIANCE_DIRECTIVE` to each of its Code and Code-fix spawns, on a line of its own.
+
 **Mint `RESOLUTION_TS` once per run:** `date -u +%Y-%m-%dT%H:%M:%SZ`. Every worktree reuses it — the resolution comment's dedup marker is searched per PR, so one run key keeps a retry of this run deduplicated while the next /resolve on the same PR posts. Phase 5 writes it as the summary's `**Date**:` and Phase 9b-2 passes it, so the local file and the posted marker agree.
 
 ### Phase 1: Parse Issues
@@ -159,7 +176,11 @@ Parse `THREAD_MAP` from Git agent output. If Git agent returns `TRACEABILITY: DE
 ### Phase 2: Global Triage
 
 **Produces:** TRIAGE_RESULTS
+<!-- learning:on -->
 **Requires:** ISSUES, DIFF_FILES, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, PR_DESCRIPTION
+<!-- learning:off -->
+**Requires:** ISSUES, DIFF_FILES, FEATURE_KNOWLEDGE, PR_DESCRIPTION
+<!-- learning:end -->
 
 Spawn a single global Triage agent for ALL issues:
 
@@ -168,11 +189,15 @@ Agent(subagent_type="Triage"):
 "ISSUES: {all_issues}
 DIFF_FILES: {diff_files}
 WORKTREE_PATH: {worktree_path}  (omit if cwd)
+<!-- learning:on -->
 DECISIONS_CONTEXT: {decisions_context}
+<!-- learning:end -->
 FEATURE_KNOWLEDGE: {feature_knowledge}
 PR_DESCRIPTION: <pr-description>{pr_description}</pr-description>
 Triage every issue: collapse duplicates first, then apply the blast-radius disposition matrix to each group's primary. Assign exactly one verdict per issue.
+<!-- learning:on -->
 Follow devflow:apply-decisions to Read full ADR/PF bodies on demand.
+<!-- learning:end -->
 Follow devflow:apply-feature-knowledge for FEATURE_KNOWLEDGE."
 ```
 
@@ -185,8 +210,10 @@ Wait for Triage agent to complete before proceeding. Parse verdict ledger from T
 - **TECH_DEBT**: Architectural overhaul only — LAST RESORT
 - **DUPLICATE**: Collapsed duplicate issue — carries `duplicate_of: <primary-id>` referencing the non-DUPLICATE primary; inherits the primary's outcome
 
+<!-- learning:on -->
 Collect every decision and pitfall the Triage agent's Reasoning columns state, in its words — the resolution summary is posted, so it never carries an ADR/PF ID.
 
+<!-- learning:end -->
 **Triage agent completeness assertion:** Verify the parsed ledger against ISSUES before proceeding:
 1. Every issue `id` from ISSUES must appear in exactly one verdict bucket — none may vanish, none may appear in multiple buckets. DUPLICATE is a valid bucket; a valid DUPLICATE entry must name its `duplicate_of` primary (the `Duplicate Of` column of the ledger's DUPLICATE table) and that primary must be a non-DUPLICATE issue id. A missing `duplicate_of` or one that chains to another DUPLICATE is a **Triage agent failure** (retry-then-abort as below).
 2. If the Triage agent output is empty, contains a skill re-entrancy guard string (e.g., contains `already running`), or is missing any issue IDs from ISSUES: treat as a **Triage agent failure**:
@@ -210,7 +237,11 @@ Otherwise, batch FIX_NOW issues for Code agent execution. **DUPLICATE issues are
 ### Phase 4: Fix (Code agent × N)
 
 **Produces:** CODE_AGENT_RESULTS
+<!-- learning:on -->
 **Requires:** BATCHES, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE
+<!-- learning:off -->
+**Requires:** BATCHES, FEATURE_KNOWLEDGE
+<!-- learning:end -->
 
 For each batch, spawn Code agent with `OPERATION: issue-fix` and `PUSH: false`:
 
@@ -221,11 +252,12 @@ TASK_ID: resolve-{batch-id}
 ISSUES: {fix_now_issues_in_batch}
 SCOPE: {risk_tier_per_issue}
 PUSH: false
-CREATE_PR: false
 WORKTREE_PATH: {worktree_path}  (omit if cwd)
+<!-- learning:on -->
 DECISIONS_CONTEXT: {decisions_context}
+<!-- learning:end -->
 FEATURE_KNOWLEDGE: {feature_knowledge}
-COMPLIANCE_FRAMEWORKS: {COMPLIANCE_FRAMEWORKS}
+{COMPLIANCE_DIRECTIVE}
 Fix only the listed pre-classified FIX_NOW issues. Do not re-litigate dispositions.
 Same-file issues → one commit. Include ## Verification block in report.
 Regression fix without failing-then-passing regression test → BLOCKED."
@@ -288,17 +320,19 @@ Run build, typecheck, lint, test. Report pass/fail with failure details."
 1. Extract failure details from Validate agent output
 2. Increment `validation_retry_count`
 3. If `validation_retry_count <= 2`:
-   - Spawn Code agent with fix context:
+   - Spawn Code-fix agent with fix context:
    ```
-   Agent(subagent_type="Code"):
+   Agent(subagent_type="Code-fix"):
    "OPERATION: validation-fix
    TASK_ID: resolve-{batch-id}-valfix-{count}
    VALIDATION_FAILURES: {parsed failures from Validate agent}
    SCOPE: Fix only the listed failures, no other changes
    PUSH: false
-   CREATE_PR: false
    WORKTREE_PATH: {worktree_path}  (omit if cwd)
-   COMPLIANCE_FRAMEWORKS: {COMPLIANCE_FRAMEWORKS}"
+   <!-- learning:on -->
+   DECISIONS_CONTEXT: {decisions_context}
+   <!-- learning:end -->
+   {COMPLIANCE_DIRECTIVE}"
    ```
    - Loop back to re-validate
 4. If `validation_retry_count > 2`: set VERIFICATION_STATUS = FAILED and exit the validation loop — record a blocking callout in the `## Verification` section (never a silent pass).
@@ -308,7 +342,7 @@ Run build, typecheck, lint, test. Report pass/fail with failure details."
 Record `## Verification` outcome in resolution-summary.md (runs unconditionally after the validation loop exits):
 - Rewrite the `## Verification` section with | Command | Result | table + `Final gate: PASS | FAILED after N attempts`
 
-Push all commits to remote once (Code agents and validation-fix Code agents ran with PUSH: false — runs whether the gate PASSED or FAILED, so the branch is always visible before Phase 9 or CI runs):
+Push all commits to remote once (Code and Code-fix agents ran with PUSH: false — runs whether the gate PASSED or FAILED, so the branch is always visible before Phase 9 or CI runs):
 ```bash
 git -C {worktree} push
 ```
@@ -346,7 +380,11 @@ Phase 7 has pushed already, so this is a no-op unless the head moved since. `exi
 3. **If NO_PR or NO_CI** → skip: "No PR/CI configured, skipping CI validation." Proceed to next phase.
 4. **If PENDING** and fewer than 3 waits have run → wait again (step 1). After the third wait → report "CI still running — verify manually before merging" and proceed.
 5. **If INDETERMINATE** and fewer than 3 waits have run → wait again (step 1). After the third wait → report "CI status unknown — verify manually before merging" and proceed.
-6. **If FAILING** and fewer than 2 fixes have run → report the failing checks from the line. Spawn `Agent(subagent_type="Code")` whose prompt opens with `OPERATION: ci-fix`, with `COMPLIANCE_FRAMEWORKS`, `CI_FAILURES` and `PUSH: false`; `CI_FAILURES` holds the failing-check names from the line and nothing else, because the Code agent fetches the full names and reads the logs itself and this command reads none. After a fix, push with the command above and, if a wait remains, wait again (step 1); a failed push records `TRACEABILITY: DEGRADED (ci push failed)`, reports "CI status unknown — verify manually before merging" and stops waiting. After the second fix still FAILING → report the failing checks and proceed.
+<!-- learning:on -->
+6. **If FAILING** and fewer than 2 fixes have run → report the failing checks from the line. Spawn `Agent(subagent_type="Code-fix")` whose prompt opens with `OPERATION: ci-fix`, with `COMPLIANCE_DIRECTIVE` (when it is not empty), `CI_FAILURES`, `DECISIONS_CONTEXT` and `PUSH: false`; `CI_FAILURES` holds the failing-check names from the line and nothing else, because the Code-fix agent fetches the full names and reads the logs itself and this command reads none. After a fix, push with the command above and, if a wait remains, wait again (step 1); a failed push records `TRACEABILITY: DEGRADED (ci push failed)`, reports "CI status unknown — verify manually before merging" and stops waiting. After the second fix still FAILING → report the failing checks and proceed.
+<!-- learning:off -->
+6. **If FAILING** and fewer than 2 fixes have run → report the failing checks from the line. Spawn `Agent(subagent_type="Code-fix")` whose prompt opens with `OPERATION: ci-fix`, with `COMPLIANCE_DIRECTIVE` (when it is not empty), `CI_FAILURES` and `PUSH: false`; `CI_FAILURES` holds the failing-check names from the line and nothing else, because the Code-fix agent fetches the full names and reads the logs itself and this command reads none. After a fix, push with the command above and, if a wait remains, wait again (step 1); a failed push records `TRACEABILITY: DEGRADED (ci push failed)`, reports "CI status unknown — verify manually before merging" and stops waiting. After the second fix still FAILING → report the failing checks and proceed.
+<!-- learning:end -->
 7. **Budget**: at most 3 waits and 2 fixes in all, per worktree. When one is spent, report the current status and proceed.
 <!-- /PATTERN: ci-status-gate -->
 
@@ -557,7 +595,11 @@ In multi-worktree mode, report results per worktree with aggregate summary.
 │  ├─ Step 0a: git worktree list → filter resolvable
 │  ├─ Step 0b: Git agent (validate-branch) per worktree [parallel] ← + DIFF_FILES
 │  ├─ Step 0c: Target latest review directory per worktree
+<!-- learning:on -->
 │  └─ Step 0d: Load project decisions → DECISIONS_CONTEXT + EVIDENCE_POLICY + REVIEW_PUBLICATION
+<!-- learning:off -->
+│  └─ Step 0d: Load project context → EVIDENCE_POLICY + REVIEW_PUBLICATION
+<!-- learning:end -->
 │
 ├─ Phase 1: Parse issues from TARGET_DIR + extract confidence %
 │
@@ -577,10 +619,10 @@ In multi-worktree mode, report results per worktree with aggregate summary.
 │
 ├─ Phase 6: Simplify [Simplify agent]
 │
-├─ Phase 7: Verification Gate [Validate agent, haiku] + push + Code agent validation-fix loop ≤2
+├─ Phase 7: Verification Gate [Validate agent, haiku] + push + Code-fix agent validation-fix loop ≤2
 │
 ├─ Phase 8: CI Status Gate (conditional — skipped if no fixes or verification FAILED)
-│  └─ push, then ci-wait.cjs (inline, one wait ≤ 570 s) → Code agent on FAILING (3 waits + 2 fixes per worktree)
+│  └─ push, then ci-wait.cjs (inline, one wait ≤ 570 s) → Code-fix agent on FAILING (3 waits + 2 fixes per worktree)
 │
 ├─ Phase 9: Git agent (manage-debt) — FIX_SEPARATE + TECH_DEBT → backfill Tracked={ISSUE_REF} (or TRACEABILITY: DEGRADED on failure)
 │  SEQUENTIAL across worktrees
@@ -651,12 +693,14 @@ Written in Phase 5 (Collect Results) to `{TARGET_DIR}/resolution-summary.md`:
 **Review**: {TARGET_DIR_REL}
 **Command**: /resolve
 
+<!-- learning:on -->
 ## Decisions Citations
 
 - {decision applied or pitfall avoided, stated in words — never its ID} — {batch-id}, {issue-id}
 
 (Omit section if no citations were made)
 
+<!-- learning:end -->
 ## Statistics
 | Metric | Value |
 |--------|-------|