agent-skillboard 0.1.1 → 0.2.1

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.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);
 }

package/src/brief-renderer.mjs

@@ -1,6 +1,5 @@
+// SIZE_OK: src/brief-renderer.mjs is pre-existing renderer debt; this change only adds narrow AI/automation copy until a broader renderer split.
 const SKILL_SECTIONS = [
-  ["What your AI can use now", "automatic_allowed"],
-  ["Manual only", "manual_allowed"],
   ["Needs your decision", "needs_review"],
   ["Blocked for safety", "blocked"]
 ];
@@ -20,6 +19,7 @@ const CLEANUP_ACTION_KINDS = new Set([
 ]);
 const COMPACT_SKILL_LIMIT = 5;
 const TOP_CATEGORY_LIMIT = 5;
+const POLICY_DIAGNOSTIC_LIMIT = 3;
 const MAX_ACTIONS_PER_TEXT_SECTION = 5;
 const ACTION_KIND_RANK = new Map([
   ["setup-guidance", 0],
@@ -48,9 +48,16 @@ export function renderSkillBrief(brief, options = {}) {
   if (brief.error !== undefined) {
     lines.push(`Error: ${safeText(brief.error.message)}`, "");
   }
+  emitIntentRoute(lines, brief);
+  emitPolicyHealth(lines, brief);
   emitCategorySummary(lines, brief);
   emitNextAction(lines, brief, { verbose });
+  emitAvailableNowSection(lines, brief, { verbose });
   for (const [title, key] of SKILL_SECTIONS) {
+    if (key === "needs_review") {
+      emitDecisionSection(lines, brief, { verbose });
+      continue;
+    }
     emitSkillSection(lines, title, brief.skills[key], {
       brief,
       groupLabel: compactGroupLabel(key),
@@ -69,6 +76,109 @@ export function renderSkillBrief(brief, options = {}) {
   return `${lines.join("\n")}\n`;
 }
 
+function emitIntentRoute(lines, brief) {
+  const route = brief.assistant_guidance?.route;
+  if (route === undefined) {
+    return;
+  }
+  lines.push("## Suggested skill for this request", "");
+  lines.push(`- Intent: ${safeText(route.intent)}`);
+  lines.push(`- Match source: ${route.match_source}`);
+  lines.push(`- Matched capability: ${route.matched_capability ?? "none"}`);
+  lines.push(`- Matched skill: ${route.matched_skill === null ? "none" : code(route.matched_skill)}`);
+  lines.push(`- Confidence: ${route.confidence}`);
+  lines.push(`- Why: ${safeText(route.recommendation_reason, 320)}`);
+  lines.push(`- Matched terms: ${formatCodeList(route.matched_terms)}`);
+  if (route.recommended_skill === null) {
+    lines.push("- Recommended skill: none");
+    lines.push("- Next step: ask a clarifying question before choosing a skill.");
+  } else {
+    lines.push(`- Recommended skill: ${code(route.recommended_skill)}`);
+    lines.push(`- Fallback skills: ${formatCodeList(route.fallback_skills)}`);
+    if ((route.route_candidates ?? []).length > 0) {
+      lines.push("- Route candidates:");
+      for (const candidate of route.route_candidates) {
+        lines.push(`  - ${code(candidate.skill)} (${routeCandidateStatus(candidate)})`);
+        if (!candidate.guard_allowed && candidate.guard_reasons.length > 0) {
+          lines.push(`    - ${safeText(candidate.guard_reasons[0])}`);
+        }
+      }
+    }
+    lines.push(`- Guard: ${code(route.guard_command, Number.POSITIVE_INFINITY)}`);
+    if (route.usage_disclosure !== null && route.usage_disclosure !== undefined) {
+      lines.push(`- Disclosure: ${routeDisclosureText(code(route.recommended_skill))}`);
+      lines.push(`- Say before use: "${safeText(route.usage_disclosure.start_message)}"`);
+      lines.push(`- Say after completion: "${safeText(route.usage_disclosure.finish_message)}"`);
+    }
+    emitPostUsePolicySuggestion(lines, route.post_use_policy_suggestion);
+  }
+  lines.push("");
+}
+
+function routeCandidateStatus(candidate) {
+  return [
+    candidate.role,
+    candidate.selected ? "selected" : null,
+    candidate.guard_allowed ? "allowed" : "denied"
+  ].filter((value) => value !== null).join(", ");
+}
+
+function routeDisclosureText(skillLabel) {
+  return `run the guard automatically, state at the start that ${skillLabel} is being used, and state at completion that it was used. No extra user approval is needed when the guard allows it.`;
+}
+
+function emitPostUsePolicySuggestion(lines, suggestion) {
+  if (suggestion === null || suggestion === undefined) {
+    return;
+  }
+  lines.push(`- After completion: ${safeText(afterUsePromptText(suggestion.question))}`);
+  lines.push(`- Policy command after confirmation: ${code(suggestion.suggested_policy.command_hint, Number.POSITIVE_INFINITY)}`);
+}
+
+function afterUsePromptText(question) {
+  return question.replace(/^Should I /u, "ask whether to ").replace(/\?$/u, ".");
+}
+
+function emitPolicyHealth(lines, brief) {
+  const policy = brief.health?.policy;
+  if (policy === undefined) {
+    return;
+  }
+  const errors = policy.errors ?? [];
+  const warnings = policy.warnings ?? [];
+  if (errors.length === 0 && warnings.length === 0) {
+    return;
+  }
+  lines.push("## Policy health", "");
+  emitPolicyDiagnostics(lines, "Policy errors", errors);
+  emitPolicyDiagnostics(lines, "Policy warnings", warnings);
+  lines.push(`- check with: ${code(policyCheckCommand(brief), Number.POSITIVE_INFINITY)}`);
+  lines.push("");
+}
+
+function emitPolicyDiagnostics(lines, label, diagnostics) {
+  if (diagnostics.length === 0) {
+    return;
+  }
+  lines.push(`- ${label}: ${diagnostics.length}`);
+  for (const diagnostic of diagnostics.slice(0, POLICY_DIAGNOSTIC_LIMIT)) {
+    lines.push(`  - ${safeText(diagnostic)}`);
+  }
+  const hidden = diagnostics.length - POLICY_DIAGNOSTIC_LIMIT;
+  if (hidden > 0) {
+    lines.push(`  - ${hidden} more hidden. Run ${code("skillboard check")}.`);
+  }
+}
+
+function policyCheckCommand(brief) {
+  const config = brief.health?.config_path;
+  const skills = brief.health?.skills_root;
+  if (config === undefined || skills === undefined) {
+    return "skillboard check";
+  }
+  return `skillboard check --config ${config} --skills ${skills}`;
+}
+
 function briefCounts(brief) {
   const automatic = brief.skills.automatic_allowed.length;
   const manual = brief.skills.manual_allowed.length;
@@ -76,32 +186,133 @@ function briefCounts(brief) {
     automatic,
     manual,
     usable: automatic + manual,
-    needsDecision: brief.skills.needs_review.length,
+    needsDecision: decisionCount(brief),
     blocked: brief.skills.blocked.length
   };
 }
 
+function decisionCount(brief) {
+  const skillDecisionCount = brief.skills.needs_review.length;
+  if (skillDecisionCount > 0) {
+    return skillDecisionCount;
+  }
+  return brief.review_queue?.length ?? 0;
+}
+
+function emitAvailableNowSection(lines, brief, options) {
+  lines.push("## What your AI can use now", "");
+  const entries = [
+    ...brief.skills.automatic_allowed.map((entry) => ({ entry, mode: "automatic" })),
+    ...brief.skills.manual_allowed.map((entry) => ({ entry, mode: "manual-only" }))
+  ];
+  if (entries.length === 0) {
+    lines.push("- none", "");
+    return;
+  }
+  lines.push("Automatic skills can be selected by the AI. On-request skills can be used when the user asks the AI; the AI runs the guard first.");
+  lines.push("When the guard allows use, disclose the selected skill at the start and completion instead of asking again.", "");
+  const visibleEntries = options.verbose ? entries : entries.slice(0, COMPACT_SKILL_LIMIT);
+  for (const item of visibleEntries) {
+    lines.push(formatSkillEntry(item.entry, [availableModeLabel(item.mode)]));
+  }
+  const hiddenEntries = entries.slice(visibleEntries.length);
+  if (hiddenEntries.length > 0) {
+    lines.push(`- ${hiddenEntries.length} more ${availableHiddenLabel(hiddenEntries)} hidden. Run ${code(verboseCommand(brief))} or ${code(listCommand(brief))}.`);
+  }
+  lines.push("");
+}
+
+function availableHiddenLabel(entries) {
+  const modes = new Set(entries.map((entry) => entry.mode));
+  if (modes.size !== 1) {
+    return "available skills";
+  }
+  return modes.has("manual-only") ? "on-request skills" : "automatic skills";
+}
+
+function availableModeLabel(mode) {
+  return mode === "manual-only" ? "on request" : mode;
+}
+
 function emitSkillSection(lines, title, entries, options) {
   lines.push(`## ${title}`, "");
   if (entries.length === 0) {
     lines.push("- none", "");
     return;
   }
+  emitSkillEntries(lines, entries, options);
+  lines.push("");
+}
+
+function emitSkillEntries(lines, entries, options) {
   const visibleEntries = options.verbose ? entries : entries.slice(0, COMPACT_SKILL_LIMIT);
   for (const entry of visibleEntries) {
-    const path = entry.path === undefined ? "" : ` (${safeText(entry.path)})`;
-    const reason = entry.reason === null || entry.reason === undefined
-      ? ""
-      : ` - ${safeText(entry.reason)}`;
-    lines.push(`- ${code(entry.id)}${path}${reason}`);
+    lines.push(formatSkillEntry(entry));
   }
   const hidden = entries.length - visibleEntries.length;
   if (hidden > 0) {
     lines.push(`- ${hidden} more ${options.groupLabel} hidden. Run ${code(verboseCommand(options.brief))} or ${code(listCommand(options.brief))}.`);
   }
+}
+
+function formatSkillEntry(entry, labels = []) {
+  const path = entry.path === undefined ? "" : ` (${safeText(entry.path)})`;
+  const reason = entry.reason === null || entry.reason === undefined ? null : safeText(entry.reason);
+  const details = [...labels, reason].filter((value) => value !== null && value !== "");
+  const suffix = details.length === 0 ? "" : ` - ${details.join("; ")}`;
+  return `- ${code(entry.id)}${path}${suffix}`;
+}
+
+function emitDecisionSection(lines, brief, options) {
+  lines.push("## Needs your decision", "");
+  const skillEntries = brief.skills.needs_review;
+  const reviewEntries = reviewEntriesForDecisionSection(brief, skillEntries);
+  if (skillEntries.length === 0 && reviewEntries.length === 0) {
+    lines.push("- none", "");
+    return;
+  }
+  if (skillEntries.length > 0) {
+    emitSkillEntries(lines, skillEntries, {
+      ...options,
+      brief,
+      groupLabel: "decision items"
+    });
+  }
+  if (reviewEntries.length > 0) {
+    emitReviewQueueEntries(lines, reviewEntries, {
+      ...options,
+      brief
+    });
+  }
   lines.push("");
 }
 
+function reviewEntriesForDecisionSection(brief, skillEntries) {
+  if (skillEntries.length === 0) {
+    return brief.review_queue ?? [];
+  }
+  return [];
+}
+
+function emitReviewQueueEntries(lines, entries, options) {
+  const visibleEntries = options.verbose ? entries : entries.slice(0, COMPACT_SKILL_LIMIT);
+  for (const entry of visibleEntries) {
+    const label = entry.label ?? entry.title ?? entry.id;
+    const action = firstActionId(entry);
+    const actionText = action === null ? "" : ` - action: ${code(action)}`;
+    lines.push(`- ${safeText(label)} - ${safeText(entry.reason)}${actionText}`);
+  }
+  const hidden = entries.length - visibleEntries.length;
+  if (hidden > 0) {
+    lines.push(`- ${hidden} more review decisions hidden. Run ${code(verboseCommand(options.brief))}.`);
+  }
+}
+
+function firstActionId(entry) {
+  const [action] = entry.action_ids ?? [];
+  return typeof action === "string" ? action : null;
+}
+
 function emitCategorySummary(lines, brief) {
   const categories = categoryCounts(brief);
   lines.push("## Top categories", "");
@@ -173,6 +384,7 @@ function workflowOption(brief) {
 function emitActions(lines, brief, options) {
   const actions = actionsForTextBrief(brief);
   lines.push("## Suggested next actions", "");
+  lines.push("AI/automation operations should use current action ids from this brief, then ask for user confirmation before applying one action.", "");
   if (actions.length === 0) {
     lines.push("- none", "");
     return;
@@ -209,6 +421,7 @@ function emitActions(lines, brief, options) {
 
 function emitNextAction(lines, brief, options) {
   lines.push("## Next safe action", "");
+  lines.push("AI/automation should present this as the next confirmable operation, not as an automatic mutation.", "");
   const action = nextSafeAction(brief);
   if (action === null) {
     lines.push("- none", "");
@@ -360,3 +573,7 @@ function safeText(value, maxLength = 180) {
 function code(value, maxLength = 180) {
   return `\`${safeText(value, maxLength)}\``;
 }
+
+function formatCodeList(values) {
+  return values.length === 0 ? "none" : values.map((value) => code(value)).join(", ");
+}