agent-skillboard 0.1.0

package/src/lifecycle-cli.mjs

@@ -0,0 +1,166 @@
+import { isAbsolute, relative, resolve } from "node:path";
+import { initProject } from "./init.mjs";
+import { uninstallProject } from "./uninstall.mjs";
+
+export async function runInitCommand(options, stdout, runtime = defaultRuntime()) {
+  const root = resolve(options.get("dir") ?? ".");
+  const result = await initProject({
+    root,
+    scanInstalled: options.get("scan-installed") !== "false" && options.get("no-scan-installed") !== "true",
+    scanRoots: readCsv(options.get("scan-root"))
+  });
+  if (result.alreadyInitialized) {
+    stdout.write(`SkillBoard already initialized: ${root}\n`);
+    return 0;
+  }
+  stdout.write(`Initialized SkillBoard: ${root}\n`);
+  writeList(stdout, "Created", result.created);
+  writeList(stdout, "Updated", result.updated);
+  if (result.scan.scannedSkills > 0 || result.scan.scannedInstallUnits > 0) {
+    stdout.write(`Scanned installed agent skills: ${result.scan.scannedSkills}\n`);
+    stdout.write(`Managed install units: ${result.scan.scannedInstallUnits}\n`);
+  }
+  writeCountedList(stdout, "Added managed skills", result.scan.addedSkills);
+  writeList(stdout, "Added install units", result.scan.addedInstallUnits);
+  writeList(stdout, "Added workflows", result.scan.addedWorkflows ?? []);
+  writeList(stdout, "Added harnesses", result.scan.addedHarnesses ?? []);
+  writeList(stdout, "Skipped existing skills", result.scan.skippedSkills);
+  writeCountedList(stdout, "Review notes", result.scan.reviewNotes ?? []);
+  writeList(stdout, "Scan warnings", result.scan.warnings ?? []);
+  writeSafetyDefault(stdout, result.safety);
+  writeNextCommands(stdout, {
+    command: commandPrefix(runtime),
+    dir: options.get("dir")
+  });
+  return 0;
+}
+
+export async function runUninstallCommand(options, stdout) {
+  if (options.get("remove-config") === "true" && options.get("reset-config") === "true") {
+    throw new Error("--remove-config and --reset-config are mutually exclusive");
+  }
+  const root = resolve(options.get("dir") ?? ".");
+  const result = await uninstallProject({
+    root,
+    dryRun: options.get("dry-run") === "true",
+    removeConfig: options.get("remove-config") === "true",
+    resetConfig: options.get("reset-config") === "true",
+    removeReports: options.get("remove-reports") === "true",
+    removeHooks: options.get("remove-hooks") === "true",
+    removeEmptyDirs: options.get("keep-empty-dirs") !== "true"
+  });
+  stdout.write(`${result.dryRun ? "Dry run: " : ""}Uninstalled SkillBoard: ${root}\n`);
+  writeList(stdout, "Removed", result.removed);
+  writeList(stdout, "Updated", result.updated);
+  writeList(stdout, "Preserved", result.preserved);
+  return 0;
+}
+
+function writeList(stdout, label, values) {
+  if (values.length > 0) {
+    stdout.write(`${label}: ${formatList(values)}\n`);
+  }
+}
+
+function writeCountedList(stdout, label, values) {
+  if (values.length === 0) {
+    return;
+  }
+  stdout.write(`${label}: ${values.length}\n`);
+  for (const value of sorted(values).slice(0, 5)) {
+    stdout.write(`- \`${value}\`\n`);
+  }
+  const hidden = values.length - 5;
+  if (hidden > 0) {
+    stdout.write(`- ... ${hidden} more\n`);
+  }
+}
+
+function writeSafetyDefault(stdout, safety) {
+  stdout.write("Safety default:\n");
+  stdout.write("- Installed does not mean allowed.\n");
+  if (safety.automatic === 0) {
+    stdout.write("- No automatic model invocation was enabled.\n");
+  } else {
+    stdout.write(`- ${safety.automatic} automatic skills enabled by existing policy.\n`);
+  }
+  stdout.write("- Imported local skills are manual-only.\n");
+  stdout.write("- Runtime/plugin/system skills are quarantined until reviewed.\n");
+  stdout.write(`- ${safety.automatic} automatic skills enabled\n`);
+  stdout.write(`- ${safety.manualOnly} manual-only skills available\n`);
+  stdout.write(`- ${safety.routerOnly} router-only skills available\n`);
+  stdout.write(`- ${safety.blocked} blocked/quarantined for safety\n`);
+}
+
+function writeNextCommands(stdout, next) {
+  const dir = next.dir === undefined ? "" : ` --dir ${shellQuote(next.dir)}`;
+  stdout.write("Next:\n");
+  stdout.write(`- ${next.command} doctor${dir} --summary\n`);
+  stdout.write(`- ${next.command} brief${dir}\n`);
+  stdout.write(`- ${next.command} brief${dir} --verbose\n`);
+}
+
+function formatList(values) {
+  return values.length === 0 ? "none" : values.map((value) => `\`${value}\``).join(", ");
+}
+
+function sorted(values) {
+  return [...values].sort((left, right) => left.localeCompare(right));
+}
+
+function readCsv(value) {
+  if (value === undefined || value.trim() === "") {
+    return [];
+  }
+  return value.split(",").map((item) => item.trim()).filter((item) => item.length > 0);
+}
+
+function defaultRuntime() {
+  return {
+    cwd: process.cwd(),
+    entrypointPath: process.argv[1],
+    packageSpec: process.env.npm_config_package
+  };
+}
+
+function commandPrefix(runtime) {
+  const entrypoint = runtime.entrypointPath ?? "";
+  const normalized = entrypoint.replaceAll("\\", "/");
+  if (normalized.includes("/_npx/")) {
+    if (runtime.packageSpec !== undefined && runtime.packageSpec !== "agent-skillboard") {
+      return `npm exec --yes --package ${shellQuote(runtime.packageSpec)} -- skillboard`;
+    }
+    return "npx agent-skillboard";
+  }
+  if (isSourceTreeEntrypoint(entrypoint)) {
+    return `node ${sourceTreeEntrypoint(entrypoint, runtime.cwd ?? process.cwd())}`;
+  }
+  return "skillboard";
+}
+
+function isSourceTreeEntrypoint(entrypoint) {
+  if (entrypoint === "") {
+    return false;
+  }
+  const normalized = entrypoint.replaceAll("\\", "/");
+  return (normalized === "bin/skillboard.mjs" || normalized.endsWith("/bin/skillboard.mjs"))
+    && !normalized.includes("/node_modules/")
+    && !normalized.includes("/_npx/")
+    && !normalized.includes("/.npm/");
+}
+
+function sourceTreeEntrypoint(entrypoint, cwd) {
+  const absoluteEntrypoint = isAbsolute(entrypoint) ? entrypoint : resolve(cwd, entrypoint);
+  const relativeEntrypoint = relative(cwd, absoluteEntrypoint).replaceAll("\\", "/");
+  if (!relativeEntrypoint.startsWith("../") && relativeEntrypoint !== ".." && !isAbsolute(relativeEntrypoint)) {
+    return shellQuote(relativeEntrypoint);
+  }
+  return shellQuote(absoluteEntrypoint);
+}
+
+function shellQuote(value) {
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value)) {
+    return value;
+  }
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}

package/src/lifecycle-content.mjs

@@ -0,0 +1,87 @@
+export const BRIDGE_START = "<!-- BEGIN SKILLBOARD -->";
+export const BRIDGE_END = "<!-- END SKILLBOARD -->";
+
+export function defaultConfig() {
+  return `version: 1
+defaults:
+  invocation_policy: deny-by-default
+  allow_model_invocation: false
+  require_explicit_workflow: true
+
+skills: {}
+capabilities: {}
+harnesses: {}
+workflows: {}
+install_units: {}
+`;
+}
+
+export function bridgeBlock() {
+  return `${BRIDGE_START}
+# SkillBoard Control Plane
+
+This project uses SkillBoard as the source of truth for agent skill activation.
+
+- Read \`skillboard.config.yaml\` before assuming an installed skill is active.
+- Installed \`SKILL.md\` files are not automatically callable.
+- When a user asks what skills are available, run \`skillboard brief --json --config skillboard.config.yaml --skills skills\` before answering. If the workflow is known, include \`--workflow <name>\`; add \`--include-actions\` only when the user wants machine-readable change suggestions.
+- Treat the brief sections headed "What your AI can use now", "Needs your decision", and "Blocked for safety" as the availability summary; do not infer availability from \`SKILL.md\` bodies.
+- Treat "Needs your decision" as a one-time decision queue, not a persistent blocked state. "Blocked for safety" means the skill/source/workflow is hard-blocked until policy or provenance changes.
+- Use \`skillboard can-use <skill-id> --workflow <name> --config skillboard.config.yaml --skills skills --json\` for machine-readable agent decisions.
+- Approval loop for action cards: read the current \`skillboard brief --json\`, pick one current action id, ask the user for confirmation, then run \`skillboard apply-action <action-id> --config skillboard.config.yaml --skills skills --yes --json\` and include \`--workflow <name>\` when a workflow is selected.
+- After \`skillboard apply-action <action-id> ... --yes --json\`, read the returned post-apply brief before answering the next availability question or applying another action. \`apply-action\` re-resolves current actions; do not apply cached or stale action ids, do not apply multiple actions, and do not run raw action-card shell text as the primary apply path.
+- Immediately before actual invocation, run \`skillboard guard use <skill-id> --workflow <name> --config skillboard.config.yaml --skills skills\`.
+- Run \`skillboard audit sources --config skillboard.config.yaml --skills skills\` before trusting newly imported external skill sources.
+- Run \`skillboard review install-unit <unit-id> --trust-level reviewed --config skillboard.config.yaml --skills skills\` after reviewing an external source and before enabling automatic invocation from it.
+- Manual underlying hook detail: preview guard hook installation with \`skillboard hook install --workflow <name> --config skillboard.config.yaml --skills skills --out .skillboard/hooks/<name>-guard.sh --dry-run --json\`; inspect \`planned.preview.shell\` before materializing an executable guard hook outside the action-card approval loop.
+- Prefer workflow-scoped skills over global skill invocation.
+- Only \`global-meta\` skills may be treated as globally available.
+- Run \`skillboard doctor --config skillboard.config.yaml --skills skills\` or \`skillboard status --config skillboard.config.yaml --skills skills --json\` to inspect control-plane health; add \`--strict\` when review-needed safe mode should fail automation.
+- Run \`skillboard check --config skillboard.config.yaml --skills skills\` when policy state matters.
+- Run \`skillboard dashboard --config skillboard.config.yaml --skills skills --out .skillboard/reports/skill-map.md\` to refresh the visible control map.
+- Run \`skillboard add skill <skill-id> --path <relative-skill-path> --config skillboard.config.yaml --skills skills\` to register a user-owned skill without treating the file as automatically active.
+- Run \`skillboard add harness <harness-name> --config skillboard.config.yaml --skills skills\` and \`skillboard add workflow <workflow-name> --harness <harness-name> --config skillboard.config.yaml --skills skills --skill <skill-id>\` to add local growth paths without editing YAML by hand.
+- Use \`skillboard activate <skill-id> --workflow <name> --config skillboard.config.yaml --skills skills\` and \`skillboard block <skill-id> --workflow <name> --config skillboard.config.yaml --skills skills\` for workflow-scoped enablement.
+- Use \`skillboard remove skill <skill-id> --config skillboard.config.yaml --skills skills --force\` only after reviewing \`skillboard impact disable <skill-id> --config skillboard.config.yaml --skills skills\`; removal updates policy references while leaving \`SKILL.md\` files on disk.
+- Run \`skillboard inventory refresh --dry-run --config skillboard.config.yaml\` after installing a new local agent skill pack, plugin, workflow bundle, or harness.
+- Run \`skillboard import --profile <id-or-path> --source-root <repo> --out .skillboard/reports/import-fragment.yaml\` after installing a new skill repository, then review the fragment before merging it into \`skillboard.config.yaml\`.
+
+${BRIDGE_END}`;
+}
+
+export function profileReadme() {
+  return `# SkillBoard source profiles
+
+Put project-specific source profiles here when a skill repository or harness
+bundle is not covered by a built-in profile.
+
+Use:
+
+\`\`\`bash
+skillboard import --profile .skillboard/profiles/example.yaml --source-root /path/to/repo
+\`\`\`
+
+The import command emits a YAML fragment with governed \`skills\` and
+\`install_units\`. Review the fragment before merging it into
+\`skillboard.config.yaml\`; imported skills are not automatically active.
+`;
+}
+
+export function hookReadme() {
+  return `# SkillBoard hooks
+
+Use this directory for executable guard scripts generated by:
+
+\`\`\`bash
+skillboard hook install --workflow <name> --config skillboard.config.yaml --skills skills --out .skillboard/hooks/<name>-guard.sh --dry-run --json
+skillboard hook install --workflow <name> --config skillboard.config.yaml --skills skills --out .skillboard/hooks/<name>-guard.sh
+\`\`\`
+
+For hook action cards, prefer the bridge approval loop with
+\`skillboard apply-action <action-id> --yes --json\`. These raw hook commands
+are the underlying manual detail: preview the JSON plan first and inspect
+\`planned.preview.shell\` before materializing an executable guard hook.
+The generated script delegates to \`skillboard guard use\` and can be wired into
+the hook mechanism of the active harness.
+`;
+}

package/src/policy.mjs

@@ -0,0 +1,42 @@
+import { buildPolicyContext } from "./domain/indexes.mjs";
+import { capabilityRules } from "./domain/rules/capabilities.mjs";
+import { harnessRules } from "./domain/rules/harnesses.mjs";
+import { installUnitRules } from "./domain/rules/install-units.mjs";
+import { skillRules } from "./domain/rules/skills.mjs";
+import { workflowRules } from "./domain/rules/workflows.mjs";
+
+const RULES = [
+  ...workflowRules,
+  ...skillRules,
+  ...capabilityRules,
+  ...harnessRules,
+  ...installUnitRules
+];
+
+export function checkPolicy(workspace) {
+  const ctx = buildPolicyContext(workspace);
+  const errors = [];
+  const warnings = [];
+
+  for (const rule of RULES) {
+    for (const diagnostic of rule.check(ctx)) {
+      const normalized = normalizeDiagnostic(rule, diagnostic);
+      if (normalized.severity === "warning") {
+        warnings.push(normalized.message);
+      } else {
+        errors.push(normalized.message);
+      }
+    }
+  }
+
+  return { ok: errors.length === 0, errors, warnings };
+}
+
+function normalizeDiagnostic(rule, diagnostic) {
+  const severity = typeof diagnostic === "string" ? rule.severity ?? "error" : diagnostic.severity ?? rule.severity ?? "error";
+  const message = typeof diagnostic === "string" ? diagnostic : diagnostic.message;
+  return {
+    severity,
+    message: `[${rule.id}] ${message}`
+  };
+}

package/src/reconcile.mjs

@@ -0,0 +1,111 @@
+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);
+}

package/src/report.mjs

@@ -0,0 +1,151 @@
+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)}`);
+    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(", ");
+}

package/src/review.mjs

@@ -0,0 +1,88 @@
+import { randomUUID } from "node:crypto";
+import { readFile, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import YAML from "yaml";
+import { textChangePlan } from "./change-plan.mjs";
+import { TRUST_LEVEL_VALUES } from "./domain/constants.mjs";
+import { checkPolicy } from "./policy.mjs";
+import { loadWorkspace } from "./workspace.mjs";
+
+export async function reviewInstallUnit(options) {
+  const trustLevel = options.trustLevel ?? "reviewed";
+  if (!TRUST_LEVEL_VALUES.has(trustLevel)) {
+    throw new Error(`review install-unit requires --trust-level ${[...TRUST_LEVEL_VALUES].join("|")}; got ${trustLevel}`);
+  }
+
+  const { document, originalText } = await loadConfig(options.configPath);
+  const installUnits = requireMapAt(document, ["install_units"], "install_units");
+  const unit = installUnits.get(options.unitId, true);
+  if (unit === undefined) {
+    throw new Error(`Unknown install unit: ${options.unitId}`);
+  }
+  const unitMap = requireYamlMap(unit, `install_units.${options.unitId}`);
+  unitMap.set("trust_level", trustLevel);
+  if (trustLevel === "blocked") {
+    unitMap.set("enabled", false);
+  }
+
+  return await writeCheckedConfig(
+    document,
+    originalText,
+    options,
+    `Reviewed install unit ${options.unitId} as ${trustLevel}`
+  );
+}
+
+async function loadConfig(path) {
+  const text = await readFile(path, "utf8");
+  const document = YAML.parseDocument(text);
+  if (document.errors.length > 0) {
+    throw new Error(`Invalid YAML config: ${document.errors.map((error) => error.message).join("; ")}`);
+  }
+  requireYamlMap(document.contents, "config root");
+  return { document, originalText: text };
+}
+
+async function writeCheckedConfig(document, originalText, options, message) {
+  const nextText = preserveLineEndings(String(document), originalText);
+  const plan = textChangePlan(originalText, nextText);
+  const tempPath = join(dirname(options.configPath), `.${basename(options.configPath)}.${randomUUID()}.tmp`);
+  await writeFile(tempPath, nextText, { encoding: "utf8", flag: "wx" });
+  try {
+    const workspace = await loadWorkspace({ configPath: tempPath, skillsRoot: options.skillsRoot });
+    const policy = checkPolicy(workspace);
+    if (!policy.ok) {
+      throw new Error(`Policy update would create invalid config:\n${policy.errors.join("\n")}`);
+    }
+    if (options.dryRun === true) {
+      return { message, policy, dryRun: true, changed: plan.changed, plan };
+    }
+    if (plan.changed) {
+      await rename(tempPath, options.configPath);
+    }
+    return { message, policy, dryRun: false, changed: plan.changed, plan };
+  } finally {
+    await rm(tempPath, { force: true });
+  }
+}
+
+function requireMapAt(document, path, label) {
+  const value = document.getIn(path, true);
+  if (value === undefined) {
+    const map = document.createNode({});
+    document.setIn(path, map);
+    return map;
+  }
+  return requireYamlMap(value, label);
+}
+
+function requireYamlMap(value, label) {
+  if (!YAML.isMap(value)) {
+    throw new Error(`${label} must be a mapping`);
+  }
+  return value;
+}
+
+function preserveLineEndings(text, reference) {
+  return reference.includes("\r\n") ? text.replace(/\n/g, "\r\n") : text;
+}