devflow-kit 3.5.0 → 3.6.0

package/dist/targets/claude-code/installer.js

@@ -1,7 +1,7 @@
 import { promises as fs } from 'fs';
 import { existsSync } from 'fs';
 import * as path from 'path';
-import { SKILL_NAMESPACE, prefixSkillName, unprefixSkillName, getAllSkillNames, getAllAgentNames, getAllCommandNames, FEATURE_OWNED_SKILLS, resolveSkillInstallPlan, omitLearningGatedSkills } from '../../core/plugins.js';
+import { SKILL_NAMESPACE, buildAssetMaps, prefixSkillName, unprefixSkillName, getAllSkillNames, getAllAgentNames, getAllCommandNames, FEATURE_OWNED_SKILLS, resolveSkillInstallPlan, omitLearningGatedSkills } from '../../core/plugins.js';
 import { skillsDir, agentSourceDirs, rulesDir, commandSourceDirs, scriptsDir, compiledSkillRefsDir } from '../../core/assets.js';
 import { getPackageRoot, isContainedIn } from '../../core/paths.js';
 import { sweepOrphanedAssets, mdFileName, mdEntryName } from '../../core/orphan-sweep.js';
@@ -1432,6 +1432,90 @@ async function removeDeselectedSkills(skillsDir, names) {
     }
     return { removed, failed };
 }
+/**
+ * Write the commands and the agents of `plugins` into `claudeDir`, and nothing else:
+ * no sweep, no stamp, no skills. The one copy path shared by `installViaFileCopy` and
+ * the selective uninstall, which rewrites the files of the plugins that stay installed
+ * after it removed a retired agent.
+ *
+ * Commands come from dist/commands/{name}.md, or — with learning off — the learning-off
+ * variant dist/learning-off/commands/{name}.md when the host has one
+ * (D-LEARNING-VARIANT-INSTALL; commandSourceDirs owns the order). A declared command
+ * with no compiled source file is a hard error, not a skip.
+ *
+ * Agents resolve dist-first with a src fallback: dist/agents/{name}.md (compiled from an
+ * .mds generator host) wins over src/assets/agents/{name}.md. A declared agent absent from
+ * BOTH is a build/packaging failure and throws rather than silently skipping (matches the
+ * command pattern); the message names the build step as well as the tree.
+ *
+ * D-TRACKER-AGENT-OWNER: every declared agent but ONE. The Tracker agent is converged by
+ * `convergeTrackerArtifacts` alone (plan A3), which runs after the install in init and
+ * reports whether this run wrote it. Copying it here too would make every install do the
+ * work twice, and a fresh install would never report `installed` because converge would
+ * find this loop's byte-identical copy already in place. The name is skipped from the COPY
+ * set only. It stays declared in `devflow-core-skills.agents`, so the agent sweep — which
+ * keys on the full registry via getAllAgentNames() — still treats a converged tracker.md as
+ * known and leaves it alone.
+ */
+export async function installCommandsAndAgents(opts) {
+    const { plugins, agentsMap, claudeDir, learning, trackerServers, warn } = opts;
+    const commandsTarget = path.join(claudeDir, 'commands', 'devflow');
+    const commandDirs = commandSourceDirs(learning);
+    const commandsSourceNames = new Set();
+    for (const plugin of plugins) {
+        for (const cmd of plugin.commands) {
+            const name = cmd.startsWith('/') ? cmd.slice(1) : cmd;
+            commandsSourceNames.add(name);
+        }
+    }
+    if (commandsSourceNames.size > 0) {
+        await fs.mkdir(commandsTarget, { recursive: true });
+        for (const name of commandsSourceNames) {
+            const srcFile = await firstExisting(commandDirs.map(dir => path.join(dir, mdFileName(name))));
+            if (srcFile === undefined) {
+                // The error names the learning-ON path: that file exists for every declared
+                // command, while a learning-off file exists only for a host with an arm.
+                throw new Error(`Command source not found for declared command "${name}": ${path.join(commandSourceDirs(true)[0], mdFileName(name))}. ` +
+                    `Ensure build:mds ran successfully before install.`);
+            }
+            await fs.copyFile(srcFile, path.join(commandsTarget, mdFileName(name)));
+        }
+    }
+    const agentsTarget = path.join(claudeDir, 'agents', 'devflow');
+    // Learning-aware (D-LEARNING-VARIANT-INSTALL). An injected list wins as given.
+    const agentDirs = opts.agentSourceDirs ?? agentSourceDirs(undefined, learning);
+    const allAgentNames = new Set();
+    for (const plugin of plugins) {
+        for (const agent of plugin.agents) {
+            if (agent === TRACKER_AGENT_NAME)
+                continue;
+            if (!allAgentNames.has(agent) && agentsMap.get(agent) === plugin.name) {
+                allAgentNames.add(agent);
+            }
+        }
+    }
+    if (allAgentNames.size > 0) {
+        await fs.mkdir(agentsTarget, { recursive: true });
+        for (const agentName of allAgentNames) {
+            if (await skipsForUserOwnedType(agentName, claudeDir, agentsTarget, warn))
+                continue;
+            const candidates = agentDirs.map(dir => path.join(dir, mdFileName(agentName)));
+            const srcFile = await firstExisting(candidates);
+            if (srcFile === undefined) {
+                throw new Error(`Agent source not found for declared agent "${agentName}": ${path.join(opts.agentSourceDirs?.[0] ?? agentSourceDirs()[0], mdFileName(agentName))}. ` +
+                    `Run \`npm run build:mds\` if it is compiled from an .mds generator host, otherwise ` +
+                    `ensure the agent file exists in src/assets/agents/ (searched: ${candidates.join(', ')}).`);
+            }
+            const agentTarget = path.join(agentsTarget, mdFileName(agentName));
+            if (isTrackerStampedAgent(agentName)) {
+                await writeStampedAgent(srcFile, agentTarget, trackerServers, warn);
+            }
+            else {
+                await fs.copyFile(srcFile, agentTarget);
+            }
+        }
+    }
+}
 /**
  * Install plugins via manual file copy.
  * Handles cleanup of old monolithic structure, deduplication of shared assets,
@@ -1576,38 +1660,42 @@ export async function installViaFileCopy(options) {
     for (const failure of deselected.failed) {
         warn(`Could not remove deselected skill "${prefixSkillName(failure.name)}" — ${String(failure.error)}`);
     }
-    // Install commands from selected plugins using registry-driven lookup.
-    // Source: dist/commands/{name}.md, or — with learning off — the learning-off
-    // variant dist/learning-off/commands/{name}.md when the host has one
-    // (D-LEARNING-VARIANT-INSTALL; commandSourceDirs owns the order).
-    // A declared command with no compiled source file is a hard error, not a skip.
+    // Retired agents. The sweep runs BEFORE the copy so the copy can see what it found:
+    // an agent file whose name left the registry means a previous release is installed
+    // here, and every command of that release still spawns the retired name. Sweeping
+    // alone would then strand the plugins that stay installed without their agents.
+    //
+    // Ungated: runs on every install shape. knownNames spans ALL plugins
+    // (getAllAgentNames) so agents from uninstalled plugins survive a partial run. Only
+    // names absent from the full registry are removed.
+    const agentsTarget = path.join(claudeDir, 'agents', 'devflow');
+    const agentSweep = await sweepOrphanedAssets(agentsTarget, new Set(getAllAgentNames()), mdEntryName);
+    recordSweep(report, 'agent', agentSweep);
+    // A partial install writes the selected plugins' commands and agents and leaves every
+    // other plugin's files alone, which is only safe while those files still name agents
+    // that exist. After a retired agent was removed they do not, so a partial install
+    // writes the commands and agents of every plugin the manifest records instead. The
+    // widening is conditional because an ordinary add-one run has nothing to repair and
+    // must not rewrite files the user did not ask about.
+    const widenToInstalled = isPartialInstall && agentSweep.removed.length > 0;
+    const commandAgentPlugins = widenToInstalled ? (options.effectivePlugins ?? plugins) : plugins;
+    const commandAgentMap = widenToInstalled ? buildAssetMaps(commandAgentPlugins).agentsMap : agentsMap;
+    // Install commands and agents (D-TRACKER-AGENT-OWNER and the source-resolution rules
+    // are documented on installCommandsAndAgents).
     spinner.message('Installing commands and agents...');
-    const commandsTarget = path.join(claudeDir, 'commands', 'devflow');
-    const commandDirs = commandSourceDirs(learning);
-    const commandsSourceNames = new Set();
-    for (const plugin of plugins) {
-        for (const cmd of plugin.commands) {
-            const name = cmd.startsWith('/') ? cmd.slice(1) : cmd;
-            commandsSourceNames.add(name);
-        }
-    }
-    if (commandsSourceNames.size > 0) {
-        await fs.mkdir(commandsTarget, { recursive: true });
-        for (const name of commandsSourceNames) {
-            const srcFile = await firstExisting(commandDirs.map(dir => path.join(dir, mdFileName(name))));
-            if (srcFile === undefined) {
-                // The error names the learning-ON path: that file exists for every declared
-                // command, while a learning-off file exists only for a host with an arm.
-                throw new Error(`Command source not found for declared command "${name}": ${path.join(commandSourceDirs(true)[0], mdFileName(name))}. ` +
-                    `Ensure build:mds ran successfully before install.`);
-            }
-            await fs.copyFile(srcFile, path.join(commandsTarget, mdFileName(name)));
-        }
-    }
+    await installCommandsAndAgents({
+        plugins: commandAgentPlugins,
+        agentsMap: commandAgentMap,
+        claudeDir,
+        learning,
+        trackerServers,
+        agentSourceDirs: options.agentSourceDirs,
+        warn,
+    });
     // Sweep stale command files — ungated: runs on every install shape.
     // knownNames spans ALL plugins (getAllCommandNames) so commands from uninstalled
     // plugins survive a partial run. Only names absent from the full registry are removed.
-    recordSweep(report, 'command', await sweepOrphanedAssets(commandsTarget, new Set(getAllCommandNames()), mdEntryName));
+    recordSweep(report, 'command', await sweepOrphanedAssets(path.join(claudeDir, 'commands', 'devflow'), new Set(getAllCommandNames()), mdEntryName));
     // D-LANGUAGE-FOCUS-STAMP: record the language focuses the EFFECTIVE selection installs on the
     // installed /code-review, on every install shape. This is the language gate the command reads
     // (no run-time probe of Claude Code's directory), so it runs after the copy and the sweep and
@@ -1620,61 +1708,6 @@ export async function installViaFileCopy(options) {
         effectivePlugins: options.effectivePlugins ?? plugins,
         warn,
     });
-    // Install agents (deduplicated), resolved dist-first with a src fallback:
-    // dist/agents/{name}.md (compiled from an .mds generator host) wins over
-    // src/assets/agents/{name}.md. A declared agent absent from BOTH is a
-    // build/packaging failure and throws rather than silently skipping (matches
-    // command pattern); the message names the build step as well as the tree.
-    //
-    // D-TRACKER-AGENT-OWNER: every declared agent but ONE. The Tracker agent is
-    // converged by `convergeTrackerArtifacts` alone (plan A3), which runs after this
-    // function in init and reports whether this run wrote it. Copying it here too
-    // would make every install do the work twice, and a fresh install would never
-    // report `installed` because converge would find this loop's byte-identical copy
-    // already in place.
-    //
-    // The name is skipped from the COPY set only. It stays declared in
-    // `devflow-core-skills.agents`, so the sweep below — which keys on the full
-    // registry via getAllAgentNames() — still treats a converged tracker.md as known
-    // and leaves it alone.
-    const agentsTarget = path.join(claudeDir, 'agents', 'devflow');
-    // Learning-aware (D-LEARNING-VARIANT-INSTALL). An injected list wins as given.
-    const agentDirs = options.agentSourceDirs ?? agentSourceDirs(undefined, learning);
-    const allAgentNames = new Set();
-    for (const plugin of plugins) {
-        for (const agent of plugin.agents) {
-            if (agent === TRACKER_AGENT_NAME)
-                continue;
-            if (!allAgentNames.has(agent) && agentsMap.get(agent) === plugin.name) {
-                allAgentNames.add(agent);
-            }
-        }
-    }
-    if (allAgentNames.size > 0) {
-        await fs.mkdir(agentsTarget, { recursive: true });
-        for (const agentName of allAgentNames) {
-            if (await skipsForUserOwnedType(agentName, claudeDir, agentsTarget, warn))
-                continue;
-            const candidates = agentDirs.map(dir => path.join(dir, mdFileName(agentName)));
-            const srcFile = await firstExisting(candidates);
-            if (srcFile === undefined) {
-                throw new Error(`Agent source not found for declared agent "${agentName}": ${path.join(options.agentSourceDirs?.[0] ?? agentSourceDirs()[0], mdFileName(agentName))}. ` +
-                    `Run \`npm run build:mds\` if it is compiled from an .mds generator host, otherwise ` +
-                    `ensure the agent file exists in src/assets/agents/ (searched: ${candidates.join(', ')}).`);
-            }
-            const agentTarget = path.join(agentsTarget, mdFileName(agentName));
-            if (isTrackerStampedAgent(agentName)) {
-                await writeStampedAgent(srcFile, agentTarget, trackerServers, warn);
-            }
-            else {
-                await fs.copyFile(srcFile, agentTarget);
-            }
-        }
-    }
-    // Sweep stale agent files — ungated: runs on every install shape.
-    // knownNames spans ALL plugins (getAllAgentNames) so agents from uninstalled
-    // plugins survive a partial run. Only names absent from the full registry are removed.
-    recordSweep(report, 'agent', await sweepOrphanedAssets(agentsTarget, new Set(getAllAgentNames()), mdEntryName));
     // Install skills from ALL plugins (skillsMap covers all plugins, not just selected).
     // Resolved from flat src/assets/skills/{name}/ (no per-plugin subdirectory).
     // A declared skill whose source directory is absent is a build/packaging failure

package/dist/targets/claude-code/tracker-servers.js

@@ -10,7 +10,7 @@
  * and `devflow tracker --servers` changes it. Decided here:
  *
  *   - Stamped agents: Git and Tracker, the two that call tracker tools. Code and Research keep a
- *     denylist and so every tool server; Scrutinize and Simplify deny them all.
+ *     denylist and so every tool server; Harden and Polish deny them all.
  *   - Where the stamp is written. Every path that writes an installed copy of either agent either
  *     stamps it or carries the stamp it finds:
  *       1. `installViaFileCopy` stamps Git as it writes it (full install and `--plugin` alike);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devflow-kit",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "description": "A meta-harness for Claude Code — turns a single coding agent into an engineering team: orchestration, parallel review, persistent memory, self-learning, and graph workflows",
   "type": "module",
   "bin": {

package/src/assets/agents/_partials/_code.mds

@@ -1,6 +1,6 @@
 A partial: the text the three Code variants share. `code.mds` (Code: implement, issue-fix),
-`code-fix.mds` (Code-fix: validation-fix, alignment-fix, qa-fix, ci-fix) and `code-edit.mds`
-(Code-edit: edit) are the hosts. A host is any file with `output-dir:`; this file declares none,
+`fix.mds` (Fix: validation-fix, alignment-fix, qa-fix, ci-fix) and `refactor.mds`
+(Refactor: edit) are the hosts. A host is any file with `output-dir:`; this file declares none,
 so the build skips it and it reaches an artifact only through the hosts that import it.
 
 D-CODE-VARIANTS: a spawn runs exactly one mode, so one agent for every mode would pay for every

package/src/assets/agents/code.mds

@@ -1,7 +1,7 @@
 ---
 output-dir: dist/agents
-# D-CODE-VARIANTS: Code runs implement and issue-fix. The gate-failure fixes run on Code-fix and
-# edit runs on Code-edit; the three hosts share _partials/_code.mds.
+# D-CODE-VARIANTS: Code runs implement and issue-fix. The gate-failure fixes run on Fix and
+# edit runs on Refactor; the three hosts share _partials/_code.mds.
 # D-CODE-PRELOADS: Code preloads git, testing, test-driven-development, worktree-support,
 # apply-feature-knowledge and apply-decisions: implement writes tests first, and only the
 # implement and issue-fix spawns pass FEATURE_KNOWLEDGE.

package/src/assets/agents/{learning.md → curate.md}

@@ -1,5 +1,5 @@
 ---
-name: Learning
+name: Curate
 description: Background decisions maintenance agent — claims the pending learning queue, captures decisions and pitfalls from the claimed turns, and maintains the decisions ledger through the learning ops. Spawned by the session-start directive when the queue is non-empty.
 model: opus
 tools:
@@ -10,7 +10,7 @@ tools:
 omitClaudeMd: true
 ---
 
-# Learning Agent
+# Curate Agent
 
 You process one project's pending decisions queue: claim it, capture the decisions and
 pitfalls worth keeping from the claimed turns, maintain the entries the ledger hands you,
@@ -108,7 +108,7 @@ cd "<project root>" && node "$HOME/.devflow/scripts/hooks/json-helper.cjs" claim
 
 - `claimed <token>` — the batch is yours. Keep the 16-hex token: your FINAL act releases the claim with it.
 - `claimed <token> takeover` — you took over a run that stopped sending heartbeats. The batch is yours, though that run may have stored part of it.
-- `busy` — another Learning agent holds the claim. Exit silently; change nothing.
+- `busy` — another Curate agent holds the claim. Exit silently; change nothing.
 - `none` — nothing is queued. Report "no pending decisions work" and finish.
 - A non-zero exit — stop and report its stderr line.
 
@@ -275,7 +275,7 @@ cd "<project root>" && node "$HOME/.devflow/scripts/hooks/json-helper.cjs" claim
 ```
 
 `due none` ends Part 2. Any other output lists due entries: resolve `${CLAUDE_CONFIG_DIR:-$HOME/.claude}`
-in Bash, Read `<that directory>/skills/devflow:agent-references/references/learning/maintain.md`
+in Bash, Read `<that directory>/skills/devflow:agent-references/references/curate/maintain.md`
 with the Read tool, and follow it for those entries.
 
 ## Finishing

package/src/assets/agents/{diagnose.mds → debug.mds}

@@ -2,8 +2,8 @@
 output-dir: dist/agents
 ---
 ---
-name: Diagnose
-description: Proactive bug finding agent with static+semantic analysis. Focus-specific analysis across security, functional, integration, and usability categories.
+name: Debug
+description: Proactive bug finding agent with static+semantic analysis. Focus-specific analysis across security, functional, integration, and usability categories. The /bug-analysis command spawns it. It is not the /debug command.
 model: opus
 effort: medium
 skills:
@@ -21,7 +21,7 @@ tools:
   - Skill
 ---
 
-# Diagnose Agent
+# Debug Agent
 
 You are a proactive bug finding agent. Your focus area is specified in the prompt. You hunt for real bugs — not style issues — using a 5-step methodology that combines static analysis findings with semantic code understanding.
 
@@ -126,7 +126,7 @@ Assign to each verified finding:
 
 **Category mapping** (for `/resolve` compatibility — severity-based approximation):
 
-> **Trade-off**: The Review agent uses location-based categories (lines you added / lines you touched / unchanged lines). The Diagnose agent focuses on diff-changed code and lacks per-line location context, so it approximates using severity as a proxy. This means a LOW-severity bug in newly-added code is placed in Pre-existing — not because it predates the change, but to signal lower urgency. The resolve pipeline should treat Pre-existing findings from the Diagnose agent as low-urgency, not as assertions about code origin.
+> **Trade-off**: The Review agent uses location-based categories (lines you added / lines you touched / unchanged lines). The Debug agent focuses on diff-changed code and lacks per-line location context, so it approximates using severity as a proxy. This means a LOW-severity bug in newly-added code is placed in Pre-existing — not because it predates the change, but to signal lower urgency. The resolve pipeline should treat Pre-existing findings from the Debug agent as low-urgency, not as assertions about code origin.
 
 - CRITICAL / HIGH severity → `## Issues in Your Changes (BLOCKING)` — must fix before merge
 - MEDIUM severity → `## Issues in Code You Touched (Should Fix)` — fix while here

package/src/assets/agents/evaluate.md

@@ -1,6 +1,6 @@
 ---
 name: Evaluate
-description: Validates implementation aligns with original request and plan. Catches missed requirements, scope creep, and intent drift. Reports misalignments for Code agent to fix.
+description: Validates implementation aligns with original request and plan. Catches missed requirements, scope creep, and intent drift. Reports misalignments for the Fix agent to fix.
 model: sonnet
 effort: medium
 skills:
@@ -17,7 +17,7 @@ omitClaudeMd: true
 
 # Evaluate Agent
 
-You are an alignment validation specialist. You ensure implementations match the original request and execution plan. You catch missed requirements, scope creep, and intent drift. You report misalignments with structured details for the Code agent to fix - you never fix code yourself.
+You are an alignment validation specialist. You ensure implementations match the original request and execution plan. You catch missed requirements, scope creep, and intent drift. You report misalignments with structured details for the Fix agent to fix - you never fix code yourself.
 
 ## Input Context
 
@@ -38,14 +38,14 @@ You receive from orchestrator:
 3. **Goal-backward verification**: Start from the user's observable goals. For each goal, ask whether the implementation delivers it. Report any goal that is not delivered.
 4. **Check completeness**: Verify all plan steps implemented, all acceptance criteria met
 5. **Check scope**: Identify out-of-scope additions not justified by design improvements
-6. **Report misalignments**: Document issues with sufficient detail for Code agent to fix
+6. **Report misalignments**: Document issues with sufficient detail for the Fix agent to fix
 
 **Gate ownership:** Run no build, test or lint command. Git read commands only. Only Validate runs the full suite.
 
 ## Principles
 
 1. **Intent over letter** - Validate the spirit of the request, not just literal interpretation
-2. **Report, don't fix** - Document misalignments for Code agent to fix; never modify code yourself
+2. **Report, don't fix** - Document misalignments for the Fix agent to fix; never modify code yourself
 3. **Allow justified improvements** - Design enhancements that don't change functionality are OK
 4. **Structured details** - Provide file references and suggested fixes for each misalignment
 5. **Honest assessment** - Report all issues found, don't minimize

package/src/assets/agents/{code-fix.mds → fix.mds}

@@ -1,15 +1,15 @@
 ---
 output-dir: dist/agents
-# D-CODE-VARIANTS: Code-fix runs validation-fix, alignment-fix, qa-fix and ci-fix, and has no default
+# D-CODE-VARIANTS: Fix runs validation-fix, alignment-fix, qa-fix and ci-fix, and has no default
 # mode. Its text is the shared partial _partials/_code.mds plus the four mode sections below.
-# D-CODE-PRELOADS: Code-fix preloads git, testing, worktree-support and apply-decisions: a gate-failure
+# D-CODE-PRELOADS: Fix preloads git, testing, worktree-support and apply-decisions: a gate-failure
 # fix runs the named tests and is not a test-first build, and no fix spawn passes FEATURE_KNOWLEDGE.
-# D-VARIANT-SLUGS: code-fix is its own `devflow agents` slug with Code's model and effort; a `code`
+# D-VARIANT-SLUGS: fix is its own `devflow agents` slug with Code's model and effort; a `code`
 # override does not reach it.
 ---
 @import "./_partials/_code.mds" as code
 ---
-name: Code-fix
+name: Fix
 description: Autonomous gate-failure repair on feature branch. Fixes the listed validation, alignment, QA or CI failures, verifies, and commits.
 model: sonnet
 effort: high
@@ -40,7 +40,7 @@ disallowedTools:
   - DesignSync
 ---
 
-# Code-fix Agent
+# Fix Agent
 
 You are an autonomous repair specialist working on a feature branch. A quality gate (validation, alignment, QA or CI) reported failures. You fix exactly the failures you are given, verify the fix and commit it. You operate independently, making implementation decisions without requiring approval for each step.
 

package/src/assets/agents/{scrutinize.mds → harden.mds}

@@ -2,7 +2,7 @@
 output-dir: dist/agents
 ---
 ---
-name: Scrutinize
+name: Harden
 description: Self-review agent that evaluates and fixes implementation issues using 9-pillar framework. Runs in fresh context after Code agent completes.
 model: opus
 effort: medium
@@ -36,9 +36,9 @@ disallowedTools:
   - mcp__*
 ---
 
-# Scrutinize Agent
+# Harden Agent
 
-You are a meticulous self-review specialist. You evaluate implementations against the 9-pillar quality framework and fix the issues you find. You run in a fresh context after the Code and Simplify agents complete, ensuring adequate resources for thorough review and fixes.
+You are a meticulous self-review specialist. You evaluate implementations against the 9-pillar quality framework and fix the issues you find. You run in a fresh context after the Code and Polish agents complete, ensuring adequate resources for thorough review and fixes.
 
 ## Input Context
 
@@ -68,7 +68,7 @@ Follow the `devflow:apply-decisions` skill to scan the index, Read full bodies o
 
 4. **Evaluate P1 pillars** (Complexity, Error Handling, Tests): These SHOULD pass. Fix all issues found.
 
-5. **Evaluate P2** (Documentation): Fix if straightforward. Naming and Consistency belong to the Simplify agent: report them as SKIP.
+5. **Evaluate P2** (Documentation): Fix if straightforward. Naming and Consistency belong to the Polish agent: report them as SKIP.
 
 6. **Commit fixes**: If any changes were made, create a commit with message "fix: address self-review issues".
 
@@ -106,8 +106,8 @@ Return structured completion status:
 - Tests: PASS | FIXED (description)
 
 ### P2 Pillars
-- Naming: SKIP (Simplify agent)
-- Consistency: SKIP (Simplify agent)
+- Naming: SKIP (Polish agent)
+- Consistency: SKIP (Polish agent)
 - Documentation: PASS | FIXED (description)
 
 ### Files Modified

package/src/assets/agents/{simplify.md → polish.md}

@@ -1,6 +1,6 @@
 ---
-name: Simplify
-description: Simplifies and refines code for clarity, consistency, and maintainability while preserving all functionality. Focuses on recently modified code unless instructed otherwise.
+name: Polish
+description: "Judgment-based clarity pass on recently changed code: improves naming, structure and consistency and keeps all behaviour. Use for 'make this code cleaner'. For a given mechanical change (rename, move, boilerplate) use Refactor."
 model: sonnet
 effort: medium
 skills:
@@ -28,7 +28,7 @@ disallowedTools:
   - mcp__*
 ---
 
-# Simplify Agent
+# Polish Agent
 
 You are an expert code simplification specialist focused on enhancing code clarity, consistency, and maintainability while preserving exact functionality. Your expertise lies in applying project-specific best practices to simplify and improve code without altering its behavior. You prioritize readable, explicit code over overly compact solutions. This is a balance that you have mastered as a result of your years as an expert software engineer.
 
@@ -106,7 +106,7 @@ Code-scanning runs in the Code agent; do not scan here.
 Return structured completion status:
 
 ```markdown
-## Simplification Report
+## Polish Report
 
 ### Changes Applied
 - {file}: {description of simplification}

package/src/assets/agents/{code-edit.mds → refactor.mds}

@@ -1,16 +1,16 @@
 ---
 output-dir: dist/agents
-# D-CODE-VARIANTS: Code-edit runs edit, a mechanical change that adds no behaviour. Its text is the
+# D-CODE-VARIANTS: Refactor runs edit, a mechanical change that adds no behaviour. Its text is the
 # shared partial _partials/_code.mds plus the one mode section below.
-# D-CODE-PRELOADS: Code-edit preloads git, worktree-support and apply-decisions: no tests are written
+# D-CODE-PRELOADS: Refactor preloads git, worktree-support and apply-decisions: no tests are written
 # and no FEATURE_KNOWLEDGE is passed.
-# D-VARIANT-SLUGS: code-edit is its own `devflow agents` slug with Code's model and effort; a `code`
+# D-VARIANT-SLUGS: refactor is its own `devflow agents` slug with Code's model and effort; a `code`
 # override does not reach it.
 ---
 @import "./_partials/_code.mds" as code
 ---
-name: Code-edit
-description: Autonomous mechanical edit on feature branch. Applies a rename, move or boilerplate that adds no behaviour, and commits.
+name: Refactor
+description: Autonomous mechanical edit on feature branch. Makes a given rename, move or boilerplate change and commits. For judgment-based cleanup use Polish.
 model: sonnet
 effort: high
 skills:
@@ -39,7 +39,7 @@ disallowedTools:
   - DesignSync
 ---
 
-# Code-edit Agent
+# Refactor Agent
 
 You are an autonomous editing specialist working on a feature branch. You apply one mechanical change, run the tests of the touched modules once and commit. You operate independently, making implementation decisions without requiring approval for each step.
 

package/src/assets/agents/test.md

@@ -143,7 +143,7 @@ One row per TP line, in TP order. PASS only when every scenario covering the TP
 - **Expected**: {what should happen}
 - **Actual**: {what actually happened}
 - **Evidence**: {stdout/stderr/exit code}
-- **Remediation**: {what Code agent should fix}
+- **Remediation**: {what the Fix agent should fix}
 
 ### Evidence Log
 {Each command run's `LOG=` path, for traceability}
@@ -154,7 +154,7 @@ Report cap: final message at most about 1,500 tokens; longer material goes to a
 ## Principles
 
 1. **User perspective** - Test what the user asked for, not implementation internals
-2. **Report, don't fix** - Document failures for Code agent to fix; never modify code yourself
+2. **Report, don't fix** - Document failures for the Fix agent to fix; never modify code yourself
 3. **Evidence-based** - Every result backed by captured stdout/stderr/exit codes
 4. **Severity-aware** - BLOCKING for acceptance criteria violations, WARNING for edge cases
 5. **Deterministic** - Scenarios must produce consistent results across runs

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

@@ -4,7 +4,7 @@ its consumers, and the lens is set from the line resolved there for the
 worktree's root.
 
 D-COMPLIANCE-INJECT: the compliance instruction reaches an agent only through a spawn
-prompt, and only when the resolved lens is on. No Code, Code-fix, Review or Design body names
+prompt, and only when the resolved lens is on. No Code, Fix, Review or Design body names
 the compliance skill, so a lens-off spawn pays nothing for it. `compliance_directive()` is the
 one home of the directive text; `compliance_inject()` is how a pass-through host sets it.
 An install-time variant keyed on the machine switch would be wrong: the lens is the union of

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

@@ -19,24 +19,39 @@ learning-on build. `decisions_gate()` and `decisions_locate()` are leaves, reach
 inside an arm (`decisions_load()`, `authoring_decisions()`, or a host's own on arm), and carry
 no arm of their own: an arm cannot nest.
 
+D-DECISIONS-SLICE: the index is handed on as a slice, never whole. The orchestrating main model
+copies the index lines that touch an agent's work, verbatim, behind a
+`(slice: N of M entries — full index: <path>)` marker and ahead of the footer, so an agent reads what
+bears on its task and `devflow:apply-decisions` sends it to the full index only when its work leaves
+that scope. Siblings over one diff share ONE slice, so their prompts stay identical. No script cuts
+it: the index stays a pre-rendered file read, never built on demand, and matching a line to a task is
+judgment, which stays with the model. When unsure, include the line: a slice that misses costs one
+full-index read, a slice that over-includes costs only its bytes. `decisions_slice()` is a leaf like
+the gate and the locator, reached only from inside a learning-on arm, so a learning-off build carries
+none of the rule (D-LEARNING-VARIANTS).
+
 @define decisions_gate():
 When the settings line says `LEARNING=off`, set `DECISIONS_CONTEXT` to `(none)` and skip this step, locating no ledger and reading no index.
 @end
 
 @define decisions_locate():
-The decisions ledger belongs to the repository, not to one checkout: in a linked worktree it lives in the main worktree, and a session started in a subdirectory reads the copy at the repository root. Locate it with ONE git call, run from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`):
+The decisions ledger belongs to the repository, not to one checkout: a linked worktree reads the main worktree's copy, a subdirectory session the repository root's. Locate it with ONE git call, run from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`):
 
 ```bash
 git -C "{start}" rev-parse --path-format=absolute --show-toplevel --git-common-dir
 ```
 
-Line 1 is the checkout's toplevel, line 2 the repository's common git directory. A git older than 2.31 echoes `--path-format=absolute` back as a line of its own first. `{ledger}` is the first of these that applies:
+Line 1 is the checkout's toplevel, line 2 the common git directory. A git older than 2.31 echoes `--path-format=absolute` back as a line of its own first. `{ledger}` is the first that applies:
 
 1. **The main worktree** — line 2 without its trailing `/.git`, when the output is exactly two lines each beginning with `/`, line 2 ends in `/.git`, and the directory left once it is removed is not your home directory and contains a `.devflow/` directory.
 2. **The toplevel** — line 1, or on an older git the line after the echoed flag.
 3. **The start directory itself** — when the command failed or printed no absolute toplevel (outside a git repository).
 
-This is the rule the learning hooks apply (D-LEDGER-MAIN-WORKTREE, D-PROMPT-ROOT), so you read the index the Learning agent writes.
+This is the rule the learning hooks apply, so you read the index the Curate agent writes.
+@end
+
+@define decisions_slice():
+Hand each agent that takes `DECISIONS_CONTEXT` a slice, not the whole index: the index lines whose title, scope or area touch the files and task it works on, verbatim, led by `(slice: N of M entries — full index: <absolute index path>)` and closed by the index footer. When unsure, include the line. Siblings over one diff share ONE slice.
 @end
 
 @define decisions_load():
@@ -54,15 +69,20 @@ Attempt to read `{ledger}/.devflow/learning/index.md`.
 - If the file exists and contains non-empty content: use that content as `DECISIONS_CONTEXT`.
 - If the file is absent or empty: set `DECISIONS_CONTEXT` to `(none)`.
 
-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.
+The index is one direct file read, written at render time by `render-decisions.cjs` — no `.cjs` script runs here.
+
+**Step 2 — Slice the index, then hand it on:**
+
+When `DECISIONS_CONTEXT` is not `(none)`, hand it only to the agents whose contract declares it.
 
-**Step 2 — Agents apply the decisions:**
+{{decisions_slice()}}
 
-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.
+Those agents follow `devflow:apply-decisions`. A host that uses the index in its own thread says so in its own step.
 
 <!-- learning:end -->
 @end
 
 @export decisions_gate
 @export decisions_locate
+@export decisions_slice
 @export decisions_load