devflow-kit 3.4.0 → 3.5.0

package/dist/cli/commands/tracker.js

@@ -16,18 +16,22 @@
  * --set converges the sentinel in BOTH directions, so flipping
  *   back to github removes what flipping away wrote.
  * A failed re-arm or sentinel step warns, it never aborts.
+ * --servers sets the machine's tracker tool servers (D-TRACKER-SERVER-ALLOWLIST) and
+ *   re-stamps the installed Git and Tracker agents at once; it is orthogonal to --set and
+ *   neither flag touches the other's manifest field.
  */
 import { Command } from 'commander';
 import { promises as fs } from 'fs';
 import * as path from 'path';
 import * as p from '@clack/prompts';
 import color from 'picocolors';
-import { DEFAULT_TRACKER_PROVIDER, TRACKER_ATTEMPTS_MAX, TRACKER_CONVENTIONS_READ_BYTES, TRACKER_PROVIDERS, applyTrackerSentinel, describeTrackerValue, parseTrackerFrontmatter, parseTrackerId, readBoundedHead, rearmTrackerInference, trackerConventionsPath, } from '../../core/tracker.js';
+import { DEFAULT_TRACKER_PROVIDER, TRACKER_ATTEMPTS_MAX, TRACKER_CONVENTIONS_READ_BYTES, TRACKER_PROVIDERS, applyTrackerSentinel, describeTrackerValue, effectiveTrackerServers, parseTrackerFrontmatter, parseTrackerId, parseTrackerServers, readBoundedHead, rearmTrackerInference, trackerConventionsPath, } from '../../core/tracker.js';
 import { readManifest, syncManifestFeature } from '../../core/manifest.js';
 import { loadSettingsModule, personalConfigTrackedWarning, repoTrackerSelection } from '../../core/evidence-policy.js';
 import { getClaudeDirectory, getDevFlowDirectory } from '../../targets/claude-code/claude-paths.js';
 import { SKILL_REFS_SKILL_NAME, installedReferenceManifest } from '../../core/mds-variants.js';
 import { prefixSkillName } from '../../core/plugins.js';
+import { TRACKER_STAMPED_AGENTS, restampTrackerAgents, } from '../../targets/claude-code/tracker-servers.js';
 /**
  * Read the provenance header of `~/.devflow/tracker/{provider}.md`.
  *
@@ -112,6 +116,10 @@ export async function readTrackerStatusConventions(devflowDir, provider) {
         provenance: await readTrackerProvenance(devflowDir, provider),
     };
 }
+/** Render the tracker servers for the `--status` note. Pure; every name was validated at its boundary. */
+export function formatTrackerServers(list, isDefault) {
+    return `${list.join(', ')}${isDefault ? ` ${color.dim('(default)')}` : ''}`;
+}
 /**
  * The `--status` note's lines. Pure.
  *
@@ -131,7 +139,7 @@ export function formatTrackerStatus(input) {
     }
     lines.push(...(input.conventions.kind === 'none'
         ? ['Conventions: none (GitHub needs no learned conventions)', 'File:        none']
-        : [`Conventions: ${formatTrackerProvenance(input.conventions.provenance)}`, `File:        ${input.conventions.file}`]), `Mechanics:   ${formatTrackerMechanics(input.mechanics)}`, `Inference:   ${input.inference}`);
+        : [`Conventions: ${formatTrackerProvenance(input.conventions.provenance)}`, `File:        ${input.conventions.file}`]), `Mechanics:   ${formatTrackerMechanics(input.mechanics)}`, `Servers:     ${formatTrackerServers(input.servers.list, input.servers.isDefault)}`, `Inference:   ${input.inference}`);
     return lines.join('\n');
 }
 /** The real adapter — the ONE binding of each operation into the `--set` path. */
@@ -164,7 +172,8 @@ export function buildTrackerSetIO() {
 export async function runTrackerSet(opts) {
     const { devflowDir, current, requested, io } = opts;
     const messages = [];
-    await io.syncManifest(devflowDir, { provider: requested });
+    // The provider changes; the tracker servers are a different setting and ride along.
+    await io.syncManifest(devflowDir, { ...current, provider: requested });
     // [DR-22] a selection change re-arms the attempt counters; [DR-10] the
     // sentinel converges in both directions.
     const rearm = await io.rearmInference(devflowDir);
@@ -180,18 +189,72 @@ export async function runTrackerSet(opts) {
     });
     return { provider: requested, messages };
 }
+/** The real adapter — the ONE binding of each operation into the `--servers` path. */
+export function buildTrackerServersIO() {
+    return {
+        syncManifest: (devflowDir, state) => syncManifestFeature(devflowDir, 'tracker', state),
+        restamp: (claudeDir, servers, warn) => restampTrackerAgents({ claudeDir, servers, warn }),
+    };
+}
+/**
+ * Set the machine's tracker tool servers.
+ *
+ * Follows `--set`'s convergence order (D-TRACKER-CONVERGE-SET): the manifest first, then
+ * the installed agents, which are re-stamped ONLY when the manifest write landed, so an
+ * installed agent never names a list the manifest does not record. Unlike `--set`, a failed
+ * manifest write is the whole command failing (there is nothing else for it to do), so it is
+ * returned as `ok: false` for the caller to exit on; a failed re-stamp warns, it never aborts.
+ *
+ * `default` removes the key, so an absent `servers` stays the one spelling of the default.
+ * Never throws.
+ */
+export async function runTrackerServers(opts) {
+    const { devflowDir, claudeDir, current, requested, io } = opts;
+    const messages = [];
+    const next = requested.kind === 'default'
+        ? { provider: current.provider }
+        : { provider: current.provider, servers: requested.servers };
+    try {
+        await io.syncManifest(devflowDir, next);
+    }
+    catch (err) {
+        messages.push({
+            level: 'error',
+            text: `Could not write the manifest — the tracker servers were not changed (${err instanceof Error ? err.message : String(err)})`,
+        });
+        return { ok: false, state: current, messages };
+    }
+    const servers = effectiveTrackerServers(next);
+    const unchanged = servers.join('\n') === effectiveTrackerServers(current).join('\n');
+    const label = `${servers.join(', ')}${requested.kind === 'default' ? ' (default)' : ''}`;
+    messages.push({ level: unchanged ? 'info' : 'success', text: `Tracker servers: ${label}${unchanged ? ' (unchanged)' : ''}` });
+    const restamp = await io.restamp(claudeDir, servers, (message) => messages.push({ level: 'warn', text: message }));
+    const done = restamp.rewritten.length + restamp.unchanged.length;
+    if (restamp.absent.length === TRACKER_STAMPED_AGENTS.length && restamp.failed.length === 0) {
+        messages.push({ level: 'info', text: 'No installed Git or Tracker agent to update — run devflow init' });
+    }
+    else if (restamp.rewritten.length > 0) {
+        messages.push({ level: 'info', text: `Updated the installed ${restamp.rewritten.join(' and ')} agent${restamp.rewritten.length > 1 ? 's' : ''}` });
+    }
+    else if (done > 0 && restamp.failed.length === 0) {
+        messages.push({ level: 'info', text: 'The installed agents already carry this list' });
+    }
+    return { ok: true, state: next, messages };
+}
 export const trackerCommand = new Command('tracker')
-    .description('Show or set the machine\'s issue tracker provider')
+    .description('Show or set the machine\'s issue tracker provider and tracker servers')
     .option('--status', 'Show the provider in effect and its learned conventions file, and re-arm background inference')
     .option('--set <id>', 'Set the machine\'s default issue tracker provider: github, jira, or linear')
+    .option('--servers <names>', 'Set the tracker servers the Git and Tracker agents may call: comma-separated names, or "default"')
     .action(async (options) => {
     const devflowDir = getDevFlowDirectory();
-    const hasFlag = options.status || options.set !== undefined;
+    const hasFlag = options.status || options.set !== undefined || options.servers !== undefined;
     if (!hasFlag) {
         p.intro(color.bgCyan(color.white(' Tracker ')));
         const validIds = TRACKER_PROVIDERS.map(t => `${t.id} — ${t.hint}`).join('\n  ');
         p.note(`${color.cyan('devflow tracker --status')}      Show the provider and learned conventions\n` +
-            `${color.cyan('devflow tracker --set <id>')}    Set the machine's default provider\n\n` +
+            `${color.cyan('devflow tracker --set <id>')}    Set the machine's default provider\n` +
+            `${color.cyan('devflow tracker --servers <names>')}  Set the tracker servers the agents may call\n\n` +
             `Valid provider IDs:\n  ${validIds}`, 'Usage');
         p.outro(color.dim('github is the default — devflow tracker --set github returns to it'));
         return;
@@ -206,7 +269,17 @@ export const trackerCommand = new Command('tracker')
         }
         setProvider = parsed.value;
     }
-    const manifest = await readManifest(devflowDir);
+    // Validate --servers the same way: a bad name exits before any I/O, never repaired.
+    let setServers;
+    if (options.servers !== undefined) {
+        const parsed = parseTrackerServers(options.servers);
+        if (!parsed.ok) {
+            p.log.error(parsed.error);
+            process.exit(1);
+        }
+        setServers = parsed.value;
+    }
+    const manifest = await readManifest(devflowDir, { onWarning: (message) => p.log.warn(message) });
     if (!manifest) {
         p.log.error('No manifest found. Run devflow init first.');
         process.exit(1);
@@ -238,6 +311,7 @@ export const trackerCommand = new Command('tracker')
             selection,
             conventions,
             mechanics,
+            servers: { list: effectiveTrackerServers(current), isDefault: current.servers === undefined },
             inference,
         }), 'Tracker Status');
         if (!statusRearm.ok)
@@ -248,13 +322,34 @@ export const trackerCommand = new Command('tracker')
         return;
     }
     // ── Set ────────────────────────────────────────────────────────────────────
-    const outcome = await runTrackerSet({
-        devflowDir,
-        current,
-        requested: setProvider ?? current.provider,
-        io: buildTrackerSetIO(),
-    });
-    for (const msg of outcome.messages) {
+    // `--set` and `--servers` are independent settings and may be given together: the provider
+    // first, then the servers against the state it left.
+    const messages = [];
+    let state = current;
+    if (setProvider !== undefined) {
+        const outcome = await runTrackerSet({
+            devflowDir,
+            current,
+            requested: setProvider,
+            io: buildTrackerSetIO(),
+        });
+        messages.push(...outcome.messages);
+        state = { ...current, provider: outcome.provider };
+    }
+    let failed = false;
+    if (setServers !== undefined) {
+        const outcome = await runTrackerServers({
+            devflowDir,
+            claudeDir: getClaudeDirectory(),
+            current: state,
+            requested: setServers,
+            io: buildTrackerServersIO(),
+        });
+        messages.push(...outcome.messages);
+        state = outcome.state;
+        failed = !outcome.ok;
+    }
+    for (const msg of messages) {
         switch (msg.level) {
             case 'success':
                 p.log.success(msg.text);
@@ -270,7 +365,9 @@ export const trackerCommand = new Command('tracker')
                 break;
         }
     }
-    if (outcome.provider !== DEFAULT_TRACKER_PROVIDER) {
+    if (failed)
+        process.exit(1);
+    if (setProvider !== undefined && state.provider !== DEFAULT_TRACKER_PROVIDER) {
         p.log.info(color.dim('Your issue conventions are learned in the background at the next session start'));
     }
 });

package/dist/cli.js

@@ -19,6 +19,7 @@ import { safeDeleteCommand } from './cli/commands/safe-delete.js';
 import { proxyCommand } from './cli/commands/proxy.js';
 import { agentsCommand } from './cli/commands/agents.js';
 import { complianceCommand } from './cli/commands/compliance.js';
+import { behaviorCommand } from './cli/commands/behavior.js';
 import { trackerCommand } from './cli/commands/tracker.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -48,6 +49,7 @@ program.addCommand(safeDeleteCommand);
 program.addCommand(proxyCommand);
 program.addCommand(agentsCommand);
 program.addCommand(complianceCommand);
+program.addCommand(behaviorCommand);
 program.addCommand(trackerCommand);
 // Handle no command (bare `devflow`) or unknown subcommand.
 // When Commander sees an unrecognised first argument it does not route to any

package/dist/commands/bug-analysis.md

@@ -38,7 +38,7 @@ git -C "{start}" rev-parse --show-toplevel
 and using its one-line output. If the command fails (outside a git repository), `{worktree}` is the start directory itself. Every docs path below is written `{worktree}/.devflow/docs/…`; a repo-relative docs path handed to an agent always travels with a `WORKTREE_PATH` naming the checkout it is relative to.
 
 Render the test-plan block from `/implement`'s evidence file, and from nothing else:
-1. `branch_slug` is `git branch --show-current` with every `/` replaced by `-`.
+1. `branch_slug` is `git -C "{worktree}" branch --show-current` with every `/` replaced by `-`.
 2. Only when `branch_slug` matches `^[A-Za-z0-9._-]{1,200}$` and the file exists, run (the path double-quoted):
 
 ```bash
@@ -218,9 +218,9 @@ Attempt to read `{ledger}/.devflow/learning/index.md`.
 
 The index is one direct file read, written at render time by `render-decisions.cjs` alongside `decisions.md`/`pitfalls.md` — no `.cjs` script runs here, and the index's own footer names the files that hold each entry's full body.
 
-**Step 2 — Apply decisions using `devflow:apply-decisions`:**
+**Step 2 — Agents apply the decisions:**
 
-When `DECISIONS_CONTEXT` is not `(none)`, follow `devflow:apply-decisions` to scan the index, identify plausibly-relevant entries, Read full entry bodies on demand, and cite verbatim IDs in downstream agent prompts and reasoning.
+When `DECISIONS_CONTEXT` is not `(none)`, hand it only to the agents whose contract declares it. They follow `devflow:apply-decisions`: scan the index, identify plausibly-relevant entries, Read full entry bodies on demand, and cite verbatim IDs in their reasoning. A host that uses the index in its own thread says so in its own step.
 
 #### Feature Knowledge
 
@@ -281,8 +281,8 @@ A KB with no Rules section labels its entries `Rules ({section name}):` and give
 
 #### Plan Artifact
 
-1. List `{worktree}/.devflow/docs/design/*.md` — sort descending by filename (timestamps are naturally sortable), scan the 10 most recent
-2. Read the most recent file if it exists
+1. List the design plans: `{worktree}/.devflow/docs/design/*.md` (a `/plan` artifact) and `{worktree}/.devflow/docs/design/*/*/*-plan.md` (a `/dynamic-plan` per-ticket plan). Sort by timestamp, newest first, and scan the 10 most recent. A `/plan` artifact's timestamp is the `YYYY-MM-DD_HHMM` before its `.md`; a per-ticket plan's is the name of its parent directory. Never sort by file name, which starts with an issue ID or a ticket slug. A per-ticket plan counts only when its `{ticket-slug}` (its file name without `-plan.md`) appears in the worktree's branch name
+2. Read the most recent file that carries an `## Acceptance Criteria` section
 3. Extract `## Acceptance Criteria` section → parse into table: `| ID | Criterion | Type | Testable Condition |`
 4. Set `PLAN_CONTEXT` to plan summary; `ACCEPTANCE_RULES` to the table
 5. If no plan files exist or section not found: `PLAN_CONTEXT=(none)`, `ACCEPTANCE_RULES=(none)`

package/dist/commands/code-review.md

@@ -22,9 +22,10 @@ Run a comprehensive code review of the current branch by spawning parallel revie
 
 **Produces:** WORKTREES
 
-1. **Discover reviewable worktrees** using the `devflow:worktree-support` skill discovery algorithm:
-   - Run `git worktree list --porcelain` → parse, filter (skip protected/detached/mid-rebase), dedup by branch, sort by recent commit
-   - Invoke the `devflow:worktree-support` skill, then Read its `references/discovery.md` from the skill's base directory for the full 7-step algorithm; the canonical protected branch list stays in the skill
+1. **Discover reviewable worktrees**:
+   - Run `git worktree list --porcelain` and count the worktrees it lists
+   - **More than one listed:** Invoke the `devflow:worktree-support` skill, then Read its `references/discovery.md` from the skill's base directory for the full 7-step algorithm; the canonical protected branch list stays in the skill. Parse the list, filter (skip protected/detached/mid-rebase), dedup by branch, sort by recent commit
+   - **Exactly one listed:** load neither the skill nor the reference — that worktree is the only candidate, and Step 0c's Git agent validates its branch
 2. **If `--path` flag provided:** use only that worktree, skip discovery
    **`--path` validation**: Before proceeding, verify the path exists as a directory and appears in `git worktree list` output. If not: report error and stop.
 3. **If only 1 reviewable worktree** (the common case): proceed as single-worktree flow — zero behavior change
@@ -71,9 +72,9 @@ Set `EVIDENCE_POLICY`, `ISSUE_REQUIRED`, `APPLY_CONVENTIONS` and `REQUIRE_NON_AU
 **Requires:** WORKTREES
 
 Discover PR description guidance from plan artifact (per worktree):
-1. List `{worktree}/.devflow/docs/design/*.md` files
-2. Sort by timestamp in filename (descending -- timestamps are YYYY-MM-DD_HHMM, naturally sortable)
-3. Read the most recent file, extract `## PR Description Guidance` section
+1. List the design plans: `{worktree}/.devflow/docs/design/*.md` (a `/plan` artifact) and `{worktree}/.devflow/docs/design/*/*/*-plan.md` (a `/dynamic-plan` per-ticket plan)
+2. Sort by timestamp, newest first, and scan the 10 most recent. A `/plan` artifact's timestamp is the `YYYY-MM-DD_HHMM` before its `.md`; a per-ticket plan's is the name of its parent directory. Never sort by file name, which starts with an issue ID or a ticket slug. A per-ticket plan counts only when its `{ticket-slug}` (its file name without `-plan.md`) appears in the worktree's branch name
+3. Read the most recent file that carries the section, extract `## PR Description Guidance` section
 4. If no plan files exist or section not found, set `PR_DESCRIPTION_GUIDANCE` to `(none)`
 
 Render the test-plan block (per worktree) from `/implement`'s evidence file, and from nothing else:
@@ -310,9 +311,9 @@ Attempt to read `{ledger}/.devflow/learning/index.md`.
 
 The index is one direct file read, written at render time by `render-decisions.cjs` alongside `decisions.md`/`pitfalls.md` — no `.cjs` script runs here, and the index's own footer names the files that hold each entry's full body.
 
-**Step 2 — Apply decisions using `devflow:apply-decisions`:**
+**Step 2 — Agents apply the decisions:**
 
-When `DECISIONS_CONTEXT` is not `(none)`, follow `devflow:apply-decisions` to scan the index, identify plausibly-relevant entries, Read full entry bodies on demand, and cite verbatim IDs in downstream agent prompts and reasoning.
+When `DECISIONS_CONTEXT` is not `(none)`, hand it only to the agents whose contract declares it. They follow `devflow:apply-decisions`: scan the index, identify plausibly-relevant entries, Read full entry bodies on demand, and cite verbatim IDs in their reasoning. A host that uses the index in its own thread says so in its own step.
 
 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.
 
@@ -408,6 +409,10 @@ Spawn Review agents **in a single message**, for the focus set `DIFF_CLASS` sele
 
 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.
 
+**Set the compliance focus directive** from `COMPLIANCE_FRAMEWORKS`. `COMPLIANCE_FOCUS_DIRECTIVE` is this one line, with `<ids>` replaced by the value of `COMPLIANCE_FRAMEWORKS`; only the compliance focus's spawn carries it:
+
+> For this compliance focus, invoke Skill(skill="devflow:compliance") and load references/{id}.md only for the ids in <ids> (none: generic controls only); never fabricate guidance for a framework you were not given.
+
 Each Review agent invocation (all in one message, **NOT background**):
 ```
 Agent(subagent_type="Review", run_in_background=false):
@@ -421,7 +426,7 @@ DECISIONS_CONTEXT: {decisions_context}
 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)
+{COMPLIANCE_FOCUS_DIRECTIVE}  (compliance focus only)
 If PRIOR_RESOLUTIONS is not (none), follow Cross-Cycle Awareness in review.md.
 Follow devflow:apply-decisions to scan the index and Read full ADR/PF bodies on demand.
 Follow devflow:apply-feature-knowledge for FEATURE_KNOWLEDGE — feature-specific patterns and anti-patterns inform findings.

package/dist/commands/debug.md

@@ -42,6 +42,14 @@ Accept the output only when it is exactly two lines: `exit=0` last and, before i
 
 The accepted line is the only source of these values: the script alone folds the committed `.devflow/project.json`, the personal `.devflow/config.json` and the machine manifest.
 
+From the same line: `COMPLIANCE_FRAMEWORKS` is the settings line's `COMPLIANCE` with `generic` written `none`: `off`, `none`, or the framework ids the machine and this repository declare.
+
+**Set the compliance directive** from `COMPLIANCE_FRAMEWORKS`. `COMPLIANCE_DIRECTIVE` is empty when `COMPLIANCE_FRAMEWORKS` is `off`: a spawn line that holds only `{COMPLIANCE_DIRECTIVE}` is then left out, so a lens-off spawn carries nothing about compliance. Otherwise `COMPLIANCE_DIRECTIVE` is this one line, with `<ids>` replaced by the value of `COMPLIANCE_FRAMEWORKS`:
+
+> 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 <ids> (none: generic controls only); never fabricate guidance for a framework you were not given.
+
+Phase 7 passes `COMPLIANCE_DIRECTIVE` to the Code agent that implements the fix, on a line of its own.
+
 ### Load DECISIONS_CONTEXT
 
 When the settings line says `LEARNING=off`, set `DECISIONS_CONTEXT` to `(none)` and skip this step, locating no ledger and reading no index.
@@ -69,9 +77,9 @@ Attempt to read `{ledger}/.devflow/learning/index.md`.
 
 The index is one direct file read, written at render time by `render-decisions.cjs` alongside `decisions.md`/`pitfalls.md` — no `.cjs` script runs here, and the index's own footer names the files that hold each entry's full body.
 
-**Step 2 — Apply decisions using `devflow:apply-decisions`:**
+**Step 2 — Agents apply the decisions:**
 
-When `DECISIONS_CONTEXT` is not `(none)`, follow `devflow:apply-decisions` to scan the index, identify plausibly-relevant entries, Read full entry bodies on demand, and cite verbatim IDs in downstream agent prompts and reasoning.
+When `DECISIONS_CONTEXT` is not `(none)`, hand it only to the agents whose contract declares it. They follow `devflow:apply-decisions`: scan the index, identify plausibly-relevant entries, Read full entry bodies on demand, and cite verbatim IDs in their reasoning. A host that uses the index in its own thread says so in its own step.
 
 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.
 
@@ -226,7 +234,20 @@ Produce the final report:
 
 Ask user via AskUserQuestion: "Want me to implement this fix?"
 
-- **YES** → Load `devflow:patterns` and `devflow:test-driven-development` skills, implement the fix, then spawn `Agent(subagent_type="Simplify")` on changed files.
+- **YES** → implement the fix through the Code agent, never in this thread, then spawn `Agent(subagent_type="Simplify")` on the changed files. /debug loads no feature knowledge, so the fix gets none:
+
+  ```
+  Agent(subagent_type="Code"):
+  "OPERATION: implement
+  TASK_ID: debug-{YYYY-MM-DD_HHMM}
+  TASK_DESCRIPTION: Implement the fix for this root cause: {bug description}
+  EXECUTION_PLAN: {Root Cause, Key Findings and Recommended Fix from Phase 6, with their file:line references}
+  PUSH: false
+  DECISIONS_CONTEXT: {decisions_context}
+  FEATURE_KNOWLEDGE: (none)
+  {COMPLIANCE_DIRECTIVE}"
+  ```
+
 - **NO** → Done. Report stands as documentation.
 
 ### Feature Knowledge Write-Back (Conditional)
@@ -307,7 +328,7 @@ When the Knowledge agent reports `KB_COMMIT: skipped (detached HEAD)`, the files
 ├─ Phase 6: Root cause report with confidence level
 │
 ├─ Phase 7: Offer Fix
-│  └─ AskUserQuestion → implement fix + Simplify agent, or done
+│  └─ AskUserQuestion → Code agent (fix) + Simplify agent, or done
 │
 └─ Feature Knowledge Write-Back (Conditional)
    └─ Knowledge agent (if investigation surfaced durable cross-cutting knowledge)

package/dist/commands/dynamic-build.md

@@ -41,7 +41,7 @@ Spawn devflow agents with:
 agent("your prompt here", { agentType: "Code" })
 ```
 
-Valid `agentType` values: Code, Validate, Simplify, Scrutinize, Evaluate, Test, Review, Git, Synthesize, Knowledge, Design.
+Valid `agentType` values: Code, Code-fix, Validate, Simplify, Scrutinize, Evaluate, Test, Review, Git, Synthesize, Knowledge, Design.
 
 **OMIT `opts.model` whenever `agentType` is set.** The agent frontmatter carries its own model tier (Code→sonnet, Validate→haiku, Review→opus, etc.) and that tier is honored automatically. Passing `opts.model` overrides it — always a mistake.
 
@@ -65,7 +65,7 @@ The `budget` global governs depth. Scale Review agent roster and verification vo
 
 ### Handoff convention for sequential Code agents within a ticket
 
-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.
+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), `{branch_slug}` being the ticket's branch name with every `/` replaced by `-`, and `{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)
 
@@ -107,7 +107,7 @@ This is the rule the learning hooks apply (D-LEDGER-MAIN-WORKTREE, D-PROMPT-ROOT
 
 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.
+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, Code-fix, 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.
 
 ---
 
@@ -121,11 +121,12 @@ The following agentType values are valid. Model tiers are shown for reference
 
 | agentType | Model tier | Role |
 |-----------|-----------|------|
-| Code | sonnet | Writes all code and all fixes — the ONLY agent that writes code |
+| Code | sonnet | Implements the plan and fixes review findings — the Code family is the ONLY one that writes code |
+| Code-fix | sonnet | Fixes the listed validation, alignment and QA failures — part of the Code family |
 | Validate | haiku | Build / typecheck / lint / test — fast correctness gate |
 | Simplify | sonnet | Reduces complexity, removes duplication, improves readability |
 | Scrutinize | opus | 9-pillar self-review — deep structural analysis |
-| Evaluate | opus | Plan-fidelity / alignment — "was the plan implemented correctly?" |
+| Evaluate | sonnet | Plan-fidelity / alignment — "was the plan implemented correctly?" |
 | Test | sonnet | Scenario-based acceptance tests against acceptance criteria |
 | Review | opus | Focus-parameterized code review — spawn ONE agent() per focus area |
 | Git | haiku | Git operations — branches, commits, merges, worktree management |
@@ -135,7 +136,7 @@ The following agentType values are valid. Model tiers are shown for reference
 
 ### Agent caveats
 
-- **A Code agent writes every fix** — no other agent type writes code. Finding-verification uses adversarial Review agent-style passes (§6.3 of design doc). Risk-assessment and tech-debt routing live in the post-code pipeline + escalation doctrine.
+- **The Code family writes every fix** — Code for review findings, Code-fix for gate failures; no other agent type writes code. Finding-verification uses adversarial Review agent-style passes (§6.3 of design doc). Risk-assessment and tech-debt routing live in the post-code pipeline + escalation doctrine.
 - **Always omit `opts.model` with `agentType`.** Each agent honors its own frontmatter model tier; overriding it defeats the per-agent specialization.
 - **Review agents are focus-parameterized.** Each focus is a SEPARATE `agent()` call with `agentType: "Review"` and the focus baked into the prompt. Do NOT batch multiple focuses into one Review agent call — that defeats parallel specialization.
 - **Do not depend on agents enumerating their own skills.** Skills are loaded (spike F5 confirmed) but self-reporting is imperfect. Write agent prompts that give the agent full context directly.
@@ -186,7 +187,7 @@ Author the resolved `ISSUE_REQUIRED` and `APPLY_CONVENTIONS` into the workflow s
 
 **Set the compliance lens** from that line: `COMPLIANCE_FRAMEWORKS` is the settings line's `COMPLIANCE` with `generic` written `none`: `off`, `none`, or the framework ids the machine and this repository declare.
 
-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**
 
@@ -268,7 +269,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.
 
 ---
 
@@ -294,6 +295,7 @@ const ISSUE_INPUT = args.issueInput || args.issueNumber || "(none)";  // this ti
 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", () =>
@@ -310,7 +312,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)";
 
@@ -336,9 +338,7 @@ ${PLAN ? `Implementation plan:\n${PLAN}` : "No plan provided — use best judgme
 Relevant architectural decisions (apply devflow:apply-decisions algorithm):
 ${DECISIONS_CONTEXT}
 
-ISSUE_NUMBER: ${ISSUE_NUMBER}
-ISSUE_PR_LINK: ${ISSUE_PR_LINK}
-COMPLIANCE_FRAMEWORKS: ${COMPLIANCE_FRAMEWORKS}
+${COMPLIANCE_DIRECTIVE}
 
 When you build or run tests to verify your work, follow your Running commands block.
 
@@ -373,10 +373,8 @@ Return: {"verdict": "PASS" | "FAIL", "details": "..."}`, { agentType: "Validate"
 Fix the validation failures on branch ${BRANCH}:
 ${failureDetails}
 DECISIONS_CONTEXT: ${DECISIONS_CONTEXT}
-ISSUE_NUMBER: ${ISSUE_NUMBER}
-ISSUE_PR_LINK: ${ISSUE_PR_LINK}
-COMPLIANCE_FRAMEWORKS: ${COMPLIANCE_FRAMEWORKS}
-Commit fixes with conventional-commit message.`, { agentType: "Code" });
+${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;
@@ -416,10 +414,8 @@ Return: {"verdict": "PASS" | "FAIL", "rationale": "..."} — FAIL if either answ
 Fix the alignment issues identified by the Evaluate agent on branch ${BRANCH}:
 ${evaluation?.rationale || "see the Evaluate agent's report"}
 DECISIONS_CONTEXT: ${DECISIONS_CONTEXT}
-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" });
+${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
     }
   }
@@ -438,10 +434,8 @@ Cover: functionality, API contracts, performance, and cover every TEST_PLAN scen
 Fix the failing acceptance test scenarios on branch ${BRANCH}:
 ${testResult.failures}
 DECISIONS_CONTEXT: ${DECISIONS_CONTEXT}
-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" });
+${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
     }
   }
@@ -558,9 +552,7 @@ ${chunk.map((f, n) => `${n + 1}. ${f.file ? `${f.file}${f.line ? `:${f.line}` :
 SCOPE: ${chunk.map((f, n) => `${n + 1}=${CAREFUL_SEVERITIES.has(String(f.severity).toLowerCase()) ? "Careful" : "Standard"}`).join(", ")}
 PUSH: false
 DECISIONS_CONTEXT: ${DECISIONS_CONTEXT}
-ISSUE_NUMBER: ${ISSUE_NUMBER}
-ISSUE_PR_LINK: ${ISSUE_PR_LINK}
-COMPLIANCE_FRAMEWORKS: ${COMPLIANCE_FRAMEWORKS}
+${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 });
@@ -619,10 +611,8 @@ Return: {"verdict": "PASS" | "FAIL", "details": "..."}`, { agentType: "Validate"
 Fix the final validation failures on branch ${BRANCH}:
 ${failureDetails}
 DECISIONS_CONTEXT: ${DECISIONS_CONTEXT}
-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" });
+${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;
@@ -707,12 +697,12 @@ Run builds, typechecks, lints and tests in the foreground, each with an explicit
 The standard implementation unit for one ticket. Run in order:
 
 ```
-Code(agentType:"Code", prompt: "OPERATION: implement" first line, then full task + plan + DECISIONS_CONTEXT + COMPLIANCE_FRAMEWORKS + handoff if sequential)
+Code(agentType:"Code", prompt: "OPERATION: implement" first line, then full task + plan + DECISIONS_CONTEXT + COMPLIANCE_DIRECTIVE + handoff if sequential)
   → gate1_postcode()
   → gate2_acceptance()   ← Gate 2 runs HERE — before the review pass, not after
 ```
 
-Every Code agent prompt opens with `OPERATION: <mode>` as its first line (`implement`, `issue-fix`, `validation-fix`, `alignment-fix` or `qa-fix`). It must include: task description, implementation plan (if one exists), relevant DECISIONS_CONTEXT (the index you loaded before authoring), the compliance lens (`COMPLIANCE_FRAMEWORKS` — every Code prompt carries it, fix prompts included), and any PRIOR_PHASE_SUMMARY / HANDOFF_FILE for sequential multi-phase tickets.
+Every Code-family agent prompt opens with `OPERATION: <mode>` as its first line: `implement` and `issue-fix` go to `agentType:"Code"`, `validation-fix`, `alignment-fix` and `qa-fix` go to `agentType:"Code-fix"`. It must include: task description, implementation plan (if one exists), relevant DECISIONS_CONTEXT (the index you loaded before authoring), the compliance directive (`COMPLIANCE_DIRECTIVE` — every Code prompt carries it when it is not empty, fix prompts included), and any PRIOR_PHASE_SUMMARY / HANDOFF_FILE for sequential multi-phase tickets.
 
 Gate 2 runs at implementation acceptance — this matches devflow's deliberate placement: "evaluation is part of implementation acceptance, not post-review" (§6.1).
 
@@ -725,7 +715,7 @@ ORDER IS LOAD-BEARING. Run exactly in this sequence:
    - BLOCKED (a P0 issue cannot be fixed in scope), or a missing or unrecognised status, which counts as BLOCKED → stop the pass and escalate as `scrutiny-blocked`; Validate does not run on code Scrutinize could not accept
 3. **Validate agent** — build / typecheck / lint / test; returns `{"verdict": "PASS" | "FAIL", "details": "..."}`. It runs LAST and UNCONDITIONALLY: one full run over the HEAD that Simplify and Scrutinize left, so it covers their commits whether or not Scrutinize changed code
    - Build/test commands follow `build_execution_doctrine()`: the Validate agent's Running commands block, foreground under an explicit Bash timeout.
-   - FAIL → Code agent fix (max 2 retries), each followed by a Validate agent re-run
+   - FAIL → Code-fix agent fix (max 2 retries), each followed by a Validate agent re-run
    - If still FAIL after 2 retries → escalate as `validation-exhausted` (do not loop endlessly)
 
 **Gate 1 contains NO Evaluate agent and NO Test agent.** Those are Gate 2 only.
@@ -746,11 +736,11 @@ Gate 2 inputs are produced by `/devflow:dynamic-plan`'s plan-challenge step —
 
 **Evaluate agent** (only if a plan exists):
 - Run `evaluator_panel()` — see that block for the one spawn and the two lenses it names
-- If the Evaluate agent returns FAIL (either lens failed): fix-and-continue — the demanded fixes are applied by a Code agent that self-verifies its own build (batched per the review-pass batching doctrine if numerous). The recorded verdict becomes `FAIL-FIXED` (issues found, fixes applied, not re-evaluated by design); Gate 2 then proceeds. In SINGLE mode the run reports it as `UNVERIFIED`, never PASS.
+- If the Evaluate agent returns FAIL (either lens failed): fix-and-continue — the demanded fixes are applied by a Code-fix agent that self-verifies its own build (batched per the review-pass batching doctrine if numerous). The recorded verdict becomes `FAIL-FIXED` (issues found, fixes applied, not re-evaluated by design); Gate 2 then proceeds. In SINGLE mode the run reports it as `UNVERIFIED`, never PASS.
 
 **Test agent** (only if acceptance criteria or a test plan exist):
 - Scenario-based acceptance tests covering functionality, API contracts, performance
-- FAIL → fix-and-continue — a Code agent applies the demanded fixes and self-verifies its own build. The recorded verdict becomes `FAIL-FIXED`; Gate 2 then proceeds. In SINGLE mode the run reports it as `UNVERIFIED`, never PASS.
+- FAIL → fix-and-continue — a Code-fix agent applies the demanded fixes and self-verifies its own build. The recorded verdict becomes `FAIL-FIXED`; Gate 2 then proceeds. In SINGLE mode the run reports it as `UNVERIFIED`, never PASS.
 
 **When Gate 2 inputs are absent:**
 - No plan → skip the Evaluate agent silently (note in output: "Gate 2 Evaluate agent skipped — no plan available")
@@ -869,7 +859,7 @@ If survivors remain: batch the confirmed findings for fixing: group findings by
 
 ### Engine invariants (non-negotiable)
 
-1. **Code is written ONLY by Code agents.** No other agent type writes code — not Review agent, not Evaluate agent.
+1. **Code is written ONLY by the Code family (Code, Code-fix).** No other agent type writes code — not Review agent, not Evaluate agent.
 2. **Findings are verified before any fix is written.** The adversarial verification step is not optional; unverified findings are not passed to the Code agent.
 3. **All written code passes Gate 1.** No code merge, commit, or handoff before Simplify agent + Scrutinize agent + Validate agent (in that order — Validate last, so its one run covers the commits of the two before it).
 4. **Gate 2 runs once, at implementation acceptance.** It does not re-run after review-fixes.
@@ -1013,7 +1003,7 @@ 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 whose prompt opens with `OPERATION: implement` and carries `COMPLIANCE_FRAMEWORKS` and `DECISIONS_CONTEXT`, with FULL intent context:
+2. Spawn a Code agent whose prompt opens with `OPERATION: implement` and carries `COMPLIANCE_DIRECTIVE` (when it is not empty) and `DECISIONS_CONTEXT`, with FULL intent context:
    - Both ticket descriptions and plans
    - The conflicting diff sections (both sides)
    - Relevant ADRs from DECISIONS_CONTEXT (loaded by main model before authoring)