devflow-kit 3.5.0 → 3.7.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/learning-install.js

@@ -72,6 +72,7 @@ import * as path from 'path';
 import { agentSourceDirs, commandSourceDirs, learningOffDir, } from '../../core/assets.js';
 import { carryStampedTools } from '../../core/agent-frontmatter.js';
 import { carryAgentOverrides, reapplyAgentMapping } from '../../core/agent-models.js';
+import { describeEchoedValue } from '../../core/echo-value.js';
 import { writeFileAtomicExclusive } from '../../core/fs-atomic.js';
 import { readManifest } from '../../core/manifest.js';
 import { getPackageRoot } from '../../core/paths.js';
@@ -431,14 +432,25 @@ export function describeLearningConverge(result, learning) {
         parts.push('the apply-decisions skill removed');
     return parts.length === 0 ? null : parts.join('; ');
 }
+/**
+ * Whether the version the manifest records is the version of the running package.
+ * Pure. An unknown running version (null) never matches: the installed files are then
+ * not known to be the ones this package would write. Both callers, the learning
+ * toggle and `init --hud-only`, ask this one question.
+ */
+export function installedVersionMatches(installedVersion, runningVersion) {
+    return runningVersion !== null && installedVersion === runningVersion;
+}
 /**
  * The version-skew check, apart from the I/O so it is provable by itself: null when
- * the installed prompts and this package agree, else the message to print.
+ * the installed prompts and this package agree, else the message to print. The
+ * installed version is hand-editable file content, so it prints through
+ * `describeEchoedValue`.
  */
 export function learningToggleSkew(installedVersion, runningVersion, learning) {
-    if (runningVersion !== null && installedVersion === runningVersion)
+    if (installedVersionMatches(installedVersion, runningVersion))
         return null;
-    return (`The installed prompts come from devflow ${installedVersion} and this CLI is ${runningVersion ?? 'of unknown version'}, ` +
+    return (`The installed prompts come from devflow ${describeEchoedValue(installedVersion)} and this CLI is ${runningVersion ?? 'of unknown version'}, ` +
         `so the learning-${learning ? 'on' : 'off'} variants were not applied. Run \`devflow init\` to apply them.`);
 }
 /**

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.7.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
@@ -56,11 +56,11 @@ Run builds, typechecks, lints and tests in the foreground, each with an explicit
 
 ## Principles
 
-1. **Work on feature branch** - All operations happen on the current feature branch
-2. **Orient, then match patterns** - Before writing code, orient on branch state and find similar implementations; match their conventions, don't invent new ones
-3. **Be decisive** - Make confident implementation choices. Don't present alternatives or ask permission for tactical decisions
-4. **Small, focused changes** - Don't scope creep beyond the plan
-5. **Fail honestly** - If blocked, report clearly with what was completed
+1. **Read once** - Never re-read an unchanged file. For a file over 400 lines, or a second look, `grep -n` first, then Read only that range (`offset`, `limit`)
+2. **Small, focused changes** - Don't scope creep beyond the plan
+3. **Fail honestly** - If blocked, report clearly with what was completed
+
+- Never print a large file whole; page it with offset and limit, and cap any output you print. Before printing search matches, list or count them.
 
 ## Output
 
@@ -100,7 +100,6 @@ Report cap: final message at most about 1,500 tokens; longer material goes to a
 - Switch branches during implementation
 - Push to branches other than your feature branch
 - Merge PRs (orchestrator handles this)
-- Trust handoff summaries without reading actual code
 @end
 
 @export input_core

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.
@@ -75,7 +75,7 @@ You receive from orchestrator:
    - Read those relevant files to understand interfaces, types, naming conventions, error handling, and testing patterns established by prior work
    - If PRIOR_PHASE_SUMMARY is provided, use it to validate your understanding — actual code is authoritative, summaries are supplementary
 {{code.decisions_orient()}}
-   - If `HANDOFF_FILE` is provided, read only the `## Phase {N} Implementation Summary` section of the phase immediately before yours — list its `##` headings with `command grep -n '^## ' "$HANDOFF_FILE"`, then Read that range with `offset` and `limit` — never the whole file. Cross-reference against actual code — code is authoritative, handoff is supplementary.
+   - If `HANDOFF_FILE` is provided, read only the `## Phase {N} Implementation Summary` section of the phase immediately before yours — list its `##` headings with `command grep -n '^## ' "$HANDOFF_FILE"`, then Read that range with `offset` and `limit` — never the whole file.
 
 2. **Implement the plan**: Work through execution steps systematically, creating and modifying files. Follow existing patterns. Type everything. Use Result types if codebase uses them.
 
@@ -100,7 +100,6 @@ When `OPERATION: issue-fix`, you are fixing pre-classified issues assigned FIX_N
    - **Standard scope**: Fix directly following existing patterns
    - **Careful scope**: systematic protocol — understand (50+ lines context, callers/consumers) → plan → write failing regression test → implement → verify tests pass → commit
 3. **Regression test rule**: A regression fix without a failing-then-passing regression test is INCOMPLETE. Report BLOCKED rather than commit an unverified fix.
-4. **Self-verification scope**: Run compile + the fix's regression test only. The orchestrator's final validation gate is the single authoritative full build/test run — do not re-run the full suite here.
 
 **Return report** (a Return block in the spawn replaces this shape):
 - Status: COMPLETE | PARTIAL | BLOCKED
@@ -127,9 +126,7 @@ When `OPERATION: issue-fix`, you are fixing pre-classified issues assigned FIX_N
 - {Decision with rationale}
 
 ### Integration Points for Next Phase
-- {Interfaces to implement against}
-- {Functions to call}
-- {Types to import}
+- `path:line` of each interface, function or type the next phase builds on
 ```
 
 {{code.tail()}}

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.
 
@@ -142,7 +142,7 @@ You are not handed CLAUDE.md or the rule files, and two checks compare a lesson
 rule that already states it: Part 1's already-encoded search and Part 2's first rung.
 Before the first of those comparisons, Read `<project root>/CLAUDE.md` once. Both also
 compare against a rules file, so list the installed ones with
-`cd "<project root>" && find "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/rules/devflow" -name '*.md'`
+`d="${CLAUDE_CONFIG_DIR:-}"; case "$d" in /*) ;; *) d="$HOME/.claude" ;; esac; cd "<project root>" && find "$d/rules/devflow" -name '*.md'`
 and Read each once. Keep what you read for every later comparison in the run; a file that
 is missing is skipped. A run that ends before any comparison reads none of them.
 
@@ -190,8 +190,6 @@ Bad:
 {"id": "obs_fix", "type": "pitfall", "title": "Fixed the claim bug (see PF-NNN)", "rule": "Use the approach from #123 at store.cjs:88; all 9 ops do it now.", "why": "It was broken.", "scope": ["area:hooks"], "provenance": "this session"}
 ```
 
-It breaks every rule above, and its why names no failure.
-
 ## Part 1 — Capture
 
 **LLM judgment — creation bar (abstain-by-default)**:
@@ -221,7 +219,7 @@ Concrete failure → PF; forward-looking architectural choice → ADR.
 For each lesson that clears the bar:
 
 1. **Dedup before creating.** Run `list` once and read ACTIVE, INACTIVE and OBSERVATIONS;
-   `show` any line that may cover the same concern. Duplication is worse than silence.
+   `show` any line that may cover the same concern.
    - An active entry or a stored observation covers it: reinforce that row with
      `put-observation --reinforce`. When the turns sharpen or correct it, rewrite it
      instead with `put-observation --update` and its whole content.
@@ -240,7 +238,7 @@ For each lesson that clears the bar:
    cd "<project root>" && node "$HOME/.devflow/scripts/hooks/json-helper.cjs" assign-anchor pitfall obs_...
    ```
 
-   The anchor is the one stdout line. NEVER invent an ADR-NNN/PF-NNN number yourself —
+   NEVER invent an ADR-NNN/PF-NNN number yourself —
    `assign-anchor` is the only source of numbering. `… is already promoted (…)` means the
    ledger holds the observation: update it instead, restoring an inactive entry first. An
    observation you do not promote waits in the log, where a recurrence promotes it and
@@ -274,8 +272,8 @@ Then take this run's work list, once:
 cd "<project root>" && node "$HOME/.devflow/scripts/hooks/json-helper.cjs" claim-due
 ```
 
-`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`
+`due none` ends Part 2. Any other output lists due entries: run `d="${CLAUDE_CONFIG_DIR:-}"; case "$d" in /*) ;; *) d="$HOME/.claude" ;; esac; printf '%s\n' "$d"`
+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/review.mds

@@ -280,3 +280,5 @@ use the same prefix so values are not double-masked.
 | java | If .java files changed |
 | python | If .py files changed |
 | rust | If .rs files changed |
+
+The gate level (`GATE_LEVEL`, `/code-review` Step 1.2b) removes focuses from this table at `standard` and `lean`.