devflow-kit 3.2.0 → 3.4.0

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

@@ -1,4 +1,7 @@
-@import "./_settings.mds" as settings
+A partial: the feature-knowledge load and write-back steps. D-SETTINGS-LINE: it
+imports nothing from `_settings.mds`. Write-back Step 1 takes `KNOWLEDGE` from the
+settings line the host's settings block resolved above, and keeps the
+`KNOWLEDGE=off` skip inside its own step.
 
 @define knowledge_load():
 ### Load Feature Knowledge
@@ -29,22 +32,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, 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.
+For each selected entry, `{kb}` is `{worktree}/.devflow/features/{slug}/KNOWLEDGE.md`:
 
-**Step 5 — Set FEATURE_KNOWLEDGE:**
+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.
 
-Concatenate the selected KNOWLEDGE.md files under slug headers:
+When a KB contradicts the code you observe, **trust the code** — the code is the freshness mechanism; the KB may lag behind. A missing Rules section, a missing heading list and `(none)` are legitimate states, not errors.
+
+**Step 5 — Set FEATURE_KNOWLEDGE and FEATURE_KNOWLEDGE_RULES:**
+
+Write one block per selected KB. Paste each bullet verbatim from the Read view, never from a shell view. The path is relative to the checkout root; an agent resolves it under `WORKTREE_PATH` when one is provided.
 
 ```
 --- Feature knowledge: {slug} ---
-{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.
 @end
 
 @export knowledge_load
@@ -60,16 +73,14 @@ 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 — Check the opt-out gate, with `{root}` = `{worktree}`:**
-
-{{settings.settings_resolve()}}
+**Step 1 — Check the opt-out gate, with `{root}` = `{worktree}`:** take the settings line resolved above for that root, resolving it with the settings block when this run has not yet.
 
 If the settings line says `KNOWLEDGE=off`, skip write-back entirely. The machine switch (`devflow knowledge --disable`), the repository and the personal settings can each turn knowledge off, and none can turn it back on (D-FEATURES-NARROW-ONLY). The fail-closed line says `KNOWLEDGE=off` too, so an unresolvable line skips write-back.
 
 **Step 2 — Evaluate whether write-back is warranted:**
 
 Only proceed if **at least one** of these is true:
-- This workflow changed files in a directory that is documented by an existing feature knowledge base (a documented area changed).
+- This workflow changed files in a directory that is documented by an existing feature knowledge base (a documented area changed). Knowledge bases are written through at that point, never on a background schedule.
 - This workflow surfaced durable, cross-cutting knowledge about a codebase area that would help future agents working in the same area — patterns, anti-patterns, integration points, gotchas not visible from a single file read.
 
 **Never spawn unconditionally.** If neither condition is met, skip write-back silently.
@@ -84,7 +95,9 @@ FEATURE_SLUG: {slug derived from primary changed directory, kebab-case}
 FEATURE_NAME: {human-readable name}
 DIRECTORIES: {list of primary directories touched by this workflow}
 FILES_CHANGED: {list of files changed}
+<!-- learning:on -->
 DECISIONS_CONTEXT: {DECISIONS_CONTEXT if available, else (none)}
+<!-- learning:end -->
 
 Write the knowledge base to:
   {worktree}/.devflow/features/{slug}/KNOWLEDGE.md
@@ -92,7 +105,7 @@ Write the knowledge base to:
 Then update the index cache by performing a read-modify-write on:
   {worktree}/.devflow/features/index.md
 
-Index line format: `- **{slug}** — {areas} — {Use-when description}`
+Index line format: `- **{slug}** — {areas} — {Use-when description}` — at most 300 characters, the description at most 220; reword a longer one, never cut it.
 
 If the line for this slug already exists in index.md, replace it. If it does not exist, append it. If index.md does not exist, create it with just this line.
 

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

@@ -46,7 +46,7 @@ Every line of a `## Test Plan` section, or of a PR's test-plan block, follows th
 
 #### Consumption by Gate 2
 
-The Evaluate agent panel receives: the per-ticket plan + the numbered acceptance criteria (positive and negative).
+The Evaluate agent receives: the per-ticket plan + the numbered acceptance criteria (positive and negative).
 
 The Test agent receives: the test plan's TP lines, once `check tp` has admitted them.
 

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

@@ -1,5 +1,21 @@
 @import "./_decisions.mds" as decisions
 
+A partial: the Workflow-authoring preamble the dynamic commands share, and the
+decisions step that precedes authoring.
+
+D-DECISIONS-AUTHORING-STEP: the "DECISIONS_CONTEXT — obtain BEFORE authoring" step
+is its own define, `authoring_decisions()`, expanded by the hosts that load
+decisions (dynamic-build, dynamic-plan, dynamic-tickets and dynamic-profile) right
+after their settings block, so the gate in it reads a line already resolved.
+`authoring_preamble()` carries no decisions text. D-LEARNING-VARIANTS: the whole of
+`authoring_decisions()` is a learning-on arm, so a learning-off build carries no decisions
+step.
+
+D-DECISIONS-DECLARED-ONLY: the step names, as the receivers of the index, only the
+agent types whose contract declares `DECISIONS_CONTEXT` among the valid
+`agentType`s. `tests/decisions/decisions-seam.test.ts` computes the declared set
+from the agent sources and holds every pass sentence to it.
+
 @define authoring_preamble():
 ## Your task: author a Claude Code dynamic Workflow and run it
 
@@ -62,17 +78,9 @@ Then run a cheap syntax gate: write the authored script to a fresh, run-unique s
 
 The `budget` global governs depth. Scale Review agent roster and verification votes to `budget`. A low-budget run uses a leaner roster and fewer verification votes; a high-budget run expands both. Never hardcode a roster size — let budget guide it.
 
-### DECISIONS_CONTEXT — obtain BEFORE authoring
-
-{{decisions.decisions_locate()}}
-
-Before you author the workflow script, 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`.
-
-The script body cannot perform this read — you (the main model) do it before authoring. Then inject the relevant DECISIONS_CONTEXT into agent prompts using the `devflow:apply-decisions` consumption algorithm (scan index → Read relevant entries → cite verbatim IDs in agent prompts). Only agents that need architectural context (Code agent, Evaluate agent, Review agent, Scrutinize agent) need DECISIONS_CONTEXT injected; lightweight agents (Validate agent, Simplify agent) do not.
-
 ### Handoff convention for sequential Code agents within a ticket
 
-When a ticket requires multiple sequential Code agent phases, each Code agent writes `{toplevel}/.devflow/docs/handoff-{branch_slug}.md` (branch-scoped to prevent concurrent session clobber), `{toplevel}` being `git rev-parse --show-toplevel` in the checkout the ticket's branch is in — never a subdirectory. The next Code agent reads it via HANDOFF_FILE input. PRIOR_PHASE_SUMMARY is the compact in-context form; the handoff file is the durable form that survives context compaction. Always read the handoff file directly — code is authoritative, summaries are supplementary.
+When a ticket requires multiple sequential Code agent phases, each Code agent appends its own `## Phase {N} Implementation Summary` section, at most 8,192 bytes, to `{toplevel}/.devflow/docs/handoff-{branch_slug}.md` (branch-scoped to prevent concurrent session clobber), `{toplevel}` being `git rev-parse --show-toplevel` in the checkout the ticket's branch is in — never a subdirectory. It never rewrites an earlier section. The next Code agent reads, via HANDOFF_FILE input, only the section of the phase immediately before its own, not the whole file. PRIOR_PHASE_SUMMARY is the compact in-context form; the handoff file is the durable form that survives context compaction. Code is authoritative, summaries are supplementary.
 
 ### IRON RULE (LLM-vs-plumbing)
 
@@ -83,4 +91,20 @@ When a ticket requires multiple sequential Code agent phases, each Code agent wr
 **NEVER merge to main or master** — the workflow merges to an integration branch only. The user merges to main themselves after reviewing. This rule is absolute and must appear as an `engine_invariants()` note in every workflow that touches git.
 @end
 
+@define authoring_decisions():
+<!-- learning:on -->
+### DECISIONS_CONTEXT — obtain BEFORE authoring
+
+{{decisions.decisions_gate()}}
+
+{{decisions.decisions_locate()}}
+
+Before you author the workflow script, 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`.
+
+The script body cannot perform this read — you (the main model) do it before authoring. Then inject the relevant DECISIONS_CONTEXT into the prompts of the Code, Design, Knowledge, Review and Scrutinize agents, using the `devflow:apply-decisions` consumption algorithm (scan index → Read relevant entries → cite verbatim IDs in agent prompts). Those are the agent types above whose contract declares it; every other agent type gets no decisions context.
+
+<!-- learning:end -->
+@end
+
 @export authoring_preamble
+@export authoring_decisions

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

@@ -1,9 +1,10 @@
-@import "./_settings.mds" as settings
+A partial: the publication-value gate. D-SETTINGS-LINE: it imports nothing from
+`_settings.mds`. Its host expands the settings block once, before the earliest of
+its consumers, and this text takes `REVIEW_PUBLICATION` from the line resolved
+there for the worktree's root.
 
 @define publication_gate():
-{{settings.settings_resolve()}}
-
-**Resolve `REVIEW_PUBLICATION` per worktree:** take `REVIEW_PUBLICATION` from that worktree's settings line, with `{root}` the worktree's root — multi-worktree repos may resolve different values per worktree. The line already caps the personal choice at the team's (D-PUBLICATION-CEILING), so it is `off`, `auto` or `full`, and `off` when the line was unresolvable.
+**Resolve `REVIEW_PUBLICATION` per worktree:** take `REVIEW_PUBLICATION` from that worktree's settings line — the line resolved above for `{root}`, the worktree's root, by the settings block when this run has not yet resolved that root; multi-worktree repos may resolve different values per worktree. The line already caps the personal choice at the team's (D-PUBLICATION-CEILING), so it is `off`, `auto` or `full`, and `off` when the line was unresolvable.
 
 **Evidence stub:** only when `EVIDENCE_POLICY` is `required`, a resolved `off` becomes `stub`, so a counts-only record still reaches the PR. `stub` is never a config value: the settings line never carries it.
 

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

@@ -40,8 +40,8 @@ For each ready ticket (sequentially by default; parallel only past the §7.1 bar
 - Branch setup: the engine's setup-task creates the ticket's branch off integration HEAD at ready-time (so it already contains merged deps); every later phase, and the merge, uses the branch setup-task created, and a setup-task that reports none stops the ticket before implementing
 - Run the single-ticket engine inside a try/catch — one ticket's crash/stall never kills the wave; catch the exception, quarantine that ticket, and continue with the remaining ready set
 - The engine gets the ticket's own reference, the one the pre-fetch printed, as its setup-task input — never the wave's tracking issue
-- On engine PASS or UNVERIFIED: merge to integration branch, run Validate agent (build + test)
-  - Merge FAIL (build red after merge): quarantine ticket, mark as escalated, continue
+- On engine PASS or UNVERIFIED: merge to the integration branch locally through Git (no push, no build or test), then the workflow spawns the Validate agent (build + test) over the merge. The merge counts as kept only when that Validate returns PASS
+  - Validate FAIL or no PASS (build red after merge): the workflow spawns Git to undo the merge, quarantines the ticket, marks it as escalated, and continues. If the undo is refused, the wave stops taking merges and rounds
 - On any other verdict (PARTIAL, FAIL, ESCALATED) or none: quarantine ticket, do not block independent siblings
 
 **Cascade quarantine:** when a ticket is quarantined for any reason (Gate-1 exhausted, engine crash/stall, build-red after merge, review coverage incomplete after retry), the quarantine cascades to its direct and transitive dependents — each is marked blocked with the named reason, naming the blocker by its `{ISSUE_REF}` (e.g. "blocked: depends on {ISSUE_REF} which failed Gate-1"). Independent siblings are never affected. The quarantined list is injected into every subsequent Design agent reader prompt so the reader never schedules dependents of failed tickets.
@@ -70,7 +70,9 @@ MAX_ROUNDS = LLM judgment based on ticket count (heuristic: ticket_count * 2 + 5
 
 **Parallel independent tickets:** each gets its own `git worktree add` + durable branch managed by the Git agent. Use explicit `git worktree add` — NOT the Workflow tool's ephemeral `isolation:'worktree'`. The branch must persist across implement → review → resolve → merge stages; ephemeral worktrees are gone when the agent call ends.
 
-**Post-merge validation:** after EVERY merge into the integration branch, run Validate agent (build + test). A red build immediately after merge is the cheapest possible conflict detector. Red → quarantine the merged result + escalate.
+**Post-merge validation:** after EVERY merge into the integration branch, the workflow itself spawns the Validate agent (build + test) over the integration branch; Git runs no build or test. A red build immediately after merge is the cheapest possible conflict detector. It always runs — the merge reports `treeEqual` (whether the merge commit's tree equals the ticket branch head's tree) and the wave row records it, but a true value never skips the Validate.
+
+**Undo of a red merge:** on FAIL or no PASS verdict the workflow spawns Git to undo the merge. The undo runs only when no remote branch contains the merge commit and the integration HEAD still equals it, as `git reset --keep {mergeSha}^1` on the integration branch — never `--hard`, never a push. It returns `{"undone": true}` or `{"undone": false, "reason": "..."}`. Undone → the row reads `merged: false` and the ticket is quarantined ("post-merge build red; merge undone"). Not undone → the wave stops taking merges and rounds, and its report names the red integration HEAD.
 
 **Commit discipline:** Git agent creates atomic commits per logical change, conventional-commit format, on the ticket branch before merge.
 @end
@@ -83,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
-2. Spawn a Code agent with FULL intent context:
+<!-- 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: Validate agent (build + test) immediately
+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():
@@ -106,7 +116,7 @@ A workflow cannot pause mid-run (F4). "Escalate" means: quarantine-and-continue
 - Ticket engine FAIL after max retries (Gate 1 exhausted)
 - Gate 2 FAIL after max retries (Evaluate agent/Test agent not satisfied)
 - Circular dependency detected (all remaining tickets blocked on each other)
-- Build red after merge (Validate agent fails post-merge)
+- Build red after merge (the post-merge Validate agent fails: the merge is undone and the ticket quarantined; a refused undo halts the wave)
 - Review coverage incomplete after retry (a focus area failed to produce a live Review agent result after the retry)
 - Ticket engine crash/stall (unrecoverable exception or watchdog kill — quarantine cascades to dependents)
 - No ticket link while issues are required (the engine stops before implementing)

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`