devflow-kit 3.3.0 → 3.4.0

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

@@ -3,13 +3,21 @@ description: Parallel wave planning — plan-challenge every ticket, produce acc
 argument-hint: "[tickets-dir | issue-list]"
 output-dir: dist/commands
 ---
-@import { authoring_preamble } from "./_partials/_preamble.mds"
+@import { authoring_preamble, authoring_decisions } from "./_partials/_preamble.mds"
 @import { docs_root } from "./_partials/_docs_root.mds"
 @import { agent_roster, agent_caveats } from "./_partials/_roster.mds"
 @import { acceptance_criteria_contract } from "./_partials/_plan_contract.mds"
 @import { issue_ref_grammar, issue_capture_contract } from "./_partials/_tracker.mds"
+@import "./_partials/_settings.mds" as settings
 {{authoring_preamble()}}
 
+<!-- learning:on -->
+### Settings line
+
+{{settings.settings_resolve()}}
+
+<!-- learning:end -->
+{{authoring_decisions()}}
 ---
 
 ## dynamic-plan — author and run a parallel planning + plan-challenge workflow
@@ -44,10 +52,12 @@ Before authoring, verify:
 
 Pass `{worktree}` to the workflow as its `root` argument.
 
+<!-- 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 verbatim ADR/PF IDs to inject into Design 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 verbatim ADR/PF IDs to inject into Design agent prompts.
 
+<!-- learning:end -->
 **2. Read the preference profile**
 
 Check whether `~/.devflow/preference-profile.md` exists:
@@ -112,7 +122,9 @@ export const meta = {
 // AskUserQuestion happens at the command boundary after this workflow returns — NOT here.
 
 const ticketSource = args.ticketSource || args[0] || "see task description";
+<!-- learning:on -->
 const DECISIONS_CONTEXT = args.decisionsContext || "";   // injected before authoring
+<!-- learning:end -->
 const PREFERENCE_PROFILE = args.preferenceProfile || "";  // injected before authoring
 const TP_CONTRACT = args.tpContract || "";  // the "Test-plan line (TP)" contract below — its paragraph and four bullets — passed verbatim as tpContract when invoking the workflow, never pasted into this script (it holds backticks)
 const slug = args.slug || "wave";
@@ -133,7 +145,9 @@ const plans = await phase("plan-parallel", () =>
   parallel((tickets || []).map(ticket => () =>
     agent(`Write an implementation plan for this ticket.
 Ticket: ${JSON.stringify(ticket)}
+<!-- learning:on -->
 Decisions context (apply devflow:apply-decisions; a plan file can be posted to the tracker, so state each decision in words, never by ID): ${DECISIONS_CONTEXT}
+<!-- learning:end -->
 The plan must cover: approach overview, affected files and modules, key design decisions, implementation sequence (what to build first), risks and mitigations, and any open questions you cannot resolve from the ticket alone.
 Write a thorough but tight plan — every section must earn its place for a Code agent who has no other context.
 Return: { ticketTitle, planMarkdown, openDecisions (array of genuine unknowns requiring user input) }.`, { agentType: "Design" })
@@ -149,7 +163,6 @@ const challenged = await phase("plan-challenge", () =>
 
 Plan under review: ${JSON.stringify(plan)}
 Ticket: ${JSON.stringify((tickets || [])[i])}
-Decisions context: ${DECISIONS_CONTEXT}
 
 Produce:
 1. List of improvements / gaps / edge cases / side-effects identified.
@@ -160,7 +173,7 @@ Produce:
    - its verification method is its method: a test committed to the suite is ci; a command run and read (a load test, a script) is local; a step performed and observed is manual;
    - the paths it exercises, from the plan's affected files, are its files: globs.
    Setup and expected outcome never go in a line: give them per TP in testScenarios.
-4. A list of genuine design decisions that require user input (not settled by the plan, the preference profile, or existing ADRs).
+4. A list of genuine design decisions that require user input (not settled by the plan or the preference profile).
 
 Test-plan line contract:
 ${TP_CONTRACT}
@@ -178,7 +191,9 @@ Return: { ticketTitle, improvements (array), acceptanceCriteria (array of number
 const crossCritic = await phase("cross-plan-critic", () =>
   agent(`Cross-plan conflict audit.
 All ticket plans + challenged criteria: ${JSON.stringify(challenged)}
+<!-- learning:on -->
 Decisions context: ${DECISIONS_CONTEXT}
+<!-- learning:end -->
 
 Audit:
 1. API conflicts: two tickets defining the same API differently (different signatures, return types, error codes).
@@ -186,7 +201,11 @@ Audit:
 3. Undeclared dependencies: ticket A's plan implicitly requires something ticket B provides, but no dependency is declared.
 4. Scope overlap: two tickets both claim ownership of the same module or behavior.
 
+<!-- learning:on -->
 For each conflict found: state which two tickets are involved, describe the conflict precisely, and propose a resolution aligned with the decisions ledger.
+<!-- learning:off -->
+For each conflict found: state which two tickets are involved, describe the conflict precisely, and propose a resolution.
+<!-- learning:end -->
 
 Return: { conflicts (array of {tickets, conflictDescription, proposedResolution}), planAmendments (array of {ticketTitle, amendment}) }.`, { agentType: "Design" })
 );
@@ -199,10 +218,9 @@ const resolved = await phase("preference-resolve", () =>
 Preference profile: ${PREFERENCE_PROFILE || "(none — no profile found)"}
 Open decisions from plan-challenge: ${JSON.stringify((challenged || []).flatMap(c => c.openDecisions || []))}
 Cross-plan conflicts needing resolution: ${JSON.stringify((crossCritic && crossCritic.conflicts) || [])}
-Decisions context (ADRs/PFs already settled): ${DECISIONS_CONTEXT}
 
 For each open decision:
-- If the preference profile or an existing ADR/PF settles it clearly: auto-resolve and note the rationale.
+- If the preference profile settles it clearly: auto-resolve and note the rationale.
 - If not settled: add to the DECISIONS-NEEDED list for the user.
 
 Return: { autoResolved (array of {decision, resolution, source}), decisionsNeeded (array of {decision, context, options}) }.`, { agentType: "Synthesize" })
@@ -224,14 +242,26 @@ For each ticket, write ${OUTDIR}/{ticket-slug}-plan.md containing:
 - ## Acceptance Criteria (numbered, positive + negative)
 - ## Test Plan — the challenger's testPlan lines, verbatim, one per line, and nothing else: no prose, no blank line between them, no setup or outcome
 - ## Test Scenarios — one line per TP, in TP order: TP-n: its setup, then its expected outcome, from testScenarios
+<!-- learning:on -->
 - ## Auto-Resolved Decisions (if any — list each as: decision → resolution → source, naming a recorded decision in words, never by ID)
+<!-- learning:off -->
+- ## Auto-Resolved Decisions (if any — list each as: decision → resolution → source)
+<!-- learning:end -->
 
 Then write ${OUTDIR}/DECISIONS-NEEDED.md:
+<!-- learning:on -->
 - ## Auto-Resolved Decisions — list each silently-resolved decision as: decision → resolution → source (preference profile / ADR-NNN), so auto-resolution is auditable and reversible. If none, write "None."
+<!-- learning:off -->
+- ## Auto-Resolved Decisions — list each silently-resolved decision as: decision → resolution → source (preference profile), so auto-resolution is auditable and reversible. If none, write "None."
+<!-- learning:end -->
 - ## Decisions Needed
 - One section per open decision: what the decision is, why it matters, what options exist.
 - Include cross-plan conflicts that were not auto-resolved.
+<!-- learning:on -->
 - If no decisions needed, write: "No open decisions — all settled by preference profile or existing ADRs."
+<!-- learning:off -->
+- If no decisions needed, write: "No open decisions — all settled by the preference profile."
+<!-- learning:end -->
 
 Return: { planPaths (array), decisionsNeededPath (string), decisionsNeededCount (number) }.`, { agentType: "Synthesize" })
 );

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

@@ -3,9 +3,17 @@ description: Decision-preference profile distiller — mine past session transcr
 argument-hint: "[--dry-run]"
 output-dir: dist/commands
 ---
-@import { authoring_preamble } from "./_partials/_preamble.mds"
+@import { authoring_preamble, authoring_decisions } from "./_partials/_preamble.mds"
+@import "./_partials/_settings.mds" as settings
 {{authoring_preamble()}}
 
+<!-- learning:on -->
+### Settings line
+
+{{settings.settings_resolve()}}
+
+<!-- learning:end -->
+{{authoring_decisions()}}
 ---
 
 ## dynamic-profile — distill a decision-preference profile from past sessions

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

@@ -3,14 +3,22 @@ description: Generalized ticket-factory — turn an initiative or spec into a re
 argument-hint: "[initiative | spec-doc]"
 output-dir: dist/commands
 ---
-@import { authoring_preamble } from "./_partials/_preamble.mds"
+@import { authoring_preamble, authoring_decisions } from "./_partials/_preamble.mds"
 @import { agent_roster, agent_caveats } from "./_partials/_roster.mds"
 @import { ticket_body_template } from "./_partials/_ticket_template.mds"
 @import { factory_shape } from "./_partials/_factory.mds"
 @import { evidence_policy } from "./_partials/_evidence_policy.mds"
 @import { docs_root } from "./_partials/_docs_root.mds"
+@import "./_partials/_settings.mds" as settings
 {{authoring_preamble()}}
 
+<!-- learning:on -->
+### Settings line
+
+{{settings.settings_resolve()}}
+
+<!-- learning:end -->
+{{authoring_decisions()}}
 ---
 
 ## dynamic-tickets — author and run a ticket-factory workflow
@@ -53,10 +61,12 @@ Before you write the workflow script:
 
 Pass `{worktree}` to the workflow as its `root` argument.
 
+<!-- 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 Design agent and Review 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 Design agent prompts.
 
+<!-- learning:end -->
 **2. Read and distill the initiative**
 
 Read or note the user's input:
@@ -93,7 +103,9 @@ export const meta = {
 const candidates = args.candidates || [];   // [{title, summary, wave, dependsOn}]
 const initiative = args.initiative || args[0] || "see task description";
 const constraints = args.constraints || "";
+<!-- learning:on -->
 const DECISIONS_CONTEXT = args.decisionsContext || "";   // injected before authoring
+<!-- learning:end -->
 const slug = args.slug || initiative.toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 40);
 const ts = new Date().toISOString().slice(0,16).replace(/[-:T]/g, (c) => c === 'T' ? '_' : c === ':' ? '' : c);
 const ROOT = args.root;  // {worktree} from Pre-authoring setup: the checkout's toplevel, never cwd
@@ -105,7 +117,9 @@ const drafts = await phase("draft", () =>
     agent(`Draft ticket for initiative: "${initiative}"
 Ticket: ${JSON.stringify(c)}
 Constraints: ${constraints}
+<!-- learning:on -->
 Decisions context (apply devflow:apply-decisions; the ticket is filed to the tracker, so state each decision in words, never by ID): ${DECISIONS_CONTEXT}
+<!-- learning:end -->
 Write the ticket body following the ticket_body_template structure (Wave/Depends-on header, Summary, Scope with In/Out + anti-features, Invariants, numbered Acceptance Criteria with at least one negative criterion, Open Questions).
 Return a JSON object with: title (string), summary (string), wave (number), dependsOn (array), bodyMarkdown (string), openQuestions (array).`, { agentType: "Design" })
   ))

package/src/assets/commands/explore.mds

@@ -4,6 +4,7 @@ output-dir: dist/commands
 ---
 @import { knowledge_writeback } from "./_partials/_knowledge.mds"
 @import { decisions_load } from "./_partials/_decisions.mds"
+@import "./_partials/_settings.mds" as settings
 # Explore Command
 
 Explore a codebase area by spawning parallel agents for flow tracing, dependency mapping, and pattern analysis. Findings are synthesized into structured output with file:line references, with optional feature knowledge created as a byproduct.
@@ -31,21 +32,34 @@ $ARGUMENTS
 
 ## Phases
 
+<!-- learning:on -->
 ### Phase 1: Load Decisions (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 framing exploration — prior decisions and pitfalls suggest specific areas to investigate. Follow `devflow:apply-decisions` to Read full entry bodies on demand. **Do NOT pass `DECISIONS_CONTEXT` to Explore sub-agents** — decisions context stays in the orchestrator, not in the investigation workers.
 
+<!-- learning:end -->
 **No up-front feature knowledge load** — explore investigation workers read code directly to avoid confirmation bias. Feature knowledge is only created as a write-back at the end, after exploration is complete.
 
 ### Phase 2: Orient
 
 **Produces:** ORIENT_OUTPUT
 
+<!-- learning:on -->
+Spawn `Agent(subagent_type="Skim")` with `LEARNING` from the settings line, to get codebase overview relevant to the exploration question:
+<!-- learning:off -->
 Spawn `Agent(subagent_type="Skim")` to get codebase overview relevant to the exploration question:
+<!-- learning:end -->
 
 - File structure and module boundaries in the target area
 - Entry points and key abstractions
@@ -91,7 +105,11 @@ Present findings to user. Use AskUserQuestion to offer focused follow-up explora
 
 ### Phase 6: Suggest Feature Knowledge Creation (Conditional)
 
+<!-- learning:on -->
 **Requires:** MERGED_FINDINGS, DECISIONS_CONTEXT
+<!-- learning:off -->
+**Requires:** MERGED_FINDINGS
+<!-- learning:end -->
 **Produces:** FEATURE_KNOWLEDGE_STATUS (created | skipped)
 
 1. Check if matching feature knowledge already exists by reading `{worktree}/.devflow/features/index.md` (or globbing frontmatter if absent). If covered → skip
@@ -125,7 +143,11 @@ Structured exploration findings with concrete code references:
 ```
 /explore (orchestrator)
 │
+<!-- learning:on -->
 ├─ Phase 1: Load Decisions (Orchestrator-Local)
+<!-- learning:off -->
+├─ Phase 1: Resolve Settings
+<!-- learning:end -->
 │
 ├─ Phase 2: Orient
 │  └─ Skim agent (codebase overview)
@@ -146,7 +168,11 @@ Structured exploration findings with concrete code references:
 
 1. **Structure over browsing** - Every claim must cite file:line references
 2. **Parallel execution** - All explorers run simultaneously for speed
+<!-- learning:on -->
 3. **Knowledge-informed** - Prior decisions guide where to look; NO pre-loaded feature knowledge in sub-agents (avoids confirmation bias)
+<!-- learning:off -->
+3. **Knowledge-informed** - NO pre-loaded feature knowledge in sub-agents (avoids confirmation bias)
+<!-- learning:end -->
 4. **User-driven depth** - Present findings, then offer drill-down into specific areas
 
 ## Error Handling

package/src/assets/commands/implement.mds

@@ -10,6 +10,7 @@ output-dir: dist/commands
 @import { test_plan_line } from "./_partials/_plan_contract.mds"
 @import { publication_gate } from "./_partials/_publication.mds"
 @import "./_partials/_compliance.mds" as compliance
+@import "./_partials/_settings.mds" as settings
 # Implement Command
 
 Orchestrate a single task through implementation by spawning specialized agents. The orchestrator only spawns agents and passes context - all work is done by agents.
@@ -57,7 +58,11 @@ If the user prompt does NOT match re-validation, proceed with the full pipeline
 
 ### Phase 1: Setup
 
-**Produces:** TASK_ID, BASE_BRANCH, EXECUTION_PLAN, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, PR_DESCRIPTION_GUIDANCE, ISSUE_NUMBER, EVIDENCE_POLICY, ISSUE_REQUIRED, APPLY_CONVENTIONS, REQUIRE_NON_AUTHOR_APPROVAL, PR_EXCEPTIONS, TEST_PLAN, EVIDENCE_FILE, PR_TEST_PLAN_BLOCK, REVIEW_PUBLICATION
+<!-- learning:on -->
+**Produces:** TASK_ID, BASE_BRANCH, EXECUTION_PLAN, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, FEATURE_KNOWLEDGE_RULES, PR_DESCRIPTION_GUIDANCE, ISSUE_NUMBER, EVIDENCE_POLICY, ISSUE_REQUIRED, APPLY_CONVENTIONS, REQUIRE_NON_AUTHOR_APPROVAL, PR_EXCEPTIONS, TEST_PLAN, EVIDENCE_FILE, PR_TEST_PLAN_BLOCK, REVIEW_PUBLICATION
+<!-- learning:off -->
+**Produces:** TASK_ID, BASE_BRANCH, EXECUTION_PLAN, FEATURE_KNOWLEDGE, FEATURE_KNOWLEDGE_RULES, PR_DESCRIPTION_GUIDANCE, ISSUE_NUMBER, EVIDENCE_POLICY, ISSUE_REQUIRED, APPLY_CONVENTIONS, REQUIRE_NON_AUTHOR_APPROVAL, PR_EXCEPTIONS, TEST_PLAN, EVIDENCE_FILE, PR_TEST_PLAN_BLOCK, REVIEW_PUBLICATION
+<!-- learning:end -->
 
 Record the current branch name as `BASE_BRANCH` - this will be the PR target.
 
@@ -167,13 +172,16 @@ node "$HOME/.devflow/scripts/verify-evidence.cjs" render --plan "{worktree}/.dev
 
 - `EVIDENCE_FILE` — `{worktree}/.devflow/docs/evidence-{branch_slug}.md`, its `## Evidence Exceptions` section now a byte copy of `PR_EXCEPTIONS` (absent when that is `(none)`).
 
+{{settings.settings_resolve()}}
+
 {{publication_gate()}}
 Phase 10b passes the resolved value to `update-pr-evidence`, which decides what each value means for the evidence comment. From the same line: {{compliance.compliance_frameworks()}} Pass it to every Code spawn.
 
 {{decisions_load()}}
+<!-- learning:on -->
+Pass `DECISIONS_CONTEXT` to Code agent (Phase 2) and Scrutinize agent (Phase 4).
 
-Pass to Code agent (Phase 2) and Scrutinize agent (Phase 4).
-
+<!-- learning:end -->
 {{knowledge_load()}}
 
 ### Phase 2: Implement
@@ -208,7 +216,9 @@ PATTERNS: {patterns from plan document or empty}
 CREATE_PR: true
 DOMAIN: {detected domain or 'fullstack'}
 FEATURE_KNOWLEDGE: {feature_knowledge}
+<!-- learning:on -->
 DECISIONS_CONTEXT: {decisions_context}
+<!-- learning:end -->
 COMPLIANCE_FRAMEWORKS: {COMPLIANCE_FRAMEWORKS}
 PR_DESCRIPTION_GUIDANCE: {pr_description_guidance}
 ISSUE_NUMBER: {ISSUE_ID captured in Phase 1, or (none)}
@@ -221,7 +231,7 @@ PR_TEST_PLAN_BLOCK: {PR_TEST_PLAN_BLOCK from Phase 1 verbatim, or (none)}"
 
 **SEQUENTIAL_CODE_AGENTS** (for HIGH/CRITICAL context risk):
 
-Spawn Code agents one at a time, passing handoff summaries between phases:
+Spawn Code agents one at a time. Each appends its own phase section to the handoff file, and the next reads only the section before it:
 
 **Phase 1 Code agent:**
 ```
@@ -235,7 +245,9 @@ PATTERNS: {patterns from plan document or empty}
 CREATE_PR: false
 DOMAIN: {phase 1 domain, e.g., 'backend'}
 FEATURE_KNOWLEDGE: {feature_knowledge}
+<!-- learning:on -->
 DECISIONS_CONTEXT: {decisions_context}
+<!-- learning:end -->
 COMPLIANCE_FRAMEWORKS: {COMPLIANCE_FRAMEWORKS}
 PR_DESCRIPTION_GUIDANCE: {pr_description_guidance}
 ISSUE_NUMBER: {ISSUE_ID captured in Phase 1, or (none)}
@@ -258,7 +270,9 @@ DOMAIN: {phase N domain, e.g., 'frontend'}
 PRIOR_PHASE_SUMMARY: {summary from previous Code agent}
 FILES_FROM_PRIOR_PHASE: {list of files created}
 FEATURE_KNOWLEDGE: {feature_knowledge}
+<!-- learning:on -->
 DECISIONS_CONTEXT: {decisions_context}
+<!-- learning:end -->
 COMPLIANCE_FRAMEWORKS: {COMPLIANCE_FRAMEWORKS}
 PR_DESCRIPTION_GUIDANCE: {pr_description_guidance}
 ISSUE_NUMBER: {ISSUE_ID captured in Phase 1, or (none)}
@@ -269,7 +283,7 @@ HANDOFF_REQUIRED: {true if not last phase}
 HANDOFF_FILE: {worktree}/.devflow/docs/handoff-{branch_slug}.md"
 ```
 
-**Handoff Protocol**: Each sequential Code agent receives the prior Code agent's implementation summary via PRIOR_PHASE_SUMMARY and FILES_FROM_PRIOR_PHASE. The Code agent's built-in branch orientation step handles git log scanning, file reading, and pattern discovery automatically. After each Code agent with HANDOFF_REQUIRED=true completes, write its phase summary to `{worktree}/.devflow/docs/handoff-{branch_slug}.md` using the Write tool (survives context compaction), keeping any `## Evidence Exceptions` section byte-identical. Delete `{worktree}/.devflow/docs/handoff-{branch_slug}.md` once the PR exists — after the final Code agent, which creates it, completes (cleanup).
+**Handoff Protocol**: Each sequential Code agent receives the prior Code agent's implementation summary via PRIOR_PHASE_SUMMARY and FILES_FROM_PRIOR_PHASE. The Code agent's built-in branch orientation step handles git log scanning, file reading, and pattern discovery automatically. Each Code agent with HANDOFF_REQUIRED=true appends its own `## Phase {N} Implementation Summary` section, at most 8,192 bytes, to `{worktree}/.devflow/docs/handoff-{branch_slug}.md` (survives context compaction), never rewriting an earlier section and keeping any `## Evidence Exceptions` section byte-identical; the next Code agent reads only the section of the phase immediately before its own through HANDOFF_FILE. The orchestrator writes no phase section. Delete `{worktree}/.devflow/docs/handoff-{branch_slug}.md` once the PR exists — after the final Code agent, which creates it, completes (cleanup).
 
 ---
 
@@ -288,7 +302,9 @@ PATTERNS: {patterns}
 CREATE_PR: false
 DOMAIN: {subtask 1 domain}
 FEATURE_KNOWLEDGE: {feature_knowledge}
+<!-- learning:on -->
 DECISIONS_CONTEXT: {decisions_context}
+<!-- learning:end -->
 COMPLIANCE_FRAMEWORKS: {COMPLIANCE_FRAMEWORKS}
 PR_DESCRIPTION_GUIDANCE: {pr_description_guidance}
 ISSUE_NUMBER: {ISSUE_ID captured in Phase 1, or (none)}
@@ -304,7 +320,9 @@ PATTERNS: {patterns}
 CREATE_PR: false
 DOMAIN: {subtask 2 domain}
 FEATURE_KNOWLEDGE: {feature_knowledge}
+<!-- learning:on -->
 DECISIONS_CONTEXT: {decisions_context}
+<!-- learning:end -->
 COMPLIANCE_FRAMEWORKS: {COMPLIANCE_FRAMEWORKS}
 PR_DESCRIPTION_GUIDANCE: {pr_description_guidance}
 ISSUE_NUMBER: {ISSUE_ID captured in Phase 1, or (none)}
@@ -344,8 +362,10 @@ After Simplify agent completes, spawn Scrutinize agent as the quality gate:
 Agent(subagent_type="Scrutinize"):
 "TASK_DESCRIPTION: {task description}
 FILES_CHANGED: {list of files from Code agent output}
+<!-- learning:on -->
 DECISIONS_CONTEXT: {decisions_context}
-FEATURE_KNOWLEDGE: {feature_knowledge}
+<!-- learning:end -->
+FEATURE_KNOWLEDGE: {feature_knowledge_rules}
 Evaluate 9 pillars, fix P0/P1 issues, report status"
 ```
 
@@ -356,7 +376,7 @@ Scrutinize agent reports `### Status: PASS | FIXED | BLOCKED`. **If BLOCKED:** r
 **Produces:** ALIGNMENT_RESULT
 **Requires:** FILES_CHANGED, EXECUTION_PLAN
 
-After Scrutinize agent passes, spawn Evaluate agent to validate alignment. Evaluate agent receives `FEATURE_KNOWLEDGE` as acceptance context only; pattern and anti-pattern judgments belong to Scrutinize agent:
+After Scrutinize agent passes, spawn Evaluate agent to validate alignment. Evaluate agent receives `FEATURE_KNOWLEDGE_RULES` as acceptance context only; pattern and anti-pattern judgments belong to Scrutinize agent:
 
 ```
 Agent(subagent_type="Evaluate"):
@@ -364,7 +384,7 @@ Agent(subagent_type="Evaluate"):
 EXECUTION_PLAN: {execution plan from Phase 1}
 FILES_CHANGED: {list of files from Code agent output}
 ACCEPTANCE_CRITERIA: {extracted criteria if available}
-FEATURE_KNOWLEDGE: {feature_knowledge}
+FEATURE_KNOWLEDGE: {feature_knowledge_rules}
 Validate alignment with request and plan. Report ALIGNED or MISALIGNED with details."
 ```
 
@@ -383,6 +403,9 @@ Validate alignment with request and plan. Report ALIGNED or MISALIGNED with deta
    MISALIGNMENTS: {structured misalignments from Evaluate agent}
    SCOPE: Fix only the listed misalignments, no other changes
    CREATE_PR: false
+   <!-- learning:on -->
+   DECISIONS_CONTEXT: {decisions_context}
+   <!-- learning:end -->
    ISSUE_NUMBER: {ISSUE_ID captured in Phase 1, or (none)}
    ISSUE_PR_LINK: {ISSUE_PR_LINK captured in Phase 1, or (none)}
    COMPLIANCE_FRAMEWORKS: {COMPLIANCE_FRAMEWORKS}"
@@ -417,6 +440,9 @@ Run build, typecheck, lint, test. Report pass/fail with failure details."
    VALIDATION_FAILURES: {parsed failures from Validate agent}
    SCOPE: Fix only the listed failures, no other changes
    CREATE_PR: false
+   <!-- learning:on -->
+   DECISIONS_CONTEXT: {decisions_context}
+   <!-- learning:end -->
    ISSUE_NUMBER: {ISSUE_ID captured in Phase 1, or (none)}
    ISSUE_PR_LINK: {ISSUE_PR_LINK captured in Phase 1, or (none)}
    COMPLIANCE_FRAMEWORKS: {COMPLIANCE_FRAMEWORKS}"
@@ -471,6 +497,9 @@ After every Test agent run — PASS or FAIL, first run or retry — append its T
    QA_FAILURES: {structured failures from Test agent}
    SCOPE: Fix only the listed failures, no other changes
    CREATE_PR: false
+   <!-- learning:on -->
+   DECISIONS_CONTEXT: {decisions_context}
+   <!-- learning:end -->
    ISSUE_NUMBER: {ISSUE_ID captured in Phase 1, or (none)}
    ISSUE_PR_LINK: {ISSUE_PR_LINK captured in Phase 1, or (none)}
    COMPLIANCE_FRAMEWORKS: {COMPLIANCE_FRAMEWORKS}"
@@ -517,7 +546,11 @@ git push origin HEAD; echo "exit=$?"
 3. **If NO_PR or NO_CI** → skip: "No PR/CI configured, skipping CI validation." Proceed to Phase 10.
 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.
+<!-- learning:on -->
+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`, `DECISIONS_CONTEXT` 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:off -->
 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:end -->
 7. **Budget**: at most 3 waits and 2 fixes in all. When one is spent, report the current status and proceed.
 <!-- /PATTERN: ci-status-gate -->
 

package/src/assets/commands/plan.mds

@@ -9,6 +9,7 @@ output-dir: dist/commands
 @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 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,7 +220,9 @@ 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)
+<!-- learning:end -->
 - `COMPLIANCE_FRAMEWORKS` (compliance focus only)
 - Multi-issue: all issue bodies
 
@@ -205,14 +230,20 @@ Each Design agent receives:
 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)
 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."
 ```
 
@@ -296,7 +327,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.
 
@@ -511,9 +542,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