agent-skillboard 0.1.2 → 0.2.2

package/src/advisor/actions.mjs

@@ -12,6 +12,7 @@ import { buildSetupGuidanceActions } from "./setup-actions.mjs";
 import { trustRecommendationAction } from "./trust-policy.mjs";
 
 const WRITABLE_MODES = new Set(["manual-only", "router-only", "workflow-auto"]);
+const NON_ACTIVATABLE_STATUSES = new Set(["deprecated", "archived", "removed"]);
 
 export function buildInitActions(paths) {
   return [makeAction({
@@ -82,7 +83,10 @@ function reviewInstallUnitActions({ paths, workflow, reviewQueue }) {
 }
 
 function activateSkillActions({ paths, workflow, skills, workspace }) {
-  const candidates = [...skills.not_in_workflow, ...skills.blocked.filter((skill) => missingProvenance(workspace, skill.id))];
+  const candidates = [
+    ...skills.not_in_workflow,
+    ...skills.blocked.filter((skill) => missingProvenance(workspace, skill.id) || canActivate(skill))
+  ];
   return candidates.flatMap((skill) => {
     if (missingProvenance(workspace, skill.id)) {
       return [blockedActivateAction(paths, workflow, skill)];
@@ -90,7 +94,7 @@ function activateSkillActions({ paths, workflow, skills, workspace }) {
     if (!canActivate(skill)) {
       return [];
     }
-    const mode = skill.advanced.invocation;
+    const mode = activationMode(skill);
     const risk = riskFromSkill(skill);
     const dryRun = command([
       "skillboard", "activate", skill.id, "--workflow", workflow.selected, "--mode", mode,
@@ -169,6 +173,7 @@ function hookInstallActions({ paths, workflow }) {
 function removeSkillForceActions({ paths, workflow, skills, workspace }) {
   return skills.blocked
     .filter((skill) => !missingProvenance(workspace, skill.id))
+    .filter((skill) => !canActivate(skill))
     .map((skill) => {
       const dryRun = command([
         "skillboard", "remove", "skill", skill.id, "--force",
@@ -230,7 +235,24 @@ function blockedActivateAction(paths, workflow, skill) {
 }
 
 function canActivate(skill) {
-  return WRITABLE_MODES.has(skill.advanced.invocation) && skill.advanced.trust.reviewed === true;
+  return activationMode(skill) !== null && skill.advanced.trust.reviewed === true;
+}
+
+function activationMode(skill) {
+  if (NON_ACTIVATABLE_STATUSES.has(skill.advanced.status)) {
+    return null;
+  }
+  if (WRITABLE_MODES.has(skill.advanced.invocation)) {
+    return skill.advanced.invocation;
+  }
+  if (
+    skill.advanced.owner_install_unit !== undefined
+    && skill.advanced.owner_install_unit !== null
+    && (skill.advanced.status === "quarantined" || skill.advanced.invocation === "blocked")
+  ) {
+    return "manual-only";
+  }
+  return null;
 }
 
 function missingProvenance(workspace, skillId) {

package/src/advisor/guidance.mjs

@@ -0,0 +1,232 @@
+import { command } from "./action-core.mjs";
+
+const GUARD_WHEN = "before invoking a skill";
+const GOAL_DOCUMENT = Object.freeze({
+  path: "docs/ai-skill-routing-goal.md",
+  purpose: "Preserve SkillBoard as a non-blocking AI skill routing control plane: route and work first when safe, explain briefly, ask after use when policy learning helps, and remember usage policy without rewriting skill bodies.",
+  when_to_read: Object.freeze([
+    "before changing routing",
+    "before changing brief output",
+    "before changing bridge instructions",
+    "before changing policy UX",
+    "before changing workflow UX"
+  ])
+});
+const GUARD_ALLOWED_USE = Object.freeze({
+  confirmation_required: false,
+  start: "State at the start which selected skill is being used for this request.",
+  finish: "State at completion which selected skill was used.",
+  start_message_template: "I will use <skill-id> for this request.",
+  finish_message_template: "I used <skill-id> for this request.",
+  ask_user_when: "Ask the user only if the guard denies use or a policy-changing action is needed."
+});
+
+export function buildAssistantGuidance(brief, options = {}) {
+  const status = guidanceStatus(brief);
+  const choices = status === "invalid-config" || hasPolicyErrors(brief) ? [] : choicesFromActions(brief.actions ?? []);
+  const route = options.route === undefined ? null : routeGuidance(options.route);
+  const guidance = {
+    status,
+    summary: summaryForStatus(status, brief),
+    goal_document: goalDocument(),
+    recommended_next_step: recommendedNextStep(status, brief, choices, route),
+    choices,
+    guard: {
+      required: true,
+      when: GUARD_WHEN,
+      command_hint: guardCommandHint(brief),
+      allowed_use: GUARD_ALLOWED_USE
+    }
+  };
+  if (route !== null) {
+    guidance.route = route;
+  }
+  return guidance;
+}
+
+function goalDocument() {
+  return {
+    ...GOAL_DOCUMENT,
+    when_to_read: [...GOAL_DOCUMENT.when_to_read]
+  };
+}
+
+function guidanceStatus(brief) {
+  if (hasInvalidConfig(brief)) {
+    return "invalid-config";
+  }
+  if (brief.error?.code === "not-initialized") {
+    return "not-initialized";
+  }
+  if (brief.error?.code === "unknown-workflow" || brief.workflow?.unknown === true) {
+    return "unknown-workflow";
+  }
+  if (brief.workflow?.needs_selection === true || brief.workflow?.selected === null) {
+    return "workflow-selection-needed";
+  }
+  if (hasPolicyErrors(brief)) {
+    return "blocked";
+  }
+  if ((brief.review_queue ?? []).length > 0 || brief.health?.review_required === true) {
+    return "needs-decision";
+  }
+  if (brief.health?.policy?.ok === false || brief.ok === false) {
+    return "blocked";
+  }
+  return "ready";
+}
+
+function hasInvalidConfig(brief) {
+  return brief.error?.code === "invalid-config"
+    || (brief.health?.config?.exists === true && brief.health.config.valid === false);
+}
+
+function summaryForStatus(status, brief) {
+  const readyCount = (brief.skills?.automatic_allowed?.length ?? 0) + (brief.skills?.manual_allowed?.length ?? 0);
+  const decisionCount = guidanceDecisionCount(brief);
+  const blockedCount = brief.skills?.blocked?.length ?? 0;
+  switch (status) {
+    case "ready":
+      return `SkillBoard is ready; ${readyCount} skills are available in this workflow.`;
+    case "needs-decision":
+      return `SkillBoard needs ${decisionCount} user ${decisionWord(decisionCount)} before this workflow is fully ready.`;
+    case "blocked":
+      return `SkillBoard found blocking policy issues; ${blockedCount} skills are blocked for safety.`;
+    case "not-initialized":
+      return "SkillBoard is not initialized in this project.";
+    case "invalid-config":
+      return "SkillBoard cannot read the project configuration.";
+    case "workflow-selection-needed":
+      return "SkillBoard needs a workflow selection before applying action cards.";
+    case "unknown-workflow":
+      return `SkillBoard does not know workflow ${brief.workflow?.selected ?? "the requested workflow"}.`;
+    default:
+      return "SkillBoard could not determine the current guidance state.";
+  }
+}
+
+function guidanceDecisionCount(brief) {
+  const skillDecisionCount = brief.skills?.needs_review?.length ?? 0;
+  if (skillDecisionCount > 0) {
+    return skillDecisionCount;
+  }
+  const reviewCount = brief.review_queue?.length ?? 0;
+  return reviewCount === 0 ? (brief.actions?.length ?? 0) : reviewCount;
+}
+
+function decisionWord(count) {
+  return count === 1 ? "decision" : "decisions";
+}
+
+function recommendedNextStep(status, brief, choices, route = null) {
+  const firstChoice = choices[0];
+  switch (status) {
+    case "ready":
+      if (route !== null) {
+        return route.recommended_skill === null
+          ? "Ask a clarifying question; no workflow capability matched this request."
+          : `Use ${route.recommended_skill} for this request after the guard check passes.`;
+      }
+      return "Run the guard check before invoking any selected skill.";
+    case "needs-decision":
+      if (route?.recommended_skill !== null && route?.guard_allowed === true) {
+        return `Use ${route.recommended_skill} for this request after the guard check passes; handle pending review decisions after the task unless a policy-changing action is needed now.`;
+      }
+      return firstChoice === undefined
+        ? "Ask the user which pending review decision to make."
+        : `Ask the user whether to approve: ${firstChoice.label}.`;
+    case "blocked":
+      if (hasPolicyErrors(brief)) {
+        return "Fix the SkillBoard policy errors before applying actions or invoking skills.";
+      }
+      return firstChoice === undefined
+        ? "Resolve the blocking policy issue before invoking skills."
+        : `Review the blocked item before applying: ${firstChoice.label}.`;
+    case "not-initialized":
+      return firstChoice === undefined
+        ? "Initialize SkillBoard before checking skill availability."
+        : `Ask the user whether to approve: ${firstChoice.label}.`;
+    case "invalid-config":
+      return "Fix the SkillBoard configuration before checking skill availability.";
+    case "workflow-selection-needed":
+      return (brief.workflow?.candidates?.length ?? 0) === 0
+        ? "Set up SkillBoard by refreshing inventory, then add a harness and workflow before applying action cards."
+        : "Ask the user which workflow to use.";
+    case "unknown-workflow":
+      return "Ask the user to choose one of the configured workflows.";
+    default:
+      return null;
+  }
+}
+
+function routeGuidance(route) {
+  return {
+    intent: route.intent,
+    workflow: route.workflow,
+    matched_capability: route.matched_capability,
+    matched_skill: route.matched_skill ?? null,
+    match_source: route.match_source,
+    confidence: route.confidence,
+    matched_terms: route.matched_terms,
+    recommendation_reason: route.recommendation_reason,
+    recommended_skill: route.recommended_skill,
+    fallback_skills: route.fallback_skills,
+    route_candidates: (route.route_candidates ?? []).map((candidate) => ({
+      skill: candidate.skill,
+      role: candidate.role,
+      selected: candidate.selected,
+      guard_allowed: candidate.guard_allowed,
+      guard_reasons: candidate.guard_reasons,
+      guard_roles: candidate.guard_roles,
+      capability_roles: candidate.capability_roles
+    })),
+    usage_disclosure: route.usage_disclosure ?? null,
+    post_use_policy_suggestion: route.post_use_policy_suggestion ?? null,
+    guard_command: route.guard_command,
+    guard_allowed: route.guard?.allowed ?? null,
+    guard_reasons: route.guard?.reasons ?? [],
+    possible_skills: route.possible_skills.map((skill) => ({
+      id: skill.id,
+      category: skill.category,
+      allowed: skill.allowed
+    }))
+  };
+}
+
+function hasPolicyErrors(brief) {
+  return (brief.health?.policy?.errors?.length ?? 0) > 0;
+}
+
+function choicesFromActions(actions) {
+  return actions.filter(confirmableAction).map((action) => ({
+    label: action.label,
+    action_id: action.id,
+    kind: action.kind,
+    applies_to: action.applies_to ?? null,
+    risk: action.risk,
+    requires_confirmation: action.requires_user_confirmation,
+    effect: action.reason,
+    blocked_reason: action.blocked_reason ?? action.application?.blocked_reason ?? null
+  }));
+}
+
+function confirmableAction(action) {
+  return action.blocked_reason === null
+    && (action.application?.blocked_reason ?? null) === null
+    && (action.application?.apply ?? null) !== null;
+}
+
+function guardCommandHint(brief) {
+  if (hasInvalidConfig(brief)) {
+    return null;
+  }
+  if (brief.workflow?.selected === null || brief.workflow?.unknown === true || brief.workflow?.needs_selection === true) {
+    return null;
+  }
+  return command([
+    "skillboard", "guard", "use", "<skill-id>",
+    "--workflow", brief.workflow.selected,
+    "--config", brief.health.config_path,
+    "--skills", brief.health.skills_root
+  ]).display;
+}

package/src/advisor/schema.mjs

@@ -1,5 +1,6 @@
 import { isAbsolute, resolve } from "node:path";
 import { uninstallProject } from "../uninstall.mjs";
+import { buildAssistantGuidance } from "./guidance.mjs";
 import { sortedStrings } from "./sort.mjs";
 
 const SCHEMA_VERSION = 1;
@@ -29,6 +30,7 @@ export function buildBrief(data) {
   if (data.actions !== undefined) {
     brief.actions = data.actions;
   }
+  brief.assistant_guidance = buildAssistantGuidance(brief, { route: data.route });
   return brief;
 }
 

package/src/advisor/skills.mjs

@@ -52,6 +52,7 @@ function declaredSkillEntry(summary, explanation, use, group) {
       invocation: summary.invocation,
       exposure: summary.exposure,
       category: summary.category,
+      variant: summary.variant ?? null,
       source_class: explanation.source.class,
       owner_install_unit: explanation.source.ownerInstallUnit,
       workflow_roles: use?.roles ?? summary.workflowRoles,
@@ -165,6 +166,7 @@ function isHardReason(reason) {
   return normalized.includes("policy check failed")
     || normalized.includes("unknown skill")
     || normalized.includes("unknown workflow")
+    || normalized.includes("conflicts with active skill")
     || normalized.includes("blocks skill")
     || normalized.includes("source trust policy")
     || (normalized.includes("install unit") && normalized.includes("disabled"))

package/src/advisor/trust-policy.mjs

@@ -21,9 +21,11 @@ export function recommendTrustLevel(unit) {
     return "trusted";
   }
 
-  // High-risk sources should not be activated from advisor suggestions without explicit blocking/review.
+  // High-risk sources require explicit review, not a default block. Blocking is
+  // still available as a recorded trust policy, but the advisor keeps the work
+  // moving by asking for a one-time source review first.
   if (risk === "high") {
-    return "blocked";
+    return "reviewed";
   }
 
   // Unknown risk always requires at least a review before any automatic use.
@@ -54,7 +56,7 @@ export function trustRecommendationAction(recommended) {
     return {
       kind: "block-install-unit",
       label: "Decide whether to block source",
-      reason: "High-risk or runtime-extending source needs a one-time decision before its skills appear again."
+      reason: "Source is blocked by trust policy and needs an explicit decision before its skills appear again."
     };
   }
   return {

package/src/advisor.mjs

@@ -3,6 +3,7 @@ import {
   listWorkflows
 } from "./control.mjs";
 import { doctorProject } from "./doctor.mjs";
+import { routeSkill } from "./route.mjs";
 import { buildActionCards, buildInitActions } from "./advisor/actions.mjs";
 import {
   buildBrief,
@@ -52,7 +53,7 @@ export async function buildSkillBrief(options = {}) {
     return buildExpectedConfigError(configDoctor, paths, cleanup, {
       code: "invalid-config",
       message: configDoctor.config.error ?? "skillboard.config.yaml is invalid"
-    });
+    }, options);
   }
 
   let workspace;
@@ -62,7 +63,7 @@ export async function buildSkillBrief(options = {}) {
     return buildExpectedConfigError(configDoctor, paths, cleanup, {
       code: "invalid-config",
       message: error instanceof Error ? error.message : String(error)
-    });
+    }, options);
   }
 
   const doctor = await doctorProject({
@@ -97,19 +98,46 @@ export async function buildSkillBrief(options = {}) {
 
   const skills = skillsForWorkflow(workspace, workflow.selected, sourceAudit);
   const actionData = actionsForBrief({ options, paths, workflow, skills, reviewQueue, cleanup, workspace });
+  const route = routeForBrief({ options, paths, workflow, workspace });
+  const availabilityOk = doctor.config.valid && doctor.policy.ok && doctor.sources.ok;
   return buildBrief({
-    ok: doctor.ok,
-    health: healthFromDoctor(doctor, paths),
+    ok: availabilityOk,
+    health: healthForBrief(doctor, paths, availabilityOk),
     workflow,
     skills,
     sources: summarizeSources(sourceAudit),
     reviewQueue: actionData.reviewQueue,
     cleanup,
-    actions: actionData.actions
+    actions: actionData.actions,
+    route
   });
 }
 
-function buildExpectedConfigError(doctor, paths, cleanup, error) {
+function routeForBrief({ options, paths, workflow, workspace }) {
+  const intent = options.intent?.trim();
+  if (intent === undefined || intent.length === 0 || workflow.selected === null || workflow.unknown || workflow.needs_selection) {
+    return undefined;
+  }
+  return routeSkill(workspace, {
+    intent,
+    workflow: workflow.selected,
+    configPath: paths.configPath,
+    skillsRoot: paths.skillsRoot
+  });
+}
+
+function healthForBrief(doctor, paths, availabilityOk) {
+  const health = healthFromDoctor(doctor, paths);
+  if (!availabilityOk || health.mode !== "failed") {
+    return health;
+  }
+  return {
+    ...health,
+    mode: health.review_required ? "safe-mode" : "passed"
+  };
+}
+
+function buildExpectedConfigError(doctor, paths, cleanup, error, options = {}) {
   return buildBrief({
     ok: false,
     error,
@@ -118,7 +146,8 @@ function buildExpectedConfigError(doctor, paths, cleanup, error) {
     skills: emptySkillGroups(),
     sources: sourcesFromDoctor(doctor),
     reviewQueue: [],
-    cleanup
+    cleanup,
+    actions: requestedActions(options) ? [] : undefined
   });
 }
 

package/src/brief-cli.mjs

@@ -6,11 +6,12 @@ export async function runBriefCommand(options, stdout, paths) {
   const json = options.get("json") === "true";
   const result = await buildSkillBrief({
     root: briefRoot(options),
-      configPath: paths.configPath,
-      skillsRoot: paths.skillsRoot,
-      workflow: options.get("workflow"),
-      includeActions: options.get("include-actions") === "true" || !json
-    });
+    configPath: paths.configPath,
+    skillsRoot: paths.skillsRoot,
+    workflow: options.get("workflow"),
+    intent: options.get("intent"),
+    includeActions: options.get("include-actions") === "true" || !json
+  });
   writeBriefOutput(stdout, result, options);
   return briefExitCode(result);
 }