devflow-kit 3.3.0 → 3.5.0

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
@@ -61,7 +67,7 @@ Author the resolved `ISSUE_REQUIRED` and `APPLY_CONVENTIONS` into the workflow s
 
 {{compliance.compliance_lens()}}
 
-Pass it as `complianceFrameworks` when invoking the workflow; the engine hands it to every Code agent.
+Pass it as `complianceFrameworks` when invoking the workflow; the engine builds `COMPLIANCE_DIRECTIVE` from it and hands that to every Code and Code-fix agent.
 
 **0c. Resolve the docs root**
 
@@ -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.
@@ -129,7 +137,7 @@ If a number is found, record it as the command-level `ISSUE_NUMBER`:
 - **SINGLE mode:** it is the ticket's own reference. Pass it as `issueNumber: <number>` when invoking the workflow; the engine hands it to setup-task as `ISSUE_INPUT`. If none is found, pass nothing.
 - **WAVE mode:** it is the tracking issue. Only steps 2 and 3 after the workflow use it: step 2 for the wave report, step 3 for the wave block's tracking line. It never reaches a ticket: each ticket's engine gets that ticket's own reference as `issueInput`.
 
-Never pass `ISSUE_PR_LINK` into the workflow. The engine binds each ticket's `ISSUE_NUMBER` and `ISSUE_PR_LINK` from that ticket's own setup-task Output (`### Handoff Values`), never from the token it passed in, and hands both to that ticket's Code agents. No `- **PR link line**:` captured ⇒ `ISSUE_PR_LINK` is `"(none)"` and the Code agent emits the `## Related Issues` heading with no reference.
+Never pass `ISSUE_PR_LINK` into the workflow. The engine binds each ticket's `ISSUE_NUMBER` and `ISSUE_PR_LINK` from that ticket's own setup-task Output (`### Handoff Values`), never from the token it passed in, and returns that ticket's `issuePrLink` for the wave PR's related line. No `- **PR link line**:` captured ⇒ `ISSUE_PR_LINK` is `"(none)"` and the ticket's related line carries no closing reference.
 
 ---
 
@@ -150,11 +158,14 @@ 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";
 const COMPLIANCE_FRAMEWORKS = /^(?:off|none|[a-z][a-z0-9-]{0,15}(?:,[a-z][a-z0-9-]{0,15}){0,7})$/.test(String(args.complianceFrameworks)) ? String(args.complianceFrameworks) : "off";  // Pre-authoring step 0b; any other shape is no lens
+const COMPLIANCE_DIRECTIVE = COMPLIANCE_FRAMEWORKS === "off" ? "" : `When the task touches regulated surface (data models, auth flows, logging/observability, payments, IaC, retention), invoke Skill(skill="devflow:compliance") and load references/{id}.md only for the ids in ${COMPLIANCE_FRAMEWORKS} (none: generic controls only); never fabricate guidance for a framework you were not given.`;  // D-COMPLIANCE-INJECT: empty when the lens is off, so a Code or Code-fix spawn then carries nothing about compliance; otherwise the one line _compliance.mds renders as compliance_directive(), with the validated ids in place of <ids>
 
 // Phase 1: Git setup — declare the operation; the agent owns the process, the branch name included
 const setup = await phase("setup", () =>
@@ -171,7 +182,7 @@ Return: {"branch": "<the - **Branch name**: value under your ### Branch, or (non
 // An Issue ID is a bare number or a KEY-number, per the provider; any other value — "none", blank, prose — is no capture, so the stop fails closed.
 const ISSUE_ID_SHAPE = /^(?:[1-9][0-9]{0,8}|[A-Z][A-Z0-9_]{0,9}-[1-9][0-9]{0,8})$/;
 const ISSUE_NUMBER = ISSUE_ID_SHAPE.test(String(setup?.issueId ?? "")) ? setup.issueId : "(none)";  // the captured Issue ID; "(none)" ⇒ none was captured
-const ISSUE_PR_LINK = setup?.prLinkLine || "(none)";  // "(none)" ⇒ Code emits the heading with no reference
+const ISSUE_PR_LINK = setup?.prLinkLine || "(none)";  // "(none)" ⇒ the wave PR carries no closing reference for this ticket
 // The branch setup-task created, as it reported it: every later phase and the merge use it. The engine never names one.
 const BRANCH = typeof setup?.branch === "string" && setup.branch.trim() !== "" && setup.branch.trim() !== "(none)" ? setup.branch : "(none)";
 
@@ -194,12 +205,12 @@ ${TICKET}
 
 ${PLAN ? `Implementation plan:\n${PLAN}` : "No plan provided — use best judgment."}
 
+<!-- learning:on -->
 Relevant architectural decisions (apply devflow:apply-decisions algorithm):
 ${DECISIONS_CONTEXT}
 
-ISSUE_NUMBER: ${ISSUE_NUMBER}
-ISSUE_PR_LINK: ${ISSUE_PR_LINK}
-COMPLIANCE_FRAMEWORKS: ${COMPLIANCE_FRAMEWORKS}
+<!-- learning:end -->
+${COMPLIANCE_DIRECTIVE}
 
 When you build or run tests to verify your work, follow your Running commands block.
 
@@ -233,10 +244,11 @@ Return: {"verdict": "PASS" | "FAIL", "details": "..."}`, { agentType: "Validate"
       await agent(`OPERATION: validation-fix
 Fix the validation failures on branch ${BRANCH}:
 ${failureDetails}
-ISSUE_NUMBER: ${ISSUE_NUMBER}
-ISSUE_PR_LINK: ${ISSUE_PR_LINK}
-COMPLIANCE_FRAMEWORKS: ${COMPLIANCE_FRAMEWORKS}
-Commit fixes with conventional-commit message.`, { agentType: "Code" });
+<!-- learning:on -->
+DECISIONS_CONTEXT: ${DECISIONS_CONTEXT}
+<!-- learning:end -->
+${COMPLIANCE_DIRECTIVE}
+Commit fixes with conventional-commit message.`, { agentType: "Code-fix" });
       const recheck = await agent(`Re-run build, typecheck, lint, tests on branch ${BRANCH} after fix attempt ${attempt} (follow your Running commands block).
 Return: {"verdict": "PASS" | "FAIL", "details": "..."}`, { agentType: "Validate" });
       if (recheck?.verdict === "PASS") break;
@@ -275,10 +287,11 @@ 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"}
-ISSUE_NUMBER: ${ISSUE_NUMBER}
-ISSUE_PR_LINK: ${ISSUE_PR_LINK}
-COMPLIANCE_FRAMEWORKS: ${COMPLIANCE_FRAMEWORKS}
-Self-verify your fix compiles, following your Running commands block. Commit fixes.`, { agentType: "Code" });
+<!-- learning:on -->
+DECISIONS_CONTEXT: ${DECISIONS_CONTEXT}
+<!-- learning:end -->
+${COMPLIANCE_DIRECTIVE}
+Self-verify your fix compiles, following your Running commands block. Commit fixes.`, { agentType: "Code-fix" });
       evalVerdict = "FAIL-FIXED";  // issues found, fixes applied, not re-evaluated by design
     }
   }
@@ -296,10 +309,11 @@ 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}
-ISSUE_NUMBER: ${ISSUE_NUMBER}
-ISSUE_PR_LINK: ${ISSUE_PR_LINK}
-COMPLIANCE_FRAMEWORKS: ${COMPLIANCE_FRAMEWORKS}
-Self-verify your fix compiles and the scenarios pass, following your Running commands block. Commit fixes.`, { agentType: "Code" });
+<!-- learning:on -->
+DECISIONS_CONTEXT: ${DECISIONS_CONTEXT}
+<!-- learning:end -->
+${COMPLIANCE_DIRECTIVE}
+Self-verify your fix compiles and the scenarios pass, following your Running commands block. Commit fixes.`, { agentType: "Code-fix" });
       testVerdict = "FAIL-FIXED";  // issues found, fixes applied, not re-evaluated by design
     }
   }
@@ -415,9 +429,10 @@ 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
-ISSUE_NUMBER: ${ISSUE_NUMBER}
-ISSUE_PR_LINK: ${ISSUE_PR_LINK}
-COMPLIANCE_FRAMEWORKS: ${COMPLIANCE_FRAMEWORKS}
+<!-- learning:on -->
+DECISIONS_CONTEXT: ${DECISIONS_CONTEXT}
+<!-- learning:end -->
+${COMPLIANCE_DIRECTIVE}
 Fix all findings in this batch. Self-verify your fix compiles, following your Running commands block. Commit with conventional-commit message.
 Return: {"status": "fixed"|"blocked", "commitShas": ["<sha>"], "unresolved": ["<description of any finding that could not be fixed>"]}`, { agentType: "Code" });
       chunkResults.push({ chunk, result: r });
@@ -475,10 +490,11 @@ Return: {"verdict": "PASS" | "FAIL", "details": "..."}`, { agentType: "Validate"
       await agent(`OPERATION: validation-fix
 Fix the final validation failures on branch ${BRANCH}:
 ${failureDetails}
-ISSUE_NUMBER: ${ISSUE_NUMBER}
-ISSUE_PR_LINK: ${ISSUE_PR_LINK}
-COMPLIANCE_FRAMEWORKS: ${COMPLIANCE_FRAMEWORKS}
-Self-verify your fix compiles. Commit fixes with conventional-commit message.`, { agentType: "Code" });
+<!-- learning:on -->
+DECISIONS_CONTEXT: ${DECISIONS_CONTEXT}
+<!-- learning:end -->
+${COMPLIANCE_DIRECTIVE}
+Self-verify your fix compiles. Commit fixes with conventional-commit message.`, { agentType: "Code-fix" });
       const recheck = await agent(`Re-run build, typecheck, lint, tests on branch ${BRANCH} (final gate, after fix attempt ${attempt}; follow your Running commands block).
 Return: {"verdict": "PASS" | "FAIL", "details": "..."}`, { agentType: "Validate" });
       if (recheck?.verdict === "PASS") break;
@@ -604,7 +620,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)) {

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
@@ -42,12 +50,14 @@ Before authoring, verify:
 
 {{docs_root()}}
 
-Pass `{worktree}` to the workflow as its `root` argument.
+Pass `{worktree}` to the workflow as its `root` argument, and its `slug` argument: the `{slug}` of the ticket directory (`tickets/{slug}/{ts}/`) when that is the ticket source, otherwise `wave`.
 
+<!-- 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,11 +122,14 @@ 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";
-const ts = new Date().toISOString().slice(0,16).replace(/[-:T]/g, (c) => c === 'T' ? '_' : c === ':' ? '' : c);
+const now = new Date(), two = (n) => String(n).padStart(2, '0');
+const ts = `${now.getFullYear()}-${two(now.getMonth() + 1)}-${two(now.getDate())}_${two(now.getHours())}${two(now.getMinutes())}`;
 const ROOT = args.root;  // {worktree} from Pre-authoring setup: the checkout's toplevel, never cwd
 const OUTDIR = `${ROOT}/.devflow/docs/design/${slug}/${ts}`;
 
@@ -133,7 +146,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 +164,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 +174,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 +192,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 +202,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 +219,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" })
@@ -218,20 +237,32 @@ Auto-resolved decisions: ${JSON.stringify(resolved && resolved.autoResolved)}
 Decisions needed: ${JSON.stringify(resolved && resolved.decisionsNeeded)}
 Output directory: ${OUTDIR}
 
-For each ticket, write ${OUTDIR}/{ticket-slug}-plan.md containing:
+For each ticket, write ${OUTDIR}/{ticket-slug}-plan.md, {ticket-slug} being the ticket's file name without .md when it came from a ticket directory, otherwise the ticket title run through title.toLowerCase().replace(/[^a-z0-9]+/g, '-') with nothing trimmed, containing:
 - ## Implementation Plan
 - The plan body (incorporate cross-plan amendments)
 - ## 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,9 +103,12 @@ 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
-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);
+<!-- learning:end -->
+const slug = args.slug || initiative.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+/, '').slice(0, 50).replace(/-+$/, '') || 'untitled';
+const now = new Date(), two = (n) => String(n).padStart(2, '0');
+const ts = `${now.getFullYear()}-${two(now.getMonth() + 1)}-${two(now.getDate())}_${two(now.getHours())}${two(now.getMinutes())}`;
 const ROOT = args.root;  // {worktree} from Pre-authoring setup: the checkout's toplevel, never cwd
 const OUTDIR = `${ROOT}/.devflow/docs/tickets/${slug}/${ts}`;
 
@@ -105,7 +118,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" })
   ))
@@ -166,7 +181,7 @@ Write the amended ticket file to ${OUTDIR}/${a.title.toLowerCase().replace(/[^a-
 return phase("tracking-issue", () =>
   agent(`Write ticket files and a tracking-issue document for initiative: "${initiative}"
 
-For each ticket in the revised set, write a file to ${OUTDIR}/{slug}.md using the ticket_body_template structure:
+For each ticket in the revised set, write a file to ${OUTDIR}/{ticket-slug}.md using the ticket_body_template structure. {ticket-slug} is the ticket title run through title.toLowerCase().replace(/[^a-z0-9]+/g, '-') with nothing trimmed, the same rule the amend phase applied, so a ticket keeps the file name its amendment wrote:
 - Wave: N header
 - Depends on: list or "none"
 - Summary, Scope (In/Out + anti-features), Invariants, numbered Acceptance Criteria (at least one negative), Open Questions
@@ -246,7 +261,7 @@ Tracking issue → `{worktree}/.devflow/docs/tickets/{slug}/{ts}/tracking-issue.
 
 `{worktree}` is the docs root resolved in Pre-authoring setup (it honours `WORKTREE_PATH` when provided).
 
-Timestamps follow the devflow `YYYY-MM-DD_HHMM` convention (date and time separated by an underscore, e.g. `2026-06-12_1148`). The `ts` variable in the workflow script generates this format.
+Timestamps follow the devflow `YYYY-MM-DD_HHMM` convention in local time (date and time separated by an underscore, e.g. `2026-06-12_1148`). The `ts` variable in the workflow script generates this format.
 
 ---
 

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
@@ -71,7 +85,7 @@ Ask each explorer for a final report of at most about 1,500 tokens: findings wit
 **Produces:** MERGED_FINDINGS
 **Requires:** EXPLORE_OUTPUT
 
-Spawn `Agent(subagent_type="Synthesize")` in `exploration` mode with combined findings:
+Spawn `Agent(subagent_type="Synthesize")` with the prompt line `Mode: exploration` first, then the combined findings:
 
 - Merge overlapping discoveries from parallel explorers
 - Resolve any contradictions between explorer findings
@@ -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