devflow-kit 3.4.0 → 3.5.0

package/dist/core/mds-variants.js

@@ -271,32 +271,38 @@ export const TRACKER_OPS = [
  */
 export const TRACKER_GITHUB_OPS = TRACKER_OPS;
 /**
- * The 9 PR/review operations whose mechanics are generated once, for every
+ * The 8 PR/review operations whose references are generated once, for every
  * provider, under `pr/`.
  *
  * A PR-HOST roster, not a tracker roster, and the distinction is the whole
  * reason this list exists separately from {@link TRACKER_OPS}: pull requests, PR
  * reviews and PR checks stay on GitHub under every issue-tracker provider, so
- * these steps are the SAME file whatever `TRACKER_PROVIDER` resolves to. Filing
- * them under `tracker/github/` would make a jira user's PR mechanics read as
- * their tracker's, and fanning them across the three provider directories would
- * ship three identical trees.
- *
- * `ensure-pr-ready` is a member of BOTH rosters by design, and the two halves do
- * not overlap: the PR skeleton (branch/commit/push, create, retitle, and step
- * 4b's open-PR lookup and body edit) is a PR-host fact and lives here; step 4b
- * itself — the issue-number lookup and the link line it renders — is a tracker
- * fact and lives in `tracker/{provider}/ensure-pr-ready.md`. The operation
- * carries one pointer to each.
- *
- * 9 entries, one above {@link MIN_VARIANT_PAIRS}, which is a floor and not a
+ * these operations are the SAME file whatever `TRACKER_PROVIDER` resolves to.
+ * Filing them under `tracker/github/` would make a jira user's PR mechanics read
+ * as their tracker's, and fanning them across the three provider directories
+ * would ship three identical trees.
+ *
+ * D-OP-ONE-REF. Each file is the WHOLE operation: its contract (description,
+ * `**Input:**`, degradation notes, `**Output:**` template, written once in
+ * `src/assets/mds/git/_ops.mds`) and then its steps. The operation loads this one
+ * file and no other operation reference.
+ *
+ * `ensure-pr-ready` is deliberately NOT a member. It is a tracker operation: step
+ * 4b, the issue-number lookup and the link line it renders, is a tracker fact and
+ * differs per provider, so the operation is one file per provider under
+ * `tracker/{provider}/ensure-pr-ready.md`. That file carries the PR skeleton
+ * (branch/commit/push, create, retitle, and step 4b's open-PR lookup and body edit)
+ * as well, written once in `_ops.mds` and expanded into all three, so the PR-host
+ * half is the same bytes under every provider and the operation still loads one
+ * file.
+ *
+ * 8 entries, exactly {@link MIN_VARIANT_PAIRS}, which is a floor and not a
  * target: a shorter roster makes every parity assertion over it vacuous (GAP-42)
- * and `expandVariants` refuses the build, so the roster can grow
- * but never drop below 8. `update-pr-evidence` (#363) is the ninth — it edits the
- * PR body and comments on the PR, both GitHub whatever the tracker is.
+ * and `expandVariants` refuses the build, so the roster can grow but never drop
+ * below 8. `update-pr-evidence` (#363) is the newest member: it edits the PR body
+ * and comments on the PR, both GitHub whatever the tracker is.
  */
 export const PR_HOST_OPS = [
-    'ensure-pr-ready',
     'validate-branch',
     'post-review-summary',
     'check-ci-status',
@@ -354,6 +360,44 @@ export const GIT_CROSS_CUTTING_DOCS = [
     'publication-gate',
     'trust-rule',
 ];
+/**
+ * The Git operations whose one operation reference is a cross-cutting document
+ * rather than a per-op file in `pr/` or `tracker/{provider}/` (D-OP-ONE-REF).
+ *
+ * `learn-conventions` is the only one: it has no PR-host half and no provider half,
+ * so its reference is the named document {@link GIT_CROSS_CUTTING_DOCS} already emits
+ * at the references root. Its contract is compiled into that document like every
+ * other operation's (D-OP-CONTRACT-ONCE).
+ */
+export const DOC_BACKED_OPS = ['learn-conventions'];
+/**
+ * Every operation the Git agent routes, derived from the three rosters that emit its
+ * reference — never retyped. Each one loads exactly one operation reference
+ * ({@link operationReferenceRel}).
+ */
+export const GIT_OPERATIONS = [...PR_HOST_OPS, ...TRACKER_OPS, ...DOC_BACKED_OPS];
+/**
+ * The skill-relative path (under `references/`) of the one reference an operation
+ * loads, or `null` for a name that is not a Git operation.
+ *
+ * D-OP-ONE-REF. A PR-host operation is `pr/{op}.md`, the same file under every
+ * provider; a tracker operation is `tracker/{provider}/{op}.md` for the resolved
+ * provider; a doc-backed operation is its named document. The Git agent's
+ * `## Loading the mechanics` table states these paths in prose, and
+ * `tests/tracker/reference-reachability.test.ts` holds the table to this function.
+ *
+ * Total and pure: an unknown operation is `null`, never a throw. `ensure-pr-ready` is
+ * a tracker operation, so it resolves per provider even though its PR half is shared.
+ */
+export function operationReferenceRel(op, provider) {
+    if (TRACKER_OPS.includes(op))
+        return `${TRACKER_DESTINATION_ROOT}/${provider}/${op}.md`;
+    if (PR_HOST_OPS.includes(op))
+        return `${PR_HOST_DESTINATION_ROOT}/${op}.md`;
+    if (DOC_BACKED_OPS.includes(op))
+        return `${op}.md`;
+    return null;
+}
 /**
  * Every reference module the build knows about — a closed registry, read the
  * same way ALLOWED_OUTPUT_DIRS is read.
@@ -378,9 +422,9 @@ export const GIT_CROSS_CUTTING_DOCS = [
  * that used to sit in the always-loaded Git agent, where every spawn paid for
  * them although most spawns run a PR-host operation that never touches the
  * issue tracker. A spawn now reads the file once, only when it runs a tracker
- * operation, before its first tracker step. The agent's retained
- * `## Loading the mechanics` section is the one line that names it; it keeps
- * the PR-mechanics load rule and the merged step order, which a PR-only spawn
+ * operation, before its first tracker step. The agent's `## Loading the mechanics`
+ * section is the one line that names it; it keeps the one-reference rule and the
+ * table naming every non-tracker operation's reference, which a PR-only spawn
  * needs and which this file cannot instruct a spawn to load. It is ungated for
  * the reason the registry's other provider-independent files are: every install
  * carries every provider, GitHub included, so no registered provider is the
@@ -389,11 +433,9 @@ export const GIT_CROSS_CUTTING_DOCS = [
  * The budget clause: the file is a per-SPAWN term of each tracker row (GitHub,
  * Jira, Linear), charged the way the tool-call contract is (`contractTerm` in
  * tests/tracker/budget-model.ts) and added in `providerLoadedSet`. It is not part
- * of `ownLoadForProvider`, of the PR-host row or of the per-operation PR-host
- * cap. ensure-pr-ready is both a PR-host and a tracker operation, so charging it
- * the contract there would put it over a lower-only cap; its full cost,
- * contract included, is priced through the tracker rows, where it is already a
- * candidate.
+ * of `ownLoadForProvider`, of the PR-host row or of the per-operation load cap
+ * (D-OP-LOAD-CAP): the cap prices one operation's own reference, which is the same
+ * whichever tracker row it is read through.
  */
 export const VARIANT_MODULES = [
     {

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',
@@ -76,28 +83,18 @@ export const DEVFLOW_PLUGINS = [
         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: [],
     },
@@ -105,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',
@@ -139,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',
@@ -163,6 +156,7 @@ export const DEVFLOW_PLUGINS = [
             'regression',
             'reliability',
             'review-methodology',
+            'security',
             'software-design',
             'test-driven-development',
             'testing',
@@ -173,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',
@@ -182,9 +179,7 @@ export const DEVFLOW_PLUGINS = [
             'consistency',
             'database',
             'dependencies',
-            'docs-framework',
             'documentation',
-            'patterns',
             'performance',
             'regression',
             'reliability',
@@ -200,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: [],
     },
@@ -226,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: [],
     },
@@ -286,7 +260,6 @@ export const DEVFLOW_PLUGINS = [
             'architecture',
             'database',
             'dependencies',
-            'docs-framework',
             'documentation',
             'git',
             'performance',
@@ -299,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',
@@ -323,9 +296,6 @@ export const DEVFLOW_PLUGINS = [
         ],
         requires: [
             'apply-decisions',
-            'boundary-validation',
-            'dependency-research',
-            'docs-framework',
             'git',
             'quality-gates',
             'research-codebase',
@@ -343,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',
@@ -491,16 +458,26 @@ 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.
  *
@@ -543,8 +520,8 @@ export function omitLearningGatedSkills(skillsMap, learning) {
  * 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 and Code agents continue
- * when the Skill invocation fails. Putting them in a `requires` would reinstate
+ * {@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).
  *

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 };
 }
 // ---------------------------------------------------------------------------