devflow-kit 3.3.0 → 3.4.0

package/src/assets/commands/_partials/_settings.mds

@@ -3,11 +3,19 @@ A partial: the one way a prompt learns the repository's settings (D-SETTINGS-LIN
 machine manifest for a value this line carries — `resolve-settings.cjs` folds all
 three, and `tests/guards/no-config-read.test.ts` holds every compiled prompt to it.
 
-Imported by `_publication.mds`, `_compliance.mds` and `_knowledge.mds` themselves,
-as ALIAS imports (a selective import deep-clones this module's scope into every
-define of the importer). A command that runs two of those gates carries the
-block twice; the text says "reuse a line this run already resolved for the same
-root", so the second copy costs bytes and never a second resolution.
+Each command host that has a consumer imports this file itself, as an ALIAS import
+(a selective import deep-clones this module's scope into every define of the
+importer), and expands `settings_resolve()` exactly once, immediately before the
+earliest of its consumers: its decisions load or gate, its compliance lens, its
+publication gate, its knowledge write-back Step 1, or a Skim spawn that takes
+`LEARNING`. The gate partials import nothing from here: their text refers to the
+settings line resolved above and keeps each gate's own condition inside its own step.
+
+The block stays a per-root procedure: "reusing a line this run already resolved for
+the same root". A consumer whose `{root}` may differ from the first-resolved root
+names that root and says its line is the one for that root, resolved by the block
+above when this run has not yet resolved it. The guard counts textual invocations,
+not runtime calls.
 
 The accepted shape below is `SETTINGS_LINE_RE` written out, and the fallback is
 `SETTINGS_FAIL_CLOSED_LINE`, both exported by `resolve-settings.cjs`;

package/src/assets/commands/_partials/_wave.mds

@@ -85,17 +85,25 @@ Two parallel sibling tickets can produce real git conflicts. The resolution is *
 **Resolution procedure:**
 
 1. Git agent detects the conflict and reports the conflicting files + sections
+<!-- learning:on -->
+2. Spawn a Code agent whose prompt opens with `OPERATION: implement` and carries `COMPLIANCE_FRAMEWORKS` and `DECISIONS_CONTEXT`, with FULL intent context:
+<!-- learning:off -->
 2. Spawn a Code agent whose prompt opens with `OPERATION: implement` and carries `COMPLIANCE_FRAMEWORKS`, with FULL intent context:
+<!-- learning:end -->
    - Both ticket descriptions and plans
    - The conflicting diff sections (both sides)
+<!-- learning:on -->
    - Relevant ADRs from DECISIONS_CONTEXT (loaded by main model before authoring)
+<!-- learning:end -->
 3. Code agent resolves to PRESERVE BOTH INTENTS — the resolution must honor what both tickets were trying to achieve
 4. If the correct resolution is NOT UNAMBIGUOUS from the intent context: **do NOT guess** → quarantine + escalate
 5. After any resolution: the post-merge Validate covers it — the workflow spawns it after the merge, and no Validate is requested from Git
 
 **Conservative-or-escalate is absolute.** An LLM silently guessing a wrong merge is the highest-danger failure mode in the whole design. When in doubt: quarantine + surface in report. The user re-runs (resume) with the escalated context.
+<!-- learning:on -->
 
 **New decisions surfaced during resolution** (a conflict that reveals an undocumented architectural choice) are noted in the run report for the user to write back as ADRs.
+<!-- learning:end -->
 @end
 
 @define escalation_model():

package/src/assets/commands/bug-analysis.mds

@@ -6,6 +6,7 @@ output-dir: dist/commands
 @import { decisions_load } from "./_partials/_decisions.mds"
 @import { docs_root } from "./_partials/_docs_root.mds"
 @import { evidence_policy } from "./_partials/_evidence_policy.mds"
+@import "./_partials/_settings.mds" as settings
 # Bug Analysis Command
 
 Run a proactive bug analysis on the current branch by combining static analysis tools with parallel semantic analyzers, then synthesizing results into an actionable bug report. Supports incremental analysis, timestamped report directories, and `/resolve` compatibility.
@@ -168,12 +169,19 @@ If no tool produced findings: set `STATIC_FINDINGS` to `(none)`.
 
 ### Phase 3: Context Loading
 
-**Produces:** DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, PLAN_CONTEXT, ACCEPTANCE_RULES
+<!-- learning:on -->
+**Produces:** DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, FEATURE_KNOWLEDGE_RULES, PLAN_CONTEXT, ACCEPTANCE_RULES
+<!-- learning:off -->
+**Produces:** FEATURE_KNOWLEDGE, FEATURE_KNOWLEDGE_RULES, PLAN_CONTEXT, ACCEPTANCE_RULES
+<!-- learning:end -->
 
+<!-- learning:on -->
 #### Decisions Index
 
-{{decisions_load()}}
+{{settings.settings_resolve()}}
 
+<!-- learning:end -->
+{{decisions_load()}}
 #### Feature Knowledge
 
 {{knowledge_load()}}
@@ -203,7 +211,11 @@ Determine which focus analyzers to run using `CHANGED_FILES` (already computed i
 ### Phase 5: Parallel Bug Analysis
 
 **Produces:** ANALYZER_OUTPUTS
+<!-- learning:on -->
 **Requires:** DIFF_RANGE, ANALYSIS_DIR, ACTIVE_FOCUSES, STATIC_FINDINGS, ACCEPTANCE_RULES, PLAN_CONTEXT, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE
+<!-- learning:off -->
+**Requires:** DIFF_RANGE, ANALYSIS_DIR, ACTIVE_FOCUSES, STATIC_FINDINGS, ACCEPTANCE_RULES, PLAN_CONTEXT, FEATURE_KNOWLEDGE
+<!-- learning:end -->
 
 Spawn ALL active Diagnose agents **in a single message** (parallel, NOT background):
 
@@ -216,11 +228,15 @@ DIFF_COMMAND: git diff {DIFF_RANGE}
 ACCEPTANCE_RULES: {ACCEPTANCE_RULES filtered to this focus type, or (none)}
 PLAN_CONTEXT: {PLAN_CONTEXT}
 STATIC_FINDINGS: {STATIC_FINDINGS if focus == security, else (none)}
+<!-- learning:on -->
 DECISIONS_CONTEXT: {DECISIONS_CONTEXT}
+<!-- learning:end -->
 FEATURE_KNOWLEDGE: {FEATURE_KNOWLEDGE}
 PR_DESCRIPTION: <pr-description>{PR_DESCRIPTION}</pr-description>
 OUTPUT_PATH: {ANALYSIS_DIR}/{focus}.md
+<!-- learning:on -->
 Follow devflow:apply-decisions to Read full ADR/PF bodies on demand.
+<!-- learning:end -->
 Follow devflow:apply-feature-knowledge for FEATURE_KNOWLEDGE.
 IMPORTANT: Write report to {ANALYSIS_DIR}/{focus}.md using Write tool"
 ```
@@ -299,7 +315,9 @@ Run `/resolve` to process and fix these findings.
 │              Write static-findings.md
 │
 ├─ Phase 3: Context Loading
+<!-- learning:on -->
 │  ├─ index.md (pre-rendered) → DECISIONS_CONTEXT
+<!-- learning:end -->
 │  ├─ Feature knowledge load → FEATURE_KNOWLEDGE
 │  └─ {worktree}/.devflow/docs/design/*.md → PLAN_CONTEXT + ACCEPTANCE_RULES
 │
@@ -356,7 +374,11 @@ Before reporting results, verify every phase was executed:
 
 - [ ] Phase 1: Pre-flight → BRANCH_INFO captured, PR_DESCRIPTION fetched (or `(none)`)
 - [ ] Phase 2: Static Analysis → STATIC_FINDINGS captured (or `(none)` if skipped/no tools/no findings); ANALYSIS_DIR created; CHANGED_FILES populated
+<!-- learning:on -->
 - [ ] Phase 3: Context Loading → DECISIONS_CONTEXT captured, FEATURE_KNOWLEDGE loaded (or `(none)`), PLAN_CONTEXT and ACCEPTANCE_RULES captured (or `(none)`)
+<!-- learning:off -->
+- [ ] Phase 3: Context Loading → FEATURE_KNOWLEDGE loaded (or `(none)`), PLAN_CONTEXT and ACCEPTANCE_RULES captured (or `(none)`)
+<!-- learning:end -->
 - [ ] Phase 4: File Analysis → ACTIVE_FOCUSES determined (security + functional always present)
 - [ ] Phase 5: Parallel Bug Analysis → ANALYZER_OUTPUTS captured per active focus; all reports written to ANALYSIS_DIR
 - [ ] Phase 6: Synthesis → BUG_ANALYSIS_SUMMARY written to `{ANALYSIS_DIR}/bug-analysis-summary.md`

package/src/assets/commands/code-review.mds

@@ -7,6 +7,7 @@ output-dir: dist/commands
 @import { compliance_gate } from "./_partials/_compliance.mds"
 @import { evidence_policy } from "./_partials/_evidence_policy.mds"
 @import { publication_gate } from "./_partials/_publication.mds"
+@import "./_partials/_settings.mds" as settings
 # Code Review Command
 
 Run a comprehensive code review of the current branch by spawning parallel review agents, then synthesizing results into PR comments. Supports incremental reviews, timestamped report directories, and multi-worktree auto-discovery.
@@ -40,6 +41,8 @@ Run a comprehensive code review of the current branch by spawning parallel revie
 
 **Produces:** COMPLIANCE_ACTIVE, COMPLIANCE_FRAMEWORKS
 
+{{settings.settings_resolve()}}
+
 {{compliance_gate()}}
 Keep each worktree's values for every downstream phase of that worktree.
 
@@ -164,10 +167,48 @@ For each reviewable worktree, call:
 
 ### Phase 1: Analyze Changed Files
 
-**Produces:** REVIEW_FOCUS_LIST
-**Requires:** DIFF_RANGE, COMPLIANCE_ACTIVE (from Step 0b)
+**Produces:** REVIEW_FOCUS_LIST, DIFF_CLASS, DIFF_FILES
+**Requires:** DIFF_RANGE, REVIEW_DIR, COMPLIANCE_ACTIVE (from Step 0b)
+
+Per worktree, in order. Each `git` command here writes to a file and prints nothing.
+
+#### Step 1.1: Classify the diff
+
+**Produces:** DIFF_CLASS, CHANGED_PATHS, REVIEW_FOCUS_LIST (reduced classes)
+**Requires:** DIFF_RANGE, REVIEW_DIR
+
+List the changed paths into `{REVIEW_DIR}/paths.txt` and print only the line count (drop `-C "{WORKTREE_PATH}"` when there is no `WORKTREE_PATH`):
+
+```bash
+git -C "{WORKTREE_PATH}" diff --name-only --no-renames {DIFF_RANGE} > "{REVIEW_DIR}/paths.txt"
+wc -l < "{REVIEW_DIR}/paths.txt"
+```
+
+Read `paths.txt` once when the count is about 40 or fewer, and in ranges of about 40 lines (Read with offset and limit) when it is more. `--no-renames` lists a moved file under its old path and its new one, so a move cannot take a file out of its own class.
+
+Set `DIFF_CLASS` by these rules, in order; the first that decides wins:
+
+1. **Instruction and config paths are `code`.** Any changed path that is `CLAUDE.md`, `AGENTS.md`, under `.claude/` or `src/assets/`, a `*.mds` file, under a plugin's `agents/`, `skills/` or `commands/` directory, `.devflow/project.json`, `.devflow/conventions.md`, or a manifest or build file (`package.json`, `go.mod`, `Cargo.toml`, `pyproject.toml`, `requirements*.txt`, `CMakeLists.txt`). This rule runs first, so a diff made only of such files is `code` and never `docs-only`.
+2. **`docs-only`.** Every changed path matches `*.md`, `*.mdx`, `*.rst`, `*.txt`, `docs/**` or `CHANGELOG*`.
+3. **`tests-only`.** Every changed path matches `tests/**`, `**/__tests__/**`, `*.test.*`, `*.spec.*`, `*_test.go`, `test_*.py` or `*_test.py`.
+4. **`lockfile-only`.** Every changed path is `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `bun.lockb`, `Cargo.lock`, `go.sum`, `poetry.lock`, `uv.lock`, `Gemfile.lock` or `composer.lock`.
+5. **Mixed non-code.** Every changed path matches the docs, tests or lockfile patterns, but no single rule above holds (docs with tests, tests with a lockfile): `DIFF_CLASS` names each class involved.
+6. **Fail-safe is `code`.** A changed path that matches no class pattern makes the diff `code`, and so does an empty path list. A manifest change is `code` and never `lockfile-only`.
+
+Each reduced class runs only its focus set, every member reading `diff.patch`:
+
+- `docs-only`: documentation, consistency, security
+- `tests-only`: testing, reliability, consistency, security
+- `lockfile-only`: dependencies, security
+
+A mixed non-code diff runs the union of the sets of the classes it holds. Language and conditional triggers inside a reduced class are suppressed: they add no focus, and Step 1.2 applies to the `code` class only.
 
-Per worktree, detect file types in diff using `DIFF_RANGE` to determine conditional reviews.
+#### Step 1.2: Choose the focuses
+
+**Produces:** REVIEW_FOCUS_LIST (code class)
+**Requires:** DIFF_CLASS, CHANGED_PATHS, COMPLIANCE_ACTIVE
+
+When `DIFF_CLASS` is `code`, read the file types from the paths in `paths.txt` to determine conditional reviews:
 
 | Condition | Adds Review |
 |-----------|-------------|
@@ -186,57 +227,104 @@ Per worktree, detect file types in diff using `DIFF_RANGE` to determine conditio
 
 If `COMPLIANCE_ACTIVE` AND the diff touches regulated surface (data models, auth flows, logging/observability, payments, IaC, retention): add `compliance` to REVIEW_FOCUS_LIST for this worktree.
 
-**Language focus presence gate.** The eight language focuses — `typescript`, `react`, `accessibility`, `ui-design`, `go`, `java`, `python`, `rust` — ship with optional plugins, so their pattern skills are installed only when the user selected that plugin. Gate them by presence: for each language focus the table above would add, check whether `{claude_dir}/skills/devflow:{focus}/SKILL.md` exists, `{claude_dir}` being Claude Code's directory as the installer resolves it — `CLAUDE_CONFIG_DIR` when that is set to an absolute path, else `$HOME/.claude` (D-CLAUDE-DIR-PROMPTS). Run one read-only, silent check per candidate focus:
+**Language focus stamp.** The eight language focuses — `typescript`, `react`, `accessibility`, `ui-design`, `go`, `java`, `python`, `rust` — ship with optional plugins, and the installer stamps the ones installed on this machine onto this line, rewriting it on every install and on `uninstall --plugin`:
+
+Installed language focuses: (none)
+
+A language focus is spawned only when its file-type condition above fires AND its name appears in that stamped line. A focus missing from the line is never spawned, even when its trigger fires. The eight core focuses are unconditional and are never stamp-gated.
+
+#### Step 1.3: Write the diff files
+
+**Produces:** DIFF_FILES
+**Requires:** DIFF_RANGE, REVIEW_DIR, REVIEW_FOCUS_LIST
+
+Write `diff.patch` once per worktree, by redirect:
 
 ```bash
-d="${CLAUDE_CONFIG_DIR:-}"; case "$d" in /*) ;; *) d="$HOME/.claude" ;; esac; test -f "$d/skills/devflow:{focus}/SKILL.md"; echo "exit=$?"
+git -C "{WORKTREE_PATH}" diff --no-color --no-ext-diff --no-textconv {DIFF_RANGE} > "{REVIEW_DIR}/diff.patch"
 ```
 
-Only `exit=0` means the skill is installed. On any other result, do NOT add that focus to `REVIEW_FOCUS_LIST` and do NOT spawn a Review agent for it — the file-type condition alone never spawns a language focus. The eight core focuses are unconditional and are never presence-gated.
+It holds the whole diff of `DIFF_RANGE`. On a `code` diff, add one patch for each language focus in REVIEW_FOCUS_LIST, by the same command with quoted pathspecs from this table:
 
+```bash
+git -C "{WORKTREE_PATH}" diff --no-color --no-ext-diff --no-textconv {DIFF_RANGE} -- '<pathspec>' ... > "{REVIEW_DIR}/diff-{focus}.patch"
+```
+
+| Focus | Pathspecs |
+|-------|-----------|
+| typescript | `'*.ts' '*.tsx'` |
+| react, accessibility | `'*.tsx' '*.jsx'` |
+| ui-design | `'*.tsx' '*.jsx' '*.css' '*.scss'` |
+| go | `'*.go'` |
+| java | `'*.java'` |
+| python | `'*.py'` |
+| rust | `'*.rs'` |
+
+The core, database, dependencies, documentation and compliance focuses, and every reduced-class focus, read `diff.patch`. A language focus sees only its own extensions and reaches anything else through `DIFF_RANGE`. Set `DIFF_FILES` to the files written. They live in `REVIEW_DIR`, under the gitignored `.devflow/` tree, with `paths.txt`: never committed, posted or passed to the Git agent.
+
+<!-- learning:on -->
 ### Phase 1b: Load Decisions Index
+<!-- learning:off -->
+### Phase 1b: Load Context
+<!-- learning:end -->
 
-**Produces:** DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, COMPLIANCE_FRAMEWORKS (carried from Step 0b)
+<!-- learning:on -->
+**Produces:** DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, FEATURE_KNOWLEDGE_RULES, COMPLIANCE_FRAMEWORKS (carried from Step 0b)
+<!-- learning:off -->
+**Produces:** FEATURE_KNOWLEDGE, FEATURE_KNOWLEDGE_RULES, COMPLIANCE_FRAMEWORKS (carried from Step 0b)
+<!-- learning:end -->
 
 {{decisions_load()}}
-
+<!-- learning:on -->
 This produces a compact index of active ADR/PF entries. Pass `DECISIONS_CONTEXT` to all Review agents. Review agents use `devflow:apply-decisions` to Read full entry bodies on demand.
 
+<!-- learning:end -->
 {{knowledge_load()}}
 
+<!-- learning:on -->
 Pass `FEATURE_KNOWLEDGE` to all Review agents alongside `DECISIONS_CONTEXT`.
+<!-- learning:off -->
+Pass `FEATURE_KNOWLEDGE` to all Review agents.
+<!-- learning:end -->
 
 ### Phase 2: Run Reviews (Parallel)
 
 **Produces:** REVIEW_FOCUS_OUTPUTS
-**Requires:** DIFF_RANGE, REVIEW_DIR, TIMESTAMP, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, PR_DESCRIPTION, PRIOR_RESOLUTIONS, REVIEW_FOCUS_LIST
-
-Spawn Review agents **in a single message**. Always run 8 core reviews; conditionally add more based on changed file types (max 20 per worktree):
-
-| Focus | Always | Pattern Skill |
-|-------|--------|---------------|
-| security | ✓ | devflow:security |
-| architecture | ✓ | devflow:architecture |
-| performance | ✓ | devflow:performance |
-| complexity | ✓ | devflow:complexity |
-| consistency | ✓ | devflow:consistency |
-| regression | ✓ | devflow:regression |
-| testing | ✓ | devflow:testing |
-| reliability | ✓ | devflow:reliability |
-| typescript | presence-gated | devflow:typescript |
-| react | presence-gated | devflow:react |
-| accessibility | presence-gated | devflow:accessibility |
-| ui-design | presence-gated | devflow:ui-design |
-| go | presence-gated | devflow:go |
-| java | presence-gated | devflow:java |
-| python | presence-gated | devflow:python |
-| rust | presence-gated | devflow:rust |
-| database | conditional | devflow:database |
-| dependencies | conditional | devflow:dependencies |
-| documentation | conditional | devflow:documentation |
-| compliance | diff-driven | devflow:compliance |
-
-Review agent count: 8 always-active, +1-12 diff-driven conditional (max 20 total per worktree).
+<!-- learning:on -->
+**Requires:** DIFF_RANGE, REVIEW_DIR, TIMESTAMP, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, PR_DESCRIPTION, PRIOR_RESOLUTIONS, REVIEW_FOCUS_LIST, DIFF_CLASS, DIFF_FILES
+<!-- learning:off -->
+**Requires:** DIFF_RANGE, REVIEW_DIR, TIMESTAMP, FEATURE_KNOWLEDGE, PR_DESCRIPTION, PRIOR_RESOLUTIONS, REVIEW_FOCUS_LIST, DIFF_CLASS, DIFF_FILES
+<!-- learning:end -->
+
+Spawn Review agents **in a single message**, for the focus set `DIFF_CLASS` selects (max 20 per worktree):
+
+- `code`: the 8 core reviews on the full `diff.patch`, plus the language and conditional focuses Phase 1 added.
+- `docs-only`, `tests-only`, `lockfile-only`: only the reduced set Phase 1 names, each reading `diff.patch`; a mixed non-code diff runs the union. No language or conditional focus is spawned, whatever its trigger.
+
+| Focus | Runs | Pattern Skill | DIFF_FILE |
+|-------|------|---------------|-----------|
+| security | ✓ | devflow:security | diff.patch |
+| architecture | ✓ | devflow:architecture | diff.patch |
+| performance | ✓ | devflow:performance | diff.patch |
+| complexity | ✓ | devflow:complexity | diff.patch |
+| consistency | ✓ | devflow:consistency | diff.patch |
+| regression | ✓ | devflow:regression | diff.patch |
+| testing | ✓ | devflow:testing | diff.patch |
+| reliability | ✓ | devflow:reliability | diff.patch |
+| typescript | stamp-gated | devflow:typescript | diff-typescript.patch |
+| react | stamp-gated | devflow:react | diff-react.patch |
+| accessibility | stamp-gated | devflow:accessibility | diff-accessibility.patch |
+| ui-design | stamp-gated | devflow:ui-design | diff-ui-design.patch |
+| go | stamp-gated | devflow:go | diff-go.patch |
+| java | stamp-gated | devflow:java | diff-java.patch |
+| python | stamp-gated | devflow:python | diff-python.patch |
+| rust | stamp-gated | devflow:rust | diff-rust.patch |
+| database | conditional | devflow:database | diff.patch |
+| dependencies | conditional | devflow:dependencies | diff.patch |
+| documentation | conditional | devflow:documentation | diff.patch |
+| compliance | diff-driven | devflow:compliance | diff.patch |
+
+Review agent count: `code` runs 8 core, +1-12 added by Phase 1 (max 20 total per worktree); a reduced class or a mix runs 2-6.
 
 Each Review agent invocation (all in one message, **NOT background**):
 ```
@@ -245,14 +333,19 @@ Agent(subagent_type="Review", run_in_background=false):
 Follow 6-step process from devflow:review-methodology.
 PR: #{pr_number}, Base: {base_branch}
 WORKTREE_PATH: {worktree_path}  (omit if cwd)
-DIFF_COMMAND: git -C {WORKTREE_PATH} diff {DIFF_RANGE}  (omit -C flag if no WORKTREE_PATH)
+DIFF_FILE: {diff_file}  (absolute: {REVIEW_DIR}/diff.patch, or {REVIEW_DIR}/diff-{focus}.patch for a language focus, per the table)
+DIFF_RANGE: {DIFF_RANGE}  (information only)
+<!-- learning:on -->
 DECISIONS_CONTEXT: {decisions_context}
+<!-- learning:end -->
 FEATURE_KNOWLEDGE: {feature_knowledge}
 PR_DESCRIPTION: <pr-description>{pr_description}</pr-description>
 PRIOR_RESOLUTIONS: <prior-resolution-summary>{prior_resolutions}</prior-resolution-summary>
 COMPLIANCE_FRAMEWORKS: {COMPLIANCE_FRAMEWORKS}  (compliance focus only)
 If PRIOR_RESOLUTIONS is not (none), follow Cross-Cycle Awareness in review.md.
+<!-- learning:on -->
 Follow devflow:apply-decisions to scan the index and Read full ADR/PF bodies on demand.
+<!-- learning:end -->
 Follow devflow:apply-feature-knowledge for FEATURE_KNOWLEDGE — feature-specific patterns and anti-patterns inform findings.
 IMPORTANT: Write report to {worktree_path}/.devflow/docs/reviews/{branch-slug}/{timestamp}/{focus}.md using Write tool"
 ```
@@ -325,13 +418,15 @@ In multi-worktree mode, report results per worktree.
 ├─ Per worktree (SEQUENTIAL — one worktree at a time):
 │  │
 │  ├─ Phase 1: Analyze changed files
-│  │  └─ Detect file types for conditional reviews
+│  │  ├─ Classify the diff (paths.txt → DIFF_CLASS)
+│  │  ├─ Choose the focuses (code class: file types + the language stamp)
+│  │  └─ Write diff.patch and diff-{focus}.patch, by redirect
 │  │
 │  ├─ Phase 2: Reviews (PARALLEL within worktree)
-│  │  ├─ Review agent: security
-│  │  ├─ Review agent: architecture, performance, complexity
-│  │  ├─ Review agent: consistency, regression, testing
-│  │  └─ Review agent: [conditional]
+│  │  ├─ code: Review agents security, architecture, performance, complexity,
+│  │  │        consistency, regression, testing, reliability (diff.patch)
+│  │  ├─ code: + language (diff-{focus}.patch) and conditional Review agents
+│  │  └─ docs-only / tests-only / lockfile-only: the reduced set (diff.patch)
 │  │
 │  ├─ Phase 3: Synthesis → Review Comment (SEQUENTIAL within worktree)
 │  │  ├─ Step 3a: Synthesize agent (mode: review, writes review-summary.md)
@@ -360,6 +455,14 @@ In multi-worktree mode, report results per worktree.
 | `--full` flag | Bypass incremental detection (Step 0d), still load PRIOR_RESOLUTIONS for cross-cycle awareness |
 | Parsing failure on resolution-summary.md | fp_ratio = 0, convergence tracking degraded (see Step 0e-ii) |
 | Concurrent sessions | Advisory only, each session computes independently |
+| Docs-only diff | `docs-only`: documentation, consistency, security on `diff.patch`; no language or conditional focus |
+| Tests-only diff | `tests-only`: testing, reliability, consistency, security on `diff.patch`; no language or conditional focus |
+| Lockfile-only diff | `lockfile-only`: dependencies, security on `diff.patch` |
+| Mixed non-code diff (docs with tests, tests with a lockfile) | The union of the matching sets, on `diff.patch` |
+| A path matching no class pattern, or an empty path list | `code` (fail-safe): the 8 core focuses on the full diff |
+| A file moved across classes | `--no-renames` lists the old and the new path, so a code path makes the diff `code` |
+| Path listing above about 40 lines | The count is printed; `paths.txt` is read in ranges of about 40 lines |
+| Language files changed, plugin not installed | The focus is absent from the stamped line: not spawned |
 | Public repo (`auto` mode) | Git agent probes visibility, posts counts-only STUB comment; full report stays local |
 | `reviewPublication: off` | Git agent skips posting the review comment (OFF) — except that, only when `EVIDENCE_POLICY` is `required`, Step 0f passes `stub` and a counts-only STUB comment posts |
 
@@ -370,9 +473,9 @@ In multi-worktree mode, report results per worktree.
 
 ## Principles
 
-1. **Orchestration only** - Command spawns agents, doesn't do git/review work itself
+1. **Orchestration only** - Command spawns agents, doesn't do git/review work itself. The exceptions are the read-only Phase 0 probes (`git worktree list`, `git -C ... branch --show-current`, `git -C ... cat-file -t`), the bounded Phase 1 path listing (a redirect into `paths.txt`, a `wc -l` count and ranged reads) and the redirect-only patch writes (`diff.patch`, `diff-{focus}.patch`). Redirect-only writes print nothing, so no diff content reaches this thread
 2. **Parallel, not background** - Multiple agents in one message, but `run_in_background=false` so phases complete before proceeding
-3. **Git agent for git work** - All git operations go through Git agent
+3. **Git agent for git work** - All git operations go through Git agent, except the exceptions named in Principle 1; redirect-only writes print nothing
 4. **Clear ownership** - Each agent owns its output completely
 5. **Honest reporting** - Display agent outputs directly
 6. **Incremental by default** - Only review new changes unless `--full` specified

package/src/assets/commands/debug.mds

@@ -5,6 +5,7 @@ output-dir: dist/commands
 @import { knowledge_writeback } from "./_partials/_knowledge.mds"
 @import { decisions_load } from "./_partials/_decisions.mds"
 @import { issue_ref_grammar, issue_capture_contract } from "./_partials/_tracker.mds"
+@import "./_partials/_settings.mds" as settings
 # Debug Command
 
 Investigate bugs by spawning parallel agents, each pursuing a different hypothesis. Evidence is aggregated and synthesized to identify the root cause.
@@ -32,20 +33,31 @@ $ARGUMENTS
 
 ## Phases
 
+<!-- learning:on -->
 ### Phase 1: Load Decisions Index (Orchestrator-Local)
+<!-- learning:off -->
+### Phase 1: Resolve Settings
+<!-- learning:end -->
 
+<!-- learning:on -->
 **Produces:** DECISIONS_CONTEXT
 
-{{decisions_load()}}
+<!-- learning:end -->
+{{settings.settings_resolve()}}
 
+{{decisions_load()}}
+<!-- learning:on -->
 The orchestrator uses `DECISIONS_CONTEXT` locally when generating hypotheses (Phase 2) — prior pitfalls and decisions can suggest specific root causes to investigate. Follow `devflow:apply-decisions` to Read full entry bodies on demand. **Do NOT pass `DECISIONS_CONTEXT` to Explore investigators** — decisions context stays in the orchestrator; investigators examine code directly.
 
+<!-- learning:end -->
 **No up-front feature knowledge load** — debug investigation workers read code directly to avoid confirmation bias. Feature knowledge is only written back at the end if the investigation surfaced durable, cross-cutting knowledge.
 
 ### Phase 2: Context Gathering
 
 **Produces:** HYPOTHESES, BUG_CONTEXT
+<!-- learning:on -->
 **Requires:** DECISIONS_CONTEXT
+<!-- learning:end -->
 
 If `COMMAND_INPUT` opens with a candidate issue reference, fetch the issue:
 
@@ -193,7 +205,11 @@ Ask user via AskUserQuestion: "Want me to implement this fix?"
 ```
 /debug (orchestrator)
 │
+<!-- learning:on -->
 ├─ Phase 1: Load Decisions Index (Orchestrator-Local)
+<!-- learning:off -->
+├─ Phase 1: Resolve Settings
+<!-- learning:end -->
 │  └─ No up-front feature knowledge load (avoids confirmation bias in investigators)
 │
 ├─ Phase 2: Context gathering

package/src/assets/commands/dynamic-build.mds

@@ -3,7 +3,7 @@ description: Dependency-aware build engine — implement, review, and verify a s
 argument-hint: "[ticket | issue-url | plan-doc]"
 output-dir: dist/commands
 ---
-@import { authoring_preamble } from "./_partials/_preamble.mds"
+@import { authoring_preamble, authoring_decisions } from "./_partials/_preamble.mds"
 @import { evidence_policy } from "./_partials/_evidence_policy.mds"
 @import { docs_root } from "./_partials/_docs_root.mds"
 @import { agent_roster, agent_caveats } from "./_partials/_roster.mds"
@@ -13,8 +13,14 @@ output-dir: dist/commands
 @import { issue_ref_grammar, issue_capture_contract } from "./_partials/_tracker.mds"
 @import "./_partials/_publication.mds" as pub
 @import "./_partials/_compliance.mds" as compliance
+@import "./_partials/_settings.mds" as settings
 {{authoring_preamble()}}
 
+### Settings line
+
+{{settings.settings_resolve()}}
+
+{{authoring_decisions()}}
 ---
 
 ## dynamic-build — author and run a build workflow
@@ -69,10 +75,12 @@ Pass it as `complianceFrameworks` when invoking the workflow; the engine hands i
 
 `{integration worktree root}` is the toplevel of the checkout the integration branch is checked out in: `{worktree}` unless the wave runs in a linked worktree.
 
+<!-- learning:on -->
 **1. Apply decisions context**
 
-Apply the `devflow:apply-decisions` algorithm to the DECISIONS_CONTEXT loaded per the preamble above: scan the index, Read relevant entries, note the verbatim ADR/PF IDs you will inject into Code agent and Evaluate agent prompts.
+Apply the `devflow:apply-decisions` algorithm to the DECISIONS_CONTEXT loaded by the decisions step above: scan the index, Read relevant entries, note the verbatim ADR/PF IDs you will inject into Code agent prompts.
 
+<!-- learning:end -->
 **2. Read budget**
 
 Note the `budget` value from the Workflow tool context (or default to "medium" if not provided). This governs Review agent roster size and verification vote count.
@@ -150,7 +158,9 @@ const TICKET = args.ticket || args[0] || "see task description";
 const PLAN = args.plan || null;
 const CRITERIA = args.criteria || null;
 const TEST_PLAN = args.testPlan || null;  // the plan's checked TP lines, one string (Pre-authoring step 4)
+<!-- learning:on -->
 const DECISIONS_CONTEXT = args.decisionsContext || "";  // injected before authoring
+<!-- learning:end -->
 const ISSUE_INPUT = args.issueInput || args.issueNumber || "(none)";  // this ticket's OWN raw reference (Pre-authoring step 5; a wave passes issueInput) — setup-task's input, never a Code agent's
 const ISSUE_REQUIRED = String(args.issueRequired) === "false" ? "false" : "true";  // Pre-authoring step 0; only an explicit false turns it off — absent or unrecognised fails closed, like the resolver
 const APPLY_CONVENTIONS = String(args.applyConventions) === "false" ? "false" : "true";
@@ -194,9 +204,11 @@ ${TICKET}
 
 ${PLAN ? `Implementation plan:\n${PLAN}` : "No plan provided — use best judgment."}
 
+<!-- learning:on -->
 Relevant architectural decisions (apply devflow:apply-decisions algorithm):
 ${DECISIONS_CONTEXT}
 
+<!-- learning:end -->
 ISSUE_NUMBER: ${ISSUE_NUMBER}
 ISSUE_PR_LINK: ${ISSUE_PR_LINK}
 COMPLIANCE_FRAMEWORKS: ${COMPLIANCE_FRAMEWORKS}
@@ -233,6 +245,9 @@ Return: {"verdict": "PASS" | "FAIL", "details": "..."}`, { agentType: "Validate"
       await agent(`OPERATION: validation-fix
 Fix the validation failures on branch ${BRANCH}:
 ${failureDetails}
+<!-- learning:on -->
+DECISIONS_CONTEXT: ${DECISIONS_CONTEXT}
+<!-- learning:end -->
 ISSUE_NUMBER: ${ISSUE_NUMBER}
 ISSUE_PR_LINK: ${ISSUE_PR_LINK}
 COMPLIANCE_FRAMEWORKS: ${COMPLIANCE_FRAMEWORKS}
@@ -275,6 +290,9 @@ Return: {"verdict": "PASS" | "FAIL", "rationale": "..."} — FAIL if either answ
       await agent(`OPERATION: alignment-fix
 Fix the alignment issues identified by the Evaluate agent on branch ${BRANCH}:
 ${evaluation?.rationale || "see the Evaluate agent's report"}
+<!-- learning:on -->
+DECISIONS_CONTEXT: ${DECISIONS_CONTEXT}
+<!-- learning:end -->
 ISSUE_NUMBER: ${ISSUE_NUMBER}
 ISSUE_PR_LINK: ${ISSUE_PR_LINK}
 COMPLIANCE_FRAMEWORKS: ${COMPLIANCE_FRAMEWORKS}
@@ -296,6 +314,9 @@ Cover: functionality, API contracts, performance, and cover every TEST_PLAN scen
       await agent(`OPERATION: qa-fix
 Fix the failing acceptance test scenarios on branch ${BRANCH}:
 ${testResult.failures}
+<!-- learning:on -->
+DECISIONS_CONTEXT: ${DECISIONS_CONTEXT}
+<!-- learning:end -->
 ISSUE_NUMBER: ${ISSUE_NUMBER}
 ISSUE_PR_LINK: ${ISSUE_PR_LINK}
 COMPLIANCE_FRAMEWORKS: ${COMPLIANCE_FRAMEWORKS}
@@ -415,6 +436,9 @@ ISSUES:
 ${chunk.map((f, n) => `${n + 1}. ${f.file ? `${f.file}${f.line ? `:${f.line}` : ""} — ` : ""}${f.description} (${f.severity})`).join("\n")}
 SCOPE: ${chunk.map((f, n) => `${n + 1}=${CAREFUL_SEVERITIES.has(String(f.severity).toLowerCase()) ? "Careful" : "Standard"}`).join(", ")}
 PUSH: false
+<!-- learning:on -->
+DECISIONS_CONTEXT: ${DECISIONS_CONTEXT}
+<!-- learning:end -->
 ISSUE_NUMBER: ${ISSUE_NUMBER}
 ISSUE_PR_LINK: ${ISSUE_PR_LINK}
 COMPLIANCE_FRAMEWORKS: ${COMPLIANCE_FRAMEWORKS}
@@ -475,6 +499,9 @@ Return: {"verdict": "PASS" | "FAIL", "details": "..."}`, { agentType: "Validate"
       await agent(`OPERATION: validation-fix
 Fix the final validation failures on branch ${BRANCH}:
 ${failureDetails}
+<!-- learning:on -->
+DECISIONS_CONTEXT: ${DECISIONS_CONTEXT}
+<!-- learning:end -->
 ISSUE_NUMBER: ${ISSUE_NUMBER}
 ISSUE_PR_LINK: ${ISSUE_PR_LINK}
 COMPLIANCE_FRAMEWORKS: ${COMPLIANCE_FRAMEWORKS}
@@ -604,7 +631,11 @@ Return: {"ready": [...ticket-ids], "blocked": [{"ticket": "id", "namedBlocker":
     try {
       // ticketId is the ISSUE_REF the pre-fetch heading printed — this ticket's OWN reference: the engine's `ticket` (its TICKET)
       // and its setup-task ISSUE_INPUT; the engine returns the branch that setup-task created, merged below; plans[ticketId] is its own plan, criteria and checked testPlan (Pre-authoring step 4)
+<!-- learning:on -->
       const engineResult = await runSingleTicketEngine({ ticket: ticketId, baseBranch: INTEGRATION_BRANCH, ...(plans[ticketId] || {}), decisionsContext: DECISIONS_CONTEXT, issueRequired: ISSUE_REQUIRED, applyConventions: APPLY_CONVENTIONS, complianceFrameworks: COMPLIANCE_FRAMEWORKS, issueInput: ticketId });
+<!-- learning:off -->
+      const engineResult = await runSingleTicketEngine({ ticket: ticketId, baseBranch: INTEGRATION_BRANCH, ...(plans[ticketId] || {}), issueRequired: ISSUE_REQUIRED, applyConventions: APPLY_CONVENTIONS, complianceFrameworks: COMPLIANCE_FRAMEWORKS, issueInput: ticketId });
+<!-- learning:end -->
       // Check both verdict (engine_output_schema) and overallVerdict (SINGLE skeleton alias).
       // PASS and UNVERIFIED merge; PARTIAL, FAIL, ESCALATED (the ticket-link and branch stops included) or no verdict quarantine.
       if (["PASS", "UNVERIFIED"].includes(engineResult.verdict || engineResult.overallVerdict)) {