devflow-kit 3.5.0 → 3.6.0

package/CHANGELOG.md

@@ -5,6 +5,103 @@ All notable changes to Devflow will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.6.0] - 2026-10-14
+
+### Upgrade notes — Agent rename (6 agents)
+
+This change releases as a minor version (3.6.0). It renames six agents, and a prompt that names
+an old agent does not work. Read the steps below that you must do by hand.
+
+Six agents have new names that state their job ([#466](https://github.com/dean0x/devflow/issues/466)).
+The agent `code` keeps its name. The learning feature keeps its names too: `devflow learning`,
+`features.learning`, `.devflow/learning/` and the learning ops do not change.
+
+| Old slug     | New slug   | Old `name:`  | New `name:` |
+|--------------|------------|--------------|-------------|
+| `code-fix`   | `fix`      | `Code-fix`   | `Fix`       |
+| `code-edit`  | `refactor` | `Code-edit`  | `Refactor`  |
+| `scrutinize` | `harden`   | `Scrutinize` | `Harden`    |
+| `simplify`   | `polish`   | `Simplify`   | `Polish`    |
+| `diagnose`   | `debug`    | `Diagnose`   | `Debug`     |
+| `learning`   | `curate`   | `Learning`   | `Curate`    |
+
+The `/debug` command does not change. `Debug` is the agent that `/bug-analysis` spawns.
+Use `Refactor` for a given mechanical change, such as "rename X to Y everywhere".
+Use `Polish` for a judgment pass that makes code cleaner and keeps its behaviour.
+
+**What devflow migrates automatically:**
+- Keys in `~/.devflow/agent-models.json`. The one-time migration `canonicalise-agent-keys-v2`
+  runs on the first `devflow init` after this upgrade. Each read of the file also maps an old key
+  to its new slug. If the old key and the new key both exist, the new key wins.
+  `devflow agents --set <old slug>` writes the new slug and tells you.
+- The session-start hook reads `agents.curate.model`, then an older `agents.learning.model`, and
+  spawns `Curate`. `devflow init` updates the hook.
+- `token-audit` counts old transcripts under the new names, so a past `Code-fix` spawn counts as
+  `Fix`. Its JSON report key `codeFixByOperation` is now `fixByOperation`.
+
+**What `devflow init` and `devflow uninstall` do to agent files:**
+- A full `devflow init` removes the six old files from `~/.claude/agents/devflow/` and installs
+  the new ones. It removes every other file in that folder that devflow does not own.
+- A partial `devflow init --plugin=<name>` and a selective `devflow uninstall --plugin=<name>`
+  run the orphan sweep. The sweep deletes every `.md` file in `~/.claude/agents/devflow/` whose
+  name is not a devflow agent. This includes the six old files.
+- Do not keep your own agent files in `~/.claude/agents/devflow/`, because devflow deletes them.
+  A file of your own directly in `~/.claude/agents/` is never touched. This is also true when it
+  has the name of an old devflow agent, for example `~/.claude/agents/simplify.md`.
+
+**Partial install and partial uninstall on a 3.5.0 install:**
+- The commands of the plugins that stay installed name the old agents until something rewrites
+  them. The sweep removes the old agent files, and the new agent files are not on disk until
+  something writes them. For this reason both commands now repair the plugins that stay installed.
+- `devflow init --plugin=<name>`: the sweep can delete an old agent file. If it does, the install
+  writes the commands and the agents of every plugin in `~/.devflow/manifest.json`. It does not
+  write only the plugin you name. If the sweep deletes nothing, the install writes only the plugin
+  you name, as before.
+- `devflow uninstall --plugin=<name>`: the sweep can delete an old agent file. If it does, the
+  uninstall writes the current commands and agents of the plugins that stay installed. It also
+  prints a note. It does not update the hooks, the scripts or `settings.json`. Run a full
+  `devflow init` to update them. Until you do, the hook from 3.5.0 can name an agent that no
+  longer exists.
+- If there is no readable `~/.devflow/manifest.json`, or the manifest lists no plugin that Devflow
+  knows, the uninstall writes nothing. It prints a warning that tells you to run `devflow init`.
+- If the install is a legacy project-local install (`<repo>/.claude`), the uninstall writes
+  nothing. It prints a warning. The warning tells you to remove that install in full with
+  `devflow uninstall --scope local`.
+- If the write fails, the rewrite stops at the first file that fails. The files that it wrote
+  before the failure stay written. The uninstall still finishes and prints a warning that tells
+  you to run `devflow init`.
+
+**What you must migrate by hand:**
+- Your own prompts, commands, agents or `CLAUDE.md` that name an old agent, for example
+  `subagent_type: "Simplify"` or `subagent_type: "Code-edit"`. Devflow cannot edit files it does
+  not own. Change them to the new name, for example `subagent_type: "Polish"`.
+- Open Claude Code sessions. Restart each one after `devflow init`. An open session loaded its
+  agent types when it started, so it does not know `Fix`, `Refactor`, `Harden`, `Polish`, `Debug`
+  or `Curate`. `devflow init` also removes the files of the old agents. The orchestrator charter
+  of an open session still names `Code-edit`.
+
+**Downgrade warning:** if you downgrade to 3.5.0, it does not know the new keys. Your per-agent
+model overrides that you saved as `fix`, `refactor`, `harden`, `polish`, `debug` or `curate` do
+not apply, and 3.5.0 gives no message. Check them with `devflow agents --list`.
+
+### Added
+
+- **The HUD shows your Codex usage limits.** A new `codexQuota` segment sits on line 2 next to the Claude quota, for example `Codex 5h ███░░░░░ 40% (1h 2m) · 7d █░░░░░░░ 12% (3d 4h)`. It reads the newest rate-limit record that Codex writes to `~/.codex/sessions`, so it opens no credential file and makes no network call. A window is identified by its length, so a weekly-only plan and a 5h + 7d plan both label correctly. A window past its reset time shows 0%, and a red `limited` marker shows while Codex reports a reached limit. The segment is hidden when there is no recent Codex session, so users without Codex see no change.
+
+### Changed
+
+- **`/plan` bounds Revise at 2 rounds** ([#455](https://github.com/dean0x/devflow/issues/455)). Each revision spawns five agents (Plan ×3, Synthesize, Design). After the second revision, Gate 2 offers Accept, Cancel or "Restart /plan with these constraints". The first-pass fan-out does not change.
+- **The PR evidence refresh and the merge-readiness check run as a script, not as a Git agent spawn** ([#455](https://github.com/dean0x/devflow/issues/455)). `/implement`, `/resolve` and `/dynamic-build` run `verify-evidence.cjs publish` from the main session, and `/resolve` runs `verify-evidence.cjs readiness`. The `update-pr-evidence` and `check-merge-readiness` operations stay defined and run the same script. The refresh never blocks, and the readiness check only reports.
+- **Agents get a scoped slice of the decisions index** ([#454](https://github.com/dean0x/devflow/issues/454)). On a direct delegation the main session passes only the index lines that match the agent's task, a `(slice: N of M entries — full index: <path>)` marker and the index footer. Sibling agents over one diff share one slice. When the main session is not sure, it includes the entry.
+- **Command bodies are smaller and have size ceilings** ([#456](https://github.com/dean0x/devflow/issues/456)). Rare `/implement` branches (the ticket-link ask, the missing-test-plan ask, the evidence exception and the re-validation path) move to reference files that the command reads by explicit path. `/implement`, `/resolve`, `/plan` and `/code-review` are shorter. A test holds a size ceiling for each of the 14 compiled commands, learning-on and learning-off.
+
+### Fixed
+
+- **`/release` no longer folds the `Exempt (not attested)` line into the last traceability bullet.** The `## Traceability exceptions` block put that line directly under the last `-` bullet, so Markdown rendered it inside that bullet (seen in the v3.5.0 release notes). The template now holds a blank line between them, and the command states the rule so a composed block always carries it.
+- **The HUD status line exits promptly.** The 2-second overall timeout timer is now cleared when a render finishes, so each status-line render takes about 0.3 s instead of about 2.1 s. A render that times out still prints nothing.
+
+---
+
 ## [3.5.0] - 2026-10-12
 
 ### Added
@@ -1577,6 +1674,7 @@ devflow init
 ---
 
 [Unreleased]: https://github.com/dean0x/devflow/compare/v2.0.0...HEAD
+[3.6.0]: https://github.com/dean0x/devflow/compare/v3.5.0...v3.6.0
 [3.5.0]: https://github.com/dean0x/devflow/compare/v3.4.0...v3.5.0
 [3.4.0]: https://github.com/dean0x/devflow/compare/v3.3.0...v3.4.0
 [3.3.0]: https://github.com/dean0x/devflow/compare/v3.2.0...v3.3.0

package/README.md

@@ -30,7 +30,7 @@ you: /implement (hand it the plan)
 
   Git                    branch feat/42-rate-limit-upload
   Code                   implements the plan — your learned decisions, pitfalls, and feature knowledge preloaded
-  Simplify · Scrutinize  cleanup pass, then 9-pillar quality gate
+  Polish · Harden        cleanup pass, then 9-pillar quality gate
   Evaluate               implementation matches the original request ✓
   Validate               build ✓ typecheck ✓ lint ✓ tests ✓
   Test                   5/5 QA scenarios pass
@@ -76,11 +76,11 @@ This is the **orchestrated flow** — you stay in the loop between every step. W
 
 **Your issue tracker, not just GitHub.** Pick the tracker your team actually uses — GitHub, Jira, or Linear — at `devflow init`, with `devflow init --tracker <id>`, or later with `devflow tracker --set <id>`; that sets your machine's default. A repository can select its own in `.devflow/project.json`, and devflow follows it there automatically — one machine can work on a Jira repository and a GitHub one side by side. Every install carries every provider's mechanics (48 generated reference files, the tool-call contract among them) and the background agent, because pull requests stay on GitHub whatever your tracker and any repository may pick any provider. On a non-GitHub tracker that agent learns your conventions once per provider (project key, issue types, required fields, workflow transitions, how a reference renders) and writes them to `~/.devflow/tracker/{provider}.md`, so traceability speaks your tracker's vocabulary instead of assuming `#123`. Each provider's conventions are learned from the first repository that uses it. Those files are yours: hand-editable, kept across an uninstall, and refused rather than silently trusted if one no longer names its own provider. The Git and Tracker agents reach a tracker only through the servers you allow (Atlassian, Jira and Linear by default); `devflow tracker --servers` names others. **GitHub is the default** and needs no configuration: no background run and no conventions file.
 
-**Full lifecycle.** Beyond the core flow: `/explore` maps a codebase into knowledge bases, `/research` runs multi-type research with trust-aware synthesis, `/debug` investigates with competing hypotheses in parallel, `/bug-analysis` hunts bugs before review, `/self-review` runs Simplify + Scrutinize quality passes, and `/release` ships with learned configuration.
+**Full lifecycle.** Beyond the core flow: `/explore` maps a codebase into knowledge bases, `/research` runs multi-type research with trust-aware synthesis, `/debug` investigates with competing hypotheses in parallel, `/bug-analysis` hunts bugs before review, `/self-review` runs Polish + Harden quality passes, and `/release` ships with learned configuration.
 
 **Everything is composable.** 21 plugins (12 core + 9 optional). Install only what you need.
 
-**HUD.** A persistent status line updates on every prompt — project, branch, diff stats, context usage, model, cost with weekly/monthly totals, quota reset timers, and configuration counts at a glance.
+**HUD.** A persistent status line updates on every prompt — project, branch, diff stats, context usage, model, cost with weekly/monthly totals, quota reset timers (Claude and Codex), and configuration counts at a glance.
 
 ```
 ~/devflow · main · +2 -1 · v2.0.0+3
@@ -166,7 +166,7 @@ To keep the knowledge bases or conventions local, add `.devflow/features/` or `.
 | `/research` | Multi-type research with trust-aware synthesis |
 | `/plan` | Full design pipeline: explore → gap analysis → design → PR-ready plan document |
 | `/implement` | Execute plan: accepts plan documents from `/plan`, issues, or task descriptions → PR |
-| `/self-review` | Simplify + Scrutinize quality pass |
+| `/self-review` | Polish + Harden quality pass |
 | `/code-review` | Multi-perspective parallel code review |
 | `/resolve` | Validate and fix all review issues |
 | `/debug` | Competing hypothesis investigation |

package/dist/agents/{diagnose.md → debug.md}

@@ -1,6 +1,6 @@
 ---
-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:
@@ -16,7 +16,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.
 
@@ -117,7 +117,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/dist/agents/{code-fix.md → fix.md}

@@ -1,5 +1,5 @@
 ---
-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
@@ -28,7 +28,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/dist/agents/{scrutinize.md → harden.md}

@@ -1,5 +1,5 @@
 ---
-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
@@ -31,9 +31,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
 
@@ -59,7 +59,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".
 
@@ -97,8 +97,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/dist/agents/{code-edit.md → refactor.md}

@@ -1,6 +1,6 @@
 ---
-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:
@@ -27,7 +27,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/dist/cli/agents-view/render.js

@@ -26,7 +26,7 @@
  * fits whole inside the cursor's "‹ … ›" wrapper with the dirty marker
  * ("‹ default (medium) ● ›", 22) — the shipped effort (D-SHIPPED-EFFORT) and the
  * unsaved mark are never clipped on the cursor row. The agent names the registry
- * holds are at most 10 characters ("Scrutinize"); longer orphan keys are
+ * holds are at most 10 characters ("Synthesize"); longer orphan keys are
  * truncated by truncateVisible.
  *
  * MODEL has no such slack for a worker row, whose shipped default is a full

package/dist/cli/commands/init.js

@@ -784,7 +784,7 @@ export const initCommand = new Command('init')
             'devflow-explore': 'codebase exploration + knowledge bases',
             'devflow-research': 'multi-type research with synthesis',
             'devflow-release': 'adaptive release with learned config',
-            'devflow-self-review': 'Simplify agent + Scrutinize agent',
+            'devflow-self-review': 'Polish agent + Harden agent',
             'devflow-bug-analysis': 'proactive bug finding, post-pipeline',
             'devflow-typescript': 'TypeScript patterns',
             'devflow-react': 'React patterns',
@@ -1967,7 +1967,7 @@ export const initCommand = new Command('init')
         content = addCaptureHooks(cleanedForCapture, devflowDir);
         // Memory hooks — Stop (memory-worker), SessionStart (session-start-memory),
         // PreCompact — through the same transform `devflow memory --enable/--disable`
-        // uses (D-FEATURES-NARROW-ONLY). Learning agent (spawned via
+        // uses (D-FEATURES-NARROW-ONLY). Curate agent (spawned via
         // session-start-context directive) handles decision/pitfall detection.
         // Knowledge is handled in-command via write-through (knowledge_writeback MDS partial).
         content = convergeMemoryHooks(content, memoryEnabled, devflowDir);
@@ -1980,7 +1980,7 @@ export const initCommand = new Command('init')
         content = addContextHook(cleanedForContext, devflowDir);
         // Legacy dream-worker hook cleanup — strip any stale spawn-dream-worker entry
         // left in settings.json by a prior install (session-start-context now spawns
-        // the Learning agent via directive).
+        // the Curate agent via directive).
         content = removeDreamHook(content);
         // Strip Devflow-managed teammateMode ("auto"). User-set values (e.g. "tmux") are preserved.
         content = stripDevflowTeammateModeFromJson(content);

package/dist/cli/commands/learning.js

@@ -3,7 +3,7 @@ import { promises as fs } from 'fs';
 import * as path from 'path';
 import * as p from '@clack/prompts';
 import color from 'picocolors';
-import { getLearningDir, getLearningTuningConfigPath, } from '../../core/project-paths.js';
+import { getLearningDir, getCurateTuningConfigPath, } from '../../core/project-paths.js';
 import { loadShippedAgentDefaults } from '../../core/agent-models.js';
 import { readMachineFeature, writeMachineFeature } from '../../core/feature-switch.js';
 import { loadSettingsModule, narrowedSwitchLabel, personalConfigTrackedWarning } from '../../core/evidence-policy.js';
@@ -263,7 +263,7 @@ async function handleRestore(anchor) {
  * The scope choices of `devflow learning --configure`.
  *
  * D-LEARNING-MODEL-PRECEDENCE: the session-start hook takes the first layer that
- * supplies a model — the project file, then a `devflow agents` Learning mapping,
+ * supplies a model — the project file, then a `devflow agents` Curate mapping,
  * then the global file. A global file therefore has no effect for a user who has
  * such a mapping, and its hint says so.
  */
@@ -272,24 +272,24 @@ export const CONFIGURE_SCOPE_OPTIONS = [
     {
         value: 'global',
         label: 'Global',
-        hint: 'All projects (~/.devflow/learning.json); a devflow agents Learning mapping takes precedence over it',
+        hint: 'All projects (~/.devflow/learning.json); a devflow agents Curate mapping takes precedence over it',
     },
 ];
 /** The models `devflow learning --configure` offers, each with what it is good for. */
-const LEARNING_MODEL_CHOICES = [
+const CURATE_MODEL_CHOICES = [
     { value: 'opus', label: 'Opus', note: 'highest quality for detection + curation judgment' },
     { value: 'sonnet', label: 'Sonnet', note: 'good balance of quality and speed' },
     { value: 'haiku', label: 'Haiku', note: 'fastest, lowest cost' },
 ];
 /**
- * D-LEARNING-SHIPPED-ROW: the model offered as "Recommended" is the one the Learning
+ * D-LEARNING-SHIPPED-ROW: the model offered as "Recommended" is the one the Curate
  * agent ships with, the `model:` line of its frontmatter. It is read from there and
  * written nowhere else, so a change of the shipped tier moves the recommendation with
  * it and this list never has to be edited. A shipped model outside the three offered
  * (or none) recommends nothing.
  */
-export function learningModelOptions(shippedModel) {
-    return LEARNING_MODEL_CHOICES.map(choice => ({
+export function curateModelOptions(shippedModel) {
+    return CURATE_MODEL_CHOICES.map(choice => ({
         value: choice.value,
         label: choice.label,
         hint: choice.value === shippedModel
@@ -299,10 +299,10 @@ export function learningModelOptions(shippedModel) {
 }
 async function handleConfigure() {
     p.intro(color.bgCyan(color.black(' Learning Configuration ')));
-    const shippedModel = (await loadShippedAgentDefaults()).learning?.model;
+    const shippedModel = (await loadShippedAgentDefaults()).curate?.model;
     const model = await p.select({
         message: 'Model for decision detection',
-        options: learningModelOptions(shippedModel),
+        options: curateModelOptions(shippedModel),
     });
     if (p.isCancel(model)) {
         p.cancel('Configuration cancelled.');
@@ -341,7 +341,7 @@ async function handleConfigure() {
         // main checkout in a linked worktree; the current directory outside git.
         const projectRoot = (await getLedgerRoot()) ?? process.cwd();
         const learningDir = getLearningDir(projectRoot);
-        const projectConfigPath = getLearningTuningConfigPath(projectRoot);
+        const projectConfigPath = getCurateTuningConfigPath(projectRoot);
         // D-CLI-NO-SYMLINK (core/linked-path.ts): nothing is written through a .devflow,
         // a learning folder or a learning.json that is a symbolic link.
         const linked = await firstSymbolicLink([path.dirname(learningDir), learningDir, projectConfigPath]);
@@ -419,7 +419,7 @@ async function handleClear() {
         process.exitCode = 1;
         return;
     }
-    // A mid-run Learning agent whose claimed batch vanishes stops without further
+    // A mid-run Curate agent whose claimed batch vanishes stops without further
     // writes — the desired outcome of clearing.
     const drain = await drainLearningQueue(ledgerRoot);
     p.log.success(`Cleared ${counted(cleared.value.cleared, 'observation')} no entry uses and kept ${cleared.value.kept} ` +
@@ -480,7 +480,7 @@ async function handleToggle(enabled) {
         return;
     }
     // Drain the current project's learning (decisions-detection) queue so stale
-    // turns don't process on re-enable. A mid-run Learning agent whose claimed
+    // turns don't process on re-enable. A mid-run Curate agent whose claimed
     // batch vanishes aborts without changes — the desired outcome of disabling.
     const ledgerRoot = await getLedgerRoot();
     if (ledgerRoot) {

package/dist/cli/commands/legacy-hooks.js

@@ -2,7 +2,7 @@ import { devflowHookOwner, hasHook, removeHooks, } from '../../targets/claude-co
 // ─── Dream worker hook cleanup ──────────────────────────────────────────────
 //
 // The spawn-dream-worker SessionStart hook belonged to the retired detached
-// dream worker. Decisions processing runs as the directive-spawned Learning agent
+// dream worker. Decisions processing runs as the directive-spawned Curate agent
 // (session-start-context Section 2), which needs no hook registration of its
 // own. remove/has exist for upgrade cleanup: init and uninstall strip any
 // stale entry left in settings.json by a prior install.

package/dist/cli/commands/uninstall.js

@@ -7,7 +7,7 @@ import color from 'picocolors';
 import { getInstallationPaths, getClaudeDirectory, getHomeDirectory, getManagedSettingsPath } from '../../targets/claude-code/claude-paths.js';
 import { getGitRoot } from '../../core/git.js';
 import { isSameLocation } from '../../core/same-location.js';
-import { DEVFLOW_PLUGINS, SKILL_NAMESPACE, getAllSkillNames, getAllAgentNames, getAllCommandNames, parsePluginSelection, resolveFeatureRedirect, prefixSkillName, unprefixSkillName, skillsOf, FEATURE_OWNED_SKILLS } from '../../core/plugins.js';
+import { DEVFLOW_PLUGINS, SKILL_NAMESPACE, buildAssetMaps, getAllSkillNames, getAllAgentNames, getAllCommandNames, parsePluginSelection, resolveFeatureRedirect, prefixSkillName, unprefixSkillName, skillsOf, FEATURE_OWNED_SKILLS } from '../../core/plugins.js';
 import { readManifest, removeManifestPlugins } from '../../core/manifest.js';
 import { sweepOrphanedAssets, mdFileName, mdEntryName } from '../../core/orphan-sweep.js';
 import { LEGACY_SKILL_NAMES } from '../../targets/claude-code/legacy.js';
@@ -20,7 +20,7 @@ import { removeContextHook } from './context.js';
 import { applyProxyTeardownToSettings } from './proxy.js';
 import { readProxyState, proxyJsonExists } from '../../core/proxy-state.js';
 import { hudCacheDir } from '../../core/cache.js';
-import { TRACKER_ATTEMPTS_NAMES, TRACKER_CLAIM_FILE, TRACKER_CONVENTIONS_DIR, TRACKER_ENABLED_FILE, TRACKER_LEGACY_ATTEMPTS_FILE, TRACKER_LEGACY_CONVENTIONS_FILE, TRACKER_PROVIDER_IDS, TRACKER_STAGED_PREFIX, } from '../../core/tracker.js';
+import { effectiveTrackerServers, TRACKER_ATTEMPTS_NAMES, TRACKER_CLAIM_FILE, TRACKER_CONVENTIONS_DIR, TRACKER_ENABLED_FILE, TRACKER_LEGACY_ATTEMPTS_FILE, TRACKER_LEGACY_CONVENTIONS_FILE, TRACKER_PROVIDER_IDS, TRACKER_STAGED_PREFIX, } from '../../core/tracker.js';
 import { CLAUDE_MD_AUDIT_STAMP_FILE, CLAUDE_MD_AUDIT_STAMP_TMP_PREFIX } from '../../core/claude-md-audit.js';
 import { revertExternalAgents } from '../../core/agent-models.js';
 import { detectShell, getProfilePath } from '../../core/safe-delete.js';
@@ -32,6 +32,7 @@ import { stripDevflowTeammateModeFromJson } from '../../core/teammate-mode-clean
 import { getPackageRoot, isContainedIn } from '../../core/paths.js';
 import { firstSymbolicLink } from '../../core/linked-path.js';
 import { restampInstalledCommands } from '../../targets/claude-code/language-stamp.js';
+import { installCommandsAndAgents } from '../../targets/claude-code/installer.js';
 /**
  * Where a retired repo-local install lives: `<gitRoot>/.claude` and `<gitRoot>/.devflow`.
  *
@@ -488,7 +489,7 @@ export function userContentPaths(devflowDir) {
             const name = `${TRACKER_LEGACY_CONVENTIONS_FILE}.${id}.bak`;
             return { relPath: name, label: `${name} (previous issue tracker conventions)` };
         }),
-        // learning.json — global learning agent tuning config
+        // learning.json — global curate agent tuning config
         { relPath: 'learning.json', label: 'learning.json' },
         // hud.json — user HUD enable/disable preference and display config
         { relPath: 'hud.json', label: 'hud.json (HUD configuration)' },
@@ -885,6 +886,89 @@ export async function runDryRunPhase(opts) {
         }
     }
 }
+/**
+ * After a selective uninstall removed a retired agent file, write the current commands
+ * and agents of the plugins that stay installed.
+ *
+ * A retired agent file only exists on a machine that ran an older release. That
+ * release's commands, for the plugins that stay, still spawn the retired name, and the
+ * agents that replaced it are not installed. Removing the file without this step would
+ * leave those plugins unable to spawn their agents until the next full `devflow init`.
+ *
+ * Writes only commands and agents, through the same copy path `devflow init` uses
+ * ({@link installCommandsAndAgents}). It does not touch the hooks, the scripts or
+ * settings.json, so the notice tells the user to run `devflow init` for those.
+ *
+ * Never runs in a legacy local scope (D-CLI-NO-SYMLINK): a repository can commit a command
+ * file as a symbolic link, and the copy writes through it. The folder guard below does not
+ * check files. `devflow init` can not update a legacy local install either, so the warning
+ * tells the user to remove it in full.
+ *
+ * Skipped, with a warning, when there is no readable manifest or it lists no known plugin (the
+ * retained set would be a guess), or when a folder is behind a link the caller's guard
+ * refuses. Those warnings name `devflow init` as the remedy. When the copy fails, it stops
+ * at the first failure: files it wrote before then stay, and the warning names the same
+ * remedy. Never throws: an uninstall must finish.
+ * Agent model lines are reverted again after the copy, as the selective phase does before
+ * its removal, so a freshly written agent carries no external-model line. Like the
+ * selective phase, it prints the warnings of that revert only with `verbose`.
+ */
+export async function refreshRetainedCommandsAndAgents(opts) {
+    const { claudeDir, devflowDir, retained, retiredAgents } = opts;
+    const scope = opts.scope ?? 'user';
+    const verbose = opts.verbose ?? false;
+    const mayChange = opts.mayChange ?? changeAnything;
+    const agentsDir = path.join(claudeDir, 'agents', 'devflow');
+    const commandsDir = path.join(claudeDir, 'commands', 'devflow');
+    const retired = `Removed the agent file(s) of an older Devflow release: ${retiredAgents.join(', ')}.`;
+    const remedy = 'Run `devflow init` to update the commands, agents, hooks and scripts of the plugins that stay installed.';
+    if (retained.length === 0)
+        return;
+    if (scope === 'local') {
+        p.log.warn(`${retired} Devflow does not rewrite files in a legacy local install, so the remaining commands can still name the removed agents. Remove the legacy local install in full with \`devflow uninstall --scope local\`.`);
+        return;
+    }
+    // readManifest returns null for a missing file and for one it can not parse or validate.
+    const manifest = await readManifest(devflowDir).catch(() => null);
+    if (manifest === null) {
+        p.log.warn(`${retired} There is no readable manifest, so Devflow did not rewrite the remaining files. ${remedy}`);
+        return;
+    }
+    if (manifest.plugins.length === 0) {
+        p.log.warn(`${retired} The manifest lists no plugins, so Devflow did not rewrite the remaining files. ${remedy}`);
+        return;
+    }
+    // resolveInstalledPlugins falls back to the whole registry when no manifest name resolves, so
+    // the retained set would hold plugins that were never installed.
+    if (!manifest.plugins.some(name => DEVFLOW_PLUGINS.some(plugin => plugin.name === name))) {
+        p.log.warn(`${retired} The manifest lists no known plugin, so Devflow did not rewrite the remaining files. ${remedy}`);
+        return;
+    }
+    if (!(await mayChange(agentsDir)) || !(await mayChange(commandsDir))) {
+        p.log.warn(`${retired} A linked folder blocks the rewrite. ${remedy}`);
+        return;
+    }
+    try {
+        await installCommandsAndAgents({
+            plugins: retained,
+            agentsMap: buildAssetMaps(retained).agentsMap,
+            claudeDir,
+            learning: manifest.features.learning,
+            trackerServers: effectiveTrackerServers(manifest.features.tracker),
+            warn: (msg) => p.log.warn(msg),
+        });
+    }
+    catch (err) {
+        p.log.warn(`${retired} Devflow could not write the current commands and agents (${err instanceof Error ? err.message : String(err)}). ${remedy}`);
+        return;
+    }
+    try {
+        await revertExternalAgents({ installDir: agentsDir, devflowDir, onWarning: (msg) => { if (verbose)
+                p.log.warn(msg); } });
+    }
+    catch { /* the revert is best effort, as in the selective phase */ }
+    p.log.info(`${retired} Devflow wrote the current commands and agents of the plugins that stay installed. Run \`devflow init\` to update the hooks and scripts.`);
+}
 /**
  * SELECTIVE PHASE (per scope): revert agent model overrides, remove the
  * selected plugins' assets, and clean up the ambient hook if the ambient
@@ -919,7 +1003,23 @@ export async function runSelectivePhaseForScope(opts) {
         }
         catch { /* agents dir absent or revert failed — non-fatal */ }
     }
-    await removeSelectedPlugins(claudeDir, selectedPlugins, verbose, installedPlugins, mayChange);
+    const sweeps = await removeSelectedPlugins(claudeDir, selectedPlugins, verbose, installedPlugins, mayChange);
+    // A retired agent file means the install is from an older release, and the commands of the
+    // plugins that stay installed still spawn the name that was just removed. Write their
+    // current commands and agents so the install stays whole. Runs before the language stamp
+    // below, which then restamps the command this wrote.
+    if (sweeps.agents.removed.length > 0) {
+        const removed = new Set(selectedPlugins.map(sp => sp.name));
+        await refreshRetainedCommandsAndAgents({
+            claudeDir,
+            devflowDir,
+            retained: installedPlugins.filter(plugin => !removed.has(plugin.name)),
+            retiredAgents: sweeps.agents.removed,
+            scope,
+            verbose,
+            mayChange,
+        });
+    }
     // D-LANGUAGE-FOCUS-STAMP: re-stamp the installed /code-review from the selection that REMAINS.
     // A language plugin owns a skill and no command, so removing it deletes the skill while its
     // name would stay on the stamped line, and /code-review would spawn a focus whose skill is gone.
@@ -1627,6 +1727,9 @@ export async function removeAllDevFlow(claudeDir, devflowScriptsDir, verbose, ma
  * A folder `mayChange` refuses is not swept at all (D-CLI-NO-SYMLINK,
  * legacyLocalChangeGuard). An entry in a swept folder that is itself a link is
  * only unlinked: `fs.rm` never follows the link it is given.
+ *
+ * Returns what each sweep removed and failed to remove, so a caller can tell that
+ * a retired agent was removed (see {@link refreshRetainedCommandsAndAgents}).
  */
 export async function sweepDevflowNamespaces(claudeDir, verbose, mayChange = changeAnything) {
     const agentsDir = path.join(claudeDir, 'agents', 'devflow');
@@ -1656,6 +1759,7 @@ export async function sweepDevflowNamespaces(claudeDir, verbose, mayChange = cha
             p.log.warn(`Could not remove orphaned ${kind} "${failure.name}" (${reason}) — remove it manually`);
         }
     }
+    return { agents: agentsSweep, commands: commandsSweep, skills: skillsSweep };
 }
 /**
  * Remove only specific plugin assets (selective uninstall).
@@ -1665,6 +1769,8 @@ export async function sweepDevflowNamespaces(claudeDir, verbose, mayChange = cha
  * For skills: only remove skills that are NOT used by any remaining plugin.
  * Each removal passes `mayChange` first, which skips one a symbolic link would
  * redirect in a legacy local install (D-CLI-NO-SYMLINK, legacyLocalChangeGuard).
+ *
+ * Returns what the closing registry-diff sweep removed.
  */
 export async function removeSelectedPlugins(claudeDir, plugins, verbose, installedPlugins = DEVFLOW_PLUGINS, mayChange = changeAnything) {
     const { skills, agents, commands, rules } = computeAssetsToRemove(plugins, installedPlugins);
@@ -1734,6 +1840,6 @@ export async function removeSelectedPlugins(claudeDir, plugins, verbose, install
     // Removes any orphaned files whose names left the registry (retired, renamed,
     // or deleted from all plugins). Spans ALL plugins so assets belonging to
     // non-selected plugins are never swept.
-    await sweepDevflowNamespaces(claudeDir, verbose, mayChange);
+    return sweepDevflowNamespaces(claudeDir, verbose, mayChange);
 }
 //# sourceMappingURL=uninstall.js.map