agent-skillboard 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## Unreleased
 
+## 0.3.2 — 2026-07-14
+
+### Changed
+
+- Made global npm updates and `skillboard setup` automatically upgrade a valid
+  version 1 user policy when every migration choice is already understood.
+- Kept the explicit `migrate v2` preview, apply, and rollback commands for
+  project policies, audits, and recovery.
+
+### Fixed
+
+- Removed the hidden manual migration step left after a 0.3.1 update while
+  preserving explicit terminal denials as disabled and review-only quarantine
+  states as enabled, agent-local skills.
+- Kept automatic migration non-mutating for unknown future ambiguity kinds or
+  policy skills that are not currently observed, and restored exact version 1
+  bytes after any transactional failure.
+- Restored invoking-user ownership for migration backups, manifests, and
+  generated inventory during sudo-driven global updates.
+
 ## 0.3.1 — 2026-07-14
 
 ### Added

package/README.md

@@ -9,7 +9,7 @@ Valid installed skills default to enabled and agent-local. Sharing is opt-in per
 skill. Optional preference ranks enabled skills installed for the current agent
 and never changes availability or copies files.
 
-Status: public alpha. Package 0.3.1 writes policy schema v2.
+Status: public alpha. Package 0.3.2 writes policy schema v2.
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/NyXXiR/skillboard/main/skillboard.png" alt="SkillBoard architecture diagram" width="100%">
@@ -56,6 +56,14 @@ prefix, activate the Node environment that owns each stale copy, and run
 uninstall another prefix. Restart or refresh agents after an update because
 some agents cache user skills.
 
+When an update finds a valid version 1 user policy, setup automatically migrates
+it only when all reported choices are understood. It creates an adjacent exact
+backup, keeps explicit terminal denials disabled, and maps review-only
+quarantine states to enabled and agent-local. Unknown future ambiguity leaves
+the policy unchanged and prints the explicit preview command instead. The same
+review path is used when a v1 policy skill is not currently observed, avoiding
+an unhealthy generated inventory or silently forgetting a denial.
+
 `setup` is safe to rerun. It refreshes managed guidance and inventory, discovers
 late standard agent homes and Hermes profiles, and fills already-selected
 `shared: true` skills into newly active roots. It does not make every skill
@@ -157,9 +165,16 @@ skillboard migrate v2 --config <path> --yes --json
 skillboard migrate v2 --config <path> --rollback <backup> --json
 ```
 
-Setup and package updates keep v1 bytes unchanged and print the preview command.
-SkillBoard does not automatically migrate version 1. All v1 mutations refuse
-and point to migration. v0.4.0 removes the v1 reader.
+Starting in 0.3.2, setup and global package updates automatically migrate a
+valid version 1 user policy when the report contains only understood choices.
+The transaction creates an adjacent exact backup. Explicit terminal denials
+remain disabled; review-only quarantine becomes enabled and agent-local. An
+unknown future ambiguity leaves the policy unchanged and prints the preview
+command. A policy skill that is not currently observed also stays on v1 for an
+explicit decision, because forgetting a disabled entry could enable it if it
+later reappears. The explicit commands remain available for project policies,
+audits, and rollback. Other v1 mutations still refuse and point to migration.
+v0.4.0 removes the v1 reader.
 
 ## Cleanup
 

package/docs/ai-skill-routing-goal.md

@@ -45,6 +45,11 @@ inventory, and materializes missing copies only for skills already marked
 discovery state. They must not introduce project scope, source trust gates, or
 another authorization layer.
 
+When setup encounters version 1 user policy, it may converge that policy to v2
+only if every migration ambiguity is a known review-only quarantine mapping.
+It must preserve terminal denials, create an exact recoverable backup, and leave
+unknown future ambiguity unchanged for an explicit decision.
+
 ## Development rule
 
 Every route, brief, guard, dashboard, generated bridge, and policy mutation must

package/docs/install.md

@@ -35,6 +35,15 @@ keep. Activate the Node environment that owns each stale prefix, confirm it with
 SkillBoard does not automatically uninstall another prefix or request elevated
 permissions for cleanup.
 
+From 0.3.2, setup and global postinstall automatically migrate a valid version
+1 user policy when every reported migration choice is understood. Migration
+creates an adjacent exact backup, preserves explicit terminal denials as
+disabled, and makes review-only quarantine states enabled and agent-local. An
+unknown future ambiguity leaves the policy unchanged and prints the explicit
+preview command; no migration files are changed. A v1 policy skill that is not
+currently observed uses the same review path so setup neither invents inventory
+nor silently forgets its policy.
+
 Run setup later when lifecycle scripts were skipped, another agent or Hermes
 profile was added, or a managed root needs to be repaired:
 
@@ -104,10 +113,12 @@ skillboard migrate v2 --config <path> --yes --json
 skillboard migrate v2 --config <path> --rollback <backup> --json
 ```
 
-Version 1 is read-only during v0.3.x. v0.4.0 removes the v1 reader.
-Setup and postinstall preserve an existing v1 policy byte-for-byte and suggest
-the preview command only. SkillBoard does not automatically migrate version 1;
-apply and rollback remain explicit user actions.
+Version 1 is read-only during v0.3.x. v0.4.0 removes the v1 reader. Setup and
+global postinstall automatically migrate an understood version 1 user policy
+through the same backup and validation transaction. Unknown future ambiguity
+or a policy skill that is not currently observed leaves it unchanged and prints
+the preview command. Explicit preview, apply, and rollback remain available for
+project policies, audits, and recovery.
 
 ## Uninstall
 

package/docs/policy-model.md

@@ -71,3 +71,10 @@ skillboard migrate v2 --config <path> --rollback <backup> --json
 ```
 
 v0.4.0 removes the v1 reader.
+
+Setup and global postinstall automatically upgrade a valid version 1 user
+policy when its migration report contains only understood choices. The
+transaction keeps an exact adjacent backup. An unknown future ambiguity leaves
+the policy unchanged and requires the explicit preview/apply flow. Policy skills
+that are not currently observed also require review rather than being silently
+forgotten.

package/docs/reference.md

@@ -153,8 +153,13 @@ Preview changes no bytes. Apply creates an adjacent byte-for-byte backup and
 writes v2 policy plus generated inventory atomically. Rollback restores the
 selected backup. v0.4.0 removes the v1 reader.
 
-Setup and npm postinstall preserve an existing v1 policy and print only the
-preview form. SkillBoard does not automatically migrate version 1.
+Setup and global npm postinstall automatically migrate a valid version 1 user
+policy when all reported choices are understood. They create an adjacent exact
+backup, preserve terminal denials as disabled, and map review-only quarantine
+to enabled and agent-local. An unknown future ambiguity leaves the policy
+unchanged, changes no migration files, and prints the preview form. The same
+review path names policy skills that are not currently observed. Explicit
+commands remain available for project policies, audit, and recovery.
 
 Legacy fields are interpreted only by migration and never become hidden v2
 authorization. Primary examples are `examples/v2-multi-source.config.yaml` and

package/docs/user-flow.md

@@ -111,4 +111,8 @@ skillboard migrate v2 --config <path> --rollback <backup> --json
 ```
 
 Version 1 remains readable but immutable for the v0.3.x one-release read-only
-window. v0.4.0 removes the v1 reader. No ordinary command migrates implicitly.
+window. Setup and global package updates automatically migrate an understood
+version 1 user policy with an exact adjacent backup. Unknown future ambiguity
+or a policy skill that is not currently observed leaves it unchanged and prints
+the preview command. Project policies and other ordinary commands still require
+explicit migration. v0.4.0 removes the v1 reader.

package/docs/value-proof.md

@@ -15,7 +15,8 @@ node --test test/v2-agent-sharing.test.mjs test/v2-onboarding-behavior.test.mjs
 - Optional preference changes ranking without changing availability.
 - Source and provenance audits do not change guard results.
 - Commands produce the same result from different working directories.
-- Version 1 is read-only until explicit migration.
+- Version 1 project policy remains read-only until explicit migration; setup
+  automatically migrates an understood user policy with an exact backup.
 
 ## Reproduce the user surface
 

package/docs/versioning.md

@@ -22,9 +22,13 @@ Preview is non-mutating, apply creates an adjacent byte-for-byte backup, and
 rollback restores the selected backup. Old action ids, hooks, and lock
 projections are invalid after migration.
 
-Package install, update, setup, and doctor never automatically migrate a v1
-policy. Setup preserves its bytes and prints the preview command so the policy
-decision stays separate from package maintenance.
+Starting in 0.3.2, setup and global package updates automatically migrate a
+valid version 1 user policy when all migration choices are understood. They use
+the same exact-backup, atomic-write, validation, and recovery transaction as
+the explicit command. Unknown future ambiguity leaves the policy unchanged and
+prints the preview command. A policy skill that is not currently observed also
+requires review, preserving future denial semantics. Doctor and project-local
+commands remain non-mutating.
 
 ## Versioned v2 contract
 
@@ -39,7 +43,8 @@ schema.
 1. Run `npm run check`.
 2. Run `npm pack --dry-run --json` and inspect public contents.
 3. Install the tarball into an isolated prefix and run
-   `skillboard doctor --summary`; verify fresh setup, v1 preservation, and a
+   `skillboard doctor --summary`; verify fresh setup, safe v1 auto-migration,
+   exact backup preservation, and a
    late-agent shared-skill reconciliation.
 4. Confirm `CHANGELOG.md` includes the package version.
 5. Push `main` and wait for the complete cross-platform check matrix.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-skillboard",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Keep agent skills broadly available while routing overlaps consistently.",
   "keywords": [
     "ai-agent",

package/src/agent-integration-cli.mjs

@@ -1,6 +1,7 @@
-import { isAbsolute, relative, resolve } from "node:path";
+import { resolve } from "node:path";
 import { mkdir } from "node:fs/promises";
 import { createInterface } from "node:readline";
+import { commandPrefix, shellQuote } from "./agent-integration-command.mjs";
 import { installAgentIntegration, uninstallAgentIntegration } from "./agent-integration-files.mjs";
 import { applyOwnership, applyOwnershipTree, resolveSetupHome, setupOwnership } from "./agent-integration-home.mjs";
 import { setupAgentSkillTargets, supportedAgentNames } from "./agent-skill-roots.mjs";
@@ -13,6 +14,7 @@ import {
 } from "./agent-root-registry.mjs";
 import { refreshAgentInventory } from "./inventory-refresh.mjs";
 import { reconcileSharedSkills } from "./shared-skill-reconcile.mjs";
+import { upgradeLegacyUserPolicy } from "./setup-policy-migration.mjs";
 
 export async function runSetupCommand(options, stdout, runtime = defaultRuntime()) {
   assertSetupOptions(options);
@@ -52,7 +54,21 @@ export async function runSetupCommand(options, stdout, runtime = defaultRuntime(
     preserveLegacyPolicy: true
   });
   const configPath = resolve(home, inventory.configPath);
-  const inventoryPath = inventory.inventoryPath === null ? null : resolve(home, inventory.inventoryPath);
+  let inventoryPath = inventory.inventoryPath === null ? null : resolve(home, inventory.inventoryPath);
+  const policyUpgrade = await upgradeLegacyUserPolicy({
+    home,
+    configPath,
+    inventoryPath,
+    observedSkillIds: inventory.observedSkillIds,
+    failpoint: runtime.migrationFailpoint
+  });
+  if (policyUpgrade.status === "upgraded") {
+    inventoryPath = policyUpgrade.inventoryPath;
+    await applyOwnership(configPath, ownership);
+    await applyOwnership(inventoryPath, ownership);
+    for (const artifact of policyUpgrade.artifacts) await applyOwnership(artifact, ownership);
+    inventory = await refreshAgentInventory({ root: home, home, env, registeredRoots });
+  }
   const shared = inventoryPath === null
     ? { created: [], unchanged: [], preserved: [], blocked: [] }
     : await reconcileSharedSkills({ home, env, targets, configPath, inventoryPath });
@@ -80,14 +96,24 @@ export async function runSetupCommand(options, stdout, runtime = defaultRuntime(
   writeList(stdout, "Blocked shared copies", shared.blocked.map(formatBlockedEntry));
   stdout.write(`User policy: ${inventory.configPath}\n`);
   stdout.write(`Observed skills: ${inventory.scan.scannedSkills}\n`);
-  if (inventory.inventoryPath === null) {
-    stdout.write("Policy version 1 remains read-only during SkillBoard v0.3.x.\n");
+  if (policyUpgrade.status === "upgraded") {
+    stdout.write("User policy upgraded automatically to version 2.\n");
+    stdout.write(`Backup: ${policyUpgrade.backupPath}\n`);
+  } else if (policyUpgrade.status === "decision-required") {
+    stdout.write("Policy version 1 needs review before migration; no migration files were changed.\n");
+    if (policyUpgrade.unobservedSkillIds.length > 0) {
+      stdout.write(`Policy skills not currently observed: ${formatList(policyUpgrade.unobservedSkillIds)}\n`);
+    }
     stdout.write(`Preview migration: ${commandPrefix(runtime)} migrate v2 --config ${shellQuote(configPath, runtime.platform)} --json\n`);
   }
   stdout.write("Next:\n");
   stdout.write("- Restart or refresh agents that cache user skills.\n");
   stdout.write("- Run skillboard doctor --summary to check policy and executable paths.\n");
-  stdout.write("- User-level policy and inventory were refreshed; no project was initialized.\n");
+  if (policyUpgrade.status === "decision-required") {
+    stdout.write("- User-level policy was preserved and installed skills were rescanned; no project was initialized.\n");
+  } else {
+    stdout.write("- User-level policy and inventory were refreshed; no project was initialized.\n");
+  }
   stdout.write('- Ask the agent in a workspace: "Review this plan and point out weak assumptions."\n');
   stdout.write("- SkillBoard will step in when skills overlap, routing is ambiguous, or you ask for a skill decision.\n");
   return 0;
@@ -222,46 +248,3 @@ function formatSharedEntry(entry) {
 function formatBlockedEntry(entry) {
   return `${entry.agent ?? "unknown"}:${entry.skill}:${entry.reason}`;
 }
-
-function commandPrefix(runtime) {
-  const entrypoint = runtime.entrypointPath ?? "";
-  const normalized = entrypoint.replace(/\\/g, "/");
-  if (normalized.includes("/_npx/")) {
-    const packageSpec = runtime.packageSpec ?? "agent-skillboard";
-    return `npx --yes --package ${shellQuote(packageSpec, runtime.platform)} skillboard`;
-  }
-  if (isSourceTreeEntrypoint(entrypoint)) {
-    return `node ${sourceTreeEntrypoint(entrypoint, runtime.cwd ?? process.cwd(), runtime.platform)}`;
-  }
-  return "skillboard";
-}
-
-function isSourceTreeEntrypoint(entrypoint) {
-  if (entrypoint === "") {
-    return false;
-  }
-  const normalized = entrypoint.replace(/\\/g, "/");
-  return (normalized === "bin/skillboard.mjs" || normalized.endsWith("/bin/skillboard.mjs"))
-    && !normalized.includes("/node_modules/")
-    && !normalized.includes("/_npx/")
-    && !normalized.includes("/.npm/");
-}
-
-function sourceTreeEntrypoint(entrypoint, cwd, platform) {
-  const absoluteEntrypoint = isAbsolute(entrypoint) ? entrypoint : resolve(cwd, entrypoint);
-  const relativeEntrypoint = relative(cwd, absoluteEntrypoint).replace(/\\/g, "/");
-  if (!relativeEntrypoint.startsWith("../") && relativeEntrypoint !== ".." && !isAbsolute(relativeEntrypoint)) {
-    return shellQuote(relativeEntrypoint, platform);
-  }
-  return shellQuote(absoluteEntrypoint, platform);
-}
-
-function shellQuote(value, platform = process.platform) {
-  if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value)) {
-    return value;
-  }
-  if (platform === "win32") {
-    return `"${value.replace(/"/g, '""')}"`;
-  }
-  return `'${value.replace(/'/g, "'\\''")}'`;
-}

package/src/agent-integration-command.mjs

@@ -0,0 +1,38 @@
+import { isAbsolute, relative, resolve } from "node:path";
+
+export function commandPrefix(runtime) {
+  const entrypoint = runtime.entrypointPath ?? "";
+  const normalized = entrypoint.replace(/\\/g, "/");
+  if (normalized.includes("/_npx/")) {
+    const packageSpec = runtime.packageSpec ?? "agent-skillboard";
+    return `npx --yes --package ${shellQuote(packageSpec, runtime.platform)} skillboard`;
+  }
+  if (isSourceTreeEntrypoint(entrypoint)) {
+    return `node ${sourceTreeEntrypoint(entrypoint, runtime.cwd ?? process.cwd(), runtime.platform)}`;
+  }
+  return "skillboard";
+}
+
+function isSourceTreeEntrypoint(entrypoint) {
+  if (entrypoint === "") return false;
+  const normalized = entrypoint.replace(/\\/g, "/");
+  return (normalized === "bin/skillboard.mjs" || normalized.endsWith("/bin/skillboard.mjs"))
+    && !normalized.includes("/node_modules/")
+    && !normalized.includes("/_npx/")
+    && !normalized.includes("/.npm/");
+}
+
+function sourceTreeEntrypoint(entrypoint, cwd, platform) {
+  const absoluteEntrypoint = isAbsolute(entrypoint) ? entrypoint : resolve(cwd, entrypoint);
+  const relativeEntrypoint = relative(cwd, absoluteEntrypoint).replace(/\\/g, "/");
+  if (!relativeEntrypoint.startsWith("../") && relativeEntrypoint !== ".." && !isAbsolute(relativeEntrypoint)) {
+    return shellQuote(relativeEntrypoint, platform);
+  }
+  return shellQuote(absoluteEntrypoint, platform);
+}
+
+export function shellQuote(value, platform = process.platform) {
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value)) return value;
+  if (platform === "win32") return `"${value.replace(/"/g, '""')}"`;
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}

package/src/inventory-refresh.mjs

@@ -85,6 +85,7 @@ async function refreshLocked(options) {
     bootstrappedV2,
     configPath: relativeArtifactPath(root, configPath),
     inventoryPath: generatedInventory === null ? null : relativeArtifactPath(root, inventoryPath),
+    observedSkillIds: inventory.skills.map(({ id }) => id).sort((left, right) => left.localeCompare(right)),
     inventoryChanged,
     changed: plan.changed,
     plan,

package/src/migration/automatic-v2.mjs

@@ -0,0 +1,14 @@
+const SAFE_AMBIGUITY_KIND = "review_only_quarantine";
+
+export function canAutomaticallyMigrateV2(report) {
+  if (report?.mode !== "preview" || report.changed !== true || report.target_version !== 2) return false;
+  if (!Array.isArray(report.ambiguities)) return false;
+  return report.ambiguities.every((ambiguity) => (
+    ambiguity?.kind === SAFE_AMBIGUITY_KIND
+    && ambiguity.mapped_enabled === true
+    && ambiguity.requires_grouped_confirmation === true
+    && Array.isArray(ambiguity.skill_ids)
+    && ambiguity.skill_ids.length > 0
+    && ambiguity.skill_ids.every((skillId) => typeof skillId === "string" && skillId.length > 0)
+  ));
+}

package/src/migration/v2-projection.mjs

@@ -103,6 +103,7 @@ export function unchangedMigrationResult(inputBytes) {
     ambiguities: [],
     grouped_decision: null,
     backup: null,
-    manifest: null
+    manifest: null,
+    inventory_backup: null
   };
 }

package/src/migration/v2-transaction.mjs

@@ -46,6 +46,9 @@ export async function migrateV2(options) {
 
 async function migrateForward(configPath, inventoryPath, options) {
   const inputBytes = await readFile(configPath);
+  if (options.expectedInputSha256 !== undefined && sha256(inputBytes) !== options.expectedInputSha256) {
+    throw new Error("Config changed after migration preview; no files were changed.");
+  }
   const inputText = inputBytes.toString("utf8");
   const { document, parsed } = parseMigrationConfig(inputText);
   const version = parsed.version ?? 1;
@@ -85,6 +88,7 @@ async function migrateForward(configPath, inventoryPath, options) {
       changed: true,
       backup: basename(backup.configBackupPath),
       manifest: basename(backup.manifestPath),
+      inventory_backup: backup.inventoryBackupPath === null ? null : basename(backup.inventoryBackupPath),
       ...report
     };
   } catch (error) {

package/src/setup-policy-migration.mjs

@@ -0,0 +1,43 @@
+import { dirname, join, resolve } from "node:path";
+import { canAutomaticallyMigrateV2 } from "./migration/automatic-v2.mjs";
+import { migrateV2 } from "./migration/v2-transaction.mjs";
+
+export async function upgradeLegacyUserPolicy(options) {
+  if (options.inventoryPath !== null) {
+    return { status: "current", inventoryPath: options.inventoryPath, artifacts: [] };
+  }
+
+  const inventoryPath = resolve(options.home, ".skillboard", "inventory.json");
+  const migrationOptions = {
+    configPath: options.configPath,
+    inventoryPath,
+    failpoint: options.failpoint
+  };
+  const preview = await migrateV2({ ...migrationOptions, apply: false });
+  const observed = new Set(options.observedSkillIds);
+  const unobservedSkillIds = preview.skills.map(({ id }) => id).filter((id) => !observed.has(id));
+  if (!canAutomaticallyMigrateV2(preview) || unobservedSkillIds.length > 0) {
+    return {
+      status: "decision-required",
+      inventoryPath: null,
+      artifacts: [],
+      preview,
+      unobservedSkillIds
+    };
+  }
+
+  const applied = await migrateV2({
+    ...migrationOptions,
+    apply: true,
+    expectedInputSha256: preview.input_sha256
+  });
+  const directory = dirname(options.configPath);
+  const artifactNames = [applied.backup, applied.manifest, applied.inventory_backup].filter(Boolean);
+  return {
+    status: "upgraded",
+    inventoryPath,
+    backupPath: join(directory, applied.backup),
+    artifacts: artifactNames.map((name) => join(directory, name)),
+    report: applied
+  };
+}