@llblab/pi-actors 0.35.0 → 0.36.0

package/lib/recipes-discovery.ts

@@ -27,6 +27,7 @@ export interface DiscoveredRecipe {
   tool: boolean;
   mutableUsage: boolean;
   diagnostics: string[];
+  riskLabels: CommandTemplates.CommandTemplateRiskLabel[];
   shadows: string[];
 }
 
@@ -110,6 +111,14 @@ function listRecipeFiles(root: string): string[] {
     );
 }
 
+function getRecipeCommandTemplateConfig(
+  config: TemplateRecipeConfig,
+): CommandTemplates.CommandTemplateConfig {
+  return (typeof config.template === "object" && config.template !== null
+    ? config.template
+    : config) as CommandTemplates.CommandTemplateConfig;
+}
+
 function getRecipeConfigDiagnostics(
   file: string,
   config: TemplateRecipeConfig | undefined,
@@ -118,15 +127,36 @@ function getRecipeConfigDiagnostics(
     const reason = RecipesReferences.diagnoseRawRecipeConfigFailure(file);
     return [`Invalid recipe: ${file}${reason ? `: ${reason}` : ""}`];
   }
-  const commandTemplateConfig =
-    typeof config.template === "object" && config.template !== null
-      ? config.template
-      : config;
   return CommandTemplates.getCommandTemplateWarnings(
-    commandTemplateConfig as CommandTemplates.CommandTemplateConfig,
+    getRecipeCommandTemplateConfig(config),
   ).map((warning) => `Recipe ${file}: ${warning}`);
 }
 
+function getRecipeRiskLabels(
+  config: TemplateRecipeConfig | undefined,
+): CommandTemplates.CommandTemplateRiskLabel[] {
+  if (!config) return [];
+  const labels = new Set(
+    CommandTemplates.getCommandTemplateRiskLabels(
+      getRecipeCommandTemplateConfig(config),
+    ),
+  );
+  if (config.async === true) labels.add("risk.long_running");
+  return [
+    "risk.shell",
+    "risk.eval",
+    "risk.destructive_fs",
+    "risk.broad_fs_write",
+    "risk.external_side_effect",
+    "risk.secret_touching",
+    "risk.network",
+    "risk.long_running",
+    "risk.platform_specific",
+  ].filter((label): label is CommandTemplates.CommandTemplateRiskLabel =>
+    labels.has(label as CommandTemplates.CommandTemplateRiskLabel),
+  );
+}
+
 function readDiscoveredRecipe(
   root: string,
   file: string,
@@ -152,6 +182,7 @@ function readDiscoveredRecipe(
       tool: defaultTool && !disabled && !invalid,
       mutableUsage,
       diagnostics: getRecipeConfigDiagnostics(file, config),
+      riskLabels: getRecipeRiskLabels(config),
       shadows: [],
     };
   } catch (error) {
@@ -169,6 +200,7 @@ function readDiscoveredRecipe(
       diagnostics: [
         `Failed to load recipe ${file}: ${error instanceof Error ? error.message : String(error)}`,
       ],
+      riskLabels: [],
       shadows: [],
     };
   }
@@ -392,7 +424,7 @@ function diagnosticSeverity(message: string): "info" | "warning" | "error" {
     return "error";
   }
   if (
-    /world-writable|group-writable|invokes bash|eval|destructive|unsafe/i.test(
+    /world-writable|group-writable|invokes bash|eval|destructive|broad filesystem|unsafe/i.test(
       message,
     )
   ) {
@@ -435,6 +467,7 @@ function diagnosticDetails(
     seen.add(key);
     details.push({
       ...(entry ? { id: entry.id, path: entry.path } : {}),
+      ...(entry?.riskLabels.length ? { risk_labels: entry.riskLabels } : {}),
       action: diagnosticSuggestedAction(message),
       message,
       severity: diagnosticSeverity(message),
@@ -496,6 +529,7 @@ function remediationForEntry(
       kind: "risky_shell_boundary",
       severity: "warning",
       path: entry.path,
+      ...(entry.riskLabels.length ? { risk_labels: entry.riskLabels } : {}),
       reason: riskyDiagnostics[0],
       action:
         "audit trusted command boundary; keep only if the recipe is local and intentional",
@@ -544,6 +578,31 @@ function discoveryRemediations(
     );
 }
 
+function summarizeRiskLabels(
+  entries: DiscoveredRecipe[],
+): Array<Record<string, unknown>> {
+  const counts = new Map<string, { count: number; ids: Set<string> }>();
+  for (const entry of entries) {
+    for (const label of entry.riskLabels) {
+      const current = counts.get(label) ?? { count: 0, ids: new Set<string>() };
+      current.count += 1;
+      current.ids.add(entry.id);
+      counts.set(label, current);
+    }
+  }
+  return [...counts.entries()]
+    .map(([label, value]) => ({
+      label,
+      count: value.count,
+      recipes: [...value.ids].sort(),
+    }))
+    .sort(
+      (a, b) =>
+        Number(b.count) - Number(a.count) ||
+        String(a.label).localeCompare(String(b.label)),
+    );
+}
+
 function recommendationForEntry(
   entry: DiscoveredRecipe,
   activePath: string | undefined,
@@ -598,6 +657,7 @@ export function listDraftRecipes(root: string): Array<Record<string, unknown>> {
       /spawn run ([^\s]+)/,
     )?.[1];
     const preview = templatePreview(config?.template);
+    const riskLabels = getRecipeRiskLabels(resolved);
     return {
       id,
       path,
@@ -607,6 +667,7 @@ export function listDraftRecipes(root: string): Array<Record<string, unknown>> {
       modified_at: stat.mtime.toISOString(),
       valid: Boolean(resolved),
       diagnostics,
+      ...(riskLabels.length ? { risk_labels: riskLabels } : {}),
       ...(config?.description ? { description: config.description } : {}),
       ...(sourceRun ? { source_run: sourceRun } : {}),
       ...(config?.async !== undefined ? { async: config.async } : {}),
@@ -639,6 +700,7 @@ export function summarizeDiscovery(
         disabled: entry.disabled,
         invalid: entry.invalid,
         shadows: entry.shadows,
+        ...(entry.riskLabels.length ? { risk_labels: entry.riskLabels } : {}),
         ...(entry.config?.imports ? { imports: entry.config.imports } : {}),
         ...(recipeUsage(entry.config)
           ? { usage: recipeUsage(entry.config) }
@@ -665,6 +727,7 @@ export function summarizeDiscovery(
       .filter((entry) => entry.disabled)
       .map((entry) => ({ id: entry.id, path: entry.path }))
       .sort((a, b) => a.id.localeCompare(b.id)),
+    risk_summary: summarizeRiskLabels(result.entries),
     recommendations,
     remediations,
     top_action: remediations[0],

package/lib/runtime-notifier.ts

@@ -147,6 +147,7 @@ export function createFileRuntimeNotifier(
       mkdirSync(dirname(file), { recursive: true });
       let position =
         options.replay || !existsSync(file) ? 0 : statSync(file).size;
+      let pending = "";
       let closed = false;
       const reconcile = (reason: RuntimeReconcileReason): void => {
         if (closed) return;
@@ -160,10 +161,15 @@ export function createFileRuntimeNotifier(
       const drain = (): void => {
         if (closed || !existsSync(file)) return;
         const buffer = readFileSync(file);
-        if (position > buffer.length) position = 0;
-        const chunk = buffer.subarray(position).toString("utf8");
+        if (position > buffer.length) {
+          position = 0;
+          pending = "";
+        }
+        const chunk = pending + buffer.subarray(position).toString("utf8");
         position = buffer.length;
-        for (const line of chunk.split("\n")) {
+        const lines = chunk.split("\n");
+        pending = chunk.endsWith("\n") ? "" : (lines.pop() ?? "");
+        for (const line of lines) {
           if (!line.trim()) continue;
           const event = parseRuntimeWakeEventLine(line);
           if (event && event.actor === actor) {

package/lib/tools-inspect.ts

@@ -248,6 +248,181 @@ function compactPiActorsRuntimeStatus(status: Record<string, unknown>): string {
   return `\npi-actors version=${String(status.version)} mode=${String(status.mode)} path=${String(status.package_root)} entrypoint=${String(status.entrypoint)}${status.git_commit ? ` git=${String(status.git_commit)}` : ""}`;
 }
 
+function isStaleClaim(message: AsyncRuns.RunInboxMessage, now: number): boolean {
+  if (message.status !== "claimed") return false;
+  const claimedAt = Date.parse(String(message.claimed_at ?? ""));
+  return Number.isFinite(claimedAt) && now - claimedAt > 5 * 60 * 1000;
+}
+
+function getRunTriageSignals(
+  runs: Array<Record<string, unknown>>,
+): Record<string, unknown> {
+  const now = Date.now();
+  const staleClaims: Array<Record<string, unknown>> = [];
+  const attentionMessages: Array<Record<string, unknown>> = [];
+  for (const run of runs) {
+    const stateDir = String(run.state_dir ?? "");
+    const runId = String(run.run ?? "");
+    if (!stateDir) continue;
+    try {
+      for (const message of AsyncRuns.readRunInboxMessages(stateDir, 200)) {
+        if (!isStaleClaim(message, now)) continue;
+        staleClaims.push({
+          run: runId,
+          id: message.id,
+          claimed_at: message.claimed_at,
+          claimed_by: message.claimed_by,
+          type: message.type,
+        });
+      }
+    } catch {}
+    try {
+      for (const event of AsyncRuns.readRunEvents(stateDir, 80)) {
+        if (event.metadata?.requires_response !== true) continue;
+        attentionMessages.push({
+          run: runId,
+          id: event.id,
+          summary: event.summary,
+          type: event.type ?? event.event,
+        });
+      }
+    } catch {}
+  }
+  return { attention_messages: attentionMessages, stale_claims: staleClaims };
+}
+
+function isTriageHighRiskRecipe(recipe: Record<string, unknown>): boolean {
+  if (recipe.tool !== true) return false;
+  const labels = Array.isArray(recipe.risk_labels)
+    ? recipe.risk_labels.map((label) => String(label))
+    : [];
+  return labels.some((label) => label !== "risk.long_running");
+}
+
+function getPiActorsTriage(
+  ctx: unknown,
+  deps: InspectToolDeps,
+): Record<string, unknown> {
+  const runtime = getPiActorsRuntimeStatus();
+  const currentSession = ToolsAccess.getContextSessionId(ctx);
+  const allRuns = AsyncRuns.listRuns().map((run) =>
+    AsyncRuns.getRunStatus(String(run.state_dir)),
+  );
+  const visibleRuns = currentSession
+    ? allRuns.filter(
+        (run) => !run.ownerId || run.ownerId === currentSession,
+      )
+    : allRuns;
+  const activeRuns = visibleRuns.filter((run) => run.status === "running");
+  const failedRuns = visibleRuns.filter((run) => run.status === "failed");
+  const otherRuns = currentSession
+    ? allRuns.filter((run) => run.ownerId && run.ownerId !== currentSession)
+    : [];
+  const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
+  const discovered = RecipesDiscovery.discoverRecipeSources([
+    { root: recipeRoot, defaultTool: true, mutableUsage: true },
+    { root: deps.packagedRecipeRoot ?? Paths.getPackagedRecipeRoot() },
+  ]);
+  const recipeSummary: Record<string, unknown> = {
+    ...RecipesDiscovery.summarizeDiscovery(discovered),
+    drafts: RecipesDiscovery.listDraftRecipes(join(recipeRoot, "drafts")),
+  };
+  const activeRecipes = Array.isArray(recipeSummary.active)
+    ? (recipeSummary.active as Array<Record<string, unknown>>)
+    : [];
+  const highRiskRecipes = activeRecipes.filter(isTriageHighRiskRecipe);
+  const signals = getRunTriageSignals(visibleRuns);
+  const attentionMessages = signals.attention_messages as Array<
+    Record<string, unknown>
+  >;
+  const staleClaims = signals.stale_claims as Array<Record<string, unknown>>;
+  const invalidRecipes = Array.isArray(recipeSummary.invalid)
+    ? (recipeSummary.invalid as Array<Record<string, unknown>>)
+    : [];
+  const remediations = Array.isArray(recipeSummary.remediations)
+    ? (recipeSummary.remediations as Array<Record<string, unknown>>)
+    : [];
+  const drafts = Array.isArray(recipeSummary.drafts)
+    ? (recipeSummary.drafts as Array<Record<string, unknown>>)
+    : [];
+  const nextActions = [
+    invalidRecipes.length || remediations.length
+      ? "inspect target=recipes view=doctor"
+      : "",
+    drafts.length ? "inspect target=recipes view=summary verbose=true" : "",
+    failedRuns[0]?.run
+      ? `inspect target=run:${String(failedRuns[0].run)} view=tail lines=80`
+      : "",
+    attentionMessages[0]?.run
+      ? `inspect target=run:${String(attentionMessages[0].run)} view=messages`
+      : "",
+    activeRuns.length
+      ? "inspect target=session:all view=runs status=active"
+      : "",
+  ].filter(Boolean);
+  return {
+    runtime,
+    current_session: currentSession ?? null,
+    active_runs: activeRuns.map((run) => ({
+      run: run.run,
+      ownerId: run.ownerId,
+      recipe: run.recipe,
+      status: run.status,
+    })),
+    other_session_runs: otherRuns.length,
+    invalid_recipes: invalidRecipes,
+    blocking_recipes: remediations.filter((item) =>
+      String(item.kind ?? "").startsWith("blocking_"),
+    ),
+    high_risk_recipes: highRiskRecipes.map((recipe) => ({
+      id: recipe.id,
+      path: recipe.path,
+      risk_labels: recipe.risk_labels,
+    })),
+    draft_recipes: drafts,
+    stale_claims: staleClaims,
+    recent_failed_runs: failedRuns.slice(0, 5).map((run) => ({
+      run: run.run,
+      recipe: run.recipe,
+      status: run.status,
+    })),
+    attention_messages: attentionMessages.slice(-10),
+    next_actions: [...new Set(nextActions)].slice(0, 5),
+  };
+}
+
+function compactPiActorsTriage(summary: Record<string, unknown>): string {
+  const runtime = asRecord(summary.runtime);
+  const activeRuns = Array.isArray(summary.active_runs)
+    ? summary.active_runs.length
+    : 0;
+  const invalidRecipes = Array.isArray(summary.invalid_recipes)
+    ? summary.invalid_recipes.length
+    : 0;
+  const blockingRecipes = Array.isArray(summary.blocking_recipes)
+    ? summary.blocking_recipes.length
+    : 0;
+  const highRiskRecipes = Array.isArray(summary.high_risk_recipes)
+    ? summary.high_risk_recipes.length
+    : 0;
+  const drafts = Array.isArray(summary.draft_recipes)
+    ? summary.draft_recipes.length
+    : 0;
+  const staleClaims = Array.isArray(summary.stale_claims)
+    ? summary.stale_claims.length
+    : 0;
+  const failedRuns = Array.isArray(summary.recent_failed_runs)
+    ? summary.recent_failed_runs.length
+    : 0;
+  const attention = Array.isArray(summary.attention_messages)
+    ? summary.attention_messages.length
+    : 0;
+  const nextActions = Array.isArray(summary.next_actions)
+    ? (summary.next_actions as string[])
+    : [];
+  return `\ntriage version=${String(runtime.version ?? "unknown")} mode=${String(runtime.mode ?? "unknown")} active_runs=${activeRuns} other_runs=${String(summary.other_session_runs ?? 0)} invalid_recipes=${invalidRecipes} blocking_recipes=${blockingRecipes} high_risk_recipes=${highRiskRecipes} drafts=${drafts} stale_claims=${staleClaims} failed_runs=${failedRuns} attention=${attention}${ToolsResponse.compactNextActions(nextActions)}`;
+}
+
 function compactToolActor(name: string, tool: Record<string, unknown>): string {
   const parameters = asRecord(tool.parameters);
   const required = Array.isArray(parameters.required)
@@ -414,10 +589,15 @@ export function createInspectToolDefinition<TContext = unknown>(
       }
       if (address.kind === "tool" && address.value) {
         if (address.value === "pi-actors") {
-          if (view !== "status") {
-            throw new Error("inspect tool:pi-actors supports view=status.");
+          if (view !== "status" && view !== "triage") {
+            throw new Error(
+              "inspect tool:pi-actors supports view=status or view=triage.",
+            );
           }
-          const details = getPiActorsRuntimeStatus();
+          const details =
+            view === "triage"
+              ? getPiActorsTriage(ctx, deps)
+              : getPiActorsRuntimeStatus();
           return {
             content: [
               {
@@ -425,7 +605,9 @@ export function createInspectToolDefinition<TContext = unknown>(
                 text: maybeJsonText(
                   details,
                   input.verbose === true,
-                  compactPiActorsRuntimeStatus(details),
+                  view === "triage"
+                    ? compactPiActorsTriage(details)
+                    : compactPiActorsRuntimeStatus(details),
                 ),
               },
             ],

package/lib/tools-response.ts

@@ -173,15 +173,26 @@ export function compactRecipeDoctor(summary: Record<string, unknown>): string {
   const recommendations = Array.isArray(summary.recommendations)
     ? (summary.recommendations as Array<Record<string, unknown>>)
     : [];
+  const riskSummary = Array.isArray(summary.risk_summary)
+    ? (summary.risk_summary as Array<Record<string, unknown>>)
+    : [];
   const counts = { error: 0, info: 0, warning: 0 };
   for (const detail of details) {
     const severity = String(detail.severity ?? "info");
     if (severity === "error" || severity === "warning" || severity === "info")
       counts[severity] += 1;
   }
+  const riskCount = riskSummary.reduce(
+    (total, item) => total + Number(item.count ?? 0),
+    0,
+  );
+  const topRisks = riskSummary
+    .slice(0, 4)
+    .map((item) => `${String(item.label)}:${String(item.count ?? 0)}`)
+    .join(",");
   const topAction = asRecord(summary.top_action);
   const lines = [
-    `recipes doctor errors=${counts.error} warnings=${counts.warning} info=${counts.info} actions=${remediations.length} recommendations=${recommendations.length}`,
+    `recipes doctor errors=${counts.error} warnings=${counts.warning} info=${counts.info} actions=${remediations.length} recommendations=${recommendations.length} risks=${riskCount}${topRisks ? ` top_risks=${topRisks}` : ""}`,
   ];
   if (Object.keys(topAction).length > 0) {
     const action = compactPreview(
@@ -200,8 +211,11 @@ export function compactRecipeDoctor(summary: Record<string, unknown>): string {
     const blocked = item.blocked_fallback
       ? ` blocked=${compactPreview(item.blocked_fallback, Limits.DOCTOR_ACTION_PREVIEW_CHARS)}`
       : "";
+    const labels = Array.isArray(item.risk_labels)
+      ? ` labels=${(item.risk_labels as unknown[]).map(String).slice(0, 4).join(",")}`
+      : "";
     lines.push(
-      `${String(item.severity ?? "info")} kind=${String(item.kind ?? "inspect")} id=${String(item.id ?? "root")}${blocked} action=${action ?? "inspect"}`,
+      `${String(item.severity ?? "info")} kind=${String(item.kind ?? "inspect")} id=${String(item.id ?? "root")}${blocked}${labels} action=${action ?? "inspect"}`,
     );
   }
   const nextActions = Array.isArray(summary.next_actions)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [
@@ -29,7 +29,8 @@
     "conformance": "node scripts/conformance.mjs",
     "test": "node --experimental-strip-types --test tests/*.test.ts",
     "pack:dry": "npm pack --dry-run",
-    "validate": "npx tsc --noEmit && npm run build && npm run check && npm test && npm run pack:dry",
+    "recipes:qa": "node scripts/validate-recipe.mjs recipes --all --qa --summary",
+    "validate": "npx tsc --noEmit && npm run recipes:qa && npm run build && npm run check && npm test && npm run pack:dry",
     "build": "node scripts/build-dist.mjs",
     "prepack": "npm run build"
   },

package/scripts/validate-recipe.mjs

@@ -27,9 +27,9 @@ const { readResolvedRecipeConfig } = await importRuntimeModule("recipes-referenc
 
 export function validateRecipeUsage() {
   return `Usage:
-  validate-recipe.mjs <recipe-file-or-dir> [--all]
+  validate-recipe.mjs <recipe-file-or-dir> [--all] [--qa] [--summary]
 
-Validates one template recipe file, or all *.json/*.md files in a directory when --all is set.`;
+Validates one template recipe file, or all *.json/*.md files in a directory when --all is set. Add --qa for packaged-recipe quality checks. Add --summary for compact CLI output.`;
 }
 
 function expandPath(value) {
@@ -63,14 +63,133 @@ function recipeFiles(target, all) {
     .map((file) => resolve(target, file));
 }
 
-function validateFile(file) {
+function mailboxType(value) {
+  if (typeof value === "string") return value;
+  if (value && typeof value === "object" && typeof value.type === "string")
+    return value.type;
+  return undefined;
+}
+
+function collectTemplateStrings(value, out = []) {
+  if (typeof value === "string") out.push(value);
+  else if (Array.isArray(value)) value.forEach((item) => collectTemplateStrings(item, out));
+  else if (value && typeof value === "object") {
+    collectTemplateStrings(value.template, out);
+    collectTemplateStrings(value.recover, out);
+  }
+  return out;
+}
+
+function hasPlatformNote(config) {
+  const text = [
+    config.description,
+    config.platforms,
+    config.platform_notes,
+    config.requirements,
+  ]
+    .filter(Boolean)
+    .join(" ");
+  return /linux|macos|darwin|windows|win32|unix|wsl|cross-platform|portable/i.test(text);
+}
+
+function validateArtifactDeclarations(config) {
+  const diagnostics = [];
+  const artifacts = config.artifacts;
+  if (artifacts === undefined) return diagnostics;
+  if (!artifacts || typeof artifacts !== "object" || Array.isArray(artifacts)) {
+    diagnostics.push("artifacts: must be an object of named artifact paths");
+    return diagnostics;
+  }
+  for (const [name, value] of Object.entries(artifacts)) {
+    const path = typeof value === "string" ? value : value?.path;
+    if (typeof path !== "string" || !path.trim())
+      diagnostics.push(`artifacts.${name}: must declare a non-empty path`);
+    if (typeof path === "string" && /^\/home\//.test(path))
+      diagnostics.push(`artifacts.${name}: must not use a machine-local absolute path`);
+  }
+  return diagnostics;
+}
+
+function validateHelperPaths(file, config) {
+  const diagnostics = [];
+  for (const template of collectTemplateStrings(config.template)) {
+    if (/(^|\s)(?:node\s+)?scripts\/[\w.-]+\.mjs/.test(template))
+      diagnostics.push("template: helper scripts must be referenced through {repo}/scripts for installed packages");
+    for (const match of template.matchAll(/\{repo\}\/scripts\/([^\s"']+\.mjs)/g)) {
+      const scriptPath = join(packageRoot(), "scripts", match[1]);
+      if (!existsSync(scriptPath))
+        diagnostics.push(`template: referenced helper script not found: scripts/${match[1]}`);
+    }
+  }
+  return diagnostics;
+}
+
+function validateMailboxContract(file, config) {
+  const diagnostics = [];
+  const mailbox = config.mailbox;
+  const accepts = Array.isArray(mailbox?.accepts) ? mailbox.accepts : [];
+  const emits = Array.isArray(mailbox?.emits) ? mailbox.emits : [];
+  if (config.async === true && !mailbox)
+    diagnostics.push("mailbox: async recipes must declare mailbox metadata");
+  if (config.async === true && !accepts.map(mailboxType).includes("control.kill"))
+    diagnostics.push("mailbox.accepts: async recipes must include control.kill");
+  const allowedLegacyTypes = new Set(["awaiting_assignment"]);
+  for (const [key, entries] of Object.entries({ accepts, emits })) {
+    entries.forEach((entry, index) => {
+      const type = mailboxType(entry);
+      if (!type) diagnostics.push(`mailbox.${key}[${index}]: must be a string or object with type`);
+      else if (
+        !allowedLegacyTypes.has(type) &&
+        !/^[a-z][a-z0-9_-]*\.(?:[a-z][a-z0-9_-]*|\*)$/.test(type)
+      )
+        diagnostics.push(`mailbox.${key}[${index}]: message type must use channel.action form`);
+    });
+  }
+  const allowedDomainTermination = new Set([
+    "coordinator-locker.json",
+    "locker.json",
+    "music-player.json",
+  ]);
+  const hasDomainTermination = accepts
+    .map(mailboxType)
+    .some((type) => type === "control.stop" || type === "control.cancel");
+  if (hasDomainTermination && !allowedDomainTermination.has(file.split(/[\\/]/).pop()))
+    diagnostics.push("mailbox.accepts: control.stop/control.cancel are reserved for actor-domain handlers");
+  return diagnostics;
+}
+
+function qaDiagnostics(file, config) {
+  const diagnostics = [];
+  const warnings = [];
+  if (typeof config.description !== "string" || !config.description.trim())
+    warnings.push("description: missing or empty");
+  diagnostics.push(...validateMailboxContract(file, config));
+  diagnostics.push(...validateArtifactDeclarations(config));
+  diagnostics.push(...validateHelperPaths(file, config));
+  const platformSpecificTemplate = collectTemplateStrings(config.template).some(
+    (template) =>
+      /(^|\s)(?:systemctl|launchctl|osascript|powershell|pwsh|cmd\.exe|apt|apt-get|dnf|yum|brew|pacman|apk)(\s|$)/i.test(
+        template,
+      ),
+  );
+  if (platformSpecificTemplate && !hasPlatformNote(config))
+    diagnostics.push("platform: platform-specific templates must document platform scope");
+  return { diagnostics, warnings };
+}
+
+function qaOk(qaReport) {
+  return qaReport.diagnostics.length === 0;
+}
+
+function validateFile(file, qa = false) {
   try {
     const config = readResolvedRecipeConfig(file);
     if (!config?.template)
       throw new Error("Recipe must define a non-empty template.");
+    const qaReport = qa ? qaDiagnostics(file, config) : { diagnostics: [], warnings: [] };
     return {
       file,
-      ok: true,
+      ok: qaOk(qaReport),
       name: config.name ?? "",
       async: Boolean(config.async),
       args: Array.isArray(config.args) ? config.args : [],
@@ -93,6 +212,15 @@ function validateFile(file) {
                 : [],
             }
           : undefined,
+      ...(qa
+        ? {
+            qa: {
+              ok: qaOk(qaReport),
+              diagnostics: qaReport.diagnostics,
+              warnings: qaReport.warnings,
+            },
+          }
+        : {}),
       template: templateKind(config.template),
     };
   } catch (error) {
@@ -107,12 +235,13 @@ function validateFile(file) {
 export function validateRecipes(argv) {
   const targetArg = argv.find((arg) => !arg.startsWith("-"));
   const all = argv.includes("--all");
+  const qa = argv.includes("--qa");
   if (!targetArg || argv.includes("--help") || argv.includes("-h")) {
     return { help: true, ok: Boolean(targetArg), usage: validateRecipeUsage() };
   }
 
   const files = recipeFiles(expandPath(targetArg), all);
-  const results = files.map(validateFile);
+  const results = files.map((file) => validateFile(file, qa));
   const failed = results.filter((result) => !result.ok).length;
   return {
     ok: failed === 0,
@@ -123,10 +252,38 @@ export function validateRecipes(argv) {
   };
 }
 
+function summarizeReport(report) {
+  const results = Array.isArray(report.results) ? report.results : [];
+  return {
+    ok: report.ok,
+    total: report.total,
+    passed: report.passed,
+    failed: report.failed,
+    diagnostics: results.reduce(
+      (total, result) => total + (result.qa?.diagnostics?.length ?? 0),
+      0,
+    ),
+    warnings: results.reduce(
+      (total, result) => total + (result.qa?.warnings?.length ?? 0),
+      0,
+    ),
+    failed_files: results
+      .filter((result) => !result.ok)
+      .map((result) => ({
+        file: result.file,
+        ...(result.error ? { error: result.error } : {}),
+        ...(result.qa?.diagnostics?.length
+          ? { diagnostics: result.qa.diagnostics }
+          : {}),
+      })),
+  };
+}
+
 try {
-  const report = validateRecipes(process.argv.slice(2));
+  const argv = process.argv.slice(2);
+  const report = validateRecipes(argv);
   if (report.help) console.error(report.usage);
-  else console.log(JSON.stringify(report, null, 2));
+  else console.log(JSON.stringify(argv.includes("--summary") ? summarizeReport(report) : report, null, 2));
   process.exit(report.ok ? 0 : 1);
 } catch (error) {
   console.error(error instanceof Error ? error.message : String(error));