agent-skillboard 0.2.17 → 0.3.0

package/src/reconcile.mjs

@@ -1,111 +1,139 @@
-const SAFE_HARNESS_STATUSES = new Set(["available", "configured", "primary", "fallback"]);
-
-export function reconcileWorkspace(workspace, options = {}) {
-  const configuredSkills = new Set(workspace.skills.map((skill) => skill.id));
-  const actualHarnesses = options.actualHarnesses ?? [];
-  const plan = {
-    skillChanges: [],
-    harnessChanges: [],
-    autoActions: [],
-    decisionsRequired: [],
-    warnings: []
-  };
-
-  for (const skill of workspace.installedSkills) {
-    if (configuredSkills.has(skill.id)) {
-      continue;
-    }
-    const capability = findCapabilityForSkill(workspace, skill.id);
-    const recommendedInvocation = recommendedInvocationFor(capability);
-    const change = {
-      type: "new-skill",
-      skillId: skill.id,
-      capability: capability?.name ?? "uncategorized",
-      recommendedStatus: "quarantined",
-      recommendedInvocation
-    };
-    plan.skillChanges.push(change);
-    plan.autoActions.push({
-      action: "quarantine-skill",
-      skillId: skill.id,
-      capability: capability?.name ?? "uncategorized",
-      recommendedStatus: "quarantined",
-      recommendedInvocation
-    });
-    plan.decisionsRequired.push(
-      `Classify ${skill.id}: keep quarantined, approve manual-only for a workflow, or archive as duplicate.`
-    );
-  }
-
-  if (actualHarnesses.length === 0) {
-    plan.warnings.push("Actual harness inventory was not provided; harness reconciliation skipped.");
-  } else {
-    reconcileHarnesses(workspace, new Set(actualHarnesses), plan);
-  }
-
-  return plan;
-}
-
-function reconcileHarnesses(workspace, actualHarnesses, plan) {
-  const desiredHarnesses = new Set(workspace.harnesses.map((harness) => harness.name));
-
-  for (const harness of workspace.harnesses) {
-    if (!SAFE_HARNESS_STATUSES.has(harness.status) || actualHarnesses.has(harness.name)) {
-      continue;
-    }
-    const affectedWorkflows = harness.workflows.length === 0
-      ? workflowsUsingHarness(workspace, harness.name)
-      : harness.workflows;
-    const change = {
-      type: "removed-harness",
-      harness: harness.name,
-      affectedWorkflows,
-      missingCommands: harness.commands,
-      recommendations: [
-        "assign a fallback harness before applying workflow changes",
-        "replace missing commands with capability-backed workflow steps"
-      ]
-    };
-    plan.harnessChanges.push(change);
-    plan.decisionsRequired.push(
-      `Migrate ${harness.name}: ${affectedWorkflows.length} workflow(s) need a fallback harness or command mapping.`
-    );
-  }
-
-  for (const harness of actualHarnesses) {
-    if (desiredHarnesses.has(harness)) {
-      continue;
-    }
-    plan.harnessChanges.push({
-      type: "new-harness",
-      harness,
-      affectedWorkflows: [],
-      missingCommands: [],
-      recommendations: ["record the harness as disabled until workflows explicitly opt in"]
-    });
-    plan.autoActions.push({
-      action: "disable-harness",
-      harness,
-      recommendedStatus: "disabled"
-    });
-  }
-}
-
-function findCapabilityForSkill(workspace, skillId) {
-  return workspace.capabilities.find((candidate) => {
-    return candidate.canonical === skillId || candidate.alternatives.includes(skillId);
-  });
-}
-
-function recommendedInvocationFor(capability) {
-  if (capability === undefined || capability.defaultPolicy === "global-auto") {
-    return "blocked";
-  }
-  return capability.defaultPolicy;
-}
-
-function workflowsUsingHarness(workspace, harnessName) {
-  return workspace.workflows
-    .filter((workflow) => workflow.harness === harnessName)
-    .map((workflow) => workflow.name);
-}
+const SAFE_HARNESS_STATUSES = new Set(["available", "configured", "primary", "fallback"]);
+
+export function reconcileWorkspace(workspace, options = {}) {
+  if (workspace.version === 2) {
+    return reconcileV2Workspace(workspace);
+  }
+  const configuredSkills = new Set(workspace.skills.map((skill) => skill.id));
+  const actualHarnesses = options.actualHarnesses ?? [];
+  const plan = {
+    skillChanges: [],
+    harnessChanges: [],
+    autoActions: [],
+    decisionsRequired: [],
+    warnings: []
+  };
+
+  for (const skill of workspace.installedSkills) {
+    if (configuredSkills.has(skill.id)) {
+      continue;
+    }
+    const capability = findCapabilityForSkill(workspace, skill.id);
+    const recommendedInvocation = recommendedInvocationFor(capability);
+    const change = {
+      type: "new-skill",
+      skillId: skill.id,
+      capability: capability?.name ?? "uncategorized",
+      recommendedStatus: "quarantined",
+      recommendedInvocation
+    };
+    plan.skillChanges.push(change);
+    plan.autoActions.push({
+      action: "quarantine-skill",
+      skillId: skill.id,
+      capability: capability?.name ?? "uncategorized",
+      recommendedStatus: "quarantined",
+      recommendedInvocation
+    });
+    plan.decisionsRequired.push(
+      `Classify ${skill.id}: keep quarantined, approve manual-only for a workflow, or archive as duplicate.`
+    );
+  }
+
+  if (actualHarnesses.length === 0) {
+    plan.warnings.push("Actual harness inventory was not provided; harness reconciliation skipped.");
+  } else {
+    reconcileHarnesses(workspace, new Set(actualHarnesses), plan);
+  }
+
+  return plan;
+}
+
+function reconcileV2Workspace(workspace) {
+  const configuredSkills = new Set(workspace.skills.map((skill) => skill.id));
+  const observedSkills = workspace.inventory?.skills ?? workspace.installedSkills;
+  const skillChanges = observedSkills
+    .filter((skill) => !configuredSkills.has(skill.id))
+    .map((skill) => ({
+      type: "new-skill",
+      skillId: skill.id,
+      recommendedEnabled: true,
+      recommendedShared: false
+    }));
+  return {
+    skillChanges,
+    harnessChanges: [],
+    autoActions: skillChanges.map((change) => ({
+      action: "enable-skill-local",
+      skillId: change.skillId,
+      enabled: true,
+      shared: false
+    })),
+    decisionsRequired: [],
+    warnings: workspace.inventory?.integrityErrors ?? []
+  };
+}
+
+function reconcileHarnesses(workspace, actualHarnesses, plan) {
+  const desiredHarnesses = new Set(workspace.harnesses.map((harness) => harness.name));
+
+  for (const harness of workspace.harnesses) {
+    if (!SAFE_HARNESS_STATUSES.has(harness.status) || actualHarnesses.has(harness.name)) {
+      continue;
+    }
+    const affectedWorkflows = harness.workflows.length === 0
+      ? workflowsUsingHarness(workspace, harness.name)
+      : harness.workflows;
+    const change = {
+      type: "removed-harness",
+      harness: harness.name,
+      affectedWorkflows,
+      missingCommands: harness.commands,
+      recommendations: [
+        "assign a fallback harness before applying workflow changes",
+        "replace missing commands with capability-backed workflow steps"
+      ]
+    };
+    plan.harnessChanges.push(change);
+    plan.decisionsRequired.push(
+      `Migrate ${harness.name}: ${affectedWorkflows.length} workflow(s) need a fallback harness or command mapping.`
+    );
+  }
+
+  for (const harness of actualHarnesses) {
+    if (desiredHarnesses.has(harness)) {
+      continue;
+    }
+    plan.harnessChanges.push({
+      type: "new-harness",
+      harness,
+      affectedWorkflows: [],
+      missingCommands: [],
+      recommendations: ["record the harness as disabled until workflows explicitly opt in"]
+    });
+    plan.autoActions.push({
+      action: "disable-harness",
+      harness,
+      recommendedStatus: "disabled"
+    });
+  }
+}
+
+function findCapabilityForSkill(workspace, skillId) {
+  return workspace.capabilities.find((candidate) => {
+    return candidate.canonical === skillId || candidate.alternatives.includes(skillId);
+  });
+}
+
+function recommendedInvocationFor(capability) {
+  if (capability === undefined || capability.defaultPolicy === "global-auto") {
+    return "blocked";
+  }
+  return capability.defaultPolicy;
+}
+
+function workflowsUsingHarness(workspace, harnessName) {
+  return workspace.workflows
+    .filter((workflow) => workflow.harness === harnessName)
+    .map((workflow) => workflow.name);
+}

package/src/report.mjs

@@ -1,151 +1,171 @@
-export function renderDashboard(workspace) {
-  const lines = ["# SkillBoard", "", "## Defaults", ""];
-  lines.push(`- Invocation policy: \`${workspace.defaults.invocationPolicy}\``);
-  lines.push(`- Model auto invocation: \`${workspace.defaults.allowModelInvocation}\``);
-  lines.push(`- Explicit workflow required: \`${workspace.defaults.requireExplicitWorkflow}\``);
-  lines.push("", "## Workflows", "");
-
-  for (const workflow of workspace.workflows) {
-    lines.push(`### ${workflow.name}`, "");
-    lines.push(`- Harness: \`${workflow.harness}\``);
-    lines.push(`- required outputs: ${formatList(workflow.requiredOutputs)}`);
-    emitSkillGroup(lines, "active", workflow.activeSkills, workspace);
-    emitSkillGroup(lines, "blocked", workflow.blockedSkills, workspace);
-    emitCapabilityRequirements(lines, workflow.requiredCapabilities);
-    lines.push("");
-  }
-
-  lines.push("## Capabilities", "");
-  if (workspace.capabilities.length === 0) {
-    lines.push("- none");
-  }
-  for (const capability of workspace.capabilities) {
-    lines.push(`- \`${capability.name}\` — canonical: \`${capability.canonical || "none"}\`, alternatives: ${formatList(capability.alternatives)}`);
-  }
-  lines.push("", "## Harnesses", "");
-  if (workspace.harnesses.length === 0) {
-    lines.push("- none");
-  }
-  for (const harness of workspace.harnesses) {
-    lines.push(`- \`${harness.name}\` — ${harness.status}, workflows: ${formatList(harness.workflows)}`);
-  }
-  lines.push("");
-
-  lines.push("## Agent Runtime Install Units", "");
-  if (workspace.installUnits.length === 0) {
-    lines.push("- none");
-  }
-  for (const unit of workspace.installUnits) {
-    lines.push(`### ${unit.id}`, "");
-    lines.push(`- Kind: \`${unit.kind}\``);
-    lines.push(`- Scope: \`${unit.scope}\``);
-    lines.push(`- Source: \`${unit.source || "unknown"}\``);
-    lines.push(`- Enabled: \`${unit.enabled}\``);
-    lines.push(`- Auto update: \`${unit.autoUpdate}\``);
-    lines.push(`- Manifest: \`${unit.manifestPath || "none"}\``);
-    lines.push(`- Cache: \`${unit.cachePath || "none"}\``);
-    lines.push(`- Provides: ${formatList(unit.providedComponents)}`);
-    lines.push(`- Skills: ${formatList(unit.components.skills)}`);
-    lines.push(`- Commands: ${formatList(unit.components.commands)}`);
-    lines.push(`- Hooks: ${formatList(unit.components.hooks)}`);
-    lines.push(`- MCP servers: ${formatList(unit.components.mcpServers)}`);
-    lines.push(`- Modifies: ${formatList(unit.modifiedConfigFiles)}`);
+export function renderDashboard(workspace) {
+  if (workspace.version === 2) return renderV2Dashboard(workspace);
+  const lines = ["# SkillBoard", "", "## Defaults", ""];
+  lines.push(`- Invocation policy: \`${workspace.defaults.invocationPolicy}\``);
+  lines.push(`- Model auto invocation: \`${workspace.defaults.allowModelInvocation}\``);
+  lines.push(`- Explicit workflow required: \`${workspace.defaults.requireExplicitWorkflow}\``);
+  lines.push("", "## Workflows", "");
+
+  for (const workflow of workspace.workflows) {
+    lines.push(`### ${workflow.name}`, "");
+    lines.push(`- Harness: \`${workflow.harness}\``);
+    lines.push(`- required outputs: ${formatList(workflow.requiredOutputs)}`);
+    emitSkillGroup(lines, "active", workflow.activeSkills, workspace);
+    emitSkillGroup(lines, "blocked", workflow.blockedSkills, workspace);
+    emitCapabilityRequirements(lines, workflow.requiredCapabilities);
+    lines.push("");
+  }
+
+  lines.push("## Capabilities", "");
+  if (workspace.capabilities.length === 0) {
+    lines.push("- none");
+  }
+  for (const capability of workspace.capabilities) {
+    lines.push(`- \`${capability.name}\` — canonical: \`${capability.canonical || "none"}\`, alternatives: ${formatList(capability.alternatives)}`);
+  }
+  lines.push("", "## Harnesses", "");
+  if (workspace.harnesses.length === 0) {
+    lines.push("- none");
+  }
+  for (const harness of workspace.harnesses) {
+    lines.push(`- \`${harness.name}\` — ${harness.status}, workflows: ${formatList(harness.workflows)}`);
+  }
+  lines.push("");
+
+  lines.push("## Agent Runtime Install Units", "");
+  if (workspace.installUnits.length === 0) {
+    lines.push("- none");
+  }
+  for (const unit of workspace.installUnits) {
+    lines.push(`### ${unit.id}`, "");
+    lines.push(`- Kind: \`${unit.kind}\``);
+    lines.push(`- Scope: \`${unit.scope}\``);
+    lines.push(`- Source: \`${unit.source || "unknown"}\``);
+    lines.push(`- Enabled: \`${unit.enabled}\``);
+    lines.push(`- Auto update: \`${unit.autoUpdate}\``);
+    lines.push(`- Manifest: \`${unit.manifestPath || "none"}\``);
+    lines.push(`- Cache: \`${unit.cachePath || "none"}\``);
+    lines.push(`- Provides: ${formatList(unit.providedComponents)}`);
+    lines.push(`- Skills: ${formatList(unit.components.skills)}`);
+    lines.push(`- Commands: ${formatList(unit.components.commands)}`);
+    lines.push(`- Hooks: ${formatList(unit.components.hooks)}`);
+    lines.push(`- MCP servers: ${formatList(unit.components.mcpServers)}`);
+    lines.push(`- Modifies: ${formatList(unit.modifiedConfigFiles)}`);
     lines.push(`- Workflow dependencies: ${formatList(unit.workflowDependencies)}`);
     lines.push(`- Trust level: \`${unit.trustLevel}\``);
     lines.push(`- permission risk: \`${unit.permissionRisk}\``);
-    lines.push(`- Rollback: \`${unit.rollback}\``);
-    lines.push("");
-  }
-
-  lines.push("## Skill Inventory", "");
-  for (const skill of workspace.skills) {
-    lines.push(`- \`${skill.id}\` — ${skill.status}, ${skill.invocation}, ${skill.exposure}, ${skill.category}, owner: \`${skill.ownerInstallUnit ?? "none"}\``);
-  }
-  lines.push("", "## Installed Skill Files", "");
-  if (workspace.installedSkills.length === 0) {
-    lines.push("- none");
-  }
-  for (const skill of workspace.installedSkills) {
-    lines.push(`- \`${skill.path}\` — ${skill.name}: ${skill.description}`);
-  }
-  lines.push("");
-  return `${lines.join("\n")}\n`;
-}
-
-export function renderReconcilePlan(plan) {
-  const lines = ["# SkillBoard Reconcile Plan", "", "## Warnings", ""];
-  if (plan.warnings.length === 0) {
-    lines.push("- none");
-  }
-  for (const warning of plan.warnings) {
-    lines.push(`- ${warning}`);
-  }
-  lines.push("", "## Automatic Actions", "");
-  if (plan.autoActions.length === 0) {
-    lines.push("- none");
-  }
-  for (const action of plan.autoActions) {
-    if (action.action === "quarantine-skill") {
-      lines.push(`- quarantine \`${action.skillId}\` as \`${action.recommendedStatus}\` / \`${action.recommendedInvocation}\` for capability \`${action.capability}\``);
-    } else if (action.action === "disable-harness") {
-      lines.push(`- disable new harness \`${action.harness}\` until a workflow opts in`);
-    }
-  }
-
-  lines.push("", "## Skill Changes", "");
-  if (plan.skillChanges.length === 0) {
-    lines.push("- none");
-  }
-  for (const change of plan.skillChanges) {
-    lines.push(`- \`${change.skillId}\`: ${change.type}, capability \`${change.capability}\`, recommend \`${change.recommendedStatus}\``);
-  }
-
-  lines.push("", "## Harness Changes", "");
-  if (plan.harnessChanges.length === 0) {
-    lines.push("- none");
-  }
-  for (const change of plan.harnessChanges) {
-    lines.push(`- \`${change.harness}\`: ${change.type}`);
-    lines.push(`  - affected workflows: ${formatList(change.affectedWorkflows)}`);
-    lines.push(`  - missing commands: ${formatList(change.missingCommands)}`);
-    lines.push(`  - recommendations: ${formatList(change.recommendations)}`);
-  }
-
-  lines.push("", "## Decisions Required", "");
-  if (plan.decisionsRequired.length === 0) {
-    lines.push("- none");
-  }
-  for (const decision of plan.decisionsRequired) {
-    lines.push(`- ${decision}`);
-  }
-  lines.push("");
-  return `${lines.join("\n")}\n`;
-}
-
-function emitSkillGroup(lines, label, skillIds, workspace) {
-  lines.push(`- ${label}:`);
-  if (skillIds.length === 0) {
-    lines.push("  - none");
-    return;
-  }
-  for (const skillId of skillIds) {
-    const skill = workspace.skills.find((candidate) => candidate.id === skillId);
-    const invocation = skill === undefined ? "missing" : skill.invocation;
-    lines.push(`  - \`${skillId}\` (${invocation})`);
-  }
-}
-
-function emitCapabilityRequirements(lines, capabilities) {
-  lines.push("- required capabilities:");
-  if (capabilities.length === 0) {
-    lines.push("  - none");
-    return;
-  }
-  for (const capability of capabilities) {
-    lines.push(`  - \`${capability.name}\` preferred \`${capability.preferred || "none"}\`, fallback: ${formatList(capability.fallback)}`);
-  }
-}
-
-function formatList(values) {
-  return values.length === 0 ? "none" : values.map((value) => `\`${value}\``).join(", ");
-}
+    lines.push(`- Rollback: \`${unit.rollback}\``);
+    lines.push("");
+  }
+
+  lines.push("## Skill Inventory", "");
+  for (const skill of workspace.skills) {
+    lines.push(`- \`${skill.id}\` — ${skill.status}, ${skill.invocation}, ${skill.exposure}, ${skill.category}, owner: \`${skill.ownerInstallUnit ?? "none"}\``);
+  }
+  lines.push("", "## Installed Skill Files", "");
+  if (workspace.installedSkills.length === 0) {
+    lines.push("- none");
+  }
+  for (const skill of workspace.installedSkills) {
+    lines.push(`- \`${skill.path}\` — ${skill.name}: ${skill.description}`);
+  }
+  lines.push("");
+  return `${lines.join("\n")}\n`;
+}
+
+function renderV2Dashboard(workspace) {
+  const lines = ["# SkillBoard", "", "## Version 2 Policy", ""];
+  for (const skill of workspace.skills) {
+    const state = skill.enabled ? "enabled" : "disabled";
+    lines.push(`- \`${skill.id}\` — ${state}, ${skill.shared ? "shared across agents" : "agent-local"}`);
+  }
+  lines.push("", "## Runtime Readiness", "");
+  const errors = workspace.inventory?.integrityErrors ?? [];
+  lines.push(errors.length === 0 ? "- inventory ready" : `- inventory unavailable: ${errors.join("; ")}`);
+  lines.push("");
+  return `${lines.join("\n")}\n`;
+}
+
+export function renderReconcilePlan(plan) {
+  const lines = ["# SkillBoard Reconcile Plan", "", "## Warnings", ""];
+  if (plan.warnings.length === 0) {
+    lines.push("- none");
+  }
+  for (const warning of plan.warnings) {
+    lines.push(`- ${warning}`);
+  }
+  lines.push("", "## Automatic Actions", "");
+  if (plan.autoActions.length === 0) {
+    lines.push("- none");
+  }
+  for (const action of plan.autoActions) {
+    if (action.action === "enable-skill-local") {
+      lines.push(`- enable \`${action.skillId}\` where it is installed`);
+    } else if (action.action === "quarantine-skill") {
+      lines.push(`- quarantine \`${action.skillId}\` as \`${action.recommendedStatus}\` / \`${action.recommendedInvocation}\` for capability \`${action.capability}\``);
+    } else if (action.action === "disable-harness") {
+      lines.push(`- disable new harness \`${action.harness}\` until a workflow opts in`);
+    }
+  }
+
+  lines.push("", "## Skill Changes", "");
+  if (plan.skillChanges.length === 0) {
+    lines.push("- none");
+  }
+  for (const change of plan.skillChanges) {
+    if (change.recommendedEnabled !== undefined) {
+      lines.push(`- \`${change.skillId}\`: ${change.type}, recommend enabled \`${change.recommendedEnabled}\`, shared \`${change.recommendedShared}\``);
+    } else {
+      lines.push(`- \`${change.skillId}\`: ${change.type}, capability \`${change.capability}\`, recommend \`${change.recommendedStatus}\``);
+    }
+  }
+
+  lines.push("", "## Harness Changes", "");
+  if (plan.harnessChanges.length === 0) {
+    lines.push("- none");
+  }
+  for (const change of plan.harnessChanges) {
+    lines.push(`- \`${change.harness}\`: ${change.type}`);
+    lines.push(`  - affected workflows: ${formatList(change.affectedWorkflows)}`);
+    lines.push(`  - missing commands: ${formatList(change.missingCommands)}`);
+    lines.push(`  - recommendations: ${formatList(change.recommendations)}`);
+  }
+
+  lines.push("", "## Decisions Required", "");
+  if (plan.decisionsRequired.length === 0) {
+    lines.push("- none");
+  }
+  for (const decision of plan.decisionsRequired) {
+    lines.push(`- ${decision}`);
+  }
+  lines.push("");
+  return `${lines.join("\n")}\n`;
+}
+
+function emitSkillGroup(lines, label, skillIds, workspace) {
+  lines.push(`- ${label}:`);
+  if (skillIds.length === 0) {
+    lines.push("  - none");
+    return;
+  }
+  for (const skillId of skillIds) {
+    const skill = workspace.skills.find((candidate) => candidate.id === skillId);
+    const invocation = skill === undefined ? "missing" : skill.invocation;
+    lines.push(`  - \`${skillId}\` (${invocation})`);
+  }
+}
+
+function emitCapabilityRequirements(lines, capabilities) {
+  lines.push("- required capabilities:");
+  if (capabilities.length === 0) {
+    lines.push("  - none");
+    return;
+  }
+  for (const capability of capabilities) {
+    lines.push(`  - \`${capability.name}\` preferred \`${capability.preferred || "none"}\`, fallback: ${formatList(capability.fallback)}`);
+  }
+}
+
+function formatList(values) {
+  return values.length === 0 ? "none" : values.map((value) => `\`${value}\``).join(", ");
+}

package/src/review.mjs

@@ -6,6 +6,7 @@ import { textChangePlan } from "./change-plan.mjs";
 import { TRUST_LEVEL_VALUES } from "./domain/constants.mjs";
 import { checkPolicy } from "./policy.mjs";
 import { loadWorkspace } from "./workspace.mjs";
+import { assertV2MutationVersion } from "./compatibility.mjs";
 
 export async function reviewInstallUnit(options) {
   const trustLevel = options.trustLevel ?? "reviewed";
@@ -14,6 +15,7 @@ export async function reviewInstallUnit(options) {
   }
 
   const { document, originalText } = await loadConfig(options.configPath);
+  assertV2MutationVersion(document.get("version") ?? 1);
   const installUnits = requireMapAt(document, ["install_units"], "install_units");
   const unit = installUnits.get(options.unitId, true);
   if (unit === undefined) {