devflow-kit 2.4.0 → 2.5.0

package/dist/core/model-discovery.js

@@ -552,7 +552,18 @@ async function _discoverInternal(cacheDir, logPath, deps) {
     // completes during the spawn's SPAWN_TIMEOUT_MS window).
     const staleRawP = findStaleFallback(cacheDir, currentKey);
     // --- Live spawn ---
-    const env = { ...scrubChildEnv(), NO_COLOR: '1' };
+    // @D-EFR-6 Discovery reads the runtime's built-in registry, never a user config.
+    //   Since 0.5.0 every implicit config load merges the runtime's user-level file
+    //   ($XDG_CONFIG_HOME/subswitch/config.json, else ~/.config/subswitch/config.json)
+    //   under the cwd project file. Devflow's relay never sees that file — it is always
+    //   started with an explicit SUBSWITCH_CONFIG, which bypasses the merge — so a user
+    //   alias leaking into discovery would be offered in the picker yet never routed,
+    //   and a malformed file would fail every live discovery. The cache key also
+    //   assumes the catalog depends on the runtime version alone. Pointing
+    //   XDG_CONFIG_HOME at devflow's own cache directory, which never holds a
+    //   `subswitch/config.json`, makes the lookup a clean ENOENT. SUBSWITCH_CONFIG
+    //   stays unset (T2): an explicit path that is missing is a hard error.
+    const env = { ...scrubChildEnv(), NO_COLOR: '1', XDG_CONFIG_HOME: cacheDir };
     const spawnFn = deps?.spawnAndCollect ?? buildRealSpawnAndCollect(logPath);
     let spawnResult;
     try {

package/dist/core/plugins.js

@@ -29,8 +29,41 @@ export const DEVFLOW_PLUGINS = [
         name: 'devflow-core-skills',
         description: 'Auto-activating quality enforcement skills - foundation layer for all Devflow plugins',
         commands: [],
-        agents: ['learning'],
+        /**
+         * Hook-spawned agents live here, and `commands: []` above is why that works.
+         *
+         * Guard 5 reverse (registry-integrity.test.ts, "declared agents are spawned")
+         * skips a plugin whose commands spawn nothing — `if (spawned.size === 0)
+         * continue` — and this plugin ships no commands at all. So `learning` and
+         * `tracker`, which are spawned by a SessionStart directive rather than by any
+         * command, satisfy the reverse check STRUCTURALLY.
+         *
+         * Recorded because the alternative looks equivalent and is not: adding either
+         * name to an exemption list would make the guard pass by being told to ignore
+         * them, which is the vacuous-guard trap this repo polices everywhere else. If
+         * this plugin ever gains a command, the right fix is a new commands-less
+         * plugin for the hook-spawned agents — never an exemption.
+         *
+         * Neither agent may gain a `_roster.mds` row: that file is asserted
+         * set-equal, both directions, against the `agentType` values present in
+         * dist/commands/, and a hook-spawned agent appears in none of them.
+         */
+        agents: ['learning', 'tracker'],
         skills: ['apply-decisions', 'apply-feature-knowledge', 'software-design', 'docs-framework', 'git', 'boundary-validation', 'test-driven-development', 'testing', 'dependency-research'],
+        requires: [
+            'architecture',
+            'complexity',
+            'consistency',
+            'database',
+            'dependencies',
+            'documentation',
+            'performance',
+            'regression',
+            'reliability',
+            'review-methodology',
+            'security',
+            'worktree-support',
+        ],
         rules: ['security', 'engineering', 'quality', 'reliability'],
     },
     {
@@ -39,6 +72,25 @@ export const DEVFLOW_PLUGINS = [
         commands: ['/plan'],
         agents: ['git', 'skim', 'synthesize', 'design'],
         skills: ['gap-analysis', 'design-review', 'patterns', 'worktree-support', 'feature-knowledge', 'apply-feature-knowledge'],
+        requires: [
+            'apply-decisions',
+            'architecture',
+            'complexity',
+            'consistency',
+            'database',
+            'dependencies',
+            'docs-framework',
+            'documentation',
+            'git',
+            'performance',
+            'regression',
+            'reliability',
+            'review-methodology',
+            'security',
+            'software-design',
+            'test-driven-development',
+            'testing',
+        ],
         rules: [],
     },
     {
@@ -47,6 +99,26 @@ export const DEVFLOW_PLUGINS = [
         commands: ['/implement'],
         agents: ['git', 'code', 'simplify', 'scrutinize', 'evaluate', 'test', 'validate', 'knowledge'],
         skills: ['patterns', 'qa', 'quality-gates', 'worktree-support', 'feature-knowledge', 'apply-feature-knowledge'],
+        requires: [
+            'apply-decisions',
+            'architecture',
+            'boundary-validation',
+            'complexity',
+            'consistency',
+            'database',
+            'dependencies',
+            'dependency-research',
+            'documentation',
+            'git',
+            'performance',
+            'regression',
+            'reliability',
+            'review-methodology',
+            'security',
+            'software-design',
+            'test-driven-development',
+            'testing',
+        ],
         rules: [],
     },
     {
@@ -55,14 +127,34 @@ export const DEVFLOW_PLUGINS = [
         commands: ['/code-review'],
         agents: ['git', 'review', 'synthesize'],
         skills: ['architecture', 'complexity', 'consistency', 'database', 'dependencies', 'documentation', 'performance', 'regression', 'reliability', 'review-methodology', 'security', 'testing', 'worktree-support', 'apply-feature-knowledge'],
+        requires: ['apply-decisions', 'docs-framework', 'git', 'quality-gates', 'software-design'],
         rules: [],
     },
     {
         name: 'devflow-resolve',
         description: 'Process and fix code review issues with blast-radius triage, Code agent fixes, and Validate agent verification',
         commands: ['/resolve'],
-        agents: ['git', 'triage', 'code', 'simplify', 'validate', 'knowledge'],
+        agents: ['git', 'triage', 'code', 'simplify', 'validate', 'test', 'knowledge'],
         skills: ['patterns', 'security', 'worktree-support', 'feature-knowledge', 'apply-feature-knowledge', 'apply-decisions'],
+        requires: [
+            'architecture',
+            'boundary-validation',
+            'complexity',
+            'consistency',
+            'database',
+            'dependencies',
+            'dependency-research',
+            'documentation',
+            'git',
+            'performance',
+            'qa',
+            'regression',
+            'reliability',
+            'review-methodology',
+            'software-design',
+            'test-driven-development',
+            'testing',
+        ],
         rules: [],
     },
     {
@@ -71,6 +163,25 @@ export const DEVFLOW_PLUGINS = [
         commands: ['/debug'],
         agents: ['git', 'synthesize', 'simplify', 'knowledge'],
         skills: ['git', 'worktree-support', 'feature-knowledge', 'apply-feature-knowledge'],
+        requires: [
+            'apply-decisions',
+            'architecture',
+            'complexity',
+            'consistency',
+            'database',
+            'dependencies',
+            'docs-framework',
+            'documentation',
+            'patterns',
+            'performance',
+            'regression',
+            'reliability',
+            'review-methodology',
+            'security',
+            'software-design',
+            'test-driven-development',
+            'testing',
+        ],
         rules: [],
     },
     {
@@ -79,6 +190,22 @@ export const DEVFLOW_PLUGINS = [
         commands: ['/explore'],
         agents: ['skim', 'synthesize', 'knowledge'],
         skills: ['worktree-support', 'apply-feature-knowledge', 'feature-knowledge'],
+        requires: [
+            'apply-decisions',
+            'architecture',
+            'complexity',
+            'consistency',
+            'database',
+            'dependencies',
+            'docs-framework',
+            'documentation',
+            'performance',
+            'regression',
+            'reliability',
+            'review-methodology',
+            'security',
+            'testing',
+        ],
         rules: [],
     },
     {
@@ -87,6 +214,22 @@ export const DEVFLOW_PLUGINS = [
         commands: ['/research'],
         agents: ['research', 'skim', 'synthesize', 'knowledge'],
         skills: ['worktree-support', 'apply-feature-knowledge', 'feature-knowledge', 'research-codebase', 'research-external', 'research-market', 'research-competitor', 'research-technology'],
+        requires: [
+            'apply-decisions',
+            'architecture',
+            'complexity',
+            'consistency',
+            'database',
+            'dependencies',
+            'docs-framework',
+            'documentation',
+            'performance',
+            'regression',
+            'reliability',
+            'review-methodology',
+            'security',
+            'testing',
+        ],
         rules: [],
     },
     {
@@ -95,6 +238,7 @@ export const DEVFLOW_PLUGINS = [
         commands: ['/release'],
         agents: ['git', 'validate'],
         skills: ['git', 'worktree-support'],
+        requires: ['testing'],
         rules: [],
     },
     {
@@ -103,6 +247,7 @@ export const DEVFLOW_PLUGINS = [
         commands: ['/self-review'],
         agents: ['simplify', 'scrutinize', 'validate', 'knowledge'],
         skills: ['quality-gates', 'software-design', 'worktree-support', 'feature-knowledge', 'apply-feature-knowledge'],
+        requires: ['apply-decisions', 'testing'],
         rules: [],
     },
     {
@@ -120,6 +265,17 @@ export const DEVFLOW_PLUGINS = [
             'security',
             'worktree-support',
         ],
+        requires: [
+            'architecture',
+            'database',
+            'dependencies',
+            'docs-framework',
+            'documentation',
+            'git',
+            'performance',
+            'review-methodology',
+            'testing',
+        ],
         rules: [],
     },
     {
@@ -148,6 +304,21 @@ export const DEVFLOW_PLUGINS = [
             'feature-knowledge',
             'apply-feature-knowledge',
         ],
+        requires: [
+            'apply-decisions',
+            'boundary-validation',
+            'dependency-research',
+            'docs-framework',
+            'git',
+            'quality-gates',
+            'research-codebase',
+            'research-competitor',
+            'research-external',
+            'research-market',
+            'research-technology',
+            'software-design',
+            'test-driven-development',
+        ],
         rules: [],
     },
     {
@@ -157,6 +328,31 @@ export const DEVFLOW_PLUGINS = [
         commands: ['/dynamic-tickets', '/dynamic-plan', '/dynamic-build', '/dynamic-profile'],
         agents: ['code', 'validate', 'simplify', 'scrutinize', 'evaluate', 'test', 'review', 'git', 'synthesize', 'knowledge', 'design'],
         skills: ['apply-decisions', 'apply-feature-knowledge', 'worktree-support', 'docs-framework'],
+        requires: [
+            'architecture',
+            'boundary-validation',
+            'complexity',
+            'consistency',
+            'database',
+            'dependencies',
+            'dependency-research',
+            'design-review',
+            'documentation',
+            'feature-knowledge',
+            'gap-analysis',
+            'git',
+            'patterns',
+            'performance',
+            'qa',
+            'quality-gates',
+            'regression',
+            'reliability',
+            'review-methodology',
+            'security',
+            'software-design',
+            'test-driven-development',
+            'testing',
+        ],
         optional: true,
         rules: [],
     },
@@ -166,6 +362,7 @@ export const DEVFLOW_PLUGINS = [
         commands: [],
         agents: [],
         skills: ['typescript'],
+        requires: [],
         optional: true,
         rules: ['typescript'],
     },
@@ -175,6 +372,7 @@ export const DEVFLOW_PLUGINS = [
         commands: [],
         agents: [],
         skills: ['react'],
+        requires: [],
         optional: true,
         rules: ['react'],
     },
@@ -184,6 +382,7 @@ export const DEVFLOW_PLUGINS = [
         commands: [],
         agents: [],
         skills: ['accessibility'],
+        requires: [],
         optional: true,
         rules: ['accessibility'],
     },
@@ -193,6 +392,7 @@ export const DEVFLOW_PLUGINS = [
         commands: [],
         agents: [],
         skills: ['ui-design'],
+        requires: [],
         optional: true,
         rules: ['ui-design'],
     },
@@ -202,6 +402,7 @@ export const DEVFLOW_PLUGINS = [
         commands: [],
         agents: [],
         skills: ['go'],
+        requires: [],
         optional: true,
         rules: ['go'],
     },
@@ -211,6 +412,7 @@ export const DEVFLOW_PLUGINS = [
         commands: [],
         agents: [],
         skills: ['java'],
+        requires: [],
         optional: true,
         rules: ['java'],
     },
@@ -220,6 +422,7 @@ export const DEVFLOW_PLUGINS = [
         commands: [],
         agents: [],
         skills: ['python'],
+        requires: [],
         optional: true,
         rules: ['python'],
     },
@@ -229,6 +432,7 @@ export const DEVFLOW_PLUGINS = [
         commands: [],
         agents: [],
         skills: ['rust'],
+        requires: [],
         optional: true,
         rules: ['rust'],
     },
@@ -280,6 +484,59 @@ export const FEATURE_OWNED_SKILLS = ['compliance'];
  * (guarded by plugins.test.ts FEATURE_OWNED constants describe block).
  */
 export const FEATURE_OWNED_RULES = ['compliance'];
+// ── Skill-closure boundaries ──────────────────────────────────────────────────
+/**
+ * Skills that are REFERENCED but never REQUIRED — the presence-gated set.
+ *
+ * D-PRESENCE-GATED: every language/ecosystem skill ships with an optional,
+ * command-less plugin, so a reference to one is a reference to something the
+ * user may deliberately not have. The referencing prompts are written to probe
+ * first and proceed without it — `/code-review` checks
+ * `~/.claude/skills/devflow:{focus}/SKILL.md` before spawning that focus, the
+ * Review and Code agents continue when the Skill invocation fails. Putting them
+ * in a `requires` would reinstate the universal install for exactly the eight
+ * skills the selection prompt exists to let a user decline (AC-25).
+ *
+ * DERIVED from the registry rather than hand-listed: a ninth language plugin is
+ * presence-gated by being declared, with no second roster to remember. Guarded
+ * against its own definition in tests/guards/requires-closure.test.ts.
+ */
+export const PRESENCE_GATED_SKILLS = [
+    ...new Set(DEVFLOW_PLUGINS
+        .filter(plugin => plugin.optional === true && plugin.commands.length === 0)
+        .flatMap(plugin => plugin.skills)),
+];
+/**
+ * The classified exception to the closure guard — declared HERE, at the
+ * declaration site of the field it exempts, and imported by the guard.
+ *
+ * D-TEMPLATE-EXCEPTION (applies PF-067: one authority for a prohibition and its
+ * exemptions). Every other templated reference in the corpus carries a literal
+ * prefix and resolves through it — `devflow:research-{RESEARCH_TYPE}` resolves
+ * because five in-scope skills start with `research-`. The Review focus skill is
+ * the one reference with NO literal prefix: the whole skill name is substituted
+ * at spawn time, and the substitution set spans the presence-gated language
+ * skills, so there is nothing a scan or a `requires` entry could resolve it to.
+ *
+ * Two spellings, one exception: the command writes the placeholder it passes and
+ * the agent writes the placeholder it receives.
+ *
+ * An entry here is NOT permission to stop thinking about the reference — the
+ * guard asserts each literal still occurs in the corpus, so an exemption that
+ * outlives its site fails rather than rotting.
+ */
+export const TEMPLATE_SKILL_REFS = [
+    {
+        literal: 'devflow:{focus}',
+        site: 'dist/commands/code-review.md (Review agent spawn prompt)',
+        why: 'the whole skill name is substituted per focus; the substitution set includes presence-gated language skills',
+    },
+    {
+        literal: 'devflow:{FOCUS}',
+        site: 'src/assets/agents/review.md (the Review agent loading its own focus skill)',
+        why: 'receiving half of the same substitution — the agent is told which focus it is, not which skill exists',
+    },
+];
 // ── Feature redirect ──────────────────────────────────────────────────────────
 /**
  * Plugin names (and aliases) that have been converted to built-in features.
@@ -405,21 +662,112 @@ export function buildAssetMaps(plugins) {
     return { skillsMap, agentsMap };
 }
 /**
- * Build a skills map from ALL plugins (regardless of selection).
- * Skills are tiny markdown files — always install all of them so commands
- * (review, resolve) can spawn agents that depend on skills from other plugins.
+ * The install closure of a plugin selection: everything those plugins own plus
+ * everything they use.
+ *
+ * ONE spelling of `skills ∪ requires`, because every consumer that spells it
+ * inline is a place the two halves can be forgotten apart: the installer's
+ * install set, its removal set, the skills-list scope and the closure guard all
+ * read this. Pure, order-independent, no I/O.
  */
-export function buildFullSkillsMap() {
+export function skillsOf(plugins) {
+    const skills = new Set();
+    for (const plugin of plugins) {
+        for (const skill of plugin.skills)
+            skills.add(skill);
+        for (const skill of plugin.requires)
+            skills.add(skill);
+    }
+    return skills;
+}
+/**
+ * Every plugin that OWNS a skill, in registry order.
+ *
+ * D-ALL-OWNERS: returns all declarers, not the first — `devflow skills list`'s
+ * owner column becomes a lie the moment install is scoped, because the answer a
+ * user needs from it is "which plugin do I select to keep this?", and a
+ * first-wins answer names one plugin out of several that would each do. Empty
+ * for a skill no plugin owns, which for a registry-valid name cannot happen:
+ * a `requires` entry is guarded to be a known skill, and a known skill is one
+ * some plugin declares.
+ */
+export function skillOwners(name) {
+    return DEVFLOW_PLUGINS.filter(plugin => plugin.skills.includes(name)).map(plugin => plugin.name);
+}
+/**
+ * Build the skill → source-plugin map for a SELECTION.
+ *
+ * The key set is the selection's closure ({@link skillsOf}); the value is the
+ * plugin the skill is copied on behalf of. A skill the selection only REQUIRES
+ * has no owner among the selected plugins, so its owner is resolved from the
+ * full registry ({@link skillOwners}) — the map's value is a provenance label,
+ * and labelling a required skill with the plugin that happens to need it would
+ * misattribute ownership.
+ */
+export function buildScopedSkillsMap(plugins) {
     const skillsMap = new Map();
-    for (const plugin of DEVFLOW_PLUGINS) {
+    for (const plugin of plugins) {
         for (const skill of plugin.skills) {
-            if (!skillsMap.has(skill)) {
+            if (!skillsMap.has(skill))
                 skillsMap.set(skill, plugin.name);
-            }
         }
     }
+    for (const skill of skillsOf(plugins)) {
+        if (skillsMap.has(skill))
+            continue;
+        const owner = skillOwners(skill)[0];
+        if (owner !== undefined)
+            skillsMap.set(skill, owner);
+    }
     return skillsMap;
 }
+/**
+ * Build a skills map over the WHOLE registry.
+ *
+ * The scoped map applied to every plugin: `skills ∪ requires` across the full
+ * registry is `skills` across the full registry, since a `requires` entry is
+ * always some plugin's owned skill. Retained for the consumers that legitimately
+ * want every skill regardless of selection — uninstall's removal manifest and
+ * `devflow skills list`'s catalogue.
+ */
+export function buildFullSkillsMap() {
+    return buildScopedSkillsMap(DEVFLOW_PLUGINS);
+}
+/**
+ * Decide the skill install/remove/dormant sets for one run — pure, no fs.
+ *
+ * H4: extracted so the decision is unit-testable without a temp tree, and so
+ * `installViaFileCopy` consumes a decision rather than growing a fourth set of
+ * inline set-arithmetic.
+ *
+ * The removal set is GATED on a full install. A `--plugin=X` run is a request to
+ * add X, not a statement that X is the whole selection, so it may never remove
+ * what another plugin contributed (AC-22). {@link FEATURE_OWNED_SKILLS} is
+ * subtracted unconditionally: those install and uninstall with their feature,
+ * and sweeping them here would delete an artifact this code does not own
+ * (applies ADR-024).
+ *
+ * A shadow is NEVER removed, whatever the selection — `~/.devflow/skills/` is
+ * user content. One that falls outside the install set simply applies to
+ * nothing, and is reported so the user can tell "inert" from "ignored".
+ */
+export function resolveSkillInstallPlan(input) {
+    const install = skillsOf(input.effectivePlugins);
+    const remove = new Set();
+    if (!input.isPartialInstall) {
+        for (const skill of skillsOf(DEVFLOW_PLUGINS)) {
+            if (install.has(skill))
+                continue;
+            if (FEATURE_OWNED_SKILLS.includes(skill))
+                continue;
+            remove.add(skill);
+        }
+    }
+    const dormantShadows = [...new Set(input.shadowedSkills)]
+        .filter(skill => !install.has(skill))
+        .sort();
+    return { install, remove, dormantShadows };
+}
 /**
  * Derive unique rule names from all plugins.
  */

package/dist/core/project-paths.js

@@ -35,7 +35,7 @@ export function getDocsDir(projectRoot) {
 // ---------------------------------------------------------------------------
 // Feature config (neutral .devflow root — not inside learning/)
 // ---------------------------------------------------------------------------
-/** .devflow/config.json — feature toggles {memory, learning, knowledge} */
+/** .devflow/config.json — per-repo facts {reviewPublication, tracker override} */
 export function getFeatureConfigPath(projectRoot) {
     return path.join(projectRoot, '.devflow', 'config.json');
 }

package/dist/core/proxy-log.js

@@ -28,12 +28,14 @@ export const PROXY_LOG_TAIL_BYTES = 1_048_576;
  * Call sites compose on top of this result to add process-specific vars
  * (e.g. SUBSWITCH_CONFIG for the relay spawn and doctor spawn).
  *
- * applies ADR-003: the prior denylist rationale is gone — the routing runtime
- * reads exactly four env vars (ANTHROPIC_API_KEY, FORCE_COLOR, NO_COLOR,
- * SUBSWITCH_CONFIG — NO_COLOR read in dist/tty.js with presence semantics; CI is
- * read only by the `init` subcommand which devflow never invokes).
- * Verified by whole-dist grep of the 0.4.0 package. An allowlist is the correct
- * shape: 61 inherited vars → 6.
+ * applies ADR-003: the prior denylist rationale is gone — on the paths devflow
+ * invokes (serve, doctor, models) the routing runtime reads ANTHROPIC_API_KEY,
+ * FORCE_COLOR, NO_COLOR (dist/tty.js, presence semantics), SUBSWITCH_CONFIG and
+ * XDG_CONFIG_HOME (user-config lookup, reached only on an implicit config load —
+ * see D-EFR-6 in model-discovery.ts). CI is read only by `init`; CODEX_HOME and
+ * CLAUDE_CONFIG_DIR only by the Codex ingress, `init` and the Codex doctor, none of
+ * which devflow enables or invokes. Verified by whole-dist grep of the 0.5.0
+ * package. An allowlist is the correct shape: 61 inherited vars → 6.
  *
  * HOME is retained: the runtime's loadConfig resolves ~ paths via homedir().
  *

package/dist/core/proxy-state.js

@@ -88,14 +88,17 @@ export async function writeProxyState(devflowDir, state) {
 // Pure helpers
 // ---------------------------------------------------------------------------
 /**
- * Accepted top-level keys for the subswitch 0.4.0 FileConfigSchema (z.strictObject).
- * Unknown top-level keys cause a hard relay startup error — never emit them.
+ * Top-level keys devflow carries into the routing config. Unknown top-level keys
+ * cause a hard relay startup error — never emit them.
  *
- * @D-EFR-4 Subswitch 0.4.0 routing config contract:
- *   FileConfigSchema is a z.strictObject with exactly 5 accepted top-level keys:
- *   port, logLevel, anthropic, providers, limits. Unknown keys cause a hard startup
- *   error — the relay refuses to start. anthropic and limits are themselves
- *   strictObject + prefault({}), so they may be partially specified.
+ * @D-EFR-4 Subswitch 0.5.0 routing config contract:
+ *   FileConfigSchema is a z.strictObject with exactly 6 accepted top-level keys:
+ *   port, logLevel, anthropic, providers, limits, codexIngress. Unknown keys cause a
+ *   hard startup error — the relay refuses to start. anthropic and limits are
+ *   themselves strictObject + prefault({}), so they may be partially specified.
+ *   codexIngress is accepted by the relay but deliberately NOT carried: devflow's
+ *   relay serves Claude Code only, and the ingress block would make it accept native
+ *   Codex traffic and hold Claude credentials on devflow's behalf.
  */
 const ROUTING_CONFIG_ALLOWED_TOP_KEYS = new Set([
     'port', 'logLevel', 'anthropic', 'providers', 'limits',
@@ -163,7 +166,7 @@ export function buildRoutingConfigJson(port, existingContent) {
             const parsed = JSON.parse(existingContent);
             if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
                 for (const [k, v] of Object.entries(parsed)) {
-                    // Only preserve the 5 accepted top-level keys; port is always ours.
+                    // Only preserve the carried top-level keys; port is always ours.
                     if (ROUTING_CONFIG_ALLOWED_TOP_KEYS.has(k) && k !== 'port') {
                         preserved[k] = v;
                     }