devflow-kit 3.3.0 → 3.5.0

package/dist/core/plugins.js

@@ -49,7 +49,14 @@ export const DEVFLOW_PLUGINS = [
          * 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'],
+        /**
+         * D-AGENT-REFS: `agent-references` is a reference-only skill. It holds the Synthesize mode
+         * templates and the Learning maintain step, which those two agents read by explicit path, so
+         * it sits here (core-skills is always installed) and no other plugin lists or requires it.
+         * It is never preloaded: tests/guards/agent-references.test.ts holds that, and the one
+         * exception to the repo-wide ban on `disable-model-invocation` names this skill alone.
+         */
+        skills: ['apply-decisions', 'apply-feature-knowledge', 'software-design', 'docs-framework', 'git', 'boundary-validation', 'test-driven-development', 'testing', 'dependency-research', 'agent-references'],
         requires: [
             'architecture',
             'complexity',
@@ -64,34 +71,30 @@ export const DEVFLOW_PLUGINS = [
             'security',
             'worktree-support',
         ],
-        rules: ['security', 'engineering', 'quality', 'reliability'],
+        // D-CONTEXT-ECONOMY-RULE: reading discipline is a core rule, not a skill, because it
+        // must reach every session and every spawned agent without an activation step. It
+        // tells the model to list a large file's headings and read ranges, and to count
+        // search matches before printing them. Its body stays near 400 characters (ceiling
+        // 450) and names no search binary, since the rule is loaded into every session;
+        // tests/rules.test.ts enforces the length, the directives and this registration.
+        rules: ['security', 'engineering', 'quality', 'reliability', 'context-economy'],
     },
     {
         name: 'devflow-plan',
         description: 'Unified design planning with gap analysis and design review',
         commands: ['/plan'],
-        agents: ['git', 'skim', 'synthesize', 'design'],
+        agents: ['git', 'skim', 'synthesize', 'design', 'explore'],
         skills: ['gap-analysis', 'design-review', 'patterns', 'worktree-support', 'feature-knowledge', 'apply-feature-knowledge'],
         // D-CHARTER-BOUNDED-INLINE: /plan's main thread orchestrates and loads no
         // companion skills, so `requires:` lists only skills this plugin's command,
         // agents and skills reference. `software-design` and `test-driven-development`
         // have no reader here; the closure guard's reverse arm rejects an unread entry.
+        // `docs-framework` is read: Phase 14 loads it at the step that names the
+        // design document (D-DOCS-NAMES-AUTHORITY).
         requires: [
             'apply-decisions',
-            'architecture',
-            'complexity',
-            'consistency',
-            'database',
-            'dependencies',
             'docs-framework',
-            'documentation',
             'git',
-            'performance',
-            'regression',
-            'reliability',
-            'review-methodology',
-            'security',
-            'testing',
         ],
         rules: [],
     },
@@ -99,17 +102,15 @@ export const DEVFLOW_PLUGINS = [
         name: 'devflow-implement',
         description: 'Complete task implementation workflow - accepts plan documents, issues, or task descriptions',
         commands: ['/implement'],
-        agents: ['git', 'code', 'simplify', 'scrutinize', 'evaluate', 'test', 'validate', 'knowledge'],
+        agents: ['git', 'code', 'code-fix', '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',
@@ -133,23 +134,21 @@ export const DEVFLOW_PLUGINS = [
         // no companion skills, so `requires:` lists only skills this plugin's command,
         // agents and skills reference. `quality-gates` and `software-design` have no
         // reader here; the closure guard's reverse arm rejects an unread entry.
-        requires: ['apply-decisions', 'docs-framework', 'git'],
+        requires: ['apply-decisions', 'git'],
         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', 'test', 'knowledge'],
-        skills: ['patterns', 'security', 'worktree-support', 'feature-knowledge', 'apply-feature-knowledge', 'apply-decisions'],
+        agents: ['git', 'triage', 'code', 'code-fix', 'simplify', 'validate', 'test', 'knowledge'],
+        skills: ['patterns', 'worktree-support', 'feature-knowledge', 'apply-feature-knowledge', 'apply-decisions'],
         requires: [
             'architecture',
-            'boundary-validation',
             'complexity',
             'consistency',
             'database',
             'dependencies',
-            'dependency-research',
             'documentation',
             'git',
             'performance',
@@ -157,6 +156,7 @@ export const DEVFLOW_PLUGINS = [
             'regression',
             'reliability',
             'review-methodology',
+            'security',
             'software-design',
             'test-driven-development',
             'testing',
@@ -167,8 +167,11 @@ export const DEVFLOW_PLUGINS = [
         name: 'devflow-debug',
         description: 'Debugging workflows with competing hypothesis investigation via parallel subagents',
         commands: ['/debug'],
-        agents: ['git', 'synthesize', 'simplify', 'knowledge'],
+        agents: ['git', 'synthesize', 'simplify', 'knowledge', 'explore', 'code'],
         skills: ['git', 'worktree-support', 'feature-knowledge', 'apply-feature-knowledge'],
+        // D-DEBUG-FIX-VIA-CODE: the fix is a Code spawn. Code loads no skill by language or mode
+        // (D-NO-RUNTIME-SKILLS), so `requires:` lists only the skills this command, its agents and the
+        // skills they preload reference; the closure guard rejects an entry nothing reads.
         requires: [
             'apply-decisions',
             'architecture',
@@ -176,9 +179,7 @@ export const DEVFLOW_PLUGINS = [
             'consistency',
             'database',
             'dependencies',
-            'docs-framework',
             'documentation',
-            'patterns',
             'performance',
             'regression',
             'reliability',
@@ -194,23 +195,12 @@ export const DEVFLOW_PLUGINS = [
         name: 'devflow-explore',
         description: 'Codebase exploration with structured analysis and optional knowledge base creation',
         commands: ['/explore'],
-        agents: ['skim', 'synthesize', 'knowledge'],
+        // 'explore' is devflow's override of Claude Code's built-in Explore agent, spawned by
+        // type name (D-EXPLORE-OVERRIDE and D-EXPLORE-NO-CLOBBER, targets/claude-code/agent-type-owner.ts).
+        agents: ['skim', 'synthesize', 'knowledge', 'explore'],
         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: [],
     },
@@ -220,21 +210,11 @@ 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'],
+        // `docs-framework` is read: Phase 2 loads it at the step that names the
+        // research directory (D-DOCS-NAMES-AUTHORITY).
         requires: [
             'apply-decisions',
-            'architecture',
-            'complexity',
-            'consistency',
-            'database',
-            'dependencies',
             'docs-framework',
-            'documentation',
-            'performance',
-            'regression',
-            'reliability',
-            'review-methodology',
-            'security',
-            'testing',
         ],
         rules: [],
     },
@@ -280,7 +260,6 @@ export const DEVFLOW_PLUGINS = [
             'architecture',
             'database',
             'dependencies',
-            'docs-framework',
             'documentation',
             'git',
             'performance',
@@ -293,7 +272,7 @@ export const DEVFLOW_PLUGINS = [
         name: 'devflow-ambient',
         description: 'Orchestrator ambient mode — session charter, per-prompt reminder, plan handoff',
         commands: [],
-        agents: ['code', 'validate', 'simplify', 'scrutinize', 'evaluate', 'test', 'skim', 'review', 'git', 'synthesize', 'triage', 'design', 'knowledge', 'research', 'learning'],
+        agents: ['code', 'code-edit', 'validate', 'simplify', 'scrutinize', 'evaluate', 'test', 'skim', 'review', 'git', 'synthesize', 'triage', 'design', 'knowledge', 'research', 'learning', 'explore'],
         skills: [
             'review-methodology',
             'security',
@@ -317,9 +296,6 @@ export const DEVFLOW_PLUGINS = [
         ],
         requires: [
             'apply-decisions',
-            'boundary-validation',
-            'dependency-research',
-            'docs-framework',
             'git',
             'quality-gates',
             'research-codebase',
@@ -337,22 +313,19 @@ export const DEVFLOW_PLUGINS = [
         description: 'Dynamic workflow recipes - dependency-aware tickets→plan→build delivery pipeline',
         // Commands compiled from commands/*.mds at build time (build:mds).
         commands: ['/dynamic-tickets', '/dynamic-plan', '/dynamic-build', '/dynamic-profile'],
-        agents: ['code', 'validate', 'simplify', 'scrutinize', 'evaluate', 'test', 'review', 'git', 'synthesize', 'knowledge', 'design'],
+        agents: ['code', 'code-fix', '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',
@@ -485,29 +458,72 @@ export const FEATURE_OWNED_SKILLS = ['compliance'];
 /**
  * Rules owned by the feature system — not any plugin in DEVFLOW_PLUGINS.
  * The compliance rule (src/assets/rules/compliance.md) is stamped and installed
- * by convergeComplianceArtifacts, not by the plugin installer.
+ * by convergeComplianceArtifacts, not by the plugin installer. The behavior rule
+ * (src/assets/rules/behavior.md) is installed and removed by convergeBehaviorRule.
+ *
+ * D-BEHAVIOR-OPT-IN: the behavior rule is OPT-IN and default off. How agents reply and
+ * act is a taste, so no install carries it until the user asks: `features.behavior` in
+ * the machine manifest (`devflow init --behavior`, `devflow behavior --enable`). That is
+ * why it sits here and in no plugin's `rules` array: a plugin's rules install for every
+ * install that selects the plugin, with no switch, and the core plugin is always
+ * selected. The rule is one bullet per behavior and stays small, because every session
+ * and every subagent that loads the rules pays for it; tests/rules.test.ts pins the
+ * shape, the length and this registration.
  *
  * Used by:
  *   - rules.ts: union into allRules for shadow/unshadow/list
- *   - tests: independent literal ['compliance'] (avoids EXCLUDED-as-oracle trap)
+ *   - tests: independent literal ['compliance', 'behavior'] (avoids EXCLUDED-as-oracle trap)
  *
  * D-FO-2: FEATURE_OWNED_RULES must be disjoint from getAllRuleNames()
  * (guarded by plugins.test.ts FEATURE_OWNED constants describe block).
  */
-export const FEATURE_OWNED_RULES = ['compliance'];
+export const FEATURE_OWNED_RULES = ['compliance', 'behavior'];
+/**
+ * Skills a learning-off machine does not install.
+ *
+ * D-LEARNING-VARIANT-INSTALL: the learning-off variants of the commands and
+ * agents (D-LEARNING-VARIANTS) carry no decisions text and preload no
+ * apply-decisions, so the skill has no reader on a machine with learning off. It
+ * stays OWNED and REQUIRED by its plugins in the registry — the closure guard
+ * reasons over the learning-on variant, the superset — and the install drops it
+ * on top of the selection: `installViaFileCopy` skips it when `learning` is false
+ * and `convergeLearningVariants` installs or removes it when the switch flips.
+ *
+ * This is a machine-switch condition, not a deselection: the plan
+ * ({@link resolveSkillInstallPlan}) is untouched, so a learning-off machine never
+ * reports the skill as "removed because no selected plugin requires it" nor its
+ * shadow as inactive for a plugin that is not selected.
+ *
+ * Used by:
+ *   - installer.ts installViaFileCopy: omits these from the install loop when learning is off
+ *   - learning-install.ts convergeLearningVariants: installs or removes the directory
+ *   - tests: independent literal ['apply-decisions'] (avoids the EXCLUDED-as-oracle trap)
+ */
+export const LEARNING_GATED_SKILLS = ['apply-decisions'];
+/**
+ * A skills map with the learning-gated skills left out when learning is off.
+ *
+ * Pure: the same map instance comes back when learning is on, a copy otherwise.
+ */
+export function omitLearningGatedSkills(skillsMap, learning) {
+    if (learning)
+        return skillsMap;
+    const gated = LEARNING_GATED_SKILLS;
+    return new Map([...skillsMap].filter(([skill]) => !gated.includes(skill)));
+}
 // ── 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
- * `skills/devflow:{focus}/SKILL.md` under Claude Code's directory (`CLAUDE_CONFIG_DIR`
- * when absolute, else `~/.claude` — D-CLAUDE-DIR-PROMPTS) 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).
+ * user may deliberately not have. The referencing prompts are written to
+ * proceed without it: `/code-review` spawns a language focus only when the
+ * installer stamped it into the command (D-LANGUAGE-FOCUS-STAMP,
+ * {@link installedLanguageFocuses}), and the Review agent continues 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
@@ -545,7 +561,7 @@ export const TEMPLATE_SKILL_REFS = [
     },
     {
         literal: 'devflow:{FOCUS}',
-        site: 'src/assets/agents/review.md (the Review agent loading its own focus skill)',
+        site: 'src/assets/agents/review.mds (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',
     },
 ];
@@ -733,6 +749,29 @@ export function buildScopedSkillsMap(plugins) {
     }
     return skillsMap;
 }
+/**
+ * The language focuses an install selection makes available — the list the
+ * installer stamps into the installed /code-review command.
+ *
+ * D-LANGUAGE-FOCUS-STAMP: the language gate moved from a run-time `test -f`
+ * probe of Claude Code's directory to this list, computed once at install time.
+ * Pure plumbing and nothing more: the registry's {@link PRESENCE_GATED_SKILLS}
+ * filtered to the skills the selection's closure installs
+ * ({@link buildScopedSkillsMap}), in registry order. Which focuses a diff gets
+ * stays a prompt rule that the orchestrator executes; no code here, or anywhere
+ * in the installer, classifies a diff or chooses a focus.
+ *
+ * The selection is the EFFECTIVE one (`FileCopyOptions.effectivePlugins`), never
+ * the plugins one run copies: `--plugin=X` installs X alone while the machine's
+ * selection is the manifest's plugins plus X, and the stamp has to describe what
+ * is on disk. Selective uninstall passes the plugins that remain.
+ *
+ * @param effectivePlugins - The plugins whose skill closure is, or stays, installed.
+ */
+export function installedLanguageFocuses(effectivePlugins) {
+    const installed = buildScopedSkillsMap(effectivePlugins);
+    return PRESENCE_GATED_SKILLS.filter(skill => installed.has(skill));
+}
 /**
  * Build a skills map over the WHOLE registry.
  *

package/dist/core/project-paths.js

@@ -131,8 +131,4 @@ export function getDesignDir(projectRoot) {
 export function getResearchDir(projectRoot) {
     return path.join(projectRoot, '.devflow', 'docs', 'research');
 }
-/** .devflow/docs/handoff-{branchSlug}.md — Code agent phase handoff artifact */
-export function getHandoffPath(projectRoot, branchSlug) {
-    return path.join(projectRoot, '.devflow', 'docs', `handoff-${branchSlug}.md`);
-}
 //# sourceMappingURL=project-paths.js.map

package/dist/core/proxy-log.js

@@ -34,7 +34,7 @@ export const PROXY_LOG_TAIL_BYTES = 1_048_576;
  * 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
+ * which devflow enables or invokes. Verified by whole-dist grep of the 0.6.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

@@ -91,7 +91,7 @@ export async function writeProxyState(devflowDir, state) {
  * 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.5.0 routing config contract:
+ * @D-EFR-4 Subswitch 0.6.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

package/dist/core/tracker.js

@@ -60,6 +60,44 @@ export const TRACKER_PROVIDER_IDS = TRACKER_PROVIDERS.map(p => p.id);
  */
 export const DEFAULT_TRACKER_PROVIDER = 'github';
 // ---------------------------------------------------------------------------
+// Tracker tool servers — the allowlist half of the Git and Tracker agents
+// ---------------------------------------------------------------------------
+/**
+ * D-TRACKER-SERVER-ALLOWLIST: the Git and Tracker agents hold a tool ALLOWLIST, and the
+ * tracker tool servers a user has connected differ per machine, so the shipped allowlist
+ * names no server (the agent sources stay vendor-neutral). The installer stamps one
+ * whole-server entry per name below onto the INSTALLED `tools:` line of those two agents
+ * (`stampAgentTools`, src/core/agent-frontmatter.ts), after the file is copied. Claude Code
+ * has no pattern form for an allowlist entry, so a server is granted by its name; a name
+ * that matches no connected server is inert (it grants nothing and blocks nothing).
+ *
+ * The default is one FLAT list, stamped whatever the provider: every install carries every
+ * provider, and a repository may select a provider other than the machine's, so a list
+ * keyed on the machine's provider would strand that repository. A server the user runs
+ * under another name is added with `devflow tracker --servers`. A wrong or missing name
+ * does not fail silently: the agent finds no tool for the capability it needs and reports
+ * `TRACEABILITY: DEGRADED (no tracker tool for {capability})`.
+ *
+ * The default leaves `github` out. Under the github provider the Git agent uses `gh` and
+ * never reads `_mcp.md`, so a stamped `github` server is never used by a tracker operation;
+ * under jira or linear, a connected GitHub server that also advertises issue creation would
+ * make the `_mcp.md` capability selection ambiguous, which is a degraded run. A user who
+ * wants it adds it with `devflow tracker --servers`.
+ */
+export const TRACKER_MCP_SERVERS_DEFAULT = Object.freeze([
+    'atlassian',
+    'jira',
+    'claude_ai_Atlassian',
+    'linear',
+    'claude_ai_Linear',
+]);
+/** A server name as a user may configure it. Byte-exact, like a provider token. */
+export const TRACKER_SERVER_NAME_RE = /^[A-Za-z0-9_-]{1,64}$/;
+/** The most servers one list may hold; every entry lands in a prompt-adjacent frontmatter line. */
+export const TRACKER_SERVERS_MAX = 32;
+/** The reserved word that returns the setting to {@link TRACKER_MCP_SERVERS_DEFAULT}. */
+export const TRACKER_SERVERS_DEFAULT_WORD = 'default';
+// ---------------------------------------------------------------------------
 // Artifact basenames — one spelling for every TypeScript reader
 //
 // NOT the only spelling in the repository, and a rename that assumes it is will
@@ -238,6 +276,72 @@ export function parseTrackerId(input) {
     }
     return { ok: true, value: input };
 }
+/**
+ * Validate a list of tracker server names. The one rule set behind both the CLI argument
+ * and the manifest field.
+ *
+ * REJECT, NEVER REPAIR (as {@link parseTrackerId}): a name is accepted byte-exact against
+ * {@link TRACKER_SERVER_NAME_RE} and must not hold `__`, which is what separates a server
+ * from its tool in an entry such as `mcp__server__tool`. No trim, no case folding, no
+ * alias. Exact duplicates collapse to the first occurrence and the order is kept. The list
+ * is non-empty and holds at most {@link TRACKER_SERVERS_MAX} distinct names.
+ */
+export function validateTrackerServers(raw) {
+    if (raw.length === 0) {
+        return { ok: false, error: 'No tracker servers given. Pass one or more server names, or "default".' };
+    }
+    const seen = new Set();
+    for (const entry of raw) {
+        if (typeof entry !== 'string' || !TRACKER_SERVER_NAME_RE.test(entry)) {
+            return {
+                ok: false,
+                error: `Invalid tracker server name: "${describeTrackerValue(entry)}". ` +
+                    'Names are 1-64 characters from A-Z, a-z, 0-9, "_" and "-".',
+            };
+        }
+        if (entry.includes('__')) {
+            return {
+                ok: false,
+                error: `Invalid tracker server name: "${describeTrackerValue(entry)}". ` +
+                    'A name must not contain "__" (it separates a server from its tool).',
+            };
+        }
+        seen.add(entry);
+    }
+    if (seen.size > TRACKER_SERVERS_MAX) {
+        return { ok: false, error: `Too many tracker servers: ${seen.size} (at most ${TRACKER_SERVERS_MAX}).` };
+    }
+    return { ok: true, value: [...seen] };
+}
+/**
+ * Strict boundary parser for `devflow tracker --servers <list>`.
+ *
+ * `default` alone selects {@link TRACKER_MCP_SERVERS_DEFAULT}; anything else is a
+ * comma-separated list of names handed to {@link validateTrackerServers} unchanged. An
+ * empty argument, an empty item (`a,,b`, a trailing comma) and the reserved word inside a
+ * list are errors, never silently dropped.
+ */
+export function parseTrackerServers(input) {
+    if (input === '') {
+        return { ok: false, error: 'Missing tracker servers. Pass a comma-separated list of names, or "default".' };
+    }
+    if (input === TRACKER_SERVERS_DEFAULT_WORD)
+        return { ok: true, value: { kind: 'default' } };
+    const items = input.split(',');
+    if (items.includes(TRACKER_SERVERS_DEFAULT_WORD)) {
+        return { ok: false, error: `"${TRACKER_SERVERS_DEFAULT_WORD}" is reserved: pass it alone, not inside a list.` };
+    }
+    const validated = validateTrackerServers(items);
+    return validated.ok ? { ok: true, value: { kind: 'list', servers: validated.value } } : validated;
+}
+/** The servers in force for `state`: its own list, else the default. */
+export function effectiveTrackerServers(state) {
+    return state.servers ?? TRACKER_MCP_SERVERS_DEFAULT;
+}
+/** The whole-server allowlist entries for `servers`, in order: `github` becomes `mcp__github`. */
+export function trackerServerTools(servers) {
+    return servers.map(name => `mcp__${name}`);
+}
 /**
  * Tolerant sink normaliser for a raw `manifest.features.tracker` value.
  *
@@ -249,9 +353,11 @@ export function parseTrackerId(input) {
  * D-TRACKER-SELF-HEAL [DR-26]: self-healing here is SILENT and emits no
  * DEGRADED — that is the correct self-heal behaviour, and it is a different
  * condition from a per-repo config value outside the domain (which does emit
- * `unknown tracker provider`). The two must not be conflated.
+ * `unknown tracker provider`). The two must not be conflated. The one exception is
+ * `servers` (see the body): a present but invalid list heals to the default AND reaches
+ * `onWarning` when a caller supplies one, because the user wrote that list on purpose.
  */
-export function normalizeTrackerFeature(raw) {
+export function normalizeTrackerFeature(raw, onWarning) {
     const DEFAULT = { provider: DEFAULT_TRACKER_PROVIDER };
     if (raw === null || raw === undefined || typeof raw !== 'object' || Array.isArray(raw)) {
         return DEFAULT;
@@ -259,6 +365,18 @@ export function normalizeTrackerFeature(raw) {
     const obj = raw;
     if (!isTrackerProvider(obj.provider))
         return DEFAULT;
+    // `servers`: absent is the default, silently. A present value that is not a valid list is
+    // dropped WHOLE (never trimmed to its valid names) and reported through `onWarning`, which a
+    // caller with a terminal passes; the reader itself has no output channel. The state then
+    // reads as the default list, and the next `devflow tracker --servers` or `devflow init`
+    // writes the manifest without the bad value.
+    if (obj.servers === undefined)
+        return { provider: obj.provider };
+    const servers = Array.isArray(obj.servers) ? validateTrackerServers(obj.servers) : undefined;
+    if (servers?.ok === true)
+        return { provider: obj.provider, servers: servers.value };
+    onWarning?.(`The manifest's tracker servers setting is not a valid list (${servers?.ok === false ? servers.error : 'not a list'}); ` +
+        'using the default. Run `devflow tracker --servers <names>` to set it, or `devflow tracker --servers default`.');
     return { provider: obj.provider };
 }
 // ---------------------------------------------------------------------------