devflow-kit 3.4.0 → 3.6.0

package/dist/targets/claude-code/behavior-install.js

@@ -0,0 +1,111 @@
+/**
+ * Behavior rule installer for the Claude Code target.
+ *
+ * Convergence function: installs `rules/devflow/behavior.md` when the machine switch is
+ * on AND the install includes rules, and removes it in every other state.
+ *
+ * D-BEHAVIOR-OPT-IN: the behavior rule is feature-owned and OPT-IN. No plugin declares
+ * it (FEATURE_OWNED_RULES in src/core/plugins.ts), so the plugin installer never copies
+ * it; this module is its only writer. The file exists exactly when
+ * `features.behavior && features.rules`, and the same function serves every caller that
+ * can change either input: `devflow init`, `devflow behavior --enable/--disable` and
+ * `devflow rules --enable`. A full install wipes `rules/devflow/` first, and a full
+ * uninstall removes the directory, so neither needs a rule of its own.
+ *
+ * The copy goes through installRuleFile, so a shadow at ~/.devflow/rules/behavior.md
+ * overrides the shipped text the way it does for every other rule. The shadow only
+ * changes WHAT is installed; the switch still decides WHETHER.
+ *
+ * I/O orchestration in src/targets/; warn-not-throw for per-item failures, with the
+ * `warn` callback injected so callers choose how a warning surfaces.
+ */
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { installRuleFile } from './installer.js';
+// ── Types ──────────────────────────────────────────────────────────────────
+export const BEHAVIOR_RULE_NAME = 'behavior';
+// ── Path helpers ───────────────────────────────────────────────────────────
+/** Installed behavior rule file: {claudeDir}/rules/devflow/behavior.md */
+export function behaviorRulePath(claudeDir) {
+    return path.join(claudeDir, 'rules', 'devflow', `${BEHAVIOR_RULE_NAME}.md`);
+}
+async function pathExists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ── Public API ─────────────────────────────────────────────────────────────
+/**
+ * Converge the behavior rule in the Claude Code install target.
+ *
+ * Convergence matrix:
+ *   enabled + rulesEnabled   → rule file installed (shipped text, or a valid shadow)
+ *   enabled + !rulesEnabled  → rule file removed
+ *   !enabled                 → rule file removed
+ *
+ * Never throws. A relative `claudeDir` is refused with a warning rather than resolved
+ * against the working directory, because the removal arm deletes a path.
+ */
+export async function convergeBehaviorRule(opts) {
+    const { claudeDir, devflowDir, enabled, rulesEnabled, warn } = opts;
+    if (!path.isAbsolute(claudeDir)) {
+        warn(`behavior: claudeDir is not an absolute path ("${claudeDir}") — skipping convergence`);
+        return { installed: false, removed: false, converged: false };
+    }
+    const target = behaviorRulePath(claudeDir);
+    if (enabled && rulesEnabled) {
+        try {
+            await fs.mkdir(path.dirname(target), { recursive: true });
+            const outcome = await installRuleFile(BEHAVIOR_RULE_NAME, devflowDir, path.dirname(target));
+            if (outcome === 'skipped') {
+                warn('behavior: rule install failed — the file could not be copied');
+                return { installed: false, removed: false, converged: false };
+            }
+            if (outcome === 'source-invalid-shadow:empty-shadow-file' || outcome === 'source-invalid-shadow:not-a-file') {
+                warn("behavior: the shadow is invalid — Devflow's version was installed");
+                return { installed: true, removed: false, converged: false };
+            }
+            return { installed: true, removed: false, converged: true };
+        }
+        catch (err) {
+            warn(`behavior: rule install failed — ${String(err)}`);
+            return { installed: false, removed: false, converged: false };
+        }
+    }
+    // Off, or rules off: no rule. Probe first so the caller can report a removal;
+    // absence is already the desired end state.
+    if (!(await pathExists(target)))
+        return { installed: false, removed: false, converged: true };
+    try {
+        await fs.rm(target, { force: true });
+        return { installed: false, removed: true, converged: true };
+    }
+    catch (err) {
+        warn(`behavior: failed to remove rule — ${String(err)}`);
+        return { installed: true, removed: false, converged: false };
+    }
+}
+// ── Manifest-slice wrapper ─────────────────────────────────────────────────
+/**
+ * Thin wrapper around convergeBehaviorRule that takes its inputs from a manifest slice
+ * in one place, so the call sites (init.ts, rules.ts, behavior.ts) do not each hand-assemble them.
+ *
+ * @param opts.rulesEnabledOverride - When provided, replaces manifest.features.rules as
+ *   the rulesEnabled source. Used by rules.ts, where rulesEnabled reflects the actual
+ *   install outcome rather than the value stored in the manifest.
+ */
+export async function convergeBehaviorFromManifest(opts) {
+    const { claudeDir, devflowDir, manifest, warn, rulesEnabledOverride } = opts;
+    return convergeBehaviorRule({
+        claudeDir,
+        devflowDir,
+        enabled: manifest.features.behavior,
+        rulesEnabled: rulesEnabledOverride ?? manifest.features.rules,
+        warn,
+    });
+}
+//# sourceMappingURL=behavior-install.js.map

package/dist/targets/claude-code/installer.js

@@ -1,13 +1,17 @@
 import { promises as fs } from 'fs';
 import { existsSync } from 'fs';
 import * as path from 'path';
-import { SKILL_NAMESPACE, prefixSkillName, unprefixSkillName, getAllSkillNames, getAllAgentNames, getAllCommandNames, FEATURE_OWNED_SKILLS, resolveSkillInstallPlan, omitLearningGatedSkills } from '../../core/plugins.js';
+import { SKILL_NAMESPACE, buildAssetMaps, prefixSkillName, unprefixSkillName, getAllSkillNames, getAllAgentNames, getAllCommandNames, FEATURE_OWNED_SKILLS, resolveSkillInstallPlan, omitLearningGatedSkills } from '../../core/plugins.js';
 import { skillsDir, agentSourceDirs, rulesDir, commandSourceDirs, scriptsDir, compiledSkillRefsDir } from '../../core/assets.js';
 import { getPackageRoot, isContainedIn } from '../../core/paths.js';
 import { sweepOrphanedAssets, mdFileName, mdEntryName } from '../../core/orphan-sweep.js';
 import { generatedReferenceManifest, installedReferenceManifest, PR_HOST_DESTINATION_ROOT, SKILL_REFS_SKILL_NAME, TRACKER_DESTINATION_ROOT } from '../../core/mds-variants.js';
 import { sweepOrphanedReferences, MAX_REFERENCE_SWEEP_DEPTH } from '../../core/reference-sweep.js';
 import { TRACKER_AGENT_NAME } from './tracker-install.js';
+import { isTrackerStampedAgent } from './tracker-servers.js';
+import { stampAgentTools } from '../../core/agent-frontmatter.js';
+import { TRACKER_MCP_SERVERS_DEFAULT, trackerServerTools } from '../../core/tracker.js';
+import { BUILTIN_OVERRIDE_AGENTS, findForeignAgentOwner } from './agent-type-owner.js';
 import { restampInstalledCommands } from './language-stamp.js';
 // ---------------------------------------------------------------------------
 // Shadow validation helpers (exported — reused by Step 4 list commands)
@@ -1264,6 +1268,61 @@ export async function composeScripts(scriptsTarget) {
     }
     catch { /* already exists from prior install — leave as-is */ }
 }
+/**
+ * Install one agent that carries the tracker-server stamp: the shipped source with
+ * `servers` appended to its `tools:` line, written in one step so no copy of it ever sits on
+ * disk unstamped (D-TRACKER-SERVER-ALLOWLIST, src/targets/claude-code/tracker-servers.ts).
+ *
+ * A source that cannot take the stamp is installed as shipped and reported: an install must
+ * not die on a stamp, and the unstamped agent then reaches no tracker server, which
+ * `devflow tracker --servers` or a re-run of `devflow init` repairs.
+ */
+async function writeStampedAgent(srcFile, target, servers, warn) {
+    const source = await fs.readFile(srcFile, 'utf-8');
+    const stamped = stampAgentTools(source, trackerServerTools(servers));
+    if (!stamped.ok) {
+        warn(`tracker servers: ${path.basename(target)} could not be stamped (${stamped.error}); installed without tracker servers`);
+        await fs.copyFile(srcFile, target);
+        return;
+    }
+    await fs.writeFile(target, stamped.value.content);
+}
+/**
+ * D-EXPLORE-NO-CLOBBER, install half: true when `agentName` takes over a built-in
+ * agent type (Explore) and the user already owns an agent of that type under
+ * `{claudeDir}/agents`, so devflow's copy must not be installed.
+ *
+ * The user's file is only ever read. A copy of devflow's own left by an earlier install
+ * is removed from `agentsTarget`, since two user-level agents of one type fall back to
+ * file load order and the stale one could win. Every outcome that is not a conflict
+ * installs: an unreadable agents directory warns and installs rather than withholding
+ * the override on a guess. Warn-not-throw, so it never aborts an install.
+ */
+async function skipsForUserOwnedType(agentName, claudeDir, agentsTarget, warn) {
+    const agentType = BUILTIN_OVERRIDE_AGENTS.get(agentName);
+    if (agentType === undefined)
+        return false;
+    const scan = await findForeignAgentOwner({
+        agentsRoot: path.join(claudeDir, 'agents'),
+        ownDir: agentsTarget,
+        agentType,
+    });
+    if (!scan.ok) {
+        warn(`Could not check ${scan.error.dir} for an existing ${agentType} agent (${scan.error.reason}); installing devflow's ${agentType} agent`);
+        return false;
+    }
+    if (scan.value === undefined)
+        return false;
+    try {
+        await fs.rm(path.join(agentsTarget, mdFileName(agentName)), { force: true });
+    }
+    catch (err) {
+        warn(`Could not remove devflow's earlier ${agentType} agent — ${String(err)}`);
+    }
+    warn(`Skipped devflow's ${agentType} agent: ${scan.value} already defines ${agentType}, and Claude Code keys agents by name. ` +
+        `That file is left untouched; delete or rename it and re-run \`devflow init\` to use devflow's.`);
+    return true;
+}
 /**
  * First path in `candidates` that exists on disk, or undefined when none do.
  * Bounded by candidates.length. The fs.access rejection is the existence probe,
@@ -1373,6 +1432,90 @@ async function removeDeselectedSkills(skillsDir, names) {
     }
     return { removed, failed };
 }
+/**
+ * Write the commands and the agents of `plugins` into `claudeDir`, and nothing else:
+ * no sweep, no stamp, no skills. The one copy path shared by `installViaFileCopy` and
+ * the selective uninstall, which rewrites the files of the plugins that stay installed
+ * after it removed a retired agent.
+ *
+ * Commands come from dist/commands/{name}.md, or — with learning off — the learning-off
+ * variant dist/learning-off/commands/{name}.md when the host has one
+ * (D-LEARNING-VARIANT-INSTALL; commandSourceDirs owns the order). A declared command
+ * with no compiled source file is a hard error, not a skip.
+ *
+ * Agents resolve dist-first with a src fallback: dist/agents/{name}.md (compiled from an
+ * .mds generator host) wins over src/assets/agents/{name}.md. A declared agent absent from
+ * BOTH is a build/packaging failure and throws rather than silently skipping (matches the
+ * command pattern); the message names the build step as well as the tree.
+ *
+ * D-TRACKER-AGENT-OWNER: every declared agent but ONE. The Tracker agent is converged by
+ * `convergeTrackerArtifacts` alone (plan A3), which runs after the install in init and
+ * reports whether this run wrote it. Copying it here too would make every install do the
+ * work twice, and a fresh install would never report `installed` because converge would
+ * find this loop's byte-identical copy already in place. The name is skipped from the COPY
+ * set only. It stays declared in `devflow-core-skills.agents`, so the agent sweep — which
+ * keys on the full registry via getAllAgentNames() — still treats a converged tracker.md as
+ * known and leaves it alone.
+ */
+export async function installCommandsAndAgents(opts) {
+    const { plugins, agentsMap, claudeDir, learning, trackerServers, warn } = opts;
+    const commandsTarget = path.join(claudeDir, 'commands', 'devflow');
+    const commandDirs = commandSourceDirs(learning);
+    const commandsSourceNames = new Set();
+    for (const plugin of plugins) {
+        for (const cmd of plugin.commands) {
+            const name = cmd.startsWith('/') ? cmd.slice(1) : cmd;
+            commandsSourceNames.add(name);
+        }
+    }
+    if (commandsSourceNames.size > 0) {
+        await fs.mkdir(commandsTarget, { recursive: true });
+        for (const name of commandsSourceNames) {
+            const srcFile = await firstExisting(commandDirs.map(dir => path.join(dir, mdFileName(name))));
+            if (srcFile === undefined) {
+                // The error names the learning-ON path: that file exists for every declared
+                // command, while a learning-off file exists only for a host with an arm.
+                throw new Error(`Command source not found for declared command "${name}": ${path.join(commandSourceDirs(true)[0], mdFileName(name))}. ` +
+                    `Ensure build:mds ran successfully before install.`);
+            }
+            await fs.copyFile(srcFile, path.join(commandsTarget, mdFileName(name)));
+        }
+    }
+    const agentsTarget = path.join(claudeDir, 'agents', 'devflow');
+    // Learning-aware (D-LEARNING-VARIANT-INSTALL). An injected list wins as given.
+    const agentDirs = opts.agentSourceDirs ?? agentSourceDirs(undefined, learning);
+    const allAgentNames = new Set();
+    for (const plugin of plugins) {
+        for (const agent of plugin.agents) {
+            if (agent === TRACKER_AGENT_NAME)
+                continue;
+            if (!allAgentNames.has(agent) && agentsMap.get(agent) === plugin.name) {
+                allAgentNames.add(agent);
+            }
+        }
+    }
+    if (allAgentNames.size > 0) {
+        await fs.mkdir(agentsTarget, { recursive: true });
+        for (const agentName of allAgentNames) {
+            if (await skipsForUserOwnedType(agentName, claudeDir, agentsTarget, warn))
+                continue;
+            const candidates = agentDirs.map(dir => path.join(dir, mdFileName(agentName)));
+            const srcFile = await firstExisting(candidates);
+            if (srcFile === undefined) {
+                throw new Error(`Agent source not found for declared agent "${agentName}": ${path.join(opts.agentSourceDirs?.[0] ?? agentSourceDirs()[0], mdFileName(agentName))}. ` +
+                    `Run \`npm run build:mds\` if it is compiled from an .mds generator host, otherwise ` +
+                    `ensure the agent file exists in src/assets/agents/ (searched: ${candidates.join(', ')}).`);
+            }
+            const agentTarget = path.join(agentsTarget, mdFileName(agentName));
+            if (isTrackerStampedAgent(agentName)) {
+                await writeStampedAgent(srcFile, agentTarget, trackerServers, warn);
+            }
+            else {
+                await fs.copyFile(srcFile, agentTarget);
+            }
+        }
+    }
+}
 /**
  * Install plugins via manual file copy.
  * Handles cleanup of old monolithic structure, deduplication of shared assets,
@@ -1381,7 +1524,7 @@ async function removeDeselectedSkills(skillsDir, names) {
  * Returns an InstallReport describing which shadows were applied and which were skipped.
  */
 export async function installViaFileCopy(options) {
-    const { plugins, claudeDir, devflowDir, skillsMap, agentsMap, rulesMap = new Map(), isPartialInstall, spinner, learning, warn = () => { }, } = options;
+    const { plugins, claudeDir, devflowDir, skillsMap, agentsMap, rulesMap = new Map(), isPartialInstall, spinner, learning, trackerServers = TRACKER_MCP_SERVERS_DEFAULT, warn = () => { }, } = options;
     const report = {
         shadowedSkills: [],
         shadowedRules: [],
@@ -1517,38 +1660,42 @@ export async function installViaFileCopy(options) {
     for (const failure of deselected.failed) {
         warn(`Could not remove deselected skill "${prefixSkillName(failure.name)}" — ${String(failure.error)}`);
     }
-    // Install commands from selected plugins using registry-driven lookup.
-    // Source: dist/commands/{name}.md, or — with learning off — the learning-off
-    // variant dist/learning-off/commands/{name}.md when the host has one
-    // (D-LEARNING-VARIANT-INSTALL; commandSourceDirs owns the order).
-    // A declared command with no compiled source file is a hard error, not a skip.
+    // Retired agents. The sweep runs BEFORE the copy so the copy can see what it found:
+    // an agent file whose name left the registry means a previous release is installed
+    // here, and every command of that release still spawns the retired name. Sweeping
+    // alone would then strand the plugins that stay installed without their agents.
+    //
+    // Ungated: runs on every install shape. knownNames spans ALL plugins
+    // (getAllAgentNames) so agents from uninstalled plugins survive a partial run. Only
+    // names absent from the full registry are removed.
+    const agentsTarget = path.join(claudeDir, 'agents', 'devflow');
+    const agentSweep = await sweepOrphanedAssets(agentsTarget, new Set(getAllAgentNames()), mdEntryName);
+    recordSweep(report, 'agent', agentSweep);
+    // A partial install writes the selected plugins' commands and agents and leaves every
+    // other plugin's files alone, which is only safe while those files still name agents
+    // that exist. After a retired agent was removed they do not, so a partial install
+    // writes the commands and agents of every plugin the manifest records instead. The
+    // widening is conditional because an ordinary add-one run has nothing to repair and
+    // must not rewrite files the user did not ask about.
+    const widenToInstalled = isPartialInstall && agentSweep.removed.length > 0;
+    const commandAgentPlugins = widenToInstalled ? (options.effectivePlugins ?? plugins) : plugins;
+    const commandAgentMap = widenToInstalled ? buildAssetMaps(commandAgentPlugins).agentsMap : agentsMap;
+    // Install commands and agents (D-TRACKER-AGENT-OWNER and the source-resolution rules
+    // are documented on installCommandsAndAgents).
     spinner.message('Installing commands and agents...');
-    const commandsTarget = path.join(claudeDir, 'commands', 'devflow');
-    const commandDirs = commandSourceDirs(learning);
-    const commandsSourceNames = new Set();
-    for (const plugin of plugins) {
-        for (const cmd of plugin.commands) {
-            const name = cmd.startsWith('/') ? cmd.slice(1) : cmd;
-            commandsSourceNames.add(name);
-        }
-    }
-    if (commandsSourceNames.size > 0) {
-        await fs.mkdir(commandsTarget, { recursive: true });
-        for (const name of commandsSourceNames) {
-            const srcFile = await firstExisting(commandDirs.map(dir => path.join(dir, mdFileName(name))));
-            if (srcFile === undefined) {
-                // The error names the learning-ON path: that file exists for every declared
-                // command, while a learning-off file exists only for a host with an arm.
-                throw new Error(`Command source not found for declared command "${name}": ${path.join(commandSourceDirs(true)[0], mdFileName(name))}. ` +
-                    `Ensure build:mds ran successfully before install.`);
-            }
-            await fs.copyFile(srcFile, path.join(commandsTarget, mdFileName(name)));
-        }
-    }
+    await installCommandsAndAgents({
+        plugins: commandAgentPlugins,
+        agentsMap: commandAgentMap,
+        claudeDir,
+        learning,
+        trackerServers,
+        agentSourceDirs: options.agentSourceDirs,
+        warn,
+    });
     // Sweep stale command files — ungated: runs on every install shape.
     // knownNames spans ALL plugins (getAllCommandNames) so commands from uninstalled
     // plugins survive a partial run. Only names absent from the full registry are removed.
-    recordSweep(report, 'command', await sweepOrphanedAssets(commandsTarget, new Set(getAllCommandNames()), mdEntryName));
+    recordSweep(report, 'command', await sweepOrphanedAssets(path.join(claudeDir, 'commands', 'devflow'), new Set(getAllCommandNames()), mdEntryName));
     // D-LANGUAGE-FOCUS-STAMP: record the language focuses the EFFECTIVE selection installs on the
     // installed /code-review, on every install shape. This is the language gate the command reads
     // (no run-time probe of Claude Code's directory), so it runs after the copy and the sweep and
@@ -1561,53 +1708,6 @@ export async function installViaFileCopy(options) {
         effectivePlugins: options.effectivePlugins ?? plugins,
         warn,
     });
-    // Install agents (deduplicated), resolved dist-first with a src fallback:
-    // dist/agents/{name}.md (compiled from an .mds generator host) wins over
-    // src/assets/agents/{name}.md. A declared agent absent from BOTH is a
-    // build/packaging failure and throws rather than silently skipping (matches
-    // command pattern); the message names the build step as well as the tree.
-    //
-    // D-TRACKER-AGENT-OWNER: every declared agent but ONE. The Tracker agent is
-    // converged by `convergeTrackerArtifacts` alone (plan A3), which runs after this
-    // function in init and reports whether this run wrote it. Copying it here too
-    // would make every install do the work twice, and a fresh install would never
-    // report `installed` because converge would find this loop's byte-identical copy
-    // already in place.
-    //
-    // The name is skipped from the COPY set only. It stays declared in
-    // `devflow-core-skills.agents`, so the sweep below — which keys on the full
-    // registry via getAllAgentNames() — still treats a converged tracker.md as known
-    // and leaves it alone.
-    const agentsTarget = path.join(claudeDir, 'agents', 'devflow');
-    // Learning-aware (D-LEARNING-VARIANT-INSTALL). An injected list wins as given.
-    const agentDirs = options.agentSourceDirs ?? agentSourceDirs(undefined, learning);
-    const allAgentNames = new Set();
-    for (const plugin of plugins) {
-        for (const agent of plugin.agents) {
-            if (agent === TRACKER_AGENT_NAME)
-                continue;
-            if (!allAgentNames.has(agent) && agentsMap.get(agent) === plugin.name) {
-                allAgentNames.add(agent);
-            }
-        }
-    }
-    if (allAgentNames.size > 0) {
-        await fs.mkdir(agentsTarget, { recursive: true });
-        for (const agentName of allAgentNames) {
-            const candidates = agentDirs.map(dir => path.join(dir, mdFileName(agentName)));
-            const srcFile = await firstExisting(candidates);
-            if (srcFile === undefined) {
-                throw new Error(`Agent source not found for declared agent "${agentName}": ${path.join(options.agentSourceDirs?.[0] ?? agentSourceDirs()[0], mdFileName(agentName))}. ` +
-                    `Run \`npm run build:mds\` if it is compiled from an .mds generator host, otherwise ` +
-                    `ensure the agent file exists in src/assets/agents/ (searched: ${candidates.join(', ')}).`);
-            }
-            await fs.copyFile(srcFile, path.join(agentsTarget, mdFileName(agentName)));
-        }
-    }
-    // Sweep stale agent files — ungated: runs on every install shape.
-    // knownNames spans ALL plugins (getAllAgentNames) so agents from uninstalled
-    // plugins survive a partial run. Only names absent from the full registry are removed.
-    recordSweep(report, 'agent', await sweepOrphanedAssets(agentsTarget, new Set(getAllAgentNames()), mdEntryName));
     // Install skills from ALL plugins (skillsMap covers all plugins, not just selected).
     // Resolved from flat src/assets/skills/{name}/ (no per-plugin subdirectory).
     // A declared skill whose source directory is absent is a build/packaging failure

package/dist/targets/claude-code/learning-install.js

@@ -70,6 +70,7 @@
 import { promises as fs } from 'fs';
 import * as path from 'path';
 import { agentSourceDirs, commandSourceDirs, learningOffDir, } from '../../core/assets.js';
+import { carryStampedTools } from '../../core/agent-frontmatter.js';
 import { carryAgentOverrides, reapplyAgentMapping } from '../../core/agent-models.js';
 import { writeFileAtomicExclusive } from '../../core/fs-atomic.js';
 import { readManifest } from '../../core/manifest.js';
@@ -161,12 +162,19 @@ async function firstReadable(candidates) {
  * stays the authority: it reads agent-models.json after the converge and the carry only agrees
  * with it (see carryAgentOverrides).
  *
+ * D-TRACKER-SERVER-ALLOWLIST, composition: the installed Git agent carries the tracker-server
+ * entries the install stamped onto its `tools:` line, and the variant source carries none.
+ * The stamp is carried the same way (carryStampedTools), so a variant switch keeps the list
+ * and a copy already holding the right variant and its stamp compares byte-equal. Install
+ * and `devflow tracker --servers` are the only writers of the list; a converge never changes it.
+ *
  * Pure.
  */
 function withInstalledState(kind, fileName, source, installed, focuses) {
     if (kind === 'agents') {
         const sourceText = source.toString('utf-8');
-        const carried = carryAgentOverrides(sourceText, installed.toString('utf-8'));
+        const installedText = installed.toString('utf-8');
+        const carried = carryStampedTools(carryAgentOverrides(sourceText, installedText), installedText);
         return carried === sourceText ? source : Buffer.from(carried, 'utf-8');
     }
     return LANGUAGE_STAMPED_COMMANDS.includes(fileName.replace(/\.md$/, ''))

package/dist/targets/claude-code/tracker-install.js

@@ -11,8 +11,10 @@
  */
 import { promises as fs } from 'fs';
 import * as path from 'path';
+import { stampAgentTools } from '../../core/agent-frontmatter.js';
 import { agentSourceDirs } from '../../core/assets.js';
 import { mdFileName } from '../../core/orphan-sweep.js';
+import { TRACKER_MCP_SERVERS_DEFAULT, trackerServerTools } from '../../core/tracker.js';
 /**
  * The agent this module owns.
  *
@@ -50,26 +52,25 @@ async function firstExisting(candidates) {
     return undefined;
 }
 /**
- * Would copying `source` over `target` change anything?
+ * Would writing `wanted` over `target` change anything?
  *
- * Asked once, between resolving the source and copying it, so a run that would write a
+ * Asked once, between resolving the wanted bytes and writing them, so a run that would write a
  * byte-identical copy of the installed agent reports `unchanged` instead of `installed`
  * — the same question the reference overlay asks per unit, for the same reason: a
  * summary that can only ever say "installed" says nothing, and a steady-state re-init
  * announcing "tracker agent installed" is the noise this closes (QA S2).
  *
- * It does NOT weaken the self-heal. A hand-edited or truncated agent differs from its
- * source, so it is copied and reported as written; only an identical file is skipped,
- * and skipping a copy of what is already there changes nothing on disk.
+ * It does NOT weaken the self-heal. A hand-edited or truncated agent differs from what is
+ * wanted, so it is written and reported as written; only an identical file is skipped,
+ * and skipping a write of what is already there changes nothing on disk.
  *
  * Any error — an absent target, an unreadable one — answers "no". The fallback is the
- * copy that was going to happen anyway, so a failure to compare costs a write, never
+ * write that was going to happen anyway, so a failure to compare costs a write, never
  * correctness.
  */
-async function copyWouldChangeNothing(source, target) {
+async function writeWouldChangeNothing(wanted, target) {
     try {
-        const [from, to] = await Promise.all([fs.readFile(source), fs.readFile(target)]);
-        return from.equals(to);
+        return (await fs.readFile(target, 'utf-8')) === wanted;
     }
     catch {
         return false;
@@ -87,11 +88,14 @@ async function copyWouldChangeNothing(source, target) {
  * INERT until that directive fires, which happens only for a provider with no
  * learned conventions.
  *
- * Copies the agent in unless the installed file is already byte-identical to the
- * source. Compared rather than trusted for existing, so a truncated or hand-edited
- * file self-heals; compared rather than re-copied blind, so a run that changes
+ * Writes the agent in unless the installed file is already byte-identical to the
+ * source wearing the tracker-server stamp (D-TRACKER-SERVER-ALLOWLIST; the stamp is the
+ * only difference between the installed file and its source, which is why the comparison
+ * is against the STAMPED text: against the bare source the file would differ on every run).
+ * Compared rather than trusted for existing, so a truncated or hand-edited
+ * file self-heals; compared rather than re-written blind, so a run that changes
  * nothing reports `unchanged` and the summary stays quiet
- * (see {@link copyWouldChangeNothing}).
+ * (see {@link writeWouldChangeNothing}).
  *
  * Never throws. A caller reads `converged`; it does not catch. The one refusal
  * that is not an I/O degradation — a claudeDir that is not absolute — is reported
@@ -115,15 +119,28 @@ export async function convergeTrackerArtifacts(opts) {
             `run \`npm run build:mds\` if it is compiled from an .mds generator host`);
         return { converged: false, agent: 'unchanged' };
     }
+    let wanted;
+    try {
+        const stamped = stampAgentTools(await fs.readFile(source, 'utf-8'), trackerServerTools(opts.servers ?? TRACKER_MCP_SERVERS_DEFAULT));
+        if (!stamped.ok) {
+            warn(`tracker: the Tracker agent source could not take the tracker servers (${stamped.error}) — not installed`);
+            return { converged: false, agent: 'unchanged' };
+        }
+        wanted = stamped.value.content;
+    }
+    catch (err) {
+        warn(`tracker: cannot read the Tracker agent source (${source}) — ${String(err)}`);
+        return { converged: false, agent: 'unchanged' };
+    }
     // Already converged — nothing to write, and nothing for the summary to announce.
     // The directory is not created either: an identical file at the target means it is
-    // already there (see {@link copyWouldChangeNothing}).
-    if (await copyWouldChangeNothing(source, target)) {
+    // already there (see {@link writeWouldChangeNothing}).
+    if (await writeWouldChangeNothing(wanted, target)) {
         return { converged: true, agent: 'unchanged' };
     }
     try {
         await fs.mkdir(path.dirname(target), { recursive: true });
-        await fs.copyFile(source, target);
+        await fs.writeFile(target, wanted);
     }
     catch (err) {
         warn(`tracker: failed to install the Tracker agent (${target}) — ${String(err)}`);

package/dist/targets/claude-code/tracker-servers.js

@@ -0,0 +1,107 @@
+/**
+ * Tracker-server stamp for the installed Git and Tracker agents.
+ *
+ * D-TRACKER-SERVER-ALLOWLIST: the Git and Tracker agents ship a tool ALLOWLIST (their
+ * frontmatter `tools:` line), and the tracker tool servers a user has connected are
+ * configured per machine, so the shipped line names none. The installer appends one
+ * whole-server entry per configured server (`mcp__<server>`, which grants every tool the
+ * server exposes) to the INSTALLED `tools:` line of those two agents, after the file is
+ * copied. The list is `manifest.features.tracker.servers`, else TRACKER_MCP_SERVERS_DEFAULT,
+ * and `devflow tracker --servers` changes it. Decided here:
+ *
+ *   - Stamped agents: Git and Tracker, the two that call tracker tools. Code and Research keep a
+ *     denylist and so every tool server; Harden and Polish deny them all.
+ *   - Where the stamp is written. Every path that writes an installed copy of either agent either
+ *     stamps it or carries the stamp it finds:
+ *       1. `installViaFileCopy` stamps Git as it writes it (full install and `--plugin` alike);
+ *          a `--plugin` run that does not install Git leaves the installed, stamped copy alone.
+ *       2. `convergeTrackerArtifacts` stamps Tracker as it writes it, and compares the STAMPED text
+ *          with the installed file, so a steady-state run reports `unchanged`.
+ *       3. `convergeLearningVariants` (init, `devflow learning --enable/--disable`) carries the
+ *          installed stamp onto the variant it writes (`carryStampedTools`), the way it carries
+ *          `model:` and `effort:`, so a variant switch keeps the list and a repeat run is byte-equal.
+ *       4. `devflow tracker --servers` re-stamps the installed copies at once ({@link restampTrackerAgents}).
+ *     `reapplyAgentMapping` and `revertExternalAgents` (`devflow agents`, the proxy, an uninstall's
+ *     revert) go through `rewriteAgentFrontmatter`, which manages `model:` and `effort:` only, so
+ *     they preserve the line. An agent has no shadow override: only skills and rules do.
+ *   - The agent sources stay vendor-neutral. No stamped name appears under src/.
+ *   - A name no connected server answers to is inert. The agent then finds no tool for the capability
+ *     it needs and reports `TRACEABILITY: DEGRADED (no tracker tool for {capability})`, so a wrong
+ *     or missing name is visible and the remedy is `devflow tracker --servers`.
+ *
+ * Never throws: every failure is a warning, because the install must not die on a stamp.
+ */
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { stampAgentTools } from '../../core/agent-frontmatter.js';
+import { writeFileAtomicExclusive } from '../../core/fs-atomic.js';
+import { mdFileName } from '../../core/orphan-sweep.js';
+import { trackerServerTools } from '../../core/tracker.js';
+import { TRACKER_AGENT_NAME } from './tracker-install.js';
+/** The registry name of the Git agent. */
+export const GIT_AGENT_NAME = 'git';
+/** The installed agents that carry the stamp. */
+export const TRACKER_STAMPED_AGENTS = [GIT_AGENT_NAME, TRACKER_AGENT_NAME];
+/** True when `agentName` is an agent that carries the stamp. */
+export function isTrackerStampedAgent(agentName) {
+    return TRACKER_STAMPED_AGENTS.includes(agentName);
+}
+/**
+ * Stamp the installed Git and Tracker agents with `servers`.
+ *
+ * Rewrites only an installed copy (an absent one stays absent), compares against the bytes on
+ * disk at the moment of writing, and writes atomically only when they differ, so a run that
+ * changes nothing writes nothing. Never throws.
+ */
+export async function restampTrackerAgents(opts) {
+    const { claudeDir, servers, warn } = opts;
+    const rewritten = [];
+    const unchanged = [];
+    const absent = [];
+    const failed = [];
+    // Precondition, asserted in production code: a relative claudeDir would resolve the targets
+    // against the working directory.
+    if (!path.isAbsolute(claudeDir)) {
+        warn(`tracker servers: claudeDir is not an absolute path ("${claudeDir}") — the installed agents were not stamped`);
+        return { rewritten, unchanged, absent, failed: [...TRACKER_STAMPED_AGENTS] };
+    }
+    const tools = trackerServerTools(servers);
+    for (const agent of TRACKER_STAMPED_AGENTS) {
+        const target = path.join(claudeDir, 'agents', 'devflow', mdFileName(agent));
+        let current;
+        try {
+            current = await fs.readFile(target, 'utf-8');
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                absent.push(agent);
+            }
+            else {
+                warn(`tracker servers: cannot read ${mdFileName(agent)} (${target}) — ${String(err)}`);
+                failed.push(agent);
+            }
+            continue;
+        }
+        const stamped = stampAgentTools(current, tools);
+        if (!stamped.ok) {
+            warn(`tracker servers: ${mdFileName(agent)} could not be stamped (${stamped.error}), so it was left as it is. ` +
+                'Run `devflow init` to reinstall it.');
+            failed.push(agent);
+            continue;
+        }
+        if (!stamped.value.changed) {
+            unchanged.push(agent);
+            continue;
+        }
+        try {
+            await writeFileAtomicExclusive(target, stamped.value.content);
+            rewritten.push(agent);
+        }
+        catch (err) {
+            warn(`tracker servers: could not rewrite ${mdFileName(agent)} (${target}) — ${String(err)}`);
+            failed.push(agent);
+        }
+    }
+    return { rewritten, unchanged, absent, failed };
+}
+//# sourceMappingURL=tracker-servers.js.map