agent-skillboard 0.2.18 → 0.3.1

package/src/inventory-refresh.mjs

@@ -1,45 +1,194 @@
-import { readFile, writeFile } from "node:fs/promises";
-import { isAbsolute, resolve } from "node:path";
+import { chmod, lstat, mkdir, open, readFile, realpath, rm } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import YAML from "yaml";
 import { discoverAgentSkillInventory, mergeAgentSkillInventory } from "./agent-inventory.mjs";
 import { textChangePlan } from "./change-plan.mjs";
+import { buildGeneratedInventory, mergeV2InventoryPolicy, renderGeneratedInventory } from "./inventory-json.mjs";
+import { atomicWrite, optionalRead } from "./migration/v2-files.mjs";
+import { loadWorkspace } from "./workspace.mjs";
+
+const MINIMAL_V2_POLICY = "version: 2\nskills: {}\n";
 
 export async function refreshAgentInventory(options = {}) {
   const root = resolve(options.root ?? ".");
-  const configPath = resolveUnderRoot(root, options.configPath ?? "skillboard.config.yaml");
-  const inventory = await discoverAgentSkillInventory({
+  const configPath = resolveUnderRoot(root, options.configPath ?? "skillboard.config.yaml", "Inventory refresh config path");
+  return withRefreshLock(root, async () => refreshLocked({ ...options, root, configPath }));
+}
+
+async function refreshLocked(options) {
+  const { root, configPath } = options;
+  const configStats = await lstat(configPath).catch(missingOnly);
+  if (configStats?.isSymbolicLink()) {
+    throw new Error("Inventory refresh config path must not be a symbolic link.");
+  }
+  const bootstrappedV2 = configStats === undefined;
+  const current = bootstrappedV2 ? MINIMAL_V2_POLICY : await readFile(configPath, "utf8");
+  if (!bootstrappedV2) {
+    await loadWorkspace({ configPath });
+  }
+  const inventory = options.inventory ?? await discoverAgentSkillInventory({
     roots: options.roots,
     home: options.home,
-    env: options.env
+    env: options.env,
+    registeredRoots: options.registeredRoots
   });
-  const current = await readFile(configPath, "utf8");
-  const merged = mergeAgentSkillInventory(current, inventory);
+  const configVersion = YAML.parse(current)?.version;
+  const generatedInventory = configVersion === 2
+    ? await buildGeneratedInventory(inventory, { root, home: options.home ?? options.env?.HOME })
+    : null;
+  const inventoryPath = resolveUnderRoot(root, options.inventoryPath ?? ".skillboard/inventory.json", "Generated inventory target");
+  const inventoryText = generatedInventory === null ? null : renderGeneratedInventory(generatedInventory);
+  if (inventoryText !== null) {
+    await assertGeneratedInventoryTarget(root, inventoryPath);
+  }
+  const previousInventoryText = inventoryText === null
+    ? null
+    : await readFile(inventoryPath, "utf8").catch((error) => error?.code === "ENOENT" ? "" : Promise.reject(error));
+  const projected = configVersion === 2
+    ? mergeV2InventoryPolicy(current, inventory)
+    : mergeAgentSkillInventory(current, inventory);
+  const merged = configVersion === 1 && options.preserveLegacyPolicy === true
+    ? { ...projected, text: current }
+    : projected;
   const plan = textChangePlan(current, merged.text);
   const dryRun = options.dryRun === true;
 
-  if (plan.changed && !dryRun) {
-    await writeFile(configPath, merged.text, "utf8");
+  const inventoryChanged = inventoryText !== null && inventoryText !== previousInventoryText;
+  if (!dryRun) {
+    const [previousConfig, previousInventory] = await Promise.all([
+      optionalRead(configPath),
+      inventoryText === null ? Promise.resolve(null) : optionalRead(inventoryPath)
+    ]);
+    try {
+      if (inventoryChanged) {
+        await mkdir(dirname(inventoryPath), { recursive: true });
+        const writeInventory = options.writeInventory ?? writeInventoryFile;
+        await writeInventory(inventoryPath, inventoryText);
+      }
+      if (bootstrappedV2) {
+        const writeConfig = options.writeConfig ?? atomicWrite;
+        await writeConfig(configPath, Buffer.from(merged.text));
+      } else if (plan.changed) {
+        const writeConfig = options.writeConfig ?? atomicWrite;
+        await writeConfig(configPath, Buffer.from(merged.text));
+      }
+      if (inventoryText !== null) await chmod(inventoryPath, 0o600);
+    } catch (error) {
+      await restoreFile(configPath, previousConfig);
+      if (inventoryText !== null) await restoreFile(inventoryPath, previousInventory);
+      throw error;
+    }
   }
 
   return {
     dryRun,
-    configPath,
+    bootstrappedV2,
+    configPath: relativeArtifactPath(root, configPath),
+    inventoryPath: generatedInventory === null ? null : relativeArtifactPath(root, inventoryPath),
+    inventoryChanged,
     changed: plan.changed,
     plan,
     scan: {
       scannedSkills: inventory.scannedSkills ?? inventory.skills.length,
       scannedInstallUnits: inventory.installUnits.length,
       addedSkills: merged.addedSkills,
-      addedInstallUnits: merged.addedInstallUnits,
-      updatedInstallUnits: merged.updatedInstallUnits,
-      addedWorkflows: merged.addedWorkflows,
-      addedHarnesses: merged.addedHarnesses,
-      skippedSkills: merged.skippedSkills,
-      reviewNotes: merged.reviewNotes,
-      warnings: inventory.warnings ?? []
+      addedInstallUnits: merged.addedInstallUnits ?? [],
+      updatedInstallUnits: merged.updatedInstallUnits ?? [],
+      addedWorkflows: merged.addedWorkflows ?? [],
+      addedHarnesses: merged.addedHarnesses ?? [],
+      skippedSkills: merged.skippedSkills ?? [],
+      reviewNotes: merged.reviewNotes ?? [],
+      warnings: [...(inventory.warnings ?? []), ...(generatedInventory?.redactions.warnings ?? [])],
+      redactedPaths: generatedInventory?.redactions.path_count ?? 0
     }
   };
 }
 
-function resolveUnderRoot(root, path) {
-  return isAbsolute(path) ? path : resolve(root, path);
+async function withRefreshLock(root, operation) {
+  const lockPath = join(root, ".skillboard-inventory-refresh.lock");
+  let handle;
+  try {
+    handle = await open(lockPath, "wx", 0o600);
+  } catch (error) {
+    if (error?.code === "EEXIST") {
+      throw new Error("Another inventory refresh is already using this project.");
+    }
+    throw error;
+  }
+  try {
+    await handle.writeFile(`${process.pid}\n`);
+    return await operation();
+  } finally {
+    await handle.close();
+    await rm(lockPath, { force: true });
+  }
+}
+
+function resolveUnderRoot(root, path, label) {
+  const target = isAbsolute(path) ? resolve(path) : resolve(root, path);
+  if (!isPathInside(root, target)) {
+    throw new Error(`${label} must remain inside the project root.`);
+  }
+  return target;
+}
+
+async function assertGeneratedInventoryTarget(root, target) {
+  if (!isPathInside(root, target)) {
+    throw new Error(`Generated inventory target is outside the project root: ${target}`);
+  }
+  const targetStats = await lstat(target).catch(missingOnly);
+  if (targetStats?.isSymbolicLink()) {
+    throw new Error(`Generated inventory target is a symlink and may resolve outside the project root: ${target}`);
+  }
+  const existingParent = await nearestExistingDirectory(dirname(target));
+  const [realRoot, realParent] = await Promise.all([realpath(root), realpath(existingParent)]);
+  if (!isPathInside(realRoot, realParent)) {
+    throw new Error(`Generated inventory target resolves outside the project root: ${target}`);
+  }
+}
+
+async function nearestExistingDirectory(start) {
+  let candidate = start;
+  while (true) {
+    const stats = await lstat(candidate).catch(missingOnly);
+    if (stats !== undefined) {
+      if (!stats.isDirectory() && !stats.isSymbolicLink()) {
+        throw new Error(`Generated inventory parent is not a directory: ${candidate}`);
+      }
+      return candidate;
+    }
+    const parent = dirname(candidate);
+    if (parent === candidate) {
+      throw new Error(`Generated inventory parent does not exist: ${start}`);
+    }
+    candidate = parent;
+  }
+}
+
+function missingOnly(error) {
+  if (error?.code === "ENOENT") {
+    return undefined;
+  }
+  throw error;
+}
+
+function isPathInside(root, candidate) {
+  const rel = relative(root, candidate);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+async function writeInventoryFile(path, text) {
+  await atomicWrite(path, Buffer.from(text));
+}
+
+async function restoreFile(path, bytes) {
+  if (bytes === null) {
+    await rm(path, { force: true });
+    return;
+  }
+  await atomicWrite(path, bytes);
+}
+
+function relativeArtifactPath(root, path) {
+  return relative(root, path).replace(/\\/g, "/") || ".";
 }

package/src/lifecycle-cli.mjs

@@ -2,6 +2,7 @@ import { isAbsolute, relative, resolve } from "node:path";
 import { runAgentLayerUninstallCommand } from "./agent-integration-cli.mjs";
 import { initProject } from "./init.mjs";
 import { uninstallProject } from "./uninstall.mjs";
+import { uninstallUser } from "./user-uninstall.mjs";
 
 export { runSetupCommand } from "./agent-integration-cli.mjs";
 
@@ -40,6 +41,9 @@ export async function runInitCommand(options, stdout, runtime = defaultRuntime()
 }
 
 export async function runUninstallCommand(options, stdout, runtime = defaultRuntime()) {
+  if (options.get("user") === "true") {
+    return await runUserUninstallCommand(options, stdout, runtime);
+  }
   if (options.get("agent-layer") === "true") {
     return await runAgentLayerUninstallCommand(options, stdout, runtime);
   }
@@ -82,6 +86,36 @@ export async function runUninstallCommand(options, stdout, runtime = defaultRunt
   return 0;
 }
 
+async function runUserUninstallCommand(options, stdout, runtime) {
+  const allowed = new Set(["user", "dry-run", "yes", "json"]);
+  for (const option of options.keys()) {
+    if (!allowed.has(option)) {
+      throw new Error(`Unknown option for uninstall --user: --${option}`);
+    }
+  }
+  const dryRun = options.get("dry-run") === "true";
+  if (!dryRun && options.get("yes") !== "true") {
+    throw new Error("skillboard uninstall --user requires --yes; preview first with --dry-run");
+  }
+  const result = await uninstallUser({
+    dryRun,
+    env: runtime.env ?? process.env,
+    runtime
+  });
+  if (options.get("json") === "true") {
+    stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return 0;
+  }
+  stdout.write(`${dryRun ? "Dry run: " : ""}Uninstalled SkillBoard user state.\n`);
+  writeList(stdout, "Managed copies", result.managed_copies.map((copy) => copy.path));
+  writeList(stdout, "Guidance removed", result.guidance.removed);
+  writeList(stdout, "Guidance updated", result.guidance.updated);
+  writeList(stdout, "State", result.state_paths);
+  writeList(stdout, "Preserved", result.preserved);
+  if (dryRun) stdout.write("Run skillboard uninstall --user --yes to apply this plan.\n");
+  return 0;
+}
+
 function writeList(stdout, label, values) {
   if (values.length > 0) {
     stdout.write(`${label}: ${formatList(values)}\n`);
@@ -104,18 +138,12 @@ function writeCountedList(stdout, label, values) {
 
 function writeSafetyDefault(stdout, safety) {
   stdout.write("Skill selection default:\n");
-  stdout.write("- Installed user skills are usable unless runtime, user, or local instructions disable them.\n");
-  if (safety.automatic === 0) {
-    stdout.write("- No automatic model invocation was enabled.\n");
-  } else {
-    stdout.write(`- ${safety.automatic} automatic skills enabled by existing policy.\n`);
-  }
-  stdout.write("- Imported local skills are available on request in generated local policy.\n");
-  stdout.write("- Runtime/plugin/system skills require source review before automatic invocation.\n");
-  stdout.write(`- ${safety.automatic} automatic skills enabled\n`);
-  stdout.write(`- ${safety.manualOnly} manual-only skills available\n`);
-  stdout.write(`- ${safety.routerOnly} router-only skills available\n`);
-  stdout.write(`- ${safety.blocked} blocked/quarantined for safety\n`);
+  stdout.write("- Valid installed skills default to enabled and agent-local.\n");
+  stdout.write("- Users may disable a skill or explicitly share that skill across agents.\n");
+  stdout.write("- Optional preference ranks candidates and never changes availability.\n");
+  stdout.write("- Source and provenance are audit metadata, never availability.\n");
+  stdout.write(`- ${safety.enabled} enabled skills\n`);
+  stdout.write(`- ${safety.disabled} disabled skills\n`);
 }
 
 function writeNextCommands(stdout, next) {

package/src/lifecycle-content.mjs

@@ -2,17 +2,8 @@ export const BRIDGE_START = "<!-- BEGIN SKILLBOARD -->";
 export const BRIDGE_END = "<!-- END SKILLBOARD -->";
 
 export function defaultConfig() {
-  return `version: 1
-defaults:
-  invocation_policy: deny-by-default
-  allow_model_invocation: false
-  require_explicit_workflow: true
-
+  return `version: 2
 skills: {}
-capabilities: {}
-harnesses: {}
-workflows: {}
-install_units: {}
 `;
 }
 
@@ -20,40 +11,49 @@ export function bridgeBlock() {
   return `${BRIDGE_START}
 # SkillBoard Control Plane
 
-Your responsibility is to answer skill availability questions from SkillBoard, translate user intent into current action ids, ask for one confirmation only before policy-changing actions, apply one current action, reread the post-apply brief, and run the guard automatically before invocation.
-
-## Product Goal
-
-- 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.
-
-## Availability
-
-- 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.
-- 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.
-
-## Intent to Action
-
-- Translate user intent into current action ids from the current brief, not saved output.
-- For action cards, read \`skillboard brief --json --config skillboard.config.yaml --skills skills --include-actions\`, pick one current action id, ask the user for one confirmation, then run \`skillboard apply-action <action-id> --config skillboard.config.yaml --skills skills --yes --json\`. Include \`--workflow <name>\` when a workflow is selected.
-- After \`skillboard apply-action <action-id> ... --yes --json\`, reread the returned post-apply brief before answering the next availability question or applying another action. \`apply-action\` re-resolves current actions; do not apply cached or stale action ids, do not apply multiple actions, and do not run raw action-card shell text as the primary apply path.
-- For an already-allowed skill, do not ask for another approval. Run \`skillboard guard use <skill-id> --workflow <name> --config skillboard.config.yaml --skills skills\` automatically. Say at the start: "I will use <skill-id> for this request." Say at completion: "I used <skill-id> for this request." Treat this disclosure as an audit trace, not a permission prompt. Ask the user only if the guard denies use or a policy-changing action is needed.
-
-## Operations
-
-- Source trust: run \`skillboard audit sources --config skillboard.config.yaml --skills skills\` before trusting newly imported external skill sources; after review, use \`skillboard review install-unit <unit-id> --trust-level reviewed --config skillboard.config.yaml --skills skills\`. Unreviewed runtime sources are a one-time review decision, not a default block recommendation; after review, activate only the needed quarantined skills as manual-only workflow skills and use ask-after policy suggestions for future preferences.
-- Health: run \`skillboard doctor --config skillboard.config.yaml --skills skills\` or \`skillboard status --config skillboard.config.yaml --skills skills --json\`; add \`--strict\` when review-needed safe mode should fail automation.
-- Hook action cards: prefer \`skillboard apply-action <action-id> --yes --json\`. The underlying manual preview is \`skillboard hook install --workflow <name> --config skillboard.config.yaml --skills skills --out .skillboard/hooks/<name>-guard.sh --dry-run --json\`; inspect \`planned.preview.shell\` before materializing an executable guard hook outside the action-card control loop. Generated hooks pin the install-time SkillBoard command, config, skills root, and workflow; set those values with hook install options such as \`--skillboard-bin\`, not runtime environment overrides.
-- Inventory/import growth: run \`skillboard inventory refresh --dry-run --config skillboard.config.yaml\` after installing local skill packs, plugins, workflow bundles, or harnesses; run \`skillboard import --profile <id-or-path> --source-root <repo> --out .skillboard/reports/import-fragment.yaml\` after installing a new skill repository, then review the fragment before merging it into \`skillboard.config.yaml\`.
-- Prefer workflow-scoped skills over global skill invocation. Only \`global-meta\` skills may be treated as globally available.
+SkillBoard keeps one user-level policy. A valid installed skill defaults to
+enabled and agent-local. Users may opt individual skills into cross-agent
+sharing. Optional preference ranks enabled skills installed for the current
+agent and never changes availability or copies files.
+
+## Route and use
+
+- Work normally unless skills overlap or the user asks
+  for a skill decision.
+- Read \`skillboard brief --intent <request> --agent <agent> --json\`.
+- Use the recommended enabled, installed skill and ordered fallbacks. Honor an
+  explicit user choice when the guard allows it.
+- Run \`skillboard guard use <skill-id> --agent <agent> --json\` immediately
+  before use.
+- Do not ask for another approval when guard allows use. Briefly disclose the
+  selected skill as an audit trace.
+- If the routed brief suggests policy memory, finish the work first, then ask
+  once whether to remember that intent preference. Do not prompt before use.
+
+## Change policy
+
+- Policy changes only enable/disable a skill, share/unshare one skill, or
+  remember optional ranking preference.
+- Read a fresh brief with \`--include-actions\`, choose one current action id, ask
+  for one confirmation, then run \`skillboard apply-action <action-id> --yes
+  --json\`.
+- Reread the returned post-apply brief. Never reuse cached action ids or apply
+  multiple actions from one confirmation.
+- If inventory no longer observes a permanently removed unshared skill, use its
+  current forget action after confirmation. Forget removes policy only and never
+  deletes skill files.
+
+## Compatibility and boundaries
+
+- If the brief reports stale version 1 policy, do not mutate it. Preview
+  \`skillboard migrate v2 --config skillboard.config.yaml --json\`, then obtain
+  confirmation before applying with \`--yes --json\`. Rollback uses
+  \`--rollback <backup> --json\`.
+- Source and provenance observations are optional audit metadata and never
+  determine availability.
+- Runtime and action authorization are outside SkillBoard's scope. Follow the
+  agent or harness permission boundary for commands, hooks, MCP servers,
+  external writes, destructive actions, network access, and secrets.
 
 ${BRIDGE_END}`;
 }
@@ -61,39 +61,24 @@ ${BRIDGE_END}`;
 export function profileReadme() {
   return `# SkillBoard source profiles
 
-Put project-specific source profiles here when a skill repository or harness
-bundle is not covered by a built-in profile.
-
-Use:
-
-\`\`\`bash
-skillboard import --profile .skillboard/profiles/example.yaml --source-root /path/to/repo
-\`\`\`
-
-The import command emits a YAML fragment with governed \`skills\` and
-\`install_units\`. Review the fragment before merging it into
-\`skillboard.config.yaml\`; imported skills are not automatically active.
+Put discovery profiles here when a skill repository is not
+covered by a built-in profile. Profiles produce inventory observations; they do
+not authorize availability. Newly discovered valid skills default to
+enabled and agent-local while existing user policy is preserved.
 `;
 }
 
 export function hookReadme() {
   return `# SkillBoard hooks
 
-Use this directory for executable guard scripts generated by:
+Preview a generated guard hook before installation:
 
 \`\`\`bash
 skillboard hook install --workflow <name> --config skillboard.config.yaml --skills skills --out .skillboard/hooks/<name>-guard.sh --dry-run --json
-skillboard hook install --workflow <name> --config skillboard.config.yaml --skills skills --out .skillboard/hooks/<name>-guard.sh
 \`\`\`
 
-For hook action cards, prefer the bridge control loop with
-\`skillboard apply-action <action-id> --yes --json\`. These raw hook commands
-are the underlying manual detail: preview the JSON plan first and inspect
-\`planned.preview.shell\` before materializing an executable guard hook.
-Generated hooks pin the install-time SkillBoard command, config, skills root,
-and workflow; set those values with hook install options such as
-\`--skillboard-bin\`, not runtime environment overrides. The generated script
-delegates to \`skillboard guard use\` and can be wired into the hook mechanism of
-the active harness.
+For persistent changes prefer one current action card applied with
+\`skillboard apply-action <action-id> --yes --json\`. Runtime hook permission is
+owned by the active harness, not SkillBoard policy.
 `;
 }

package/src/migration/v1-to-v2.mjs

@@ -0,0 +1,212 @@
+import { EXPOSURE_VALUES, INVOCATION_VALUES, STATUS_VALUES } from "../domain/constants.mjs";
+import { TERMINAL_STATUSES, validateSkillState } from "../domain/skill-state-matrix.mjs";
+
+const V1_SKILL_POLICY_FIELDS = new Set(["status", "invocation", "exposure"]);
+const V1_SKILL_LOCATION_FIELDS = new Set(["path", "owner_install_unit"]);
+
+/**
+ * Purely project a parsed v1 config into v2 policy and audit observations.
+ * The caller retains ownership of input and may safely hash/reuse it afterward.
+ */
+export function mapV1ConfigToV2(input) {
+  const config = requireRecord(input, "v1 config");
+  if (config.version !== undefined && config.version !== 1) {
+    throw new Error(`Expected version 1 config; got version ${String(config.version)}`);
+  }
+  const skills = requireRecord(config.skills ?? {}, "v1 config skills");
+  const workflows = requireRecord(config.workflows ?? {}, "v1 config workflows");
+  const capabilities = requireRecord(config.capabilities ?? {}, "v1 config capabilities");
+  const installUnits = requireRecord(config.install_units ?? {}, "v1 config install_units");
+  const workflowNames = Object.keys(workflows).sort();
+  const warnings = [];
+  const losses = collectLosses(config);
+  const policySkills = {};
+  const inventorySkills = [];
+  const uncertainQuarantines = [];
+
+  for (const [skillId, rawSkill] of Object.entries(skills).sort(byEntryKey)) {
+    const skill = requireRecord(rawSkill, `skill ${skillId}`);
+    validateState(skillId, skill);
+    const enabled = !TERMINAL_STATUSES.has(skill.status);
+    const preference = preferenceFor(skillId, capabilities, workflows);
+    policySkills[skillId] = {
+      enabled,
+      shared: false,
+      ...(preference === null ? {} : { preference })
+    };
+    if (isReviewOnlyQuarantine(skillId, skill, workflowNames, workflows)) {
+      uncertainQuarantines.push(skillId);
+    }
+    inventorySkills.push(skillObservation(skillId, skill));
+  }
+
+  const ambiguities = uncertainQuarantines.length === 0 ? [] : [{
+    kind: "review_only_quarantine",
+    skill_ids: uncertainQuarantines,
+    mapped_enabled: true,
+    requires_grouped_confirmation: true
+  }];
+  if (uncertainQuarantines.length > 0) {
+    warnings.push(
+      `${uncertainQuarantines.length} review-only quarantine state(s) were mapped enabled; confirm them together when applying the migration.`
+    );
+  }
+
+  return {
+    policy: {
+      version: 2,
+      skills: policySkills
+    },
+    inventory: {
+      format_version: 1,
+      skills: inventorySkills,
+      install_units: Object.entries(installUnits).sort(byEntryKey).map(([id, unit]) => ({
+        id,
+        observations: clone(requireRecord(unit, `install unit ${id}`))
+      }))
+    },
+    warnings,
+    losses,
+    ambiguities
+  };
+}
+
+function isReviewOnlyQuarantine(skillId, skill, workflowNames, workflows) {
+  if (skill.status !== "quarantined" || skill.invocation !== "blocked") return false;
+  return !workflowNames.some((name) => stringList(workflows[name]?.blocked_skills).includes(skillId));
+}
+
+function validateState(skillId, skill) {
+  if (!STATUS_VALUES.has(skill.status)) {
+    throw new Error(`Skill ${skillId} has unsupported status: ${String(skill.status)}`);
+  }
+  if (!INVOCATION_VALUES.has(skill.invocation)) {
+    throw new Error(`Skill ${skillId} has unsupported invocation: ${String(skill.invocation)}`);
+  }
+  if (!EXPOSURE_VALUES.has(skill.exposure)) {
+    throw new Error(`Skill ${skillId} has unsupported exposure: ${String(skill.exposure)}`);
+  }
+  const diagnostic = validateSkillState(skill.status, skill.invocation, skillId);
+  if (typeof diagnostic === "string") throw new Error(diagnostic);
+}
+
+function preferenceFor(skillId, capabilities, workflows) {
+  const roles = [];
+  for (const [name, rawCapability] of Object.entries(capabilities)) {
+    const capability = requireRecord(rawCapability, `capability ${name}`);
+    if (capability.canonical === skillId) roles.push({ intent: name, priority: 100 });
+    if (stringList(capability.alternatives).includes(skillId)) roles.push({ intent: name, priority: 50 });
+  }
+  for (const rawWorkflow of Object.values(workflows)) {
+    const workflow = requireRecord(rawWorkflow, "workflow");
+    const requirements = requireRecord(workflow.required_capabilities ?? {}, "workflow required_capabilities");
+    for (const [name, rawRequirement] of Object.entries(requirements)) {
+      const requirement = requireRecord(rawRequirement, `workflow capability ${name}`);
+      if (requirement.preferred === skillId) roles.push({ intent: name, priority: 100 });
+      stringList(requirement.fallback).forEach((candidate, index) => {
+        if (candidate === skillId) roles.push({ intent: name, priority: 90 - index });
+      });
+    }
+  }
+  if (roles.length === 0) return null;
+  return {
+    intents: [...new Set(roles.map(({ intent }) => intent))].sort(),
+    priority: Math.max(...roles.map(({ priority }) => priority))
+  };
+}
+
+function skillObservation(id, skill) {
+  const aliases = Array.isArray(skill.source_aliases) ? clone(skill.source_aliases) : [];
+  const observations = Object.fromEntries(
+    Object.entries(skill)
+      .filter(([key]) => !V1_SKILL_POLICY_FIELDS.has(key)
+        && !V1_SKILL_LOCATION_FIELDS.has(key)
+        && key !== "source_aliases")
+      .map(([key, value]) => [key, clone(value)])
+  );
+  return {
+    id,
+    path: typeof skill.path === "string" && skill.path.length > 0 ? skill.path : id,
+    owner_install_unit: typeof skill.owner_install_unit === "string" && skill.owner_install_unit.length > 0
+      ? skill.owner_install_unit
+      : "migration.unowned",
+    aliases,
+    installed_on: installedAgents(skill),
+    observations
+  };
+}
+
+function installedAgents(skill) {
+  const units = [skill.owner_install_unit, ...(skill.source_aliases ?? []).map((alias) => alias?.owner_install_unit)];
+  return [...new Set(units.map(agentForUnit).filter(Boolean))].sort();
+}
+
+function agentForUnit(unit) {
+  if (typeof unit !== "string") return "";
+  return ["codex", "claude", "opencode", "hermes"].find((agent) => unit === agent || unit.startsWith(`${agent}.`)) ?? "";
+}
+
+function collectLosses(config) {
+  const losses = [];
+  visit(config, "", (path, value) => {
+    if (path === "/version") return;
+    losses.push({ path, value: clone(value), disposition: lossDisposition(path) });
+  });
+  return losses;
+}
+
+function visit(value, path, add) {
+  if (value === null || typeof value !== "object") {
+    add(path, value);
+    return;
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) add(path, []);
+    value.forEach((entry, index) => visit(entry, `${path}/${index}`, add));
+    return;
+  }
+  const entries = Object.entries(value);
+  if (entries.length === 0) add(path, {});
+  entries.forEach(([key, entry]) => visit(entry, `${path}/${escapePointer(key)}`, add));
+}
+
+function lossDisposition(path) {
+  if (/^\/skills\/[^/]+\/(status|invocation|exposure)$/.test(path)) return "mapped_to_v2_policy";
+  if (path.startsWith("/skills/") || path.startsWith("/install_units/")) return "preserved_in_inventory_observation";
+  if (path.startsWith("/capabilities/") || path.startsWith("/workflows/")) return "mapped_where_applicable";
+  return "not_part_of_v2_policy";
+}
+
+function requireRecord(value, label) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object mapping`);
+  }
+  return value;
+}
+
+function stringList(value) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+    throw new Error("Expected a list of strings in v1 config");
+  }
+  return value;
+}
+
+function clone(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => clone(entry));
+  }
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, clone(entry)]));
+  }
+  return value;
+}
+
+/** @param {[string, unknown]} left @param {[string, unknown]} right */
+function byEntryKey(left, right) {
+  return left[0].localeCompare(right[0]);
+}
+
+function escapePointer(value) {
+  return value.split("~").join("~0").split("/").join("~1");
+}