devflow-kit 3.3.0 → 3.5.0

package/dist/targets/claude-code/agent-type-owner.js

@@ -0,0 +1,164 @@
+/**
+ * Who else defines an agent type: the install-edge check behind devflow's Explore
+ * override.
+ *
+ * Pure core (`parseAgentType`) with one bounded I/O function (`findForeignAgentOwner`)
+ * at the installer edge. Result-style outcomes: nothing here throws.
+ *
+ * D-EXPLORE-OVERRIDE: devflow ships an agent whose frontmatter `name:` is `Explore`,
+ * the same type as the Explore agent built into Claude Code. This is a documented,
+ * supported override, not a collision: Claude Code merges its agent sources into one
+ * map keyed by the exact `name:` string, in the order built-in, plugin, user, project,
+ * flag, policy, and a later source replaces an earlier one. A user-level agent named
+ * Explore therefore replaces the built-in for every session on the machine, plan mode
+ * included, because the lookup is by agent type and no session mode bypasses it.
+ *
+ * Verified against Claude Code 2.1.296 (`claude --version`) by reading the binary:
+ *   - the merge is `bz` (the Map keyed by `agentType`, last source wins);
+ *   - the built-in Explore is `omitClaudeMd: true` with `model: "inherit"`, and its
+ *     inherit-cap to Opus is gated on `source === "built-in"`, so it does not follow
+ *     the override;
+ *   - `omitGitStatus` is set by `agentType === "Explore" || agentType === "Plan"` and
+ *     checks no source, so devflow's Explore is spared the git-status block too;
+ *   - agents are matched with strict equality, so `explore` and `Explore` are two
+ *     different agents.
+ * Uninstalling removes devflow's copy, and the built-in applies again.
+ *
+ * D-EXPLORE-NO-CLOBBER: two user-level agents with one type fall back to file load
+ * order, so devflow never installs a second Explore beside the user's own. The install
+ * skips its copy when another file under the agents directory defines the type, and
+ * never touches that file. Matching is exact, as Claude Code's is: a lowercase
+ * `explore` agent is a different agent and does not block the install.
+ */
+import { promises as fs, constants as fsConstants } from 'fs';
+import * as path from 'path';
+/**
+ * Registry agents that deliberately take over a built-in agent type, mapped to the
+ * frontmatter `name:` they ship. The install checks each against the user's own agents.
+ */
+export const BUILTIN_OVERRIDE_AGENTS = new Map([['explore', 'Explore']]);
+/** Bytes read from the start of an agent file: enough for any frontmatter name line. */
+export const FRONTMATTER_READ_BYTES = 4096;
+/** Directory levels below the agents directory that the scan descends. */
+export const MAX_AGENT_SCAN_DEPTH = 3;
+/** Entries the scan inspects before it stops: a user directory is not an archive. */
+export const MAX_AGENT_SCAN_ENTRIES = 500;
+/** Frontmatter lines inspected for the name key. */
+const MAX_FRONTMATTER_LINES = 60;
+/**
+ * The agent type a markdown file declares: the top-level `name:` key of its leading
+ * `---` frontmatter block, unquoted. Undefined when the file has no closed frontmatter
+ * block, no top-level `name:` key, or an empty value.
+ *
+ * Reads only the key Claude Code keys agents by. It is deliberately not a YAML parser:
+ * a name written any other way (block scalar, flow mapping) reads as absent, so the
+ * check errs toward installing rather than skipping.
+ */
+export function parseAgentType(head) {
+    const lines = head.replace(/^/, '').split(/\r?\n/);
+    if (lines[0]?.trimEnd() !== '---')
+        return undefined;
+    const limit = Math.min(lines.length, MAX_FRONTMATTER_LINES);
+    for (let i = 1; i < limit; i++) {
+        const line = lines[i];
+        if (line.trimEnd() === '---')
+            return undefined;
+        const key = /^name[ \t]*:(.*)$/.exec(line);
+        if (key === null)
+            continue;
+        return closesFrontmatter(lines, i + 1, limit) ? unquoteScalar(key[1]) : undefined;
+    }
+    return undefined;
+}
+/** True when a `---` line closes the block somewhere in `lines[from, limit)`. */
+function closesFrontmatter(lines, from, limit) {
+    for (let i = from; i < limit; i++) {
+        if (lines[i].trimEnd() === '---')
+            return true;
+    }
+    return false;
+}
+function unquoteScalar(raw) {
+    const value = raw.trim();
+    const quoted = /^(["'])(.*?)\1(?:[ \t]+#.*)?$/.exec(value);
+    const text = quoted !== null ? quoted[2] : value.replace(/[ \t]+#.*$/, '');
+    const trimmed = text.trim();
+    return trimmed === '' ? undefined : trimmed;
+}
+/**
+ * The first file under `agentsRoot`, outside `ownDir`, whose frontmatter declares
+ * `agentType`: undefined when there is none.
+ *
+ * Bounded: descends at most {@link MAX_AGENT_SCAN_DEPTH} levels, inspects at most
+ * {@link MAX_AGENT_SCAN_ENTRIES} entries and reads at most {@link FRONTMATTER_READ_BYTES}
+ * bytes of any file. Symlinks, to files or directories, are never followed. A missing
+ * agents directory means no owner; an unreadable root is an error outcome; an
+ * unreadable entry below it is skipped. Entries are visited in sorted order, so the
+ * answer does not depend on the filesystem's listing order.
+ */
+export async function findForeignAgentOwner(opts) {
+    const { agentsRoot, ownDir, agentType } = opts;
+    const own = path.resolve(ownDir);
+    let inspected = 0;
+    const walk = async (dir, depth) => {
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch (err) {
+            if (depth === 0)
+                throw err;
+            return undefined;
+        }
+        entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        for (const entry of entries) {
+            if (inspected >= MAX_AGENT_SCAN_ENTRIES)
+                return undefined;
+            inspected++;
+            if (entry.isSymbolicLink())
+                continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (path.resolve(full) === own || depth >= MAX_AGENT_SCAN_DEPTH)
+                    continue;
+                const found = await walk(full, depth + 1);
+                if (found !== undefined)
+                    return found;
+                continue;
+            }
+            if (!entry.isFile() || !entry.name.endsWith('.md'))
+                continue;
+            if (parseAgentType(await readHead(full)) === agentType)
+                return full;
+        }
+        return undefined;
+    };
+    try {
+        return { ok: true, value: await walk(agentsRoot, 0) };
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { ok: true, value: undefined };
+        return {
+            ok: false,
+            error: { kind: 'unreadable-root', dir: agentsRoot, reason: err instanceof Error ? err.message : String(err) },
+        };
+    }
+}
+/** The first {@link FRONTMATTER_READ_BYTES} bytes of a file as text; '' when it cannot be read. */
+async function readHead(file) {
+    let handle;
+    try {
+        handle = await fs.open(file, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0));
+        const buffer = Buffer.alloc(FRONTMATTER_READ_BYTES);
+        const { bytesRead } = await handle.read(buffer, 0, FRONTMATTER_READ_BYTES, 0);
+        return buffer.subarray(0, bytesRead).toString('utf-8');
+    }
+    catch {
+        return '';
+    }
+    finally {
+        await handle?.close().catch(() => { });
+    }
+}
+//# sourceMappingURL=agent-type-owner.js.map

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,18 @@
 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 } from '../../core/plugins.js';
-import { skillsDir, agentSourceDirs, rulesDir, commandsDir, scriptsDir, compiledSkillRefsDir } from '../../core/assets.js';
+import { SKILL_NAMESPACE, 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)
 // ---------------------------------------------------------------------------
@@ -1263,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,
@@ -1278,6 +1338,39 @@ async function firstExisting(candidates) {
     }
     return undefined;
 }
+/**
+ * Resolve the directory a registry skill installs from: its valid shadow, else
+ * the shipped source (an invalid shadow is reported and the source is
+ * installed in its place).
+ *
+ * The ONE spelling of that decision: the install loop and
+ * convergeLearningVariants both call it, so a skill the learning toggle installs
+ * later is shadowed exactly as one the install installed.
+ *
+ * The shipped source is stat-checked FIRST, even under a valid shadow, so an
+ * absent source is a packaging failure that throws (the hard-error policy for a
+ * declared source) rather than being masked by a shadow. Callers that must not
+ * throw catch it.
+ *
+ * @param packageRoot - Package root the shipped source is read from. Injectable so
+ *   a caller working on a temp tree resolves the skill from the same root as its
+ *   other sources; omitted, it is the running package.
+ */
+export async function resolveSkillSource(skillName, devflowDir, packageRoot) {
+    const skillSource = path.join(skillsDir(packageRoot), skillName);
+    let isDir = false;
+    try {
+        isDir = (await fs.stat(skillSource)).isDirectory();
+    }
+    catch { /* stat failed — source absent */ }
+    if (!isDir) {
+        throw new Error(`Skill source not found for declared skill "${skillName}": ${skillSource}. ` +
+            `Ensure the skill directory exists in src/assets/skills/.`);
+    }
+    const shadowDir = path.join(devflowDir, 'skills', skillName);
+    const shadow = await validateSkillShadow(shadowDir);
+    return { dir: shadow === 'valid' ? shadowDir : skillSource, shadow };
+}
 /**
  * Registry skills that have a shadow directory under `~/.devflow/skills/`.
  *
@@ -1347,7 +1440,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, 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: [],
@@ -1484,11 +1577,13 @@ export async function installViaFileCopy(options) {
         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 (single lookup directory for all commands).
+    // 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.
     spinner.message('Installing commands and agents...');
     const commandsTarget = path.join(claudeDir, 'commands', 'devflow');
-    const cDir = commandsDir();
+    const commandDirs = commandSourceDirs(learning);
     const commandsSourceNames = new Set();
     for (const plugin of plugins) {
         for (const cmd of plugin.commands) {
@@ -1499,12 +1594,11 @@ export async function installViaFileCopy(options) {
     if (commandsSourceNames.size > 0) {
         await fs.mkdir(commandsTarget, { recursive: true });
         for (const name of commandsSourceNames) {
-            const srcFile = path.join(cDir, mdFileName(name));
-            try {
-                await fs.access(srcFile);
-            }
-            catch {
-                throw new Error(`Command source not found for declared command "${name}": ${srcFile}. ` +
+            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)));
@@ -1514,6 +1608,18 @@ export async function installViaFileCopy(options) {
     // 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));
+    // 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
+    // whether or not code-review's own plugin is in this run: `--plugin=devflow-typescript` copies no
+    // command, yet must update a code-review an earlier run installed. The copy above wrote the shipped
+    // `(none)` line; the rewrite compares against what is on disk now, so neither that copy nor the
+    // pre-clean can defeat it. A failure is a warning, never an abort.
+    await restampInstalledCommands({
+        claudeDir,
+        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
@@ -1532,7 +1638,8 @@ export async function installViaFileCopy(options) {
     // registry via getAllAgentNames() — still treats a converged tracker.md as known
     // and leaves it alone.
     const agentsTarget = path.join(claudeDir, 'agents', 'devflow');
-    const agentDirs = options.agentSourceDirs ?? agentSourceDirs();
+    // 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) {
@@ -1546,14 +1653,22 @@ export async function installViaFileCopy(options) {
     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}": ${candidates[0]}. ` +
+                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)));
+            const agentTarget = path.join(agentsTarget, mdFileName(agentName));
+            if (isTrackerStampedAgent(agentName)) {
+                await writeStampedAgent(srcFile, agentTarget, trackerServers, warn);
+            }
+            else {
+                await fs.copyFile(srcFile, agentTarget);
+            }
         }
     }
     // Sweep stale agent files — ungated: runs on every install shape.
@@ -1564,33 +1679,21 @@ export async function installViaFileCopy(options) {
     // Resolved from flat src/assets/skills/{name}/ (no per-plugin subdirectory).
     // A declared skill whose source directory is absent is a build/packaging failure
     // and throws rather than silently skipping (matches command pattern).
+    //
+    // D-LEARNING-VARIANT-INSTALL: a learning-off machine skips the learning-gated
+    // skills here. The pre-clean above walked the UNFILTERED map, so on a full
+    // install a leftover copy is already gone; a partial install leaves removal to
+    // convergeLearningVariants, which init runs straight after this call.
     spinner.message('Installing skills...');
-    for (const [skillName] of skillsMap) {
-        const skillSource = path.join(skillsDir(), skillName);
-        let isDir = false;
-        try {
-            const stat = await fs.stat(skillSource);
-            isDir = stat.isDirectory();
-        }
-        catch { /* stat failed — source absent */ }
-        if (!isDir) {
-            throw new Error(`Skill source not found for declared skill "${skillName}": ${skillSource}. ` +
-                `Ensure the skill directory exists in src/assets/skills/.`);
-        }
-        const shadowDir = path.join(devflowDir, 'skills', skillName);
-        const prefixedName = prefixSkillName(skillName);
-        const skillTarget = path.join(claudeDir, 'skills', prefixedName);
-        const shadowState = await validateSkillShadow(shadowDir);
-        if (shadowState === 'valid') {
-            await copyDirectory(shadowDir, skillTarget);
+    for (const [skillName] of omitLearningGatedSkills(skillsMap, learning)) {
+        const resolved = await resolveSkillSource(skillName, devflowDir);
+        const skillTarget = path.join(claudeDir, 'skills', prefixSkillName(skillName));
+        await copyDirectory(resolved.dir, skillTarget);
+        if (resolved.shadow === 'valid') {
             report.shadowedSkills.push(skillName);
         }
-        else if (shadowState === 'missing-skill-md') {
+        else if (resolved.shadow === 'missing-skill-md') {
             report.skippedShadows.push({ kind: 'skill', name: skillName, reason: 'missing-skill-md' });
-            await copyDirectory(skillSource, skillTarget);
-        }
-        else {
-            await copyDirectory(skillSource, skillTarget);
         }
         // Converge the generated references onto the skill that was just installed. One call
         // site downstream of all three branches above, so a shadowed devflow:git receives the