devflow-kit 3.5.0 → 3.7.0

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

package/dist/cli.js

@@ -21,6 +21,7 @@ import { agentsCommand } from './cli/commands/agents.js';
 import { complianceCommand } from './cli/commands/compliance.js';
 import { behaviorCommand } from './cli/commands/behavior.js';
 import { trackerCommand } from './cli/commands/tracker.js';
+import { gatesCommand } from './cli/commands/gates.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 // Read version from package.json
@@ -51,6 +52,7 @@ program.addCommand(agentsCommand);
 program.addCommand(complianceCommand);
 program.addCommand(behaviorCommand);
 program.addCommand(trackerCommand);
+program.addCommand(gatesCommand);
 // Handle no command (bare `devflow`) or unknown subcommand.
 // When Commander sees an unrecognised first argument it does not route to any
 // registered subcommand; instead the root action fires with that argument

package/dist/commands/bug-analysis.md

@@ -187,27 +187,27 @@ If no tool produced findings: set `STATIC_FINDINGS` to `(none)`.
 node "$HOME/.devflow/scripts/resolve-settings.cjs" "{root}" 2>/dev/null; echo "exit=$?"
 ```
 
-Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `TRACKER=<github|jira|linear> TRACKER_SOURCE=<project|personal|machine|default> TRACKER_WARN=<none|mismatch|invalid> SITE=<none|https://<host>> KEY=<none|<key>> REVIEW_PUBLICATION=<off|auto|full> COMPLIANCE=<off|generic|<id>[,<id>…]> MEMORY=<on|off> LEARNING=<on|off> KNOWLEDGE=<on|off>` — these fields, in this order, nothing else, where `<host>` is a lowercase dotted host name alone, `<key>` is 2–10 of `A-Z`, `0-9` and `_` starting with a letter, and each `<id>` is one of `gdpr`, `hipaa`, `pci-dss`, `soc2`, `iso-27001`, `sox`. **Anything else** (a non-zero exit, no line, extra text, or a missing, reordered or unlisted field or value) ⇒ use `TRACKER=github TRACKER_SOURCE=default TRACKER_WARN=invalid SITE=none KEY=none REVIEW_PUBLICATION=off COMPLIANCE=generic MEMORY=on LEARNING=on KNOWLEDGE=off` instead.
+Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `TRACKER=<github|jira|linear> TRACKER_SOURCE=<project|personal|machine|default> TRACKER_WARN=<none|mismatch|invalid> SITE=<none|https://<host>> KEY=<none|<key>> REVIEW_PUBLICATION=<off|auto|full> COMPLIANCE=<off|generic|<id>[,<id>…]> MEMORY=<on|off> LEARNING=<on|off> KNOWLEDGE=<on|off> GATE_LEVEL=<full|standard|lean>` — these fields, in this order, nothing else, where `<host>` is a lowercase dotted host name alone, `<key>` is 2–10 of `A-Z`, `0-9` and `_` starting with a letter, and each `<id>` is one of `gdpr`, `hipaa`, `pci-dss`, `soc2`, `iso-27001`, `sox`. **Anything else** (a non-zero exit, no line, extra text, or a missing, reordered or unlisted field or value) ⇒ use `TRACKER=github TRACKER_SOURCE=default TRACKER_WARN=invalid SITE=none KEY=none REVIEW_PUBLICATION=off COMPLIANCE=generic MEMORY=on LEARNING=on KNOWLEDGE=off GATE_LEVEL=full` instead.
 
-The accepted line is the only source of these values: the script alone folds the committed `.devflow/project.json`, the personal `.devflow/config.json` and the machine manifest.
+The accepted line is the only source of these values.
 
 ### Load DECISIONS_CONTEXT
 
 When the settings line says `LEARNING=off`, set `DECISIONS_CONTEXT` to `(none)` and skip this step, locating no ledger and reading no index.
 
-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:**
 
@@ -216,11 +216,15 @@ 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.
+
+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.
 
 #### Feature Knowledge
 
@@ -246,7 +250,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:**
 
@@ -277,7 +281,7 @@ 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.**
 
 #### Plan Artifact
 
@@ -306,11 +310,11 @@ Determine which focus analyzers to run using `CHANGED_FILES` (already computed i
 **Produces:** ANALYZER_OUTPUTS
 **Requires:** DIFF_RANGE, ANALYSIS_DIR, ACTIVE_FOCUSES, STATIC_FINDINGS, ACCEPTANCE_RULES, PLAN_CONTEXT, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE
 
-Spawn ALL active Diagnose agents **in a single message** (parallel, NOT background):
+Spawn ALL active Debug agents **in a single message** (parallel, NOT background):
 
 For each active focus, spawn:
 ```
-Agent(subagent_type="Diagnose", run_in_background=false):
+Agent(subagent_type="Debug", run_in_background=false):
 "Analyze focusing on {focus}.
 FOCUS: {focus}
 DIFF_COMMAND: git diff {DIFF_RANGE}
@@ -408,10 +412,10 @@ Run `/resolve` to process and fix these findings.
 │  └─ Detect active focuses (security + functional always; integration + usability conditional)
 │
 ├─ Phase 5: Bug Analysis (PARALLEL)
-│  ├─ Diagnose agent: security (+ STATIC_FINDINGS)
-│  ├─ Diagnose agent: functional
-│  ├─ Diagnose agent: integration (conditional)
-│  └─ Diagnose agent: usability (conditional)
+│  ├─ Debug agent: security (+ STATIC_FINDINGS)
+│  ├─ Debug agent: functional
+│  ├─ Debug agent: integration (conditional)
+│  └─ Debug agent: usability (conditional)
 │
 ├─ Phase 6: Synthesis
 │  └─ Synthesize agent (mode: bug-analysis)
@@ -448,7 +452,7 @@ Run `/resolve` after `/bug-analysis` to fix identified bugs. `/resolve` automati
 2. **Parallel, not background** — Analyzers spawn in one message with `run_in_background=false`
 3. **Static + semantic** — Two complementary tracks, each validates the other
 4. **Incremental by default** — Only analyze new changes unless `--full` specified
-5. **Verify before reporting** — Diagnose agents self-verify every finding
+5. **Verify before reporting** — Debug agents self-verify every finding
 6. **Honest reporting** — Display risk level and counts directly from synthesis
 
 ## Phase Completion Checklist