devflow-kit 3.3.0 → 3.5.0

package/dist/cli/commands/init-seed.js

@@ -12,7 +12,7 @@
  * beside init.ts in src/cli/commands/ rather than in src/core/ (which holds
  * agent-neutral, target-agnostic utilities).
  */
-import { resolveExistingViewMode, settingHoldsManagedShape, FLAG_REGISTRY, defaultValueOf, readViewMode, } from '../../core/flags.js';
+import { resolveExistingViewMode, settingHoldsManagedShape, respectUserOwnedSettings, FLAG_REGISTRY, defaultValueOf, readViewMode, } from '../../core/flags.js';
 import { partitionSelectablePlugins } from '../../core/plugins.js';
 import { DEFAULT_TRACKER_PROVIDER } from '../../core/tracker.js';
 /** Registry defaults — all features enabled except proxy (advanced-only, off by default). */
@@ -24,6 +24,7 @@ export const FEATURE_DEFAULTS = {
     learning: true,
     rules: true,
     proxy: false,
+    behavior: false,
     compliance: { enabled: false, frameworks: [] },
     tracker: { provider: DEFAULT_TRACKER_PROVIDER },
 };
@@ -44,6 +45,8 @@ export function resolveSeedFeatures(manifest) {
     const hud = manifest?.features.hud ?? FEATURE_DEFAULTS.hud;
     const rules = manifest?.features.rules ?? FEATURE_DEFAULTS.rules;
     const proxy = manifest?.features.proxy ?? FEATURE_DEFAULTS.proxy;
+    // D-BEHAVIOR-OPT-IN: a manifest from before the switch has no key — it seeds the default (off).
+    const behavior = manifest?.features.behavior ?? FEATURE_DEFAULTS.behavior;
     // Return a fresh object so callers never hold a reference to FEATURE_DEFAULTS.compliance.
     // Without the spread, `manifest?.features.compliance ?? FEATURE_DEFAULTS.compliance` returns
     // the module-level default by reference — downstream mutation would corrupt it process-wide.
@@ -57,7 +60,7 @@ export function resolveSeedFeatures(manifest) {
     const memory = manifest?.features.memory ?? FEATURE_DEFAULTS.memory;
     const knowledge = manifest?.features.knowledge ?? FEATURE_DEFAULTS.knowledge;
     const learning = manifest?.features.learning ?? FEATURE_DEFAULTS.learning;
-    return { ambient, memory, hud, knowledge, learning, rules, proxy, compliance, tracker };
+    return { ambient, memory, hud, knowledge, learning, rules, proxy, behavior, compliance, tracker };
 }
 /**
  * Resolve the flag record for the init seed.
@@ -233,7 +236,7 @@ export function resolveInitSeed(seedManifest, settingsSnapshot, plugins) {
     // seedManifest?.features.flags may be absent at runtime on very old manifests not yet
     // healed — ?? null collapses to fresh-install behavior (all flags at registry defaults).
     const manifestFlags = seedManifest?.features.flags ?? null;
-    const flags = resolveSeedFlags(manifestFlags);
+    const flags = respectUserOwnedSettings(resolveSeedFlags(manifestFlags), manifestFlags, settingsSnapshot);
     const manifestPlugins = seedManifest !== null ? seedManifest.plugins : null;
     const { workflowPlugins, languagePlugins } = resolveSeedPlugins(manifestPlugins, seedManifest?.knownPlugins, plugins);
     // Encode the resolved view mode into flags['view-mode'] (all flag state in FlagsRecord).
@@ -312,6 +315,7 @@ export function applyCliToggles(base, toggles) {
         learning: toggles.learning ?? base.learning,
         rules: toggles.rules ?? base.rules,
         proxy: toggles.proxy ?? base.proxy,
+        behavior: toggles.behavior ?? base.behavior,
         compliance: toggles.compliance ?? base.compliance,
         tracker: toggles.tracker ?? base.tracker,
     };

package/dist/cli/commands/init.js

@@ -39,10 +39,14 @@ import { removeManagedDenyList, describeManagedDenyRemoval } from './security.js
 import { resolveInitSeed, applyCliToggles, resolveResetGatedInputs, resolvePluginsToInstall } from './init-seed.js';
 import { parseFrameworkList, normalizeFrameworks } from '../../core/compliance.js';
 import { formatComplianceSummary, shouldRunComplianceStep, runComplianceStep, buildClackCompliancePrompts, } from './compliance-prompts.js';
-import { applyTrackerSentinel, parseTrackerId, rearmTrackerInference, DEFAULT_TRACKER_PROVIDER, } from '../../core/tracker.js';
+import { shouldRunBehaviorStep, runBehaviorStep, buildClackBehaviorPrompts } from './behavior-prompts.js';
+import { convergeBehaviorFromManifest } from '../../targets/claude-code/behavior-install.js';
+import { applyTrackerSentinel, effectiveTrackerServers, parseTrackerId, rearmTrackerInference, DEFAULT_TRACKER_PROVIDER, } from '../../core/tracker.js';
 import { formatTrackerSummary, shouldRunTrackerStep, runTrackerStep, buildClackTrackerPrompts, } from './tracker-prompts.js';
 import { shouldRunAttributionStep, runAttributionStep, buildClackAttributionPrompts, applyAttributionAnswer, attributionSeedFrom, } from './attribution-prompts.js';
 import { convergeFromManifest } from '../../targets/claude-code/compliance-install.js';
+import { convergeLearningVariants } from '../../targets/claude-code/learning-install.js';
+import { auditAndRecordClaudeMd, formatClaudeMdAuditNote, formatClaudeMdAuditUnavailable, } from '../../core/claude-md-audit.js';
 import * as os from 'os';
 // Re-export pure functions for tests (canonical source is post-install.ts)
 export { substituteSettingsTemplate, mergeDenyList, discoverProjectGitRoots } from '../../targets/claude-code/post-install.js';
@@ -319,11 +323,29 @@ export function trackerOverrideMessage(provider) {
         text: `Tracker: ${formatTrackerSummary(provider)}`,
     };
 }
+/**
+ * The audit's printable outcome, the ONE function both init paths use.
+ *
+ * D-CLAUDE-MD-IMPORT-AUDIT, D-INIT-REAL-OUTCOME: the Recommended summary note prints
+ * before the install runs, and the Advanced path prints no end-of-wizard summary
+ * (D-TRACKER-CLI-SURFACE), so the audit cannot be a row of either. It is decided after
+ * the install, from the CLAUDE.md files as they are, and printed as one note by the single
+ * call site in `run`, whichever path got there: the lines are the script's own formatter's,
+ * the ones the SessionStart hook shows in its systemMessage. Nothing is printed when
+ * nothing is flagged; a failure is at most one degraded line and never changes the exit code.
+ *
+ * Pure — returns text, prints nothing.
+ */
+export function claudeMdAuditStep(outcome) {
+    if (!outcome.ok)
+        return { note: null, degraded: formatClaudeMdAuditUnavailable(outcome.error) };
+    return { note: formatClaudeMdAuditNote(outcome.value), degraded: null };
+}
 /** The real adapter — the ONE binding of each owner into the init lifecycle. */
 export function buildTrackerLifecycleIO() {
     return {
         writeManifest,
-        convergeArtifacts: (claudeDir, warn) => convergeTrackerArtifacts({ claudeDir, warn }),
+        convergeArtifacts: (claudeDir, servers, warn) => convergeTrackerArtifacts({ claudeDir, servers, warn }),
         rearmInference: rearmTrackerInference,
         applySentinel: applyTrackerSentinel,
     };
@@ -376,7 +398,7 @@ export async function persistManifestThenConvergeTracker(opts) {
     // The Tracker agent file — installed on every machine (D-INSTALL-ALL-PROVIDERS),
     // because a repository can select a provider the machine never did.
     const agentWarnings = [];
-    const artifacts = await io.convergeArtifacts(claudeDir, (msg) => agentWarnings.push(msg));
+    const artifacts = await io.convergeArtifacts(claudeDir, effectiveTrackerServers(manifestData.features.tracker), (msg) => agentWarnings.push(msg));
     for (const text of agentWarnings)
         messages.push({ level: 'warn', text });
     // D-TRACKER-PARALLEL: the two owners touch disjoint files — the attempt
@@ -475,6 +497,7 @@ export function buildHudOnlyManifest(existing, version, now) {
         features: {
             ambient: false, memory: false, hud: true, knowledge: false,
             learning: false, rules: false, flags: {}, proxy: false,
+            behavior: false,
             compliance: { enabled: false, frameworks: [] },
             // The exported default, not a literal — the one constant every other
             // module reads, so a moved default moves here too.
@@ -578,6 +601,8 @@ export const initCommand = new Command('init')
     .option('--no-rules', 'Disable rules')
     .option('--proxy', 'Enable external model routing (GPT models via your OpenAI/Codex subscription)')
     .option('--no-proxy', 'Disable external model routing')
+    .option('--behavior', 'Enable the behavior rule (agents reply in ASD-STE100 Simplified Technical English; off by default)')
+    .option('--no-behavior', 'Disable the behavior rule')
     .option('--compliance <list>', 'Enable compliance with comma-separated framework IDs (e.g., gdpr,hipaa)')
     .option('--no-compliance', 'Disable compliance (removes the rule; the skill and framework references stay installed; frameworks remembered for re-enable)')
     .option('--tracker <id>', 'The machine\'s default issue tracker provider: github, jira, or linear')
@@ -669,7 +694,7 @@ export const initCommand = new Command('init')
     // ── Hoisted reads: the prior state that seeds the prompts (InitSeed, Phase 4) ──
     let existingManifest = null;
     try {
-        existingManifest = await readManifest(devflowDir);
+        existingManifest = await readManifest(devflowDir, { onWarning: (message) => p.log.warn(message) });
     }
     catch { /* unreadable manifest — seeded as a fresh install */ }
     // D-INIT-NOT-HOME (same-location.ts): a repository rooted at HOME is no
@@ -895,6 +920,10 @@ export const initCommand = new Command('init')
     // Fresh installs → false (FEATURE_DEFAULTS.proxy). Re-inits → prior manifest value.
     // --reset → false (resolveResetGatedInputs null-seeds the manifest).
     let proxyEnabled = seed.features.proxy;
+    // behavior (D-BEHAVIOR-OPT-IN): opt-in, manifest-group like proxy. Fresh installs and --reset
+    // → false (FEATURE_DEFAULTS.behavior); re-inits and the Recommended path keep the prior
+    // manifest value; only --behavior/--no-behavior and the Advanced wizard change it.
+    let behaviorEnabled = seed.features.behavior;
     // compliance: manifest-group (like proxy); seed from prior manifest value.
     // CLI override applied below in both Recommended and Advanced paths.
     let complianceEnabled = seed.features.compliance.enabled;
@@ -902,6 +931,10 @@ export const initCommand = new Command('init')
     // tracker: manifest-group (like proxy and compliance); seed from prior manifest.
     // CLI override applied below in both Recommended and Advanced paths.
     let trackerProvider = seed.features.tracker.provider;
+    // The tracker tool servers (D-TRACKER-SERVER-ALLOWLIST) are set by `devflow tracker --servers`
+    // alone, so init carries the prior value through untouched: it stamps the installed agents
+    // with it and writes it back to the manifest. Absent stays absent (the default list).
+    const trackerServers = seed.features.tracker.servers;
     let enabledFlags = { ...seed.flags };
     // viewModeExplicit: true when --reset is passed; signals resolveFinalViewMode to let the
     // seed-time view-mode win over an externally-set value in settings.json.
@@ -1012,6 +1045,7 @@ export const initCommand = new Command('init')
             learning: options.learning,
             rules: options.rules,
             proxy: options.proxy,
+            behavior: options.behavior,
             compliance: cliComplianceOverride ?? wizardCompliance,
             // Precedence: cliOverride ?? wizardResult ?? seed (applyCliToggles supplies the seed arm).
             tracker: cliTrackerOverride ?? wizardTracker,
@@ -1023,6 +1057,7 @@ export const initCommand = new Command('init')
         learningEnabled = effectiveFeatures.learning;
         rulesEnabled = effectiveFeatures.rules;
         proxyEnabled = effectiveFeatures.proxy;
+        behaviorEnabled = effectiveFeatures.behavior;
         complianceEnabled = effectiveFeatures.compliance.enabled;
         complianceFrameworks = effectiveFeatures.compliance.frameworks;
         trackerProvider = effectiveFeatures.tracker.provider;
@@ -1063,6 +1098,7 @@ export const initCommand = new Command('init')
             `HUD:             ${hudEnabled ? 'enabled' : 'disabled'}`,
             `Knowledge bases: ${knowledgeEnabled ? 'enabled' : 'disabled'}`,
             `Ext model routing: ${proxyEnabled ? 'enabled' : 'disabled'}`,
+            `Behavior rule:   ${behaviorEnabled ? 'enabled' : 'disabled'}`,
             `Compliance:      ${complianceSummary}`,
             // Recommended emits no per-step outcome lines, so this summary row is the
             // tracker step's ONLY surface on this path — both surfaces or it is
@@ -1194,6 +1230,33 @@ export const initCommand = new Command('init')
             }
             rulesEnabled = rulesChoice;
         }
+        // Behavior rule (Advanced-only; opt-in, default OFF; D-BEHAVIOR-OPT-IN). Runs after the
+        // rules step because the rule installs only while rules are on, and the gate knows it.
+        // A skipped gate leaves the seeded value, which --behavior/--no-behavior replace.
+        if (shouldRunBehaviorStep({
+            isTTY: process.stdin.isTTY,
+            hasCliOverride: options.behavior !== undefined,
+            rulesEnabled,
+        })) {
+            const behaviorStep = await runBehaviorStep({
+                seed: behaviorEnabled,
+                prompts: buildClackBehaviorPrompts(),
+            });
+            if (behaviorStep.kind === 'cancelled') {
+                p.cancel('Installation cancelled.');
+                process.exit(0);
+            }
+            behaviorEnabled = behaviorStep.enabled;
+            for (const msg of behaviorStep.messages) {
+                if (msg.level === 'success')
+                    p.log.success(msg.text);
+                else
+                    p.log.info(msg.text);
+            }
+        }
+        else if (options.behavior !== undefined) {
+            behaviorEnabled = options.behavior;
+        }
         // External model routing (Advanced-only; default OFF; never part of Recommended)
         if (options.proxy !== undefined) {
             proxyEnabled = options.proxy;
@@ -1558,6 +1621,11 @@ export const initCommand = new Command('init')
             rulesMap,
             isPartialInstall: !!options.plugin,
             spinner: s,
+            // The SETTLED switch, after the flag, the prompt and the seed have all had
+            // their say (D-LEARNING-VARIANT-INSTALL): the files installed here and the
+            // manifest written at the end of init cannot disagree about it.
+            learning: learningEnabled,
+            trackerServers,
             // Non-fatal install notices with no other channel (skipped symlinks in the
             // generated reference tree, mode-normalisation failures) reach the user rather
             // than the void. Collected now, emitted after the spinner stops.
@@ -1569,6 +1637,30 @@ export const initCommand = new Command('init')
         p.log.error(`${error}`);
         process.exit(1);
     }
+    // D-LEARNING-VARIANT-INSTALL: converge the learning variants. The file copy above
+    // installed the variant of everything IT installed; on a `--plugin` install the
+    // other plugins' files, already on disk, may still be the other variant (this run
+    // may have flipped the switch), and the apply-decisions skill is removed here when
+    // the copy skipped it on a partial install. Rewrites only what is installed.
+    // Warn-not-abort: either mismatch is safe (an on variant is still gated at run
+    // time, an off variant loads no decisions). The agent mapping is reapplied below.
+    try {
+        const learningConverge = await convergeLearningVariants({
+            claudeDir,
+            devflowDir,
+            learning: learningEnabled,
+            plugins: effectivePlugins,
+            warn: (msg) => installWarnings.push(msg),
+        });
+        if (verbose && learningConverge.converged) {
+            p.log.info(`Learning ${learningEnabled ? 'on' : 'off'} variants: ` +
+                `${learningConverge.commandsRewritten.length} command(s) and ${learningConverge.agentsRewritten.length} agent(s) ` +
+                `rewritten, ${learningConverge.unchanged} already current`);
+        }
+    }
+    catch (err) {
+        installWarnings.push(`Learning variant convergence failed — ${err instanceof Error ? err.message : String(err)}`);
+    }
     // Converge compliance artifacts (always converge, never short-circuit).
     // Called unconditionally so that enabling/disabling compliance during init
     // is reflected in the installed artifacts without a separate devflow compliance run.
@@ -1595,6 +1687,25 @@ export const initCommand = new Command('init')
         p.log.warn(`Compliance artifact convergence failed — install succeeded but compliance artifacts may be stale: ` +
             `${err instanceof Error ? err.message : String(err)}`);
     }
+    // D-BEHAVIOR-OPT-IN: converge the behavior rule. The plugin installer never copies it (no
+    // plugin declares it) and a full install wiped rules/devflow/ above, so this is the one
+    // writer: it installs the file when the switch is on and rules are on, and removes it
+    // otherwise. Warn-not-abort, like the compliance convergence.
+    try {
+        await convergeBehaviorFromManifest({
+            claudeDir,
+            devflowDir,
+            manifest: { features: { behavior: behaviorEnabled, rules: rulesEnabled } },
+            warn: (msg) => p.log.warn(msg),
+        });
+    }
+    catch (err) {
+        p.log.warn(`Behavior rule convergence failed — install succeeded but the behavior rule may be stale: ` +
+            `${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (behaviorEnabled && !rulesEnabled) {
+        p.log.info('Behavior rule is on but rules are disabled, so it is not installed — run `devflow rules --enable`.');
+    }
     // Clean up stale skills from previous installations
     s.message('Cleaning up');
     const skillsDir = path.join(claudeDir, 'skills');
@@ -2201,6 +2312,10 @@ export const initCommand = new Command('init')
             security: securityMode,
             // Final resolved value — may be forced off by preflight failure.
             proxy: proxyEnabled,
+            // Resolved behavior switch (D-BEHAVIOR-OPT-IN) — seeded from the prior manifest,
+            // overridden by --behavior/--no-behavior and the Advanced wizard. The rule file was
+            // converged above to match it.
+            behavior: behaviorEnabled,
             // Resolved compliance state — seeded from prior manifest, overridden by CLI flags
             // and Advanced wizard selection. convergeComplianceArtifacts was called above.
             // normalizeFrameworks: dedup + filter unknowns before persisting.
@@ -2208,7 +2323,7 @@ export const initCommand = new Command('init')
             // Resolved tracker selection. Already a validated TrackerProvider — it came
             // through parseTrackerId (CLI), the typed wizard select, or the seed, which
             // itself came through normalizeTrackerFeature on read.
-            tracker: { provider: trackerProvider },
+            tracker: { provider: trackerProvider, ...(trackerServers !== undefined ? { servers: trackerServers } : {}) },
         },
         installedAt: existingManifest?.installedAt ?? now,
         updatedAt: now,
@@ -2263,6 +2378,20 @@ export const initCommand = new Command('init')
         agent: trackerLifecycle.agent,
     });
     logSummaryLines(trackerLines);
+    // CLAUDE.md import audit (D-CLAUDE-MD-IMPORT-AUDIT, D-AUDIT-STAMP): after the install, on
+    // both paths, through claudeMdAuditStep. Global roots always; the project's roots when init
+    // runs inside a git repository that is not HOME, at its toplevel. The stamp is written here,
+    // now that the machine root exists, so the first SessionStart repeats nothing printed below.
+    const auditStep = claudeMdAuditStep(await auditAndRecordClaudeMd({
+        claudeDir,
+        projectRoot: gitRoot,
+        home: homeDir,
+        devflowDir,
+    }));
+    if (auditStep.note !== null)
+        p.note(auditStep.note, 'CLAUDE.md import audit');
+    if (auditStep.degraded !== null)
+        p.log.warn(auditStep.degraded);
     // External model routing status line (Advanced path / explicit --proxy flag only)
     if (proxyEnabled) {
         p.log.info(`External model routing: ${color.green('enabled')} — takes effect in new Claude Code sessions`);

package/dist/cli/commands/learning.js

@@ -7,7 +7,8 @@ import { getLearningDir, getLearningTuningConfigPath, } from '../../core/project
 import { loadShippedAgentDefaults } from '../../core/agent-models.js';
 import { readMachineFeature, writeMachineFeature } from '../../core/feature-switch.js';
 import { loadSettingsModule, narrowedSwitchLabel, personalConfigTrackedWarning } from '../../core/evidence-policy.js';
-import { getDevFlowDirectory } from '../../targets/claude-code/claude-paths.js';
+import { getClaudeDirectory, getDevFlowDirectory } from '../../targets/claude-code/claude-paths.js';
+import { applyLearningToggle, describeLearningConverge, readRunningVersion, } from '../../targets/claude-code/learning-install.js';
 import { getLedgerRoot } from '../../core/ledger-root.js';
 import { drainLearningQueue } from '../../core/learning-queue-cleanup.js';
 import { firstSymbolicLink } from '../../core/linked-path.js';
@@ -426,11 +427,44 @@ async function handleClear() {
     if (!drain.drained)
         p.log.warn(formatRefusedDrain('learning', drain.linkedFolder));
 }
+/**
+ * Make the installed prompts match the switch just written
+ * (D-LEARNING-VARIANT-INSTALL): the learning-on or learning-off commands and
+ * agents, and the apply-decisions skill. The same convergence `devflow init` runs,
+ * followed by reapplying the saved agent model mapping so `devflow agents`
+ * overrides survive.
+ *
+ * Warn-not-fail: the switch itself is already recorded, and either mismatch is
+ * safe (an on variant is still gated at run time, an off variant loads no
+ * decisions), so a problem here never changes the exit code.
+ */
+async function convergeInstalledVariants(enabled) {
+    try {
+        const outcome = await applyLearningToggle({
+            claudeDir: getClaudeDirectory(),
+            devflowDir: getDevFlowDirectory(),
+            learning: enabled,
+            runningVersion: await readRunningVersion(),
+            warn: (msg) => p.log.warn(msg),
+        });
+        if (outcome.kind === 'skipped') {
+            p.log.warn(outcome.message);
+            return;
+        }
+        const changed = describeLearningConverge(outcome.result, enabled);
+        if (changed !== null)
+            p.log.info(color.dim(`Installed prompts: ${changed}`));
+    }
+    catch (err) {
+        p.log.warn(`Could not update the installed prompts for the new learning setting — run ${color.cyan('devflow init')}: ${String(err)}`);
+    }
+}
 /**
  * `--enable` / `--disable`: the machine-wide switch (D-FEATURES-NARROW-ONLY),
  * converged exactly as `devflow init --learning / --no-learning` converges it —
- * the manifest value, and on disable a drained queue in the current project.
- * Never requires a git root: the switch is not a per-project setting.
+ * the manifest value, the installed prompt variants and skill
+ * (D-LEARNING-VARIANT-INSTALL), and on disable a drained queue in the current
+ * project. Never requires a git root: the switch is not a per-project setting.
  */
 async function handleToggle(enabled) {
     const recorded = await writeMachineFeature(getDevFlowDirectory(), 'learning', enabled);
@@ -439,6 +473,7 @@ async function handleToggle(enabled) {
         process.exitCode = 1;
         return;
     }
+    await convergeInstalledVariants(enabled);
     if (enabled) {
         p.log.success('Learning enabled in every project (a repository can opt out)');
         p.log.info(color.dim('Architectural decisions and pitfalls will be detected from your sessions'));

package/dist/cli/commands/rules.js

@@ -9,6 +9,7 @@ import { readManifest, writeManifest } from '../../core/manifest.js';
 import { rulesDir } from '../../core/assets.js';
 import { installAllRules, validateRuleShadow } from '../../targets/claude-code/installer.js';
 import { convergeFromManifest } from '../../targets/claude-code/compliance-install.js';
+import { convergeBehaviorFromManifest } from '../../targets/claude-code/behavior-install.js';
 /**
  * Check whether a rule has a user shadow file at ~/.devflow/rules/{name}.md.
  */
@@ -256,6 +257,21 @@ export async function runRulesEnable(claudeDir, devflowDir) {
         // Warn-not-abort — compliance convergence failure does not undo rules install
         p.log.warn(`Compliance rule convergence failed — rules installed but compliance rule may be stale: ${err instanceof Error ? err.message : String(err)}`);
     }
+    // D-BEHAVIOR-OPT-IN: the wipe above removed the opt-in behavior rule with the rest of
+    // the directory, so bring it back when its switch is on. Same rulesEnabledOverride
+    // reasoning as compliance: a failed install leaves no rules to add this one to.
+    try {
+        await convergeBehaviorFromManifest({
+            claudeDir,
+            devflowDir,
+            manifest,
+            warn: (msg) => p.log.warn(msg),
+            rulesEnabledOverride: !installFailed,
+        });
+    }
+    catch (err) {
+        p.log.warn(`Behavior rule convergence failed — rules installed but the behavior rule may be stale: ${err instanceof Error ? err.message : String(err)}`);
+    }
 }
 export const rulesCommand = new Command('rules')
     .description('Manage Devflow rules')

package/dist/cli/commands/tracker.js

@@ -16,18 +16,22 @@
  * --set converges the sentinel in BOTH directions, so flipping
  *   back to github removes what flipping away wrote.
  * A failed re-arm or sentinel step warns, it never aborts.
+ * --servers sets the machine's tracker tool servers (D-TRACKER-SERVER-ALLOWLIST) and
+ *   re-stamps the installed Git and Tracker agents at once; it is orthogonal to --set and
+ *   neither flag touches the other's manifest field.
  */
 import { Command } from 'commander';
 import { promises as fs } from 'fs';
 import * as path from 'path';
 import * as p from '@clack/prompts';
 import color from 'picocolors';
-import { DEFAULT_TRACKER_PROVIDER, TRACKER_ATTEMPTS_MAX, TRACKER_CONVENTIONS_READ_BYTES, TRACKER_PROVIDERS, applyTrackerSentinel, describeTrackerValue, parseTrackerFrontmatter, parseTrackerId, readBoundedHead, rearmTrackerInference, trackerConventionsPath, } from '../../core/tracker.js';
+import { DEFAULT_TRACKER_PROVIDER, TRACKER_ATTEMPTS_MAX, TRACKER_CONVENTIONS_READ_BYTES, TRACKER_PROVIDERS, applyTrackerSentinel, describeTrackerValue, effectiveTrackerServers, parseTrackerFrontmatter, parseTrackerId, parseTrackerServers, readBoundedHead, rearmTrackerInference, trackerConventionsPath, } from '../../core/tracker.js';
 import { readManifest, syncManifestFeature } from '../../core/manifest.js';
 import { loadSettingsModule, personalConfigTrackedWarning, repoTrackerSelection } from '../../core/evidence-policy.js';
 import { getClaudeDirectory, getDevFlowDirectory } from '../../targets/claude-code/claude-paths.js';
 import { SKILL_REFS_SKILL_NAME, installedReferenceManifest } from '../../core/mds-variants.js';
 import { prefixSkillName } from '../../core/plugins.js';
+import { TRACKER_STAMPED_AGENTS, restampTrackerAgents, } from '../../targets/claude-code/tracker-servers.js';
 /**
  * Read the provenance header of `~/.devflow/tracker/{provider}.md`.
  *
@@ -112,6 +116,10 @@ export async function readTrackerStatusConventions(devflowDir, provider) {
         provenance: await readTrackerProvenance(devflowDir, provider),
     };
 }
+/** Render the tracker servers for the `--status` note. Pure; every name was validated at its boundary. */
+export function formatTrackerServers(list, isDefault) {
+    return `${list.join(', ')}${isDefault ? ` ${color.dim('(default)')}` : ''}`;
+}
 /**
  * The `--status` note's lines. Pure.
  *
@@ -131,7 +139,7 @@ export function formatTrackerStatus(input) {
     }
     lines.push(...(input.conventions.kind === 'none'
         ? ['Conventions: none (GitHub needs no learned conventions)', 'File:        none']
-        : [`Conventions: ${formatTrackerProvenance(input.conventions.provenance)}`, `File:        ${input.conventions.file}`]), `Mechanics:   ${formatTrackerMechanics(input.mechanics)}`, `Inference:   ${input.inference}`);
+        : [`Conventions: ${formatTrackerProvenance(input.conventions.provenance)}`, `File:        ${input.conventions.file}`]), `Mechanics:   ${formatTrackerMechanics(input.mechanics)}`, `Servers:     ${formatTrackerServers(input.servers.list, input.servers.isDefault)}`, `Inference:   ${input.inference}`);
     return lines.join('\n');
 }
 /** The real adapter — the ONE binding of each operation into the `--set` path. */
@@ -164,7 +172,8 @@ export function buildTrackerSetIO() {
 export async function runTrackerSet(opts) {
     const { devflowDir, current, requested, io } = opts;
     const messages = [];
-    await io.syncManifest(devflowDir, { provider: requested });
+    // The provider changes; the tracker servers are a different setting and ride along.
+    await io.syncManifest(devflowDir, { ...current, provider: requested });
     // [DR-22] a selection change re-arms the attempt counters; [DR-10] the
     // sentinel converges in both directions.
     const rearm = await io.rearmInference(devflowDir);
@@ -180,18 +189,72 @@ export async function runTrackerSet(opts) {
     });
     return { provider: requested, messages };
 }
+/** The real adapter — the ONE binding of each operation into the `--servers` path. */
+export function buildTrackerServersIO() {
+    return {
+        syncManifest: (devflowDir, state) => syncManifestFeature(devflowDir, 'tracker', state),
+        restamp: (claudeDir, servers, warn) => restampTrackerAgents({ claudeDir, servers, warn }),
+    };
+}
+/**
+ * Set the machine's tracker tool servers.
+ *
+ * Follows `--set`'s convergence order (D-TRACKER-CONVERGE-SET): the manifest first, then
+ * the installed agents, which are re-stamped ONLY when the manifest write landed, so an
+ * installed agent never names a list the manifest does not record. Unlike `--set`, a failed
+ * manifest write is the whole command failing (there is nothing else for it to do), so it is
+ * returned as `ok: false` for the caller to exit on; a failed re-stamp warns, it never aborts.
+ *
+ * `default` removes the key, so an absent `servers` stays the one spelling of the default.
+ * Never throws.
+ */
+export async function runTrackerServers(opts) {
+    const { devflowDir, claudeDir, current, requested, io } = opts;
+    const messages = [];
+    const next = requested.kind === 'default'
+        ? { provider: current.provider }
+        : { provider: current.provider, servers: requested.servers };
+    try {
+        await io.syncManifest(devflowDir, next);
+    }
+    catch (err) {
+        messages.push({
+            level: 'error',
+            text: `Could not write the manifest — the tracker servers were not changed (${err instanceof Error ? err.message : String(err)})`,
+        });
+        return { ok: false, state: current, messages };
+    }
+    const servers = effectiveTrackerServers(next);
+    const unchanged = servers.join('\n') === effectiveTrackerServers(current).join('\n');
+    const label = `${servers.join(', ')}${requested.kind === 'default' ? ' (default)' : ''}`;
+    messages.push({ level: unchanged ? 'info' : 'success', text: `Tracker servers: ${label}${unchanged ? ' (unchanged)' : ''}` });
+    const restamp = await io.restamp(claudeDir, servers, (message) => messages.push({ level: 'warn', text: message }));
+    const done = restamp.rewritten.length + restamp.unchanged.length;
+    if (restamp.absent.length === TRACKER_STAMPED_AGENTS.length && restamp.failed.length === 0) {
+        messages.push({ level: 'info', text: 'No installed Git or Tracker agent to update — run devflow init' });
+    }
+    else if (restamp.rewritten.length > 0) {
+        messages.push({ level: 'info', text: `Updated the installed ${restamp.rewritten.join(' and ')} agent${restamp.rewritten.length > 1 ? 's' : ''}` });
+    }
+    else if (done > 0 && restamp.failed.length === 0) {
+        messages.push({ level: 'info', text: 'The installed agents already carry this list' });
+    }
+    return { ok: true, state: next, messages };
+}
 export const trackerCommand = new Command('tracker')
-    .description('Show or set the machine\'s issue tracker provider')
+    .description('Show or set the machine\'s issue tracker provider and tracker servers')
     .option('--status', 'Show the provider in effect and its learned conventions file, and re-arm background inference')
     .option('--set <id>', 'Set the machine\'s default issue tracker provider: github, jira, or linear')
+    .option('--servers <names>', 'Set the tracker servers the Git and Tracker agents may call: comma-separated names, or "default"')
     .action(async (options) => {
     const devflowDir = getDevFlowDirectory();
-    const hasFlag = options.status || options.set !== undefined;
+    const hasFlag = options.status || options.set !== undefined || options.servers !== undefined;
     if (!hasFlag) {
         p.intro(color.bgCyan(color.white(' Tracker ')));
         const validIds = TRACKER_PROVIDERS.map(t => `${t.id} — ${t.hint}`).join('\n  ');
         p.note(`${color.cyan('devflow tracker --status')}      Show the provider and learned conventions\n` +
-            `${color.cyan('devflow tracker --set <id>')}    Set the machine's default provider\n\n` +
+            `${color.cyan('devflow tracker --set <id>')}    Set the machine's default provider\n` +
+            `${color.cyan('devflow tracker --servers <names>')}  Set the tracker servers the agents may call\n\n` +
             `Valid provider IDs:\n  ${validIds}`, 'Usage');
         p.outro(color.dim('github is the default — devflow tracker --set github returns to it'));
         return;
@@ -206,7 +269,17 @@ export const trackerCommand = new Command('tracker')
         }
         setProvider = parsed.value;
     }
-    const manifest = await readManifest(devflowDir);
+    // Validate --servers the same way: a bad name exits before any I/O, never repaired.
+    let setServers;
+    if (options.servers !== undefined) {
+        const parsed = parseTrackerServers(options.servers);
+        if (!parsed.ok) {
+            p.log.error(parsed.error);
+            process.exit(1);
+        }
+        setServers = parsed.value;
+    }
+    const manifest = await readManifest(devflowDir, { onWarning: (message) => p.log.warn(message) });
     if (!manifest) {
         p.log.error('No manifest found. Run devflow init first.');
         process.exit(1);
@@ -238,6 +311,7 @@ export const trackerCommand = new Command('tracker')
             selection,
             conventions,
             mechanics,
+            servers: { list: effectiveTrackerServers(current), isDefault: current.servers === undefined },
             inference,
         }), 'Tracker Status');
         if (!statusRearm.ok)
@@ -248,13 +322,34 @@ export const trackerCommand = new Command('tracker')
         return;
     }
     // ── Set ────────────────────────────────────────────────────────────────────
-    const outcome = await runTrackerSet({
-        devflowDir,
-        current,
-        requested: setProvider ?? current.provider,
-        io: buildTrackerSetIO(),
-    });
-    for (const msg of outcome.messages) {
+    // `--set` and `--servers` are independent settings and may be given together: the provider
+    // first, then the servers against the state it left.
+    const messages = [];
+    let state = current;
+    if (setProvider !== undefined) {
+        const outcome = await runTrackerSet({
+            devflowDir,
+            current,
+            requested: setProvider,
+            io: buildTrackerSetIO(),
+        });
+        messages.push(...outcome.messages);
+        state = { ...current, provider: outcome.provider };
+    }
+    let failed = false;
+    if (setServers !== undefined) {
+        const outcome = await runTrackerServers({
+            devflowDir,
+            claudeDir: getClaudeDirectory(),
+            current: state,
+            requested: setServers,
+            io: buildTrackerServersIO(),
+        });
+        messages.push(...outcome.messages);
+        state = outcome.state;
+        failed = !outcome.ok;
+    }
+    for (const msg of messages) {
         switch (msg.level) {
             case 'success':
                 p.log.success(msg.text);
@@ -270,7 +365,9 @@ export const trackerCommand = new Command('tracker')
                 break;
         }
     }
-    if (outcome.provider !== DEFAULT_TRACKER_PROVIDER) {
+    if (failed)
+        process.exit(1);
+    if (setProvider !== undefined && state.provider !== DEFAULT_TRACKER_PROVIDER) {
         p.log.info(color.dim('Your issue conventions are learned in the background at the next session start'));
     }
 });