devflow-kit 3.5.0 → 3.6.0

package/dist/commands/self-review.md

@@ -1,9 +1,9 @@
 ---
-description: Self-review workflow - Simplify agent (code clarity) then Scrutinize agent (9-pillar quality gate)
+description: Self-review workflow - Polish agent (code clarity) then Harden agent (9-pillar quality gate)
 ---
 # Self-Review Command
 
-Run Simplify agent and Scrutinize agent sequentially on changed files for post-implementation quality refinement.
+Run Polish agent and Harden agent sequentially on changed files for post-implementation quality refinement.
 
 ## Usage
 
@@ -22,7 +22,7 @@ Detect changed files and build context:
 2. Else run `git diff --name-only HEAD` + `git diff --name-only --cached` to get staged + unstaged
 3. If no changes found, report "No changes to review" and exit
 4. Build TASK_DESCRIPTION from recent commit messages or branch name
-5. Record `HEAD_BEFORE` (`git rev-parse HEAD`) now, before Simplify runs — Phase 3 compares against it
+5. Record `HEAD_BEFORE` (`git rev-parse HEAD`) now, before Polish runs — Phase 3 compares against it
 
 **Resolve the settings line** once per worktree root, reusing a line this run already resolved for the same root. `{root}` is the worktree the values are for — the repository root when the run has one worktree:
 
@@ -38,19 +38,19 @@ The accepted line is the only source of these values: the script alone folds the
 
 When the settings line says `LEARNING=off`, set `DECISIONS_CONTEXT` to `(none)` and skip this step, locating no ledger and reading no index.
 
-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.
 
 **Step 1 — Read the pre-rendered index:**
 
@@ -59,13 +59,17 @@ 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 — Agents apply the decisions:**
+**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. 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.
+When `DECISIONS_CONTEXT` is not `(none)`, hand it only to the agents whose contract declares it.
 
-Pass `DECISIONS_CONTEXT` to Scrutinize agent — the compact index lists active ADR/PF entries; Scrutinize agent uses `devflow:apply-decisions` to Read full entry bodies on demand. Known pitfalls help identify reintroduced issues, prior decisions help validate architectural consistency. (Simplify agent does not consume decisions — it operates at code-shape level and Scrutinize agent runs after to catch any architectural drift.)
+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.
+
+Those agents follow `devflow:apply-decisions`. A host that uses the index in its own thread says so in its own step.
+
+Pass `DECISIONS_CONTEXT` to Harden agent — the compact index lists active ADR/PF entries; Harden agent uses `devflow:apply-decisions` to Read full entry bodies on demand. Known pitfalls help identify reintroduced issues, prior decisions help validate architectural consistency. (Polish agent does not consume decisions — it operates at code-shape level and Harden agent runs after to catch any architectural drift.)
 
 ### Load Feature Knowledge
 
@@ -89,7 +93,7 @@ If `index.md` exists and contains at least one entry line, use it for relevance
 
 **Step 2 — Fallback: glob frontmatter (if `index.md` is absent or empty):**
 
-Glob `{worktree}/.devflow/features/*/KNOWLEDGE.md`. For each file found, read only its YAML frontmatter block (between the opening and closing `---` delimiters). The frontmatter fields `name`, `description`, and `directories` are the authoritative relevance surface — `index.md` is only a cache.
+Glob `{worktree}/.devflow/features/*/KNOWLEDGE.md`. For each file found, read only its YAML frontmatter block (between the opening and closing `---` delimiters).
 
 **Step 3 — Pick relevant KBs:**
 
@@ -120,35 +124,35 @@ Headings: L5 Rules · L40 Overview · L62 Anti-Patterns · L118 Key Files
 
 A KB with no Rules section labels its entries `Rules ({section name}):` and gives them no ID. `FEATURE_KNOWLEDGE` is these blocks; `FEATURE_KNOWLEDGE_RULES` is the same blocks without the `Headings:` line. Both come from this one selection, and each spawn names the variable its recipient takes. If no KBs exist, no KBs are relevant, or `.devflow/features/` is absent, set both to `(none)`.
 
-**One git call, then direct reads — no `.cjs` script.** After resolving `{worktree}`, this step is 1 index read (or N frontmatter reads on fallback), plus one heading listing and one Rules read per selected KB, bounded by KB count.
+**One git call, then direct reads — no `.cjs` script.**
 
-Pass `FEATURE_KNOWLEDGE_RULES` to Scrutinize agent.
+Pass `FEATURE_KNOWLEDGE_RULES` to Harden agent.
 
 **Extract:** FILES_CHANGED (list), TASK_DESCRIPTION (string), DECISIONS_CONTEXT (string, optional), FEATURE_KNOWLEDGE (string, optional), FEATURE_KNOWLEDGE_RULES (string, optional), HEAD_BEFORE (40-hex SHA)
 
-### Phase 1: Simplify agent (Code Refinement)
+### Phase 1: Polish agent (Code Refinement)
 
-**Produces:** SIMPLIFY_COMMITS
+**Produces:** POLISH_COMMITS
 **Requires:** FILES_CHANGED, TASK_DESCRIPTION
 
-Spawn Simplify agent to refine code for clarity and consistency:
+Spawn Polish agent to refine code for clarity and consistency:
 
-Agent(subagent_type="Simplify", run_in_background=false):
+Agent(subagent_type="Polish", run_in_background=false):
 "TASK_DESCRIPTION: {task_description}
 FILES_CHANGED: {files_changed}
-Simplify and refine the code for clarity and consistency while preserving functionality.
+Polish and refine the code for clarity and consistency while preserving functionality.
 Commit any improvements with a conventional-commit message."
 
-**Wait for completion.** Simplify agent commits changes directly.
+**Wait for completion.** Polish agent commits changes directly.
 
-### Phase 2: Scrutinize agent (9-Pillar Quality Gate)
+### Phase 2: Harden agent (9-Pillar Quality Gate)
 
-**Produces:** SCRUTINIZE_STATUS
+**Produces:** HARDEN_STATUS
 **Requires:** FILES_CHANGED, TASK_DESCRIPTION, DECISIONS_CONTEXT
 
-Spawn Scrutinize agent for quality evaluation and fixing:
+Spawn Harden agent for quality evaluation and fixing:
 
-Agent(subagent_type="Scrutinize", run_in_background=false):
+Agent(subagent_type="Harden", run_in_background=false):
 "TASK_DESCRIPTION: {task_description}
 FILES_CHANGED: {files_changed}
 DECISIONS_CONTEXT: {decisions_context}
@@ -162,11 +166,11 @@ Follow devflow:apply-feature-knowledge for FEATURE_KNOWLEDGE. Skip if (none)."
 ### Phase 3: Conditional Validation
 
 **Produces:** VALIDATION_RESULT
-**Requires:** HEAD_BEFORE, SCRUTINIZE_STATUS
+**Requires:** HEAD_BEFORE, HARDEN_STATUS
 
 If STATUS is BLOCKED, skip this phase: the report (Phase 4) names the blocker.
 
-Run this phase only if HEAD moved — `git rev-parse HEAD` differs from `HEAD_BEFORE`, meaning Simplify or Scrutinize committed (Simplify alone counts, whatever Scrutinize's STATUS is). Otherwise skip it. Its scope is changed-only over what the two agents changed:
+Run this phase only if HEAD moved — `git rev-parse HEAD` differs from `HEAD_BEFORE`, meaning Polish or Harden committed (Polish alone counts, whatever Harden's STATUS is). Otherwise skip it. Its scope is changed-only over what the two agents changed:
 
 Agent(subagent_type="Validate", run_in_background=false):
 "FILES_CHANGED: {output of `git diff --name-only HEAD_BEFORE..HEAD`}
@@ -178,7 +182,7 @@ Run build, typecheck, lint, test on modified files"
 
 ### Phase 4: Report
 
-**Requires:** SCRUTINIZE_STATUS, VALIDATION_RESULT
+**Requires:** HARDEN_STATUS, VALIDATION_RESULT
 
 Display summary:
 
@@ -187,10 +191,10 @@ Display summary:
 **Files Reviewed**: {n}
 **Status**: {PASS|FIXED|BLOCKED}
 
-### Simplify agent
+### Polish agent
 - {n} files refined for clarity
 
-### Scrutinize agent (9-Pillar Evaluation)
+### Harden agent (9-Pillar Evaluation)
 | Pillar | Status |
 |--------|--------|
 | Design | {status} |
@@ -240,21 +244,17 @@ FEATURE_SLUG: {slug derived from primary changed directory, kebab-case}
 FEATURE_NAME: {human-readable name}
 DIRECTORIES: {list of primary directories touched by this workflow}
 FILES_CHANGED: {list of files changed}
-DECISIONS_CONTEXT: {DECISIONS_CONTEXT if available, else (none)}
+DECISIONS_CONTEXT: {the slice for these directories, else (none)}
 
 Write the knowledge base to:
   {worktree}/.devflow/features/{slug}/KNOWLEDGE.md
 
-Then update the index cache by performing a read-modify-write on:
+Then update the index cache:
   {worktree}/.devflow/features/index.md
 
 Index line format: `- **{slug}** — {areas} — {Use-when description}` — at most 300 characters, the description at most 220; reword a longer one, never cut it.
 
-If the line for this slug already exists in index.md, replace it. If it does not exist, append it. If index.md does not exist, create it with just this line.
-
-The frontmatter in KNOWLEDGE.md is the source of truth — index.md is only a cache. Write the two files directly — no intermediate result JSON files, no external scripts.
-
-After writing, commit the two files to the current worktree branch yourself by running git via your Bash tool (do not use a script). Stage ONLY .devflow/features/index.md and .devflow/features/{slug}/KNOWLEDGE.md, then commit just those paths with a docs(knowledge): message. Do NOT push, do NOT force, do NOT stage anything else. Follow your Commit Protocol — it is non-blocking, so if any git step fails, report KB_COMMIT and finish normally."
+Then commit the two files as your Commit Protocol directs."
 ```
 
 **Step 4 — Surface an uncommitted knowledge base:**
@@ -272,14 +272,14 @@ When the Knowledge agent reports `KB_COMMIT: skipped (detached HEAD)`, the files
 │  ├─ Record HEAD_BEFORE
 │  └─ Read index.md → DECISIONS_CONTEXT
 │
-├─ Phase 1: Simplify agent
+├─ Phase 1: Polish agent
 │  └─ Code refinement (commits directly)
 │
-├─ Phase 2: Scrutinize agent
+├─ Phase 2: Harden agent
 │  └─ 9-pillar quality gate (may fix and commit)
 │
 ├─ Phase 3: Validate agent (conditional)
-│  └─ If HEAD moved since HEAD_BEFORE (Simplify or Scrutinize committed), changed-only Validate over HEAD_BEFORE..HEAD
+│  └─ If HEAD moved since HEAD_BEFORE (Polish or Harden committed), changed-only Validate over HEAD_BEFORE..HEAD
 │
 └─ Phase 4: Report
    └─ Display summary with pillar status
@@ -289,15 +289,15 @@ When the Knowledge agent reports `KB_COMMIT: skipped (detached HEAD)`, the files
 | Case | Handling |
 |------|----------|
 | No changes | Report "No changes to review" and exit |
-| Simplify agent finds nothing | Normal, continue to Scrutinize agent |
-| Scrutinize agent BLOCKED | Report blocking issue, halt workflow |
+| Polish agent finds nothing | Normal, continue to Harden agent |
+| Harden agent BLOCKED | Report blocking issue, halt workflow |
 | Validation fails | Report failures, halt (don't create broken state) |
 | Not in git repo | Report error, suggest running in git repo |
 
 ## Principles
 
 1. **Orchestration only** - Command spawns agents, doesn't do the work
-2. **Sequential execution** - Simplify agent must complete before Scrutinize agent
-3. **Validation gate** - If Simplify agent or Scrutinize agent committed, the changes must pass validation
+2. **Sequential execution** - Polish agent must complete before Harden agent
+3. **Validation gate** - If Polish agent or Harden agent committed, the changes must pass validation
 4. **Honest reporting** - Display actual agent outputs
 5. **Fail fast** - Stop on BLOCKED or validation failure

package/dist/core/agent-models.js

@@ -142,38 +142,56 @@ export function validateWorkerValue(field, value) {
 // Key migration
 // ---------------------------------------------------------------------------
 /**
- * Maps old agent keys (form A slugs) to their canonical replacement keys.
+ * Maps every retired agent key to the live slug that replaces it. Two renames feed it:
  *
- * 13 agents renamed from noun form (coder, reviewer, …) to action-verb form
- * (code, review, …). The canonicalise-agent-keys-v1 migration in migrations.ts
- * calls canonicaliseAgentKeys() to rewrite ~/.devflow/agent-models.json on the
- * user's first init after upgrading.
+ *   - The 2.0.0 action-verb rename (coder, reviewer, …) and the 1.x names that rename
+ *     retired (scrutinizer, simplifier, bug-analyzer).
+ *   - The rename of six agents to the names that state their job (code-fix, code-edit,
+ *     scrutinize, simplify, diagnose, learning).
+ *
+ * SINGLE HOP: every value is a live slug and no value is itself a key. A 1.x name
+ * therefore points straight at its final slug (scrutinizer → harden, never
+ * scrutinizer → scrutinize → harden), so one pass of canonicaliseAgentKeys() lands
+ * every key. The two canonicalise-agent-keys migrations in migrations.ts call it to
+ * rewrite ~/.devflow/agent-models.json; readAgentMapping() calls it on every read.
  *
  * PROTOTYPE SAFETY: Object.create(null) prevents prototype-pollution.
  * Every lookup MUST use Object.hasOwn — never key in LEGACY_AGENT_KEYS or
  * direct bracket access. `--set constructor` would otherwise return a function
  * that flows into path.join (the object-literal lookup on argv trap).
  *
+ * ORDER: entries are declared oldest first. canonicaliseAgentKeys() reads that order
+ * when two keys meet at one slug (scrutinizer and scrutinize both mean harden): the
+ * entry declared later is the more recent name and wins.
+ *
  * DORMANCY: entries here are stored whether or not the key rename has been
  * applied to the file yet. canonicaliseAgentKeys() is idempotent, so
  * double-execution from concurrent sessions is a harmless no-op — the second
  * run finds the file already migrated and makes zero writes.
  */
 export const LEGACY_AGENT_KEYS = Object.assign(Object.create(null), {
-    // Phase 4 — agent-action-verbs rename (old slug → new slug)
+    // 1.x names (noun form), retargeted to the live slug of their final rename.
+    'scrutinizer': 'harden',
+    'simplifier': 'polish',
+    'bug-analyzer': 'debug',
+    // 2.0.0 action-verb rename (old slug → new slug).
     'coder': 'code',
     'designer': 'design',
     'evaluator': 'evaluate',
     'researcher': 'research',
     'reviewer': 'review',
-    'scrutinizer': 'scrutinize',
-    'simplifier': 'simplify',
     'skimmer': 'skim',
     'synthesizer': 'synthesize',
     'tester': 'test',
     'triager': 'triage',
     'validator': 'validate',
-    'bug-analyzer': 'diagnose',
+    // Rename of six agents to the names that state their job.
+    'code-fix': 'fix',
+    'code-edit': 'refactor',
+    'scrutinize': 'harden',
+    'simplify': 'polish',
+    'diagnose': 'debug',
+    'learning': 'curate',
 });
 /**
  * Canonicalise agent keys in a raw agents map by applying LEGACY_AGENT_KEYS.
@@ -184,6 +202,10 @@ export const LEGACY_AGENT_KEYS = Object.assign(Object.create(null), {
  *
  * Collision detection is against the ORIGINAL map so results are order-independent.
  *
+ * Two legacy keys that name one agent (scrutinizer and scrutinize both mean harden) meet
+ * at one slug. The key declared later in LEGACY_AGENT_KEYS, the more recent name, wins;
+ * the other is dropped. The pick reads the declaration order, never the file order.
+ *
  * The function is pure and idempotent: calling it twice on the same input
  * produces the same result as calling it once (idempotent under concurrent execution).
  *
@@ -208,6 +230,19 @@ export function canonicaliseAgentKeys(rawAgents, onWarning) {
     }
     // Snapshot the original keys for collision detection (order-independent result).
     const originalKeys = new Set(Object.keys(rawAgents));
+    // When several legacy keys in the file name one agent, the one declared latest in
+    // LEGACY_AGENT_KEYS is the one that is renamed; the others are dropped below.
+    const declared = Object.keys(LEGACY_AGENT_KEYS);
+    const winnerByTarget = new Map();
+    for (const oldKey of originalKeys) {
+        if (oldKey === '__proto__' || !Object.hasOwn(LEGACY_AGENT_KEYS, oldKey))
+            continue;
+        const target = LEGACY_AGENT_KEYS[oldKey];
+        const held = winnerByTarget.get(target);
+        if (held === undefined || declared.indexOf(oldKey) > declared.indexOf(held)) {
+            winnerByTarget.set(target, oldKey);
+        }
+    }
     const result = { ...rawAgents };
     let didMutate = false;
     for (const oldKey of originalKeys) {
@@ -237,8 +272,9 @@ export function canonicaliseAgentKeys(rawAgents, onWarning) {
             didMutate = true;
             continue;
         }
-        if (originalKeys.has(newKey)) {
-            // Collision: new (canonical) key already present → new wins, old dropped.
+        if (originalKeys.has(newKey) || winnerByTarget.get(newKey) !== oldKey) {
+            // Collision: new (canonical) key already present, or a more recent legacy key
+            // names the same agent → that value wins, old dropped.
             // Warning is surfaced by the caller's structured dropped-block (e.g. migrations.ts)
             // to avoid printing the same collision twice in two different vocabularies (F8).
             dropped.push(oldKey);

package/dist/core/{learning-tuning-config.js → curate-tuning-config.js}

@@ -1,17 +1,17 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { getDevFlowDirectory } from '../targets/claude-code/claude-paths.js';
-import { getLearningTuningConfigPath } from './project-paths.js';
+import { getCurateTuningConfigPath } from './project-paths.js';
 const VALID_MODELS = new Set(['opus', 'sonnet', 'haiku']);
 function isValidModel(value) {
     return typeof value === 'string' && VALID_MODELS.has(value);
 }
 /**
- * D-LEARNING-SHIPPED-ROW: the default model is the model the Learning agent ships
- * with, the `model:` line of src/assets/agents/learning.md. With no layer
+ * D-LEARNING-SHIPPED-ROW: the default model is the model the Curate agent ships
+ * with, the `model:` line of src/assets/agents/curate.md. With no layer
  * configuring a model, the spawn directive names none and that line decides, so a
  * different default here would describe a run that never happens.
- * tests/decisions/config.test.ts holds this value equal to the Learning row of the
+ * tests/decisions/config.test.ts holds this value equal to the Curate row of the
  * agent-config table, which a change of the shipped tier edits with the frontmatter.
  */
 const DEFAULTS = {
@@ -19,12 +19,12 @@ const DEFAULTS = {
     debug: false,
 };
 /**
- * Apply a single JSON config layer onto a LearningTuningConfig, returning a new object.
+ * Apply a single JSON config layer onto a CurateTuningConfig, returning a new object.
  * Skips fields with wrong types. Swallows parse errors — callers see defaults.
  * Unknown fields (e.g. an old config still on disk with extra knobs) are
  * silently ignored, not an error.
  */
-export function applyLearningTuningConfigLayer(config, json) {
+export function applyCurateTuningConfigLayer(config, json) {
     try {
         const parsed = JSON.parse(json);
         // Object-shape guard mirrors coerceConfig in feature-config.ts: a JSON
@@ -34,7 +34,7 @@ export function applyLearningTuningConfigLayer(config, json) {
         }
         const raw = parsed;
         return {
-            // Only accept a model value that belongs to the closed LearningModelAlias domain.
+            // Only accept a model value that belongs to the closed CurateModelAlias domain.
             model: isValidModel(raw.model) ? raw.model : config.model,
             debug: typeof raw.debug === 'boolean' ? raw.debug : config.debug,
         };
@@ -54,13 +54,13 @@ function readConfigFile(filePath) {
     catch (err) {
         if (err.code !== 'ENOENT') {
             // Warn but don't crash — callers fall back to defaults.
-            console.warn(`[learning-tuning-config] warning: could not read ${filePath}: ${err.message}`);
+            console.warn(`[curate-tuning-config] warning: could not read ${filePath}: ${err.message}`);
         }
         return null;
     }
 }
 /**
- * Load and merge learning agent tuning configuration.
+ * Load and merge curate agent tuning configuration.
  *
  * Priority (highest wins): project config → global config → defaults.
  *
@@ -71,18 +71,18 @@ function readConfigFile(filePath) {
  *
  * Invalid JSON in either file is silently ignored and treated as absent.
  */
-export function loadLearningTuningConfig(ledgerRoot) {
+export function loadCurateTuningConfig(ledgerRoot) {
     const globalConfigPath = path.join(getDevFlowDirectory(), 'learning.json');
-    const projectConfigPath = getLearningTuningConfigPath(ledgerRoot);
+    const projectConfigPath = getCurateTuningConfigPath(ledgerRoot);
     let config = { ...DEFAULTS };
     const globalJson = readConfigFile(globalConfigPath);
     if (globalJson !== null) {
-        config = applyLearningTuningConfigLayer(config, globalJson);
+        config = applyCurateTuningConfigLayer(config, globalJson);
     }
     const projectJson = readConfigFile(projectConfigPath);
     if (projectJson !== null) {
-        config = applyLearningTuningConfigLayer(config, projectJson);
+        config = applyCurateTuningConfigLayer(config, projectJson);
     }
     return config;
 }
-//# sourceMappingURL=learning-tuning-config.js.map
+//# sourceMappingURL=curate-tuning-config.js.map

package/dist/core/learning-queue-cleanup.js

@@ -11,7 +11,7 @@ import { drainQueueFiles } from './queue-drain.js';
 /**
  * Drain the learning (decisions-detection) pending-turns queue, its claimed
  * batch and the claim's owner file so stale turns don't process later — used by
- * both `--clear` and `--disable`. A mid-run Learning agent whose claimed batch
+ * both `--clear` and `--disable`. A mid-run Curate agent whose claimed batch
  * vanishes aborts without changes, which is the desired outcome in both cases.
  * Refused, deleting nothing, when `.devflow` or `.devflow/learning` under `gitRoot`
  * is a symbolic link (D-CLI-NO-SYMLINK). ENOENT-tolerant; other errors propagate.

package/dist/core/migrations.js

@@ -14,6 +14,55 @@ import { writeFileAtomicExclusive } from './fs-atomic.js';
 import { getMemoryDir } from './project-paths.js';
 import { LEGACY_AGENT_KEYS, canonicaliseAgentKeys, parseAgentMappingEnvelope } from './agent-models.js';
 import { migrateLegacyTrackerConventions } from './tracker.js';
+/**
+ * The body of every canonicalise-agent-keys-vN migration: read agent-models.json raw,
+ * apply LEGACY_AGENT_KEYS once, and write the result back atomically when a key changed.
+ * Each migration id passes its own id so that its warnings name it. Idempotent, and a
+ * file with no legacy key is left untouched.
+ */
+function canonicaliseAgentKeysRun(migrationId) {
+    return async (ctx) => {
+        const infos = [];
+        const warnings = [];
+        // Fast path: no legacy keys defined — skip without touching the file.
+        if (Object.keys(LEGACY_AGENT_KEYS).length === 0)
+            return { infos, warnings };
+        const filePath = path.join(ctx.devflowDir, 'agent-models.json');
+        // parseAgentMappingEnvelope handles IO, BOM-strip, JSON parse, and shape validation.
+        // Raw read intentionally avoids readAgentMapping (which would drop unknown fields).
+        const envelope = await parseAgentMappingEnvelope(filePath);
+        if (envelope.kind === 'skip')
+            return { infos, warnings };
+        if (envelope.kind === 'warn') {
+            warnings.push(`${migrationId}: ${envelope.message}`);
+            return { infos, warnings };
+        }
+        const onWarning = (msg) => warnings.push(msg);
+        const { agents: migrated, didMutate, renamed, dropped, guardDropped } = canonicaliseAgentKeys(envelope.rawAgents, onWarning);
+        if (!didMutate)
+            return { infos, warnings };
+        // Write back with the canonical keys, preserving the rest of the envelope.
+        // Idempotent under concurrent execution (no lock needed; see D31 comment above).
+        const updated = { ...envelope.envelope, agents: migrated };
+        try {
+            await writeFileAtomicExclusive(filePath, JSON.stringify(updated, null, 2) + '\n');
+        }
+        catch (err) {
+            warnings.push(`${migrationId}: failed to write ${filePath}: ${err.message}`);
+            return { infos, warnings };
+        }
+        if (renamed.length > 0) {
+            infos.push(`Migrated agent-models.json: renamed ${renamed.map(k => `'${k}' → '${LEGACY_AGENT_KEYS[k]}'`).join(', ')}`);
+        }
+        if (dropped.length > 0) {
+            warnings.push(`${migrationId}: dropped legacy key(s) ${dropped.map(k => `'${k}'`).join(', ')} — the replacement key already holds a value, existing value kept`);
+        }
+        if (guardDropped.length > 0) {
+            warnings.push(`${migrationId}: dropped legacy key(s) ${guardDropped.map(k => `'${k}'`).join(', ')} — skipped due to prototype-pollution guard`);
+        }
+        return { infos, warnings };
+    };
+}
 /**
  * D31: Registry pattern over scattered `if (!applied.includes(...))` conditionals.
  *
@@ -33,9 +82,9 @@ import { migrateLegacyTrackerConventions } from './tracker.js';
  * This was acceptable with an empty MIGRATIONS registry (D37: the vacuous-truth
  * case); this registry's first real entry is added below. Fix deferred.
  *
- * Note how that interacts with `canonicalise-agent-keys-v1`: runGlobalMigration
- * marks a migration applied for ANY non-throwing return, and that entry never
- * throws — it catches every I/O and parse failure and returns it as a *warning*.
+ * Note how that interacts with the `canonicalise-agent-keys-vN` entries: runGlobalMigration
+ * marks a migration applied for ANY non-throwing return, and those entries never
+ * throw — it catches every I/O and parse failure and returns it as a *warning*.
  * So it does NOT hit the unbounded-retry path. It hits the opposite one: a
  * transient EACCES or a failed write records the migration as applied and it
  * never runs again, leaving legacy keys on disk permanently.
@@ -52,47 +101,17 @@ export const MIGRATIONS = [
         id: 'canonicalise-agent-keys-v1',
         description: 'Rename legacy agent keys in ~/.devflow/agent-models.json to their canonical names',
         scope: 'global',
-        async run(ctx) {
-            const infos = [];
-            const warnings = [];
-            // Fast path: no legacy keys defined — skip without touching the file.
-            if (Object.keys(LEGACY_AGENT_KEYS).length === 0)
-                return { infos, warnings };
-            const filePath = path.join(ctx.devflowDir, 'agent-models.json');
-            // parseAgentMappingEnvelope handles IO, BOM-strip, JSON parse, and shape validation.
-            // Raw read intentionally avoids readAgentMapping (which would drop unknown fields).
-            const envelope = await parseAgentMappingEnvelope(filePath);
-            if (envelope.kind === 'skip')
-                return { infos, warnings };
-            if (envelope.kind === 'warn') {
-                warnings.push(`canonicalise-agent-keys-v1: ${envelope.message}`);
-                return { infos, warnings };
-            }
-            const onWarning = (msg) => warnings.push(msg);
-            const { agents: migrated, didMutate, renamed, dropped, guardDropped } = canonicaliseAgentKeys(envelope.rawAgents, onWarning);
-            if (!didMutate)
-                return { infos, warnings };
-            // Write back with the canonical keys, preserving the rest of the envelope.
-            // Idempotent under concurrent execution (no lock needed; see D31 comment above).
-            const updated = { ...envelope.envelope, agents: migrated };
-            try {
-                await writeFileAtomicExclusive(filePath, JSON.stringify(updated, null, 2) + '\n');
-            }
-            catch (err) {
-                warnings.push(`canonicalise-agent-keys-v1: failed to write ${filePath}: ${err.message}`);
-                return { infos, warnings };
-            }
-            if (renamed.length > 0) {
-                infos.push(`Migrated agent-models.json: renamed ${renamed.map(k => `'${k}' → '${LEGACY_AGENT_KEYS[k]}'`).join(', ')}`);
-            }
-            if (dropped.length > 0) {
-                warnings.push(`canonicalise-agent-keys-v1: dropped legacy key(s) ${dropped.map(k => `'${k}'`).join(', ')} — canonical key already present, existing value kept`);
-            }
-            if (guardDropped.length > 0) {
-                warnings.push(`canonicalise-agent-keys-v1: dropped legacy key(s) ${guardDropped.map(k => `'${k}'`).join(', ')} — skipped due to prototype-pollution guard`);
-            }
-            return { infos, warnings };
-        },
+        run: canonicaliseAgentKeysRun('canonicalise-agent-keys-v1'),
+    },
+    {
+        // v1 is already recorded as applied on every machine that upgraded through 2.x, so the
+        // six-agent rename needs an id of its own. Both ids run the same body. On a 1.x machine
+        // v1 runs first and, with the single-hop LEGACY_AGENT_KEYS, already lands every key on its
+        // final slug, so v2 finds nothing to rewrite and makes no write.
+        id: 'canonicalise-agent-keys-v2',
+        description: 'Rename the keys of the six renamed agents in ~/.devflow/agent-models.json to their new names',
+        scope: 'global',
+        run: canonicaliseAgentKeysRun('canonicalise-agent-keys-v2'),
     },
     {
         id: 'tracker-conventions-per-provider-v1',