agent-skillboard 0.3.3 → 0.3.4

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.3.4 — 2026-07-21
+
+### Fixed
+
+- Separated generated-inventory integrity failures from sorted stale
+  removed-skill policy observations. Valid inventory now keeps doctor, status,
+  brief, strict health, and observed-skill routing healthy while absent skills
+  remain guard-denied and available for explicit, confirmation-required policy
+  forget actions.
+
 ## 0.3.3 — 2026-07-15
 
 ### Added

package/README.md

@@ -10,7 +10,7 @@ skill. The model makes semantic skill choices from the request, eligible skill
 descriptions, and raw saved preferences. SkillBoard does not tokenize, score,
 match, or recommend from v2 request text.
 
-Status: public alpha. Package 0.3.3 writes policy schema v2.
+Status: public alpha. Package 0.3.4 writes policy schema v2.
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/NyXXiR/skillboard/main/skillboard.png" alt="SkillBoard architecture diagram" width="100%">
@@ -192,6 +192,15 @@ skillboard skill forget <skill-id>
 `forget` never deletes skill files. It refuses skills that are still observed or
 shared, so shared skills must be unshared first.
 
+A valid generated inventory remains healthy when it no longer observes an
+unshared policy entry. Doctor/status expose sorted entries as
+`inventory.stalePolicySkills`; brief exposes the same observation as
+`health.inventory.stale_policy_skills`. Stale removed-skill policy does not fail
+strict health, change passed mode, or block other observed skills. The absent
+skill itself remains unavailable to route and guard. SkillBoard never deletes
+these entries automatically: review one current forget action, confirm it, and
+then reread the returned brief.
+
 Before removing the SkillBoard package, preview and apply the complete
 user-level cleanup:
 

package/docs/policy-model.md

@@ -54,6 +54,15 @@ optional audit metadata and never determine availability. Runtime and action
 authorization are outside SkillBoard's scope and remain with the agent or
 harness.
 
+Generated-inventory integrity is separate from stale removed-skill policy.
+Missing, malformed, unsupported, duplicate, or internally inconsistent
+inventory remains a hard health failure. When inventory is valid, policy ids it
+does not observe are reported as sorted stale-policy observations without
+failing strict health, changing passed mode, or blocking other observed skills.
+The absent skill remains unavailable to route and guard. Stale policy is retained
+until an explicit, confirmation-required forget action removes only that policy
+entry; SkillBoard never auto-deletes it.
+
 ## Installation default
 
 A newly discovered valid skill receives `enabled: true` and `shared: false`.

package/docs/reference.md

@@ -103,6 +103,17 @@ provenance, digests, aliases, install units, and runtime-component observations.
 Only `installed_on` participates in the presence check. Other observations are
 optional audit metadata and never determine availability.
 
+Missing, invalid JSON, unsupported flags or format, duplicate records, and
+malformed records are generated-inventory integrity failures. With an otherwise
+valid inventory, policy ids absent from inventory are instead sorted,
+non-blocking stale-policy observations. Doctor/status return them in
+`inventory.stalePolicySkills`; brief returns them in
+`health.inventory.stale_policy_skills`. They do not fail strict health or stop
+observed skills from routing and guard, while the specifically absent skill
+remains unavailable. No command automatically removes stale policy. A current
+`v2:forget-skill:<skill-id>` action requires explicit confirmation, refuses
+installed or shared skills, and changes policy only.
+
 Runtime and action authorization are outside SkillBoard's scope. The active
 agent or harness owns permission checks for hooks, MCP servers, commands,
 network access, external writes, destructive operations, and secrets.

package/package.json

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

package/src/advisor/schema.mjs

@@ -93,7 +93,8 @@ export function healthFromDoctor(doctor, paths) {
       required: true,
       ok: doctor.inventory.ok,
       path: doctor.inventory.path,
-      errors: sortedStrings(doctor.inventory.errors)
+      errors: sortedStrings(doctor.inventory.errors),
+      stale_policy_skills: sortedStrings(doctor.inventory.stalePolicySkills ?? [])
     };
   }
   return health;

package/src/brief-renderer.mjs

@@ -53,6 +53,7 @@ export function renderSkillBrief(brief, options = {}) {
   }
   emitIntentRoute(lines, brief);
   emitPolicyHealth(lines, brief);
+  emitStalePolicy(lines, brief);
   emitCategorySummary(lines, brief);
   emitNextAction(lines, brief, { verbose });
   emitAvailableNowSection(lines, brief, { verbose });
@@ -109,6 +110,19 @@ function emitPolicyHealth(lines, brief) {
   lines.push("");
 }
 
+function emitStalePolicy(lines, brief) {
+  const skills = brief.health?.inventory?.stale_policy_skills ?? [];
+  if (skills.length === 0) {
+    return;
+  }
+  lines.push("## Stale removed-skill policy", "");
+  lines.push("These policy entries are retained for explicit review and do not block other installed skills.");
+  for (const skill of skills) {
+    lines.push(`- ${safeText(skill)}`);
+  }
+  lines.push("");
+}
+
 function emitPolicyDiagnostics(lines, label, diagnostics) {
   if (diagnostics.length === 0) {
     return;

package/src/cli.mjs

@@ -1709,6 +1709,8 @@ function renderDoctorSummary(result) {
     `SkillBoard doctor: ${status}`,
     renderInstallation(result.installation),
     `Workspace: ${result.workspace.skills.declared} skills, ${result.workspace.workflows} workflows, ${result.workspace.harnesses} harnesses, ${result.workspace.installUnits.total} install units`,
+    `Inventory integrity: ${result.inventory.ok ? "passed" : "failed"} (${result.inventory.errors.length} errors)`,
+    `Stale removed-skill policy: ${result.inventory.stalePolicySkills.length}`,
     `Source audit: ${result.sources.ok ? "passed" : "failed"} (${result.sources.errors.length} errors, ${result.sources.warnings.length} warnings, ${result.sources.blockingWarnings.length} blocking)`,
     `Policy: ${result.policy.ok ? "passed" : "failed"} (${result.policy.errors.length} errors, ${result.policy.warnings.length} warnings)`
   ];
@@ -1746,6 +1748,8 @@ function renderDoctor(result) {
     `Config: ${result.config.exists ? result.config.valid ? `valid v${result.config.version}` : `invalid (${result.config.error})` : "missing"}`,
     `Bridge: ${bridges}`,
     `Workspace: ${result.workspace.skills.declared} declared skills, ${result.workspace.skills.installed} installed skills, ${result.workspace.workflows} workflows, ${result.workspace.harnesses} harnesses, ${result.workspace.installUnits.total} install units`,
+    `Inventory integrity: ${result.inventory.ok ? "passed" : "failed"} (${result.inventory.errors.length} errors)`,
+    `Stale removed-skill policy (${result.inventory.stalePolicySkills.length}): ${formatList(result.inventory.stalePolicySkills)}`,
     `Skill states: ${renderCounts(result.workspace.skills.byStatus)}`,
     `Invocations: ${renderCounts(result.workspace.skills.byInvocation)}`,
     `Source classes: ${renderCounts(result.workspace.installUnits.bySourceClass)}`,

package/src/doctor.mjs

@@ -47,7 +47,7 @@ export async function doctorProject(options = {}) {
     bridges,
     installation,
     workspace: emptyWorkspaceSummary(),
-    inventory: { required: false, ok: true, path: null, errors: [] },
+    inventory: { required: false, ok: true, path: null, errors: [], stalePolicySkills: [] },
     policy: { ok: false, errors: [], warnings: [] },
     sources: { checked: false, verified: options.verifySources === true, ok: false, errors: [], warnings: [], blockingWarnings: [], units: [] },
     uninstall,
@@ -136,12 +136,9 @@ function doctorRecommendations(result) {
   const recommendations = [];
   if (!result.inventory.ok) {
     recommendations.push("run skillboard inventory refresh and fix generated inventory integrity errors");
-    for (const error of result.inventory.errors) {
-      const match = /^skill (?<skill>[^ ]+) is missing from generated inventory$/u.exec(error);
-      if (match?.groups?.skill !== undefined) {
-        recommendations.push(`reinstall ${match.groups.skill} or run skillboard skill forget ${match.groups.skill}`);
-      }
-    }
+  }
+  for (const skill of result.inventory.stalePolicySkills) {
+    recommendations.push(`reinstall ${skill} or run skillboard skill forget ${skill}`);
   }
   if (!result.bridges.some((bridge) => bridge.status === "installed")) {
     recommendations.push("legacy project bridge blocks are absent; run skillboard init only if maintaining deprecated project-local policy");
@@ -176,20 +173,22 @@ function doctorRecommendations(result) {
 
 function inventoryHealth(workspace) {
   if (workspace.version !== 2) {
-    return { required: false, ok: true, path: null, errors: [] };
+    return { required: false, ok: true, path: null, errors: [], stalePolicySkills: [] };
   }
   const errors = [...(workspace.inventory?.integrityErrors ?? ["generated inventory is unavailable"])];
   const observed = new Set(workspace.inventory?.skillIds ?? []);
-  for (const skill of workspace.skills) {
-    if (!observed.has(skill.id)) {
-      errors.push(`skill ${skill.id} is missing from generated inventory`);
-    }
-  }
+  const stalePolicySkills = errors.length === 0
+    ? workspace.skills
+      .map((skill) => skill.id)
+      .filter((skillId) => !observed.has(skillId))
+      .sort((left, right) => left.localeCompare(right))
+    : [];
   return {
     required: true,
     ok: errors.length === 0,
     path: workspace.inventory?.path ?? null,
-    errors
+    errors,
+    stalePolicySkills
   };
 }