agent-skillboard 0.2.15 → 0.2.17

package/src/lifecycle-cli.mjs

@@ -1,15 +1,9 @@
-import { execFile } from "node:child_process";
-import { access, chown, mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
-import { createInterface } from "node:readline";
-import { promisify } from "node:util";
-import { setupAgentSkillTargets, supportedAgentNames } from "./agent-skill-roots.mjs";
+import { isAbsolute, relative, resolve } from "node:path";
+import { runAgentLayerUninstallCommand } from "./agent-integration-cli.mjs";
 import { initProject } from "./init.mjs";
 import { uninstallProject } from "./uninstall.mjs";
 
-const AGENT_INTEGRATION_START = "<!-- BEGIN SKILLBOARD AGENT INTEGRATION -->";
-const AGENT_INTEGRATION_END = "<!-- END SKILLBOARD AGENT INTEGRATION -->";
-const execFileAsync = promisify(execFile);
+export { runSetupCommand } from "./agent-integration-cli.mjs";
 
 export async function runInitCommand(options, stdout, runtime = defaultRuntime()) {
   const root = resolve(options.get("dir") ?? ".");
@@ -45,61 +39,41 @@ export async function runInitCommand(options, stdout, runtime = defaultRuntime()
   return 0;
 }
 
-export async function runSetupCommand(options, stdout, runtime = defaultRuntime()) {
-  if (options.get("dir") !== undefined) {
-    throw new Error("skillboard setup is agent-layer setup and does not accept --dir");
+export async function runUninstallCommand(options, stdout, runtime = defaultRuntime()) {
+  if (options.get("agent-layer") === "true") {
+    return await runAgentLayerUninstallCommand(options, stdout, runtime);
   }
-  const env = runtime.env ?? process.env;
-  const home = await resolveSetupHome(env, runtime);
-  const targets = await agentSetupTargets(options, runtime, home);
-  if (targets.length === 0) {
-    stdout.write("No supported agent user skill roots were detected.\n");
-    stdout.write(`Create a supported agent home or pass --agent ${supportedAgentNames().join(",")} to choose targets.\n`);
-    return 1;
-  }
-  if (options.get("yes") !== "true") {
-    writeSetupConfirmation(stdout, targets, commandPrefix(runtime));
-    if (!canPrompt(runtime)) {
-      return 1;
-    }
-    const confirmed = await promptForSetup(runtime);
-    if (!confirmed) {
-      stdout.write("Skipped SkillBoard setup.\n");
-      return 1;
-    }
-  }
-  const result = await installAgentIntegration(targets, setupOwnership(env, runtime, home));
-  stdout.write("SkillBoard agent integration installed.\n");
-  writeList(stdout, "Created", result.created);
-  writeList(stdout, "Updated", result.updated);
-  writeList(stdout, "Unchanged", result.unchanged);
-  writeList(stdout, "Preserved", result.preserved);
-  stdout.write("Next:\n");
-  stdout.write("- Restart or refresh agents that cache user skills.\n");
-  stdout.write('- Ask the agent in a workspace: "Which skill should you use for this?"\n');
-  return 0;
-}
-
-export async function runUninstallCommand(options, stdout) {
   const removeConfig = options.get("remove-config") === "true";
   const resetConfig = options.get("reset-config") === "true";
   const purge = options.get("purge") === "true";
+  const keepSettings = options.get("keep-settings") === "true";
+  const removeReports = options.get("remove-reports") === "true";
+  const removeHooks = options.get("remove-hooks") === "true";
   if (removeConfig && resetConfig) {
     throw new Error("--remove-config and --reset-config are mutually exclusive");
   }
   if (removeConfig && purge) {
     throw new Error("--remove-config cannot be combined with --purge");
   }
+  if (keepSettings && purge) {
+    throw new Error("--keep-settings cannot be combined with --purge");
+  }
+  if (keepSettings && (removeConfig || resetConfig)) {
+    throw new Error("--keep-settings cannot be combined with --remove-config or --reset-config");
+  }
   const root = resolve(options.get("dir") ?? ".");
+  const granularCleanup = removeConfig || resetConfig || removeReports || removeHooks;
+  const cleanSettings = !keepSettings && (purge || !granularCleanup);
   const result = await uninstallProject({
     root,
     dryRun: options.get("dry-run") === "true",
+    keepBridge: keepSettings,
     removeConfig,
-    resetConfig: resetConfig || purge,
-    removeReports: options.get("remove-reports") === "true" || purge,
-    removeHooks: options.get("remove-hooks") === "true" || purge,
-    removeProjectState: purge,
-    removeEmptyDirs: options.get("keep-empty-dirs") !== "true"
+    resetConfig: resetConfig || cleanSettings,
+    removeReports: removeReports || cleanSettings,
+    removeHooks: removeHooks || cleanSettings,
+    removeProjectState: cleanSettings,
+    removeEmptyDirs: !keepSettings && options.get("keep-empty-dirs") !== "true"
   });
   stdout.write(`${result.dryRun ? "Dry run: " : ""}Uninstalled SkillBoard: ${root}\n`);
   writeList(stdout, "Removed", result.removed);
@@ -164,40 +138,6 @@ function writeNextCommands(stdout, next) {
   stdout.write(`- ${next.command} brief --workflow ${shellQuote(workflow)}${dir} --verbose\n`);
 }
 
-function writeSetupConfirmation(stdout, targets, command) {
-  stdout.write("SkillBoard setup installs agent-layer integration, not project files.\n");
-  stdout.write("It writes a SkillBoard guidance skill into detected user agent skill roots so agents can resolve skill priority when choices overlap.\n");
-  stdout.write("Targets:\n");
-  for (const target of targets) {
-    stdout.write(`- ${target.agent}: ${target.skillPath}\n`);
-  }
-  stdout.write("Run with --yes to install agent-layer integration:\n");
-  stdout.write(`- ${command} setup --agent ${targets.map((target) => target.agent).join(",")} --yes\n`);
-}
-
-function canPrompt(runtime) {
-  return runtime.stdin?.isTTY === true && runtime.stdout?.isTTY === true;
-}
-
-async function promptForSetup(runtime) {
-  const rl = createInterface({
-    input: runtime.stdin,
-    output: runtime.stdout
-  });
-  try {
-    const answer = await question(rl, "Install SkillBoard agent integration now? [y/N] ");
-    return /^(y|yes)$/i.test(answer.trim());
-  } finally {
-    rl.close();
-  }
-}
-
-function question(rl, prompt) {
-  return new Promise((resolve) => {
-    rl.question(prompt, resolve);
-  });
-}
-
 function formatList(values) {
   return values.length === 0 ? "none" : values.map((value) => `\`${value}\``).join(", ");
 }
@@ -221,226 +161,6 @@ function defaultRuntime() {
   };
 }
 
-async function agentSetupTargets(options, runtime, setupHome) {
-  const env = runtime.env ?? process.env;
-  const home = setupHome ?? await resolveSetupHome(env, runtime);
-  const requested = readCsv(options.get("agent"));
-  const supported = new Set(supportedAgentNames());
-  const names = requested.length === 0 ? supportedAgentNames() : requested;
-  const targets = [];
-  for (const name of names) {
-    if (!supported.has(name)) {
-      throw new Error(`Unsupported setup agent: ${name}`);
-    }
-    targets.push(...await setupAgentSkillTargets(name, home, env, { includeFallback: requested.length > 0 }));
-  }
-  return targets;
-}
-
-async function resolveSetupHome(env, runtime) {
-  const explicit = nonEmpty(env.SKILLBOARD_SETUP_HOME);
-  if (explicit !== null) {
-    return explicit;
-  }
-  if (shouldUseSudoUserHome(env)) {
-    const sudoHome = nonEmpty(env.SUDO_HOME)
-      ?? await passwdHome(env.SUDO_USER, runtime.passwdPath ?? "/etc/passwd")
-      ?? await getentHome(env.SUDO_USER, env)
-      ?? await conventionalUserHome(env.SUDO_USER);
-    if (sudoHome !== null) {
-      return sudoHome;
-    }
-  }
-  return env.HOME ?? env.USERPROFILE;
-}
-
-function setupOwnership(env, runtime, home) {
-  if (process.platform === "win32" || !shouldUseSudoUserHome(env)) {
-    return null;
-  }
-  const uid = parseNonNegativeInteger(env.SUDO_UID);
-  const gid = parseNonNegativeInteger(env.SUDO_GID);
-  if (uid === null || gid === null) {
-    return null;
-  }
-  return {
-    uid,
-    gid,
-    home: resolve(home),
-    chown: runtime.chown ?? chown
-  };
-}
-
-function parseNonNegativeInteger(value) {
-  if (value === undefined || !/^\d+$/.test(value)) {
-    return null;
-  }
-  const parsed = Number(value);
-  return Number.isSafeInteger(parsed) ? parsed : null;
-}
-
-function shouldUseSudoUserHome(env) {
-  const sudoUser = nonEmpty(env.SUDO_USER);
-  return process.platform !== "win32"
-    && sudoUser !== null
-    && sudoUser !== "root"
-    && (
-      env.SUDO_UID !== undefined
-      || env.SUDO_GID !== undefined
-      || env.USER === "root"
-      || env.LOGNAME === "root"
-      || env.HOME === "/root"
-    );
-}
-
-async function passwdHome(user, passwdPath) {
-  const text = await readFile(passwdPath, "utf8").catch(() => "");
-  for (const line of text.split("\n")) {
-    if (line.startsWith(`${user}:`)) {
-      return nonEmpty(line.split(":")[5]);
-    }
-  }
-  return null;
-}
-
-async function getentHome(user, env) {
-  try {
-    const { stdout } = await execFileAsync("getent", ["passwd", user], {
-      env,
-      timeout: 1000
-    });
-    return nonEmpty(stdout.trim().split(":")[5]);
-  } catch {
-    return null;
-  }
-}
-
-async function conventionalUserHome(user) {
-  const candidates = process.platform === "darwin"
-    ? [`/Users/${user}`]
-    : [`/home/${user}`];
-  for (const candidate of candidates) {
-    if (await exists(candidate)) {
-      return candidate;
-    }
-  }
-  return null;
-}
-
-async function exists(path) {
-  return access(path).then(() => true, () => false);
-}
-
-function nonEmpty(value) {
-  return value === undefined || value.trim() === "" ? null : value;
-}
-
-async function installAgentIntegration(targets, ownership = null) {
-  const created = [];
-  const updated = [];
-  const unchanged = [];
-  const preserved = [];
-  const content = agentIntegrationSkill();
-  for (const target of targets) {
-    const existing = await readFile(target.skillPath, "utf8").catch((error) => {
-      if (error?.code === "ENOENT") {
-        return null;
-      }
-      throw error;
-    });
-    if (existing === content) {
-      await applyOwnership(target.skillPath, ownership);
-      unchanged.push(`${target.agent}:${target.skillPath}`);
-      continue;
-    }
-    if (existing !== null && !existing.includes(AGENT_INTEGRATION_START)) {
-      preserved.push(`${target.agent}:${target.skillPath}`);
-      continue;
-    }
-    await mkdir(dirname(target.skillPath), { recursive: true });
-    await writeFile(target.skillPath, content, "utf8");
-    await applyOwnership(target.skillPath, ownership);
-    (existing === null ? created : updated).push(`${target.agent}:${target.skillPath}`);
-  }
-  return { created, updated, unchanged, preserved };
-}
-
-async function applyOwnership(path, ownership) {
-  if (ownership === null) {
-    return;
-  }
-  for (const ownedPath of ownershipPaths(path, ownership.home)) {
-    await ownership.chown(ownedPath, ownership.uid, ownership.gid);
-  }
-}
-
-function ownershipPaths(path, home) {
-  const resolvedHome = resolve(home);
-  const resolvedPath = resolve(path);
-  if (!isInside(resolvedPath, resolvedHome)) {
-    return [];
-  }
-  const directories = [];
-  let current = dirname(resolvedPath);
-  while (current !== resolvedHome && isInside(current, resolvedHome)) {
-    directories.push(current);
-    const parent = dirname(current);
-    if (parent === current) {
-      break;
-    }
-    current = parent;
-  }
-  return [...directories.reverse(), resolvedPath];
-}
-
-function isInside(path, parent) {
-  const relativePath = relative(parent, path);
-  return relativePath !== "" && !relativePath.startsWith("..") && !isAbsolute(relativePath);
-}
-
-function agentIntegrationSkill() {
-  return `---
-name: skillboard
-description: Use SkillBoard when several installed skills could apply, a skill choice is ambiguous, or the user asks which skill should be used, preferred, avoided, reviewed, or prioritized for the current workflow.
----
-${AGENT_INTEGRATION_START}
-# SkillBoard Agent Integration
-
-Use this skill to let SkillBoard guide skill selection above individual projects.
-
-## Layering
-
-- SkillBoard is the user-level control plane for skill priority, overlap resolution, and workflow-aware routing.
-- Project management belongs to the agent or workspace layer. Do not initialize, attach, rewrite, or manage a project just because SkillBoard is installed.
-- Package install and \`skillboard setup\` install user-agent guidance only.
-
-## Default Behavior
-
-- Installed user skills are usable by default unless the runtime, user, or local instructions disable them.
-- Do not ask for permission merely because you selected a skill.
-- When you use a skill, disclose it briefly at the start and completion.
-- Use SkillBoard when more than one skill matches, when skills overlap, or when workflow priority should choose between plausible skills.
-
-## Cross-Agent Skill Reuse
-
-- When the user wants to use a skill from another agent, run \`skillboard import-skill --from <source-agent> --to <this-agent> --skill <skill> --json\`.
-- If SkillBoard reports the skill is compatible, install it with \`--yes\` and use the copied target-agent skill.
-- If SkillBoard reports \`needs-adaptation\`, explain the compatibility reasons and ask before changing the skill body for this agent.
-- If the user approves, inspect the source skill, write an adapted \`SKILL.md\` for this agent, then install it with \`skillboard import-skill --from <source-agent> --to <this-agent> --skill <skill> --adapted-file <adapted-skill.md> --yes --json\`.
-- This is still user-agent setup. Do not create or mutate project policy files for cross-agent skill reuse.
-
-## Ambiguity Resolution
-
-1. Identify the candidate skills that match the request.
-2. Prefer the skill whose description, workflow guidance, and local instructions most directly match the user's task.
-3. If a project or agent has explicit SkillBoard policy, use \`skillboard brief --intent <request> --json\` or \`skillboard route <intent> --workflow <name> --json\` to break ties.
-4. If the best choice is still ambiguous or the choice would change persistent policy, ask the user which priority to remember.
-5. Continue with the selected skill; do not stop only because other candidate skills exist.
-
-${AGENT_INTEGRATION_END}
-`;
-}
-
 function commandPrefix(runtime) {
   const entrypoint = runtime.entrypointPath ?? "";
   const normalized = entrypoint.replace(/\\/g, "/");

package/src/lifecycle-content.mjs

@@ -24,7 +24,8 @@ Your responsibility is to answer skill availability questions from SkillBoard, t
 
 ## Product Goal
 
-- SkillBoard is a non-blocking AI skill routing control plane, not a pre-task settings checklist.
+- SkillBoard is a permissive AI skill routing layer, not a pre-task settings checklist.
+- Keep installed skills broadly available by default; use SkillBoard to resolve overlap when several skills could steer the same task.
 - Read \`docs/ai-skill-routing-goal.md\` before changing routing, brief, bridge, policy, or workflow UX.
 - Preserve the loop: observe → route → work → explain briefly → ask after → remember policy.
 - SkillBoard does not rewrite \`SKILL.md\` bodies to personalize behavior; record usage policy for when to use, prefer, reference, avoid, or block skills.
@@ -33,7 +34,8 @@ Your responsibility is to answer skill availability questions from SkillBoard, t
 
 - Use SkillBoard as the source of truth for project-local policy and workflow priority; installed \`SKILL.md\` files are candidates, not enough to resolve overlap by themselves.
 - Read the current brief before answering: \`skillboard brief --json --config skillboard.config.yaml --skills skills\`. If the workflow is known, include \`--workflow <name>\`; add \`--include-actions\` when the user wants you to mediate a change.
-- When the user asks which skill fits a task, read \`skillboard brief --intent <request> --json --config skillboard.config.yaml --skills skills\`. Include \`--workflow <name>\` when known. Read \`assistant_guidance.route\`; use \`recommended_skill\`, \`fallback_skills\`, \`route_candidates\`, \`post_use_policy_suggestion\`, and \`guard_command\` instead of guessing from raw skill text. Inspect \`route_candidates\` when several skills match so denied candidates and selected fallbacks are clear. If \`post_use_policy_suggestion\` is present, work first with the allowed routed skill, then ask after completion whether to remember the suggested policy. If no skill matches, ask a clarifying question before choosing a skill.
+- For ordinary user requests, work normally unless skill choice is ambiguous, several skills overlap, workflow priority matters, or the user explicitly asks for a SkillBoard or skill decision. In those cases, read \`skillboard brief --intent <request> --json --config skillboard.config.yaml --skills skills\`. Include \`--workflow <name>\` when known. Read \`assistant_guidance.route\`; use \`recommended_skill\`, \`fallback_skills\`, \`route_candidates\`, \`overlap_resolution\`, \`policy_memory\`, \`post_use_policy_suggestion\`, and \`guard_command\` instead of guessing from raw skill text. Inspect \`overlap_resolution\` and \`route_candidates\` when several skills match so allowed overlap, denied candidates, and selected fallbacks are clear. If \`policy_memory\` is present, mention after completion that remembered or configured policy selected this skill even though other allowed skills were available. If \`post_use_policy_suggestion\` is present, work first with the allowed routed skill, then ask after completion whether to remember the suggested policy. If no skill matches, ask a clarifying question before choosing a skill.
+- If the user explicitly requests a specific already-allowed skill, honor that request after guard use instead of rerouting away solely because another skill also matches.
 - Treat the brief sections headed "What your AI can use now", "Needs your decision", and "Blocked for safety" as the availability summary; do not infer availability from \`SKILL.md\` bodies.
 - Treat "Needs your decision" as a one-time decision queue, not a persistent blocked state. "Blocked for safety" means the skill/source/workflow is hard-blocked until policy or provenance changes.
 - Use \`skillboard can-use <skill-id> --workflow <name> --config skillboard.config.yaml --skills skills --json\` for machine-readable agent decisions.

package/src/route-advisory.mjs

@@ -0,0 +1,214 @@
+import { command } from "./advisor/action-core.mjs";
+
+const DEFAULT_CONFIG_PATH = "skillboard.config.yaml";
+const DEFAULT_SKILLS_ROOT = "skills";
+
+export function routeCandidate(entry, selected) {
+  return {
+    skill: entry.skill,
+    role: entry.role,
+    selected,
+    guard_allowed: entry.guard.allowed,
+    guard_reasons: entry.guard.reasons,
+    guard_roles: entry.guard.roles,
+    capability_roles: entry.guard.capabilityRoles
+  };
+}
+
+export function usageDisclosure(skillId, policyMemory = null) {
+  const finishMessage = policyMemory?.finish_disclosure
+    ?? `I used ${skillId} for this request.`;
+  return {
+    confirmation_required: false,
+    start: `State at the start that ${skillId} is being used for this request.`,
+    finish: policyMemory === null
+      ? `State at completion that ${skillId} was used.`
+      : `State at completion that ${skillId} was used because remembered or configured policy preferred it over other allowed skills.`,
+    start_message: `I will use ${skillId} for this request.`,
+    finish_message: finishMessage,
+    policy_memory: policyMemory,
+    guard: "Run the guard automatically immediately before invocation. Ask the user only if the guard denies use or a policy-changing action is needed."
+  };
+}
+
+export function selectedRouteSkill(routedSkills) {
+  return routedSkills.find((entry) => entry.guard.allowed) ?? routedSkills[0] ?? null;
+}
+
+export function allowedFallbackSkills(routedSkills, recommended) {
+  return routedSkills
+    .filter((entry) => entry.guard.allowed && entry.skill !== recommended?.skill)
+    .map((entry) => entry.skill);
+}
+
+export function overlapResolutionForRoute({ matchedCapability, recommended, routedSkills, workflowName }) {
+  if (recommended === null || routedSkills.length < 2) {
+    return null;
+  }
+  const matchedSkills = routedSkills.map((entry) => entry.skill);
+  const allowedSkills = routedSkills.filter((entry) => entry.guard.allowed).map((entry) => entry.skill);
+  const deniedSkills = routedSkills.filter((entry) => !entry.guard.allowed).map((entry) => entry.skill);
+  if (deniedSkills.length > 0 && recommended.guard.allowed) {
+    return {
+      status: "resolved",
+      mode: "allowed-fallback",
+      selected_skill: recommended.skill,
+      matched_skills: matchedSkills,
+      allowed_skills: allowedSkills,
+      denied_skills: deniedSkills,
+      summary: `Some matching skills are denied for ${matchedCapability}; SkillBoard keeps allowed skills available and routes ${workflowName} to ${recommended.skill}.`
+    };
+  }
+  if (allowedSkills.length > 1) {
+    return {
+      status: "resolved",
+      mode: "permissive-routing",
+      selected_skill: recommended.skill,
+      matched_skills: matchedSkills,
+      allowed_skills: allowedSkills,
+      denied_skills: deniedSkills,
+      summary: `Multiple allowed skills match ${matchedCapability}; SkillBoard keeps them available and routes ${workflowName} to ${recommended.skill}.`
+    };
+  }
+  return {
+    status: "blocked",
+    mode: "guard-denied",
+    selected_skill: recommended.skill,
+    matched_skills: matchedSkills,
+    allowed_skills: allowedSkills,
+    denied_skills: deniedSkills,
+    summary: `Matching skills exist for ${matchedCapability}, but the guard currently denies the selected route.`
+  };
+}
+
+export function policyMemoryForRoute({ matchedCapability, routeMatch, recommended, routedSkills, workflowName }) {
+  if (recommended === null || recommended.guard.allowed !== true || recommended.role !== "preferred" || !routeMatch.required_by_workflow) {
+    return null;
+  }
+  const alternatives = routedSkills
+    .filter((entry) => entry.guard.allowed && entry.skill !== recommended.skill)
+    .map((entry) => entry.skill);
+  if (alternatives.length === 0) {
+    return null;
+  }
+  const alternativeText = alternatives.join(", ");
+  return {
+    status: "applied",
+    mode: "remembered-or-configured-preference",
+    selected_skill: recommended.skill,
+    available_alternatives: alternatives,
+    summary: `Remembered or configured policy selected ${recommended.skill} for ${matchedCapability} in ${workflowName}; other allowed skills were also available: ${alternativeText}.`,
+    finish_disclosure: `I used ${recommended.skill} for this request because SkillBoard has a remembered or configured preference for it; other allowed skills were also available: ${alternativeText}.`
+  };
+}
+
+export function postUsePolicySuggestionForCapabilityRoute({ matchedCapability, routeMatch, recommended, routedSkills, workflowName, options }) {
+  return postUsePolicySuggestionForDeniedPreferredFallback({
+    matchedCapability,
+    recommended,
+    routedSkills,
+    workflowName,
+    options
+  }) ?? postUsePolicySuggestionForAllowedAmbiguity({
+    matchedCapability,
+    routeMatch,
+    recommended,
+    routedSkills,
+    workflowName,
+    options
+  });
+}
+
+function postUsePolicySuggestionForDeniedPreferredFallback({ matchedCapability, recommended, routedSkills, workflowName, options }) {
+  if (recommended === null || recommended.role !== "fallback" || recommended.guard.allowed !== true) {
+    return null;
+  }
+  const preferred = routedSkills.find((entry) => entry.role === "preferred");
+  if (preferred === undefined || preferred.guard.allowed === true) {
+    return null;
+  }
+  return {
+    timing: "after_use",
+    mode: "ask_after_use",
+    reason: `SkillBoard selected fallback ${recommended.skill} because preferred skill ${preferred.skill} is denied. After completing the task, ask whether to remember ${recommended.skill} as the preferred skill for ${matchedCapability} in ${workflowName}.`,
+    question: `Should I remember ${recommended.skill} as the preferred skill for similar ${matchedCapability} requests in ${workflowName}?`,
+    requires_confirmation: true,
+    suggested_policy: {
+      kind: "prefer-skill",
+      skill: recommended.skill,
+      workflow: workflowName,
+      capability: matchedCapability,
+      command_hint: command([
+        "skillboard", "prefer", recommended.skill,
+        "--workflow", workflowName,
+        "--capability", matchedCapability,
+        "--config", routeConfigPath(options),
+        "--skills", routeSkillsRoot(options)
+      ]).display
+    }
+  };
+}
+
+function postUsePolicySuggestionForAllowedAmbiguity({ matchedCapability, routeMatch, recommended, routedSkills, workflowName, options }) {
+  if (recommended === null || recommended.guard.allowed !== true || routeMatch.required_by_workflow) {
+    return null;
+  }
+  const allowedSkills = routedSkills.filter((entry) => entry.guard.allowed);
+  if (allowedSkills.length < 2) {
+    return null;
+  }
+  return {
+    timing: "after_use",
+    mode: "ask_after_use",
+    reason: `SkillBoard found multiple allowed skills for ${matchedCapability} and selected ${recommended.skill}. After completing the task, ask whether to remember ${recommended.skill} as the preferred skill for ${matchedCapability} in ${workflowName} to reduce future ambiguity.`,
+    question: `Should I remember ${recommended.skill} as the preferred skill for similar ${matchedCapability} requests in ${workflowName}?`,
+    requires_confirmation: true,
+    suggested_policy: {
+      kind: "prefer-skill",
+      skill: recommended.skill,
+      workflow: workflowName,
+      capability: matchedCapability,
+      command_hint: command([
+        "skillboard", "prefer", recommended.skill,
+        "--workflow", workflowName,
+        "--capability", matchedCapability,
+        "--config", routeConfigPath(options),
+        "--skills", routeSkillsRoot(options)
+      ]).display
+    }
+  };
+}
+
+export function recommendationReason({ match, matchedFields, matchedTerms, skill, guard }) {
+  const fieldText = matchedFields.length === 0
+    ? ""
+    : ` through ${matchedFields.join(", ")}`;
+  const termText = matchedTerms.length === 0
+    ? ""
+    : ` (${matchedTerms.join(", ")})`;
+  if (skill === null || guard === null) {
+    return `${match}${fieldText}${termText}, but no workflow-bound skill is available.`;
+  }
+  if (guard.allowed) {
+    return `${match}${fieldText}${termText}; recommended ${skill} because the guard allows ${skill}.`;
+  }
+  const reason = guard.reasons[0] ?? "the guard did not provide a reason";
+  return `${match}${fieldText}${termText}; recommended ${skill}, but the guard currently denies it: ${reason}`;
+}
+
+export function guardCommand(skillId, workflowName, options) {
+  return command([
+    "skillboard", "guard", "use", skillId,
+    "--workflow", workflowName,
+    "--config", routeConfigPath(options),
+    "--skills", routeSkillsRoot(options)
+  ]).display;
+}
+
+function routeConfigPath(options) {
+  return options.configPath ?? DEFAULT_CONFIG_PATH;
+}
+
+function routeSkillsRoot(options) {
+  return options.skillsRoot ?? DEFAULT_SKILLS_ROOT;
+}