agent-skillboard 0.1.0

package/src/domain/rules/install-units.mjs

@@ -0,0 +1,95 @@
+import { RESERVED_SOURCE_CLASSES, hasRuntimeComponents, isModelSelectableInvocation, isUserControlledSource } from "../source-classes.mjs";
+
+export const installUnitRules = [
+  {
+    id: "UNIT-COMPONENT-001",
+    check(ctx) {
+      const diagnostics = [];
+      for (const unit of ctx.installUnits) {
+        if (unit.sourceClass !== undefined && RESERVED_SOURCE_CLASSES.has(unit.sourceClass) && !isUserControlledSource(unit)) {
+          diagnostics.push(`Install unit ${unit.id} uses reserved source_class: ${unit.sourceClass}.`);
+        }
+        diagnostics.push(...validateProvidedComponents(unit));
+        for (const skillId of unit.components.skills) {
+          const skill = ctx.skillsById.get(skillId);
+          if (skill === undefined) {
+            diagnostics.push(`Install unit ${unit.id} declares undeclared component skill: ${skillId}`);
+          } else if (skill.ownerInstallUnit !== undefined && skill.ownerInstallUnit !== unit.id) {
+            diagnostics.push(`Install unit ${unit.id} declares component skill ${skillId} owned by ${skill.ownerInstallUnit}.`);
+          }
+        }
+      }
+      return diagnostics;
+    }
+  },
+  {
+    id: "UNIT-REF-001",
+    check(ctx) {
+      const diagnostics = [];
+      for (const unit of ctx.installUnits) {
+        for (const workflow of unit.workflowDependencies) {
+          if (!ctx.workflowsByName.has(workflow)) {
+            diagnostics.push(`Install unit ${unit.id} references undeclared workflow dependency: ${workflow}`);
+          }
+        }
+      }
+      return diagnostics;
+    }
+  },
+  {
+    id: "UNIT-TRUST-001",
+    check(ctx) {
+      const diagnostics = [];
+      for (const unit of ctx.installUnits) {
+        if (unit.enabled && unit.trustLevel === "blocked") {
+          diagnostics.push(`Install unit ${unit.id} is enabled but trust_level is blocked.`);
+        }
+        const automaticSkills = unit.components.skills
+          .map((skillId) => ctx.skillsById.get(skillId))
+          .filter((skill) => skill !== undefined && isModelSelectableInvocation(skill.invocation));
+        if (unit.enabled && !isUserControlledSource(unit) && unit.trustLevel === "unreviewed" && automaticSkills.length > 0) {
+          diagnostics.push({
+            severity: "warning",
+            message: `Install unit ${unit.id} is unreviewed but owns model-selectable skills: ${automaticSkills.map((skill) => skill.id).join(", ")}.`
+          });
+        }
+        if (unit.enabled && unit.permissionRisk === "high" && !["trusted", "reviewed"].includes(unit.trustLevel)) {
+          diagnostics.push({
+            severity: "warning",
+            message: `Install unit ${unit.id} is high risk but not reviewed or trusted.`
+          });
+        }
+        if (unit.enabled && hasRuntimeComponents(unit) && unit.trustLevel === "unreviewed") {
+          diagnostics.push({
+            severity: "warning",
+            message: `Install unit ${unit.id} provides runtime components but is unreviewed.`
+          });
+        }
+      }
+      return diagnostics;
+    }
+  }
+];
+
+function validateProvidedComponents(unit) {
+  return [
+    ...validateComponentGroup(unit, "skills", unit.components.skills, ["skills", "skill"]),
+    ...validateComponentGroup(unit, "commands", unit.components.commands, ["commands", "command"]),
+    ...validateComponentGroup(unit, "hooks", unit.components.hooks, ["hooks", "hook"]),
+    ...validateComponentGroup(unit, "mcp_servers", unit.components.mcpServers, ["mcp-server", "mcp-servers", "mcp_server", "mcp_servers"])
+  ];
+}
+
+function validateComponentGroup(unit, label, values, aliases) {
+  const provides = aliases.some((alias) => unit.providedComponents.includes(alias));
+  if (values.length > 0 && !provides) {
+    return [`Install unit ${unit.id} lists ${label} but does not include ${aliases[0]} in provided_components.`];
+  }
+  if (values.length === 0 && provides) {
+    return [{
+      severity: "warning",
+      message: `Install unit ${unit.id} declares ${aliases[0]} in provided_components but lists no ${label}.`
+    }];
+  }
+  return [];
+}

package/src/domain/rules/skills.mjs

@@ -0,0 +1,105 @@
+import {
+  LEGACY_STATUSES,
+  TERMINAL_STATUSES,
+  validateSkillState
+} from "../skill-state-matrix.mjs";
+
+export const skillRules = [
+  {
+    id: "SKILL-STATUS-001",
+    check(ctx) {
+      const diagnostics = [];
+      for (const skill of ctx.skills) {
+        diagnostics.push(...validateStatusInvocation(skill));
+      }
+      return diagnostics;
+    }
+  },
+  {
+    id: "SKILL-SCOPE-001",
+    check(ctx) {
+      const diagnostics = [];
+      for (const skill of ctx.skills) {
+        if (ctx.defaults.requireExplicitWorkflow && skill.invocation === "workflow-auto" && !ctx.workflowScopedSkillIds.has(skill.id)) {
+          diagnostics.push(`Skill ${skill.id} uses workflow-auto but is not scoped to any workflow.`);
+        }
+      }
+      return diagnostics;
+    }
+  },
+  {
+    id: "SKILL-GLOBAL-001",
+    check(ctx) {
+      const diagnostics = [];
+      for (const skill of ctx.skills) {
+        if (skill.invocation !== "global-auto") {
+          continue;
+        }
+        diagnostics.push({
+          severity: "warning",
+          message: `Skill ${skill.id} is global-auto; prefer workflow-auto or router-only.`
+        });
+        if (skill.exposure !== "global-meta") {
+          diagnostics.push(`Skill ${skill.id} uses global-auto but is not exposure: global-meta.`);
+        }
+      }
+      return diagnostics;
+    }
+  },
+  {
+    id: "SKILL-REF-001",
+    check(ctx) {
+      const diagnostics = [];
+      for (const skill of ctx.skills) {
+        if (skill.replacedBy !== undefined && !ctx.skillsById.has(skill.replacedBy)) {
+          diagnostics.push(`Skill ${skill.id} replaced_by points to undeclared skill: ${skill.replacedBy}`);
+        }
+        for (const capabilityName of skill.canonicalFor) {
+          const capability = ctx.capabilitiesByName.get(capabilityName);
+          if (capability === undefined) {
+            diagnostics.push(`Skill ${skill.id} canonical_for references undeclared capability: ${capabilityName}`);
+          } else if (capability.canonical !== skill.id) {
+            diagnostics.push(`Skill ${skill.id} claims canonical_for ${capabilityName} but capability canonical is ${capability.canonical || "none"}.`);
+          }
+        }
+        for (const skillId of skill.conflictsWith) {
+          if (!ctx.skillsById.has(skillId)) {
+            diagnostics.push(`Skill ${skill.id} conflicts_with undeclared skill: ${skillId}`);
+          }
+        }
+      }
+      return diagnostics;
+    }
+  },
+  {
+    id: "SKILL-OWNER-001",
+    check(ctx) {
+      const diagnostics = [];
+      for (const skill of ctx.skills) {
+        if (skill.ownerInstallUnit !== undefined && !ctx.installUnitsById.has(skill.ownerInstallUnit)) {
+          diagnostics.push(`Skill ${skill.id} owner_install_unit points to undeclared install unit: ${skill.ownerInstallUnit}`);
+        }
+        if (skill.exposure === "unit-managed" && skill.ownerInstallUnit === undefined) {
+          diagnostics.push(`Skill ${skill.id} is unit-managed but does not declare owner_install_unit.`);
+        }
+        const owner = skill.ownerInstallUnit === undefined ? undefined : ctx.installUnitsById.get(skill.ownerInstallUnit);
+        if (owner !== undefined && !owner.components.skills.includes(skill.id)) {
+          diagnostics.push(`Skill ${skill.id} declares owner_install_unit ${owner.id} but is not listed in its component skills.`);
+        }
+      }
+      return diagnostics;
+    }
+  }
+];
+
+function validateStatusInvocation(skill) {
+  const diagnostics = [];
+  const result = validateSkillState(skill.status, skill.invocation, skill.id);
+  if (result !== null) {
+    diagnostics.push(result);
+  }
+  if (["active", "canonical"].includes(skill.status) && TERMINAL_STATUSES.has(skill.invocation)) {
+    diagnostics.push(`Active skill ${skill.id} cannot use invocation: ${skill.invocation}.`);
+  }
+  return diagnostics;
+}

package/src/domain/rules/workflows.mjs

@@ -0,0 +1,105 @@
+import {
+  INVOCATION_VALUES,
+  NON_CALLABLE_WORKFLOW_INVOCATIONS,
+  NON_CALLABLE_WORKFLOW_STATUSES
+} from "../constants.mjs";
+
+export const workflowRules = [
+  {
+    id: "WF-REF-001",
+    check(ctx) {
+      const diagnostics = [];
+      for (const workflow of ctx.workflows) {
+        if (workflow.harness !== "unspecified" && !ctx.harnessesByName.has(workflow.harness)) {
+          diagnostics.push(`Workflow ${workflow.name} references undeclared harness: ${workflow.harness}`);
+        }
+        for (const skillId of workflow.activeSkills) {
+          if (!ctx.skillsById.has(skillId)) {
+            diagnostics.push(`Workflow ${workflow.name} references undeclared active skill: ${skillId}`);
+          }
+        }
+        for (const skillId of workflow.blockedSkills) {
+          if (!ctx.skillsById.has(skillId)) {
+            diagnostics.push(`Workflow ${workflow.name} references undeclared blocked skill: ${skillId}`);
+          }
+        }
+        for (const capability of workflow.requiredCapabilities) {
+          if (!ctx.capabilitiesByName.has(capability.name)) {
+            diagnostics.push(`Workflow ${workflow.name} references undeclared required capability: ${capability.name}`);
+          }
+          if (capability.preferred !== "" && !ctx.skillsById.has(capability.preferred)) {
+            diagnostics.push(`Capability requirement ${capability.name} in workflow ${workflow.name} references undeclared preferred skill: ${capability.preferred}`);
+          }
+          for (const skillId of capability.fallback) {
+            if (!ctx.skillsById.has(skillId)) {
+              diagnostics.push(`Capability requirement ${capability.name} in workflow ${workflow.name} references undeclared fallback skill: ${skillId}`);
+            }
+          }
+        }
+      }
+      return diagnostics;
+    }
+  },
+  {
+    id: "WF-ACTIVE-001",
+    check(ctx) {
+      const diagnostics = [];
+      for (const workflow of ctx.workflows) {
+        const blocked = new Set(workflow.blockedSkills);
+        for (const skillId of workflow.activeSkills) {
+          const skill = ctx.skillsById.get(skillId);
+          if (skill === undefined) {
+            continue;
+          }
+          if (blocked.has(skillId)) {
+            diagnostics.push(`Workflow ${workflow.name} lists skill ${skillId} as both active and blocked.`);
+          }
+          diagnostics.push(...nonCallableDiagnostics(`Workflow ${workflow.name} activates`, skill));
+        }
+      }
+      return diagnostics;
+    }
+  },
+  {
+    id: "WF-CAPABILITY-001",
+    check(ctx) {
+      const diagnostics = [];
+      for (const workflow of ctx.workflows) {
+        const blocked = new Set(workflow.blockedSkills);
+        for (const capability of workflow.requiredCapabilities) {
+          if (!INVOCATION_VALUES.has(capability.policy)) {
+            diagnostics.push(`Capability requirement ${capability.name} in workflow ${workflow.name} has unsupported policy: ${capability.policy}`);
+          }
+          if (capability.preferred !== "" && blocked.has(capability.preferred)) {
+            diagnostics.push(`Capability requirement ${capability.name} in workflow ${workflow.name} prefers blocked skill: ${capability.preferred}`);
+          }
+          for (const skillId of capability.fallback) {
+            if (blocked.has(skillId)) {
+              diagnostics.push(`Capability requirement ${capability.name} in workflow ${workflow.name} lists blocked fallback skill: ${skillId}`);
+            }
+            const fallback = ctx.skillsById.get(skillId);
+            if (fallback !== undefined) {
+              diagnostics.push(...nonCallableDiagnostics(`Capability requirement ${capability.name} in workflow ${workflow.name} lists fallback`, fallback));
+            }
+          }
+          const preferred = capability.preferred === "" ? undefined : ctx.skillsById.get(capability.preferred);
+          if (preferred !== undefined) {
+            diagnostics.push(...nonCallableDiagnostics(`Capability requirement ${capability.name} in workflow ${workflow.name} prefers`, preferred));
+          }
+        }
+      }
+      return diagnostics;
+    }
+  }
+];
+
+function nonCallableDiagnostics(prefix, skill) {
+  const diagnostics = [];
+  if (NON_CALLABLE_WORKFLOW_STATUSES.has(skill.status)) {
+    diagnostics.push(`${prefix} non-callable skill ${skill.id} with status: ${skill.status}.`);
+  }
+  if (NON_CALLABLE_WORKFLOW_INVOCATIONS.has(skill.invocation)) {
+    diagnostics.push(`${prefix} non-callable skill ${skill.id} with invocation: ${skill.invocation}.`);
+  }
+  return diagnostics;
+}

package/src/domain/skill-state-matrix.mjs

@@ -0,0 +1,79 @@
+/**
+ * Status/invocation state matrix for skill lifecycle.
+ *
+ * SkillBoard allows 14 statuses and 7 invocations, but only a subset
+ * of the 98 combinations is meaningful. This module makes the allowed
+ * combinations explicit and provides helpers for policy checks.
+ */
+
+/**
+ * Allowed status -> invocation combinations.
+ * A status maps to one or more valid invocations.
+ * Any combination not listed here is rejected by policy.
+ */
+export const SKILL_STATE_MATRIX = {
+  discovered: ["manual-only", "blocked"],
+  quarantined: ["blocked"],
+  vendor: ["manual-only"],
+  candidate: ["manual-only", "router-only", "workflow-auto"],
+  active: ["manual-only", "router-only", "workflow-auto", "global-auto"],
+  "active-manual": ["manual-only"],
+  "active-router": ["router-only"],
+  "active-auto": ["workflow-auto"],
+  canonical: ["workflow-auto", "global-auto"],
+  blocked: ["blocked"],
+  deprecated: ["blocked", "deprecated"],
+  archived: ["blocked", "deprecated"],
+  removed: ["blocked", "deprecated"]
+};
+
+/**
+ * Statuses that exist only for backward compatibility or external import.
+ * They are still accepted but produce a warning because their semantics
+ * overlap with explicit invocation values.
+ */
+export const LEGACY_STATUSES = new Set([
+  "active-manual",
+  "active-router",
+  "active-auto",
+  "archived",
+  "removed"
+]);
+
+/**
+ * Statuses that imply a skill is no longer selectable in any workflow.
+ */
+export const TERMINAL_STATUSES = new Set(["blocked", "deprecated", "archived", "removed"]);
+
+/**
+ * Return true if the given status/invocation combination is allowed.
+ */
+export function isValidSkillState(status, invocation) {
+  const allowed = SKILL_STATE_MATRIX[status];
+  if (allowed === undefined) {
+    return false;
+  }
+  return allowed.includes(invocation);
+}
+
+/**
+ * Return a diagnostic message if the combination is disallowed, otherwise null.
+ */
+export function validateSkillState(status, invocation, skillId = "") {
+  if (!isValidSkillState(status, invocation)) {
+    const allowed = SKILL_STATE_MATRIX[status] ?? [];
+    const prefix = skillId ? `Skill ${skillId}` : "Skill";
+    if (allowed.length === 0) {
+      return `${prefix} has unsupported status: ${status}.`;
+    }
+    return `${prefix} with status ${status} must use one of: ${allowed.join(", ")}; got ${invocation}.`;
+  }
+  if (LEGACY_STATUSES.has(status)) {
+    const prefix = skillId ? `Skill ${skillId}` : "Skill";
+    return {
+      severity: "warning",
+      message: `${prefix} uses legacy status ${status}; prefer status "active" with an explicit invocation.`
+    };
+  }
+  return null;
+}

package/src/domain/source-classes.mjs

@@ -0,0 +1,99 @@
+import { isAbsolute } from "node:path";
+
+export function installUnitSourceClass(unit) {
+  if (unit.sourceClass !== undefined && unit.sourceClass.length > 0 && !RESERVED_SOURCE_CLASSES.has(unit.sourceClass)) {
+    return unit.sourceClass;
+  }
+  if (unit.kind === "harness") {
+    return "harness-bundle";
+  }
+  if (unit.kind === "workflow") {
+    return "workflow-bundle";
+  }
+  if (unit.kind === "plugin" || unit.kind === "marketplace") {
+    return "external-package";
+  }
+  if (unit.kind === "package-manager-dependency") {
+    return "package-manager";
+  }
+  if (["mcp-server", "hook", "agent", "lsp"].includes(unit.kind)) {
+    return "runtime-extension";
+  }
+  if (isUserControlledSource(unit)) {
+    return "user";
+  }
+  if (unit.kind === "skill") {
+    return "skill-pack";
+  }
+  return "unknown";
+}
+
+export function sourcePriority(sourceClass) {
+  if (sourceClass === "user") {
+    return 100;
+  }
+  if (sourceClass === "skill-pack") {
+    return 70;
+  }
+  if (sourceClass === "workflow-bundle") {
+    return 65;
+  }
+  if (sourceClass === "harness-bundle") {
+    return 60;
+  }
+  if (sourceClass === "runtime-extension") {
+    return 55;
+  }
+  if (sourceClass === "package-manager") {
+    return 50;
+  }
+  if (sourceClass === "external-package") {
+    return 40;
+  }
+  return 0;
+}
+
+export function installUnitPriority(unit) {
+  if (unit.priority !== null && unit.priority !== undefined) {
+    return unit.priority;
+  }
+  return sourcePriority(installUnitSourceClass(unit));
+}
+
+export function isUserControlledSource(unit) {
+  return unit.kind === "skill" && isLocalSourceReference(unit.source);
+}
+
+export function isLocalSourceReference(source, options = {}) {
+  const value = source.trim();
+  if (value.length === 0 || isCommandSourceReference(value)) {
+    return false;
+  }
+  if (value.startsWith("~/") || value.startsWith("./") || value.startsWith("../") || value === "." || value === "..") {
+    return true;
+  }
+  if (isAbsolute(value)) {
+    return true;
+  }
+  return options.allowBareRelative === true && !value.includes("://");
+}
+
+export function isCommandSourceReference(source) {
+  const value = source.trim();
+  return /^(?:npx|npm|pnpm|yarn|bunx|git|gh|curl|wget|uvx|pipx)\s+/u.test(value)
+    || /^\/[A-Za-z][\w-]*\s+/u.test(value);
+}
+
+export function hasRuntimeComponents(unit) {
+  const components = unit.components ?? {};
+  return ["mcp-server", "hook", "agent", "lsp"].includes(unit.kind)
+    || components.commands?.length > 0
+    || components.hooks?.length > 0
+    || components.mcpServers?.length > 0;
+}
+
+export function isModelSelectableInvocation(invocation) {
+  return invocation === "router-only" || invocation === "workflow-auto" || invocation === "global-auto";
+}
+
+export const RESERVED_SOURCE_CLASSES = new Set(["user"]);

package/src/hook-plan.mjs

@@ -0,0 +1,152 @@
+import { lstat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { loadWorkspace } from "./workspace.mjs";
+
+export const GUARD_HOOK_MODE = 0o755;
+
+export async function planGuardHookInstall(options) {
+  const { plan } = await buildGuardHookInstallPlan(options);
+  return plan;
+}
+
+export async function buildGuardHookInstallPlan(options) {
+  const workspace = await loadWorkspace({ configPath: options.configPath, skillsRoot: options.skillsRoot });
+  requireWorkflow(workspace, options.workflow);
+  const out = options.out ?? join(dirname(options.configPath), ".skillboard", "hooks", `skillboard-guard-${safeHookFilePart(options.workflow)}.sh`);
+  const command = options.command ?? "skillboard";
+  const skillsRoot = options.skillsRoot ?? "skills";
+  const script = renderGuardHookScript({
+    command,
+    workflow: options.workflow,
+    configPath: options.configPath,
+    skillsRoot
+  });
+  const target = await inspectHookTarget(out);
+  const plannedMode = modeToOctal(GUARD_HOOK_MODE);
+  const plan = {
+    path: out,
+    workflow: options.workflow,
+    command,
+    target_exists: target.exists,
+    target_type: target.type,
+    planned_mode: plannedMode,
+    permissions: modeToPermissions(GUARD_HOOK_MODE),
+    would_be_executable: (GUARD_HOOK_MODE & 0o111) !== 0,
+    preview: {
+      display: `Install executable guard hook for workflow ${options.workflow} at ${out}`,
+      shell: renderGuardHookInstallShellPreview({ path: out, mode: plannedMode, script })
+    }
+  };
+
+  return { plan, script };
+}
+
+export function assertGuardHookPlanIsInstallable(plan) {
+  if (plan.target_exists) {
+    throw new Error(`Refusing to overwrite existing hook path: ${plan.path}`);
+  }
+}
+
+function requireWorkflow(workspace, name) {
+  const workflow = workspace.workflows.find((candidate) => candidate.name === name);
+  if (workflow === undefined) {
+    throw new Error(`Unknown workflow: ${name}`);
+  }
+}
+
+function renderGuardHookScript(options) {
+  return `#!/usr/bin/env sh
+set -eu
+
+SKILLBOARD_BIN=\${SKILLBOARD_BIN:-${shellQuote(options.command)}}
+SKILLBOARD_CONFIG=\${SKILLBOARD_CONFIG:-${shellQuote(options.configPath)}}
+SKILLBOARD_SKILLS=\${SKILLBOARD_SKILLS:-${shellQuote(options.skillsRoot)}}
+SKILLBOARD_WORKFLOW=\${SKILLBOARD_WORKFLOW:-${shellQuote(options.workflow)}}
+
+if [ "\${SKILLBOARD_SKILL_ID:-}" != "" ]; then
+  skill_id="$SKILLBOARD_SKILL_ID"
+elif [ "\${1:-}" != "" ]; then
+  skill_id="$1"
+else
+  echo "SKILLBOARD_SKILL_ID or first argument is required" >&2
+  exit 64
+fi
+
+# Split SKILLBOARD_BIN so local hook configs can use commands like:
+#   SKILLBOARD_BIN="node bin/skillboard.mjs"
+# Paths containing spaces should be provided through an environment wrapper.
+set -- $SKILLBOARD_BIN
+exec "$@" guard use "$skill_id" --workflow "$SKILLBOARD_WORKFLOW" --config "$SKILLBOARD_CONFIG" --skills "$SKILLBOARD_SKILLS"
+`;
+}
+
+function renderGuardHookInstallShellPreview(options) {
+  const delimiter = uniqueHeredocDelimiter(options.script);
+  return [
+    `mkdir -p ${shellQuote(dirname(options.path))}`,
+    `cat > ${shellQuote(options.path)} <<'${delimiter}'`,
+    options.script,
+    delimiter,
+    `chmod ${options.mode} ${shellQuote(options.path)}`
+  ].join("\n");
+}
+
+function uniqueHeredocDelimiter(body) {
+  const usedLines = new Set(body.split(/\r?\n/u));
+  const base = "SKILLBOARD_GUARD_HOOK";
+  if (!usedLines.has(base)) {
+    return base;
+  }
+  for (let index = 1; ; index += 1) {
+    const candidate = `${base}_${index}`;
+    if (!usedLines.has(candidate)) {
+      return candidate;
+    }
+  }
+}
+
+async function inspectHookTarget(path) {
+  const existing = await lstat(path).catch((error) => {
+    if (error?.code === "ENOENT") {
+      return undefined;
+    }
+    throw error;
+  });
+  if (existing === undefined) {
+    return { exists: false, type: "missing" };
+  }
+  if (existing.isSymbolicLink()) {
+    return { exists: true, type: "symlink" };
+  }
+  if (existing.isFile()) {
+    return { exists: true, type: "file" };
+  }
+  if (existing.isDirectory()) {
+    return { exists: true, type: "directory" };
+  }
+  return { exists: true, type: "other" };
+}
+
+function modeToOctal(mode) {
+  return mode.toString(8).padStart(4, "0");
+}
+
+function modeToPermissions(mode) {
+  const triplets = [
+    [0o400, 0o200, 0o100],
+    [0o040, 0o020, 0o010],
+    [0o004, 0o002, 0o001]
+  ];
+  return triplets.map(([read, write, execute]) => {
+    return `${mode & read ? "r" : "-"}${mode & write ? "w" : "-"}${mode & execute ? "x" : "-"}`;
+  }).join("");
+}
+
+function shellQuote(value) {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function safeHookFilePart(value) {
+  const cleaned = value.replace(/[^A-Za-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
+  return cleaned.length === 0 ? "workflow" : cleaned;
+}

package/src/impact.mjs

@@ -0,0 +1,41 @@
+export function impactDisable(workspace, skillId) {
+  const affectedWorkflowEntries = workspace.workflows
+    .filter((workflow) => workflow.activeSkills.includes(skillId) || workflow.requiredCapabilities.some((capability) => {
+      return capability.preferred === skillId || capability.fallback.includes(skillId);
+    }));
+  const affectedWorkflows = affectedWorkflowEntries.map((workflow) => workflow.name);
+  const affectedOutputs = [...new Set(affectedWorkflowEntries.flatMap((workflow) => workflow.requiredOutputs))];
+  const skill = workspace.skills.find((candidate) => candidate.id === skillId);
+  const alternatives = alternativesForSkill(workspace, skillId, skill);
+  return {
+    skillId,
+    exists: skill !== undefined,
+    affectedWorkflows,
+    affectedOutputs,
+    alternatives,
+    risk: riskFor(skill, affectedWorkflows, alternatives)
+  };
+}
+
+function alternativesForSkill(workspace, skillId, skill) {
+  if (skill?.replacedBy !== undefined) {
+    return [skill.replacedBy];
+  }
+  const capability = workspace.capabilities.find((candidate) => {
+    return candidate.canonical === skillId || candidate.alternatives.includes(skillId);
+  });
+  if (capability === undefined) {
+    return [];
+  }
+  return [capability.canonical, ...capability.alternatives].filter((candidate) => candidate !== skillId);
+}
+
+function riskFor(skill, affectedWorkflows, alternatives) {
+  if (skill === undefined) {
+    return "unknown";
+  }
+  if (affectedWorkflows.length === 0) {
+    return "low";
+  }
+  return alternatives.length === 0 ? "high" : "medium";
+}