@ctxr/skill-llm-wiki 1.0.1 → 1.1.0

package/scripts/lib/contract.mjs

@@ -0,0 +1,257 @@
+// contract.mjs — stable, machine-readable description of what this
+// skill speaks to consumers. The single source of truth for the
+// skill's format + CLI surface version.
+//
+// Consumers (other skills, agents, CI jobs) invoke
+// `node scripts/cli.mjs contract --json` and assert
+// `format_version >= <their required>` rather than drift-testing
+// against SKILL.md prose. Bump FORMAT_VERSION on any breaking change
+// to: leaf frontmatter schema, layout-contract grammar, CLI wire
+// protocol, or exit-code meanings. Additive changes do not bump.
+//
+// The shape returned by `getContract()` is documented in
+// guide/consumers/recipes/format-gate.md.
+
+import { readFileSync } from "node:fs";
+
+// ─── Version constants ──────────────────────────────────────────────
+// `FORMAT_VERSION` is an integer. Bumps are breaking changes to the
+// consumer-visible contract. Start at 1.
+export const FORMAT_VERSION = 1;
+
+// `MIN_CONSUMER_FORMAT_VERSION` is the oldest consumer-declared
+// format_version this skill still speaks to. A consumer whose
+// `required_format_version` is below this refuses to run; a consumer
+// whose `required_format_version` is between this and FORMAT_VERSION
+// runs unchanged. Bumps here signal a deprecation window closing.
+export const MIN_CONSUMER_FORMAT_VERSION = 1;
+
+// ─── Canonical shape ────────────────────────────────────────────────
+
+// Leaf + index frontmatter fields the skill reads and writes.
+// Mirrors scripts/lib/draft.mjs AUTHORED_LEAF_FIELDS for leaves
+// and scripts/lib/indices.mjs / scripts/lib/validate.mjs for
+// indices. Enums here are the canonical values the skill's own
+// code emits and validate.mjs accepts; consumers authoring their
+// own frontmatter must pick from these.
+const FRONTMATTER_SCHEMA = {
+  leaf: {
+    required: ["id", "type", "depth_role", "focus", "parents", "source"],
+    fields: {
+      id: { kind: "string", description: "Unique leaf identifier; derived from source path." },
+      // Leaves are `primary` by default; `overlay` is a dedicated
+      // type that carries a smaller body budget (see validate.mjs
+      // SIZE-CAP) and mandates overlay_targets[].
+      type: { kind: "enum", values: ["primary", "overlay"] },
+      // Leaves only ever carry depth_role "leaf". Indices have
+      // their own depth_role vocabulary (see index.depth_role
+      // below).
+      depth_role: { kind: "enum", values: ["leaf"] },
+      focus: { kind: "string", description: "One-line subject of the leaf." },
+      covers: { kind: "string[]", description: "Sub-topics or H2 headings." },
+      parents: { kind: "string[]", description: "Relative paths to parent index.md files (e.g. [index.md] or [../index.md])." },
+      tags: { kind: "string[]" },
+      source: {
+        kind: "object",
+        fields: {
+          origin: { kind: "enum", values: ["file", "synthetic"] },
+          path: { kind: "string", description: "POSIX-relative path from the source root." },
+          hash: { kind: "string", description: "SHA-256 of the source content." },
+        },
+      },
+      activation: { kind: "object", description: "Routing hints: keyword_matches, tag_matches, etc." },
+      domains: { kind: "string[]" },
+      aliases: { kind: "string[]" },
+      shared_covers: { kind: "string[]" },
+      // Only present (and required) when type === "overlay".
+      overlay_targets: { kind: "string[]" },
+      links: { kind: "string[]" },
+    },
+  },
+  index: {
+    required: ["id", "type", "depth_role", "focus"],
+    fields: {
+      id: { kind: "string", description: "Must match the containing directory's basename." },
+      type: { kind: "enum", values: ["index"] },
+      // `category` is the root index of a wiki; `subcategory` is
+      // any nested index. There is no `root` or `branch` role in
+      // the canonical shape; the skill refuses those.
+      depth_role: { kind: "enum", values: ["category", "subcategory"] },
+      focus: { kind: "string", description: "One-line subject of this branch." },
+      depth: { kind: "integer", description: "0 for root category, 1+ for subcategories." },
+      parents: { kind: "string[]", description: "Empty at the root; [../index.md] for nested." },
+      children: { kind: "string[]", description: "Relative paths to nested index files." },
+      entries: { kind: "object[]", description: "Per-leaf summaries (id, file, type, focus, tags)." },
+      shared_covers: { kind: "string[]", description: "Inherited by this branch's leaves." },
+      orientation: { kind: "string", description: "Authored guidance block; preserved across rebuilds." },
+      rebuild_command: { kind: "string" },
+      // Skill-generated marker; validate rejects a wiki root
+      // whose root index.md lacks it.
+      generator: { kind: "string", description: "e.g. \"skill-llm-wiki/v1\"; required on the root index." },
+    },
+  },
+};
+
+// Dynamic-subdirs template tokens supported inside
+// `.llmwiki.layout.yaml` under `layout[].dynamic_subdirs.template`.
+const LAYOUT_TOKENS = [
+  { token: "{yyyy}", description: "4-digit year." },
+  { token: "{mm}", description: "2-digit month." },
+  { token: "{dd}", description: "2-digit day of month." },
+  { token: "{slug}", description: "Leaf slug derived from source filename." },
+];
+
+// Exit code contract. Mirrors the banner in cli.mjs printUsage().
+// Listed here so consumers have a single machine-readable source.
+const EXIT_CODES = {
+  0: "ok",
+  1: "usage error",
+  2: "validation or ambiguity error",
+  3: "resolve-wiki miss",
+  4: "Node.js too old",
+  5: "git missing or too old",
+  6: "wiki corrupt",
+  7: "NEEDS_TIER2 — suspend and resume; not a failure",
+  8: "DEPS_MISSING — required runtime dep missing",
+};
+
+// Top-level subcommands consumers are expected to invoke. Low-level
+// helpers (`ingest`, `draft-leaf`, etc.) are deliberately omitted
+// from the contract: they are internal tools, subject to change
+// without a format_version bump. Keep this list in sync with
+// cli.mjs printUsage() top-level operations.
+// Keep this table in sync with scripts/cli.mjs. A drift test in
+// tests/unit/contract.test.mjs asserts every flag listed here is
+// actually accepted by the CLI's shared parser or one of the
+// per-subcommand handlers. `SUBCOMMANDS[*].flags` lists canonical
+// consumer-surface flags only; legacy aliases accepted by the CLI
+// (for example `--json-errors` as an alias of `--json`) are
+// deliberately omitted so consumers standardise on the current
+// flag form.
+const SUBCOMMANDS = {
+  build: {
+    positionals: ["source"],
+    flags: [
+      "--layout-mode",
+      "--target",
+      "--quality-mode",
+      "--fanout-target",
+      "--max-depth",
+      "--soft-dag-parents",
+      "--no-prompt",
+      "--accept-dirty",
+      "--accept-foreign-target",
+      "--json",
+    ],
+  },
+  extend: {
+    positionals: ["wiki"],
+    flags: [
+      "--quality-mode",
+      "--no-prompt",
+      "--json",
+    ],
+  },
+  validate: { positionals: ["wiki"], flags: ["--json"] },
+  rebuild: {
+    positionals: ["wiki"],
+    flags: [
+      "--quality-mode",
+      "--fanout-target",
+      "--max-depth",
+      "--soft-dag-parents",
+      "--review",
+      "--no-prompt",
+      "--json",
+    ],
+  },
+  fix: { positionals: ["wiki"], flags: ["--json"] },
+  join: {
+    // Variadic positionals — the CLI accepts
+    // `join <wiki-a> <wiki-b> [<wiki-c>...]`. `positionals` lists
+    // the minimum shape; `min_positionals` / `variadic` describe
+    // the full contract so consumers generating invocations or
+    // validating argument counts don't assume exactly two sources.
+    positionals: ["wiki-a", "wiki-b"],
+    min_positionals: 2,
+    variadic: true,
+    flags: [
+      "--target",
+      "--canonical",
+      "--id-collision",
+      "--quality-mode",
+      "--json",
+    ],
+  },
+  rollback: { positionals: ["wiki"], flags: ["--to", "--json"] },
+  init: {
+    positionals: ["topic"],
+    flags: ["--kind", "--template", "--force", "--json"],
+  },
+  heal: { positionals: ["wiki"], flags: ["--dry-run", "--json"] },
+  where: { positionals: [], flags: ["--json"] },
+  contract: { positionals: [], flags: ["--json"] },
+  "testkit-stub": { positionals: [], flags: ["--at", "--layout"] },
+};
+
+// Envelope schema that --json stdout follows across every command.
+// Full JSON Schema lives in scripts/lib/json-envelope.mjs (Feature
+// 5). Consumers gate on the `schema` discriminator.
+const ENVELOPE_SCHEMA = {
+  schema: "skill-llm-wiki/v1",
+  fields: {
+    schema: { kind: "string", const: "skill-llm-wiki/v1" },
+    command: { kind: "string" },
+    target: { kind: "string|null" },
+    verdict: { kind: "string" },
+    exit: { kind: "integer" },
+    diagnostics: { kind: "object[]" },
+    artifacts: { kind: "object" },
+    timing_ms: { kind: "integer" },
+    // `next` is optional: present only when the subcommand wants
+    // to hand the consumer a machine-readable follow-up command
+    // (init emits `{command:"skill-llm-wiki", args:["build",...]}`,
+    // heal emits the fix/rebuild invocation). When absent, the
+    // consumer has nothing to run.
+    next: { kind: "object|null", fields: { command: "string", args: "string[]" } },
+  },
+};
+
+// ─── Assembly ───────────────────────────────────────────────────────
+
+function packageVersion() {
+  try {
+    const pkgUrl = new URL("../../package.json", import.meta.url);
+    return JSON.parse(readFileSync(pkgUrl, "utf8")).version;
+  } catch {
+    return "unknown";
+  }
+}
+
+export function getContract() {
+  return {
+    schema: "skill-llm-wiki/contract/v1",
+    format_version: FORMAT_VERSION,
+    min_consumer_format_version: MIN_CONSUMER_FORMAT_VERSION,
+    package_version: packageVersion(),
+    frontmatter_schema: FRONTMATTER_SCHEMA,
+    layout_tokens: LAYOUT_TOKENS,
+    subcommands: SUBCOMMANDS,
+    envelope_schema: ENVELOPE_SCHEMA,
+    exit_codes: EXIT_CODES,
+  };
+}
+
+// Human-readable summary. Used when `contract` is invoked without
+// --json. Keep it short: anyone who wants detail takes --json.
+export function renderContractText(contract) {
+  const lines = [];
+  lines.push(`skill-llm-wiki contract`);
+  lines.push(`  package_version: ${contract.package_version}`);
+  lines.push(`  format_version: ${contract.format_version}`);
+  lines.push(`  min_consumer_format_version: ${contract.min_consumer_format_version}`);
+  lines.push(`  subcommands: ${Object.keys(contract.subcommands).join(", ")}`);
+  lines.push(`  layout_tokens: ${contract.layout_tokens.map((t) => t.token).join(" ")}`);
+  lines.push(`  envelope: ${contract.envelope_schema.schema}`);
+  return lines.join("\n") + "\n";
+}

package/scripts/lib/decision-log.mjs

@@ -16,9 +16,14 @@
 // queryable even after the op is reset.
 
 import {
+  appendFileSync,
+  closeSync,
   existsSync,
+  fstatSync,
   mkdirSync,
+  openSync,
   readFileSync,
+  readSync,
   renameSync,
   writeFileSync,
 } from "node:fs";
@@ -130,27 +135,112 @@ function emitEntry(entry) {
   return lines.join("\n");
 }
 
-// Append an entry atomically.
+// Append an entry.
+//
+// Hot path: at large-corpus scale (596 leaves → 189k pairwise
+// decisions observed) this is called once per decision. An earlier
+// implementation read the whole file, concatenated the new entry,
+// wrote to a temp, and renamed — O(file-size) per append. On a
+// 45 MB decisions.yaml that's ~22 MB of avg-read per call × 189k
+// calls ≈ 4 TB of I/O, which alone accounted for most of a 2h15m
+// build's wall-clock time.
+//
+// Durability guarantees:
+//
+//   - First call (file doesn't exist): writes header + first entry
+//     via temp+rename. The initial file materialises atomically —
+//     a crash during the first call leaves either no file or a
+//     well-formed single-entry file.
+//
+//   - Subsequent calls: best-effort `appendFileSync`. Each call is
+//     a single `write(2)` syscall of the serialised entry. In the
+//     common case the kernel writes the full buffer atomically,
+//     but this is NOT a formal durability contract for regular
+//     files the way temp+rename is:
+//
+//       * A crash mid-write can leave a torn trailing entry. On
+//         recovery the YAML parser will reject the truncated
+//         scalar; the audit log is recoverable by removing the
+//         last partial `- ...` block and re-running the op.
+//
+//       * Node's `writeSync`/`appendFileSync` MAY split a large
+//         buffer into multiple `write(2)` calls. Typical entry
+//         blocks here are ~200 bytes — well under typical
+//         single-write thresholds — but there is no portable
+//         small-write atomicity guarantee for regular files
+//         (POSIX's PIPE_BUF atomicity applies to pipes/FIFOs, not
+//         disk files).
+//
+//       * On Windows, `appendFileSync` has no equivalent of
+//         POSIX O_APPEND kernel serialisation under concurrent
+//         writers from multiple processes. This phase runs
+//         single-process though, so cross-process interleaving
+//         is not a concern in practice.
+//
+// The decision log is an audit trail, not a reproducibility
+// artefact — lost tail bytes on a crash are annoying but
+// recoverable, and the output tree's byte-reproducibility is
+// independent of this file's exact contents. If stronger
+// durability is needed for a specific use case, callers should
+// batch-flush to a temp file and rename on phase boundaries.
+//
+// Cost per append: O(entry-size), not O(file-size). ~200 µs vs
+// ~20 ms on a big log — a 100× speedup at scale.
 export function appendDecision(wikiRoot, entry) {
   validate(entry);
   const path = decisionLogPath(wikiRoot);
   mkdirSync(dirname(path), { recursive: true });
   const block = emitEntry(entry) + "\n";
-  let payload;
   if (!existsSync(path)) {
-    payload =
+    // First call: lay down the header atomically via temp+rename so
+    // a crash mid-creation doesn't leave an empty or orphan file.
+    const payload =
       "# skill-llm-wiki tiered-AI decision log (append-only)\n" +
       "version: 1\n" +
       "entries:\n" +
       block;
-  } else {
-    const existing = readFileSync(path, "utf8");
-    const prefix = existing.endsWith("\n") ? existing : existing + "\n";
-    payload = prefix + block;
+    const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
+    writeFileSync(tmp, payload, "utf8");
+    renameSync(tmp, path);
+    return;
+  }
+  // Subsequent appends: O(entry-size) via POSIX append. Peek at
+  // the last byte first: if the existing file doesn't end in a
+  // newline (manual edit, prior torn-tail truncation, or a
+  // creative crash), appending directly would concatenate the new
+  // entry onto the previous line and produce invalid YAML. Prefix
+  // a newline in that case — a leading blank line inside the
+  // entries[] list is harmless and parses fine.
+  const needsLeadingNewline = !endsWithNewline(path);
+  appendFileSync(path, needsLeadingNewline ? "\n" + block : block, "utf8");
+}
+
+// Check the last byte of the decision log without reading the
+// whole file. Uses a small anchored read rather than `readFileSync`
+// so the hot append path still pays O(1) regardless of log size.
+// An unreadable file (ENOENT, EACCES, race window) is treated as
+// "already newline-terminated" so the caller doesn't double up on
+// leading newlines on a transient read error.
+function endsWithNewline(path) {
+  let fd;
+  try {
+    fd = openSync(path, "r");
+    const { size } = fstatSync(fd);
+    if (size === 0) return true; // empty file has no trailing content to collide
+    const buf = Buffer.alloc(1);
+    readSync(fd, buf, 0, 1, size - 1);
+    return buf[0] === 0x0a; // 0x0a == '\n'
+  } catch {
+    return true;
+  } finally {
+    if (fd !== undefined) {
+      try {
+        closeSync(fd);
+      } catch {
+        /* best-effort */
+      }
+    }
   }
-  const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
-  writeFileSync(tmp, payload, "utf8");
-  renameSync(tmp, path);
 }
 
 // Convenience helper for cluster-NEST outcomes. The convergence
@@ -164,14 +254,18 @@ export function appendDecision(wikiRoot, entry) {
 //
 //   op_id, operator="NEST"                — as-is
 //   sources                               — leaf ids in the cluster
-//   tier_used                             — 2 (every NEST decision
-//                                           touches Tier 2 either
-//                                           via propose_structure
-//                                           or nest_decision)
+//   tier_used                             — caller-supplied (default 2
+//                                           for legacy Tier-2-touching
+//                                           NEST paths; 0 under
+//                                           `--quality-mode deterministic`
+//                                           since no sub-agent is
+//                                           consulted)
 //   similarity                            — average_affinity
 //   confidence_band                       — one of:
 //                                           "tier2-proposed",
+//                                           "tier2-and-math",
 //                                           "math-gated",
+//                                           "deterministic-math",
 //                                           "empty-partition",
 //                                           "rejected-by-metric",
 //                                           "rejected-by-gate"
@@ -187,16 +281,28 @@ export function appendDecision(wikiRoot, entry) {
 // Coercion: average_affinity may be undefined for Tier-2-proposed
 // clusters; we coerce to 0 so the finite-number validator does
 // not reject the entry.
+//
+// tier_used default: pre-deterministic-mode every NEST decision
+// touched Tier 2 via propose_structure or nest_decision, so the
+// default of 2 was correct. Under `--quality-mode deterministic`
+// Tier 2 is never consulted for math candidates; callers on that
+// path pass `tier_used: 0` so the audit trail correctly reflects
+// the fact that no sub-agent was invoked. The default remains 2
+// for backward compatibility with every existing call site.
 export function appendNestDecision(wikiRoot, entry) {
   const similarity =
     Number.isFinite(entry.similarity)
       ? entry.similarity
       : (Number.isFinite(entry.average_affinity) ? entry.average_affinity : 0);
+  const tier_used =
+    typeof entry.tier_used === "number" && Number.isInteger(entry.tier_used)
+      ? entry.tier_used
+      : 2;
   appendDecision(wikiRoot, {
     op_id: entry.op_id,
     operator: "NEST",
     sources: Array.isArray(entry.sources) ? entry.sources : [],
-    tier_used: 2,
+    tier_used,
     similarity,
     confidence_band: entry.confidence_band ?? null,
     decision: entry.decision,

package/scripts/lib/heal.mjs

@@ -0,0 +1,167 @@
+// heal.mjs — classify validate findings and name the next command.
+//
+// `skill-llm-wiki heal <wiki>` runs validate internally, then maps
+// the findings to one of five verdicts:
+//
+//   ok            → nothing to do
+//   fixable       → `skill-llm-wiki fix <wiki>` will resolve it
+//   needs-rebuild → `skill-llm-wiki rebuild <wiki>` is required
+//   broken        → the wiki is corrupt; manual intervention needed
+//   ambiguous     → validate itself failed before producing findings
+//
+// The consumer invokes the recommended command as a separate step.
+// Heal does not run fix/rebuild directly: doing so pulls in the
+// orchestrator's error surface (Tier 2 exits, validation rollback,
+// non-interactive refusal) that a classify-only shape deliberately
+// avoids. A follow-up can add --apply once that error-mapping is
+// proven.
+//
+// The classification table below is the public contract: consumers
+// who want to pre-classify findings themselves (e.g. for a CI dash)
+// can import FINDING_ACTIONS.
+
+import { validateWiki } from "./validate.mjs";
+
+// Map every known finding code to the minimum action that resolves
+// it. Ranked from cheapest ("none") to most invasive ("manual"):
+//
+//   none    → a warning; no mutating step required
+//   fix     → `skill-llm-wiki fix` is sufficient
+//   rebuild → `skill-llm-wiki rebuild` is required
+//   manual  → the wiki is broken in a way the skill cannot self-heal
+export const FINDING_ACTIONS = Object.freeze({
+  // Wiki substrate / git:
+  "WIKI-01": "manual", // not a valid wiki root
+  "GIT-01": "manual", // private git is broken / divergent
+
+  // Content loss:
+  "LOSS-01": "rebuild", // source bytes not accounted for in target
+
+  // Parse / malformed frontmatter:
+  PARSE: "manual", // cannot parse YAML; user must edit
+
+  // Frontmatter field issues — fix regenerates most of these:
+  "MISSING-FIELD": "fix",
+  "DUP-ID": "rebuild",
+  "ALIAS-COLLIDES-ID": "fix",
+  "ID-MISMATCH-DIR": "rebuild",
+  "ID-MISMATCH-FILE": "rebuild",
+  "DEPTH-ROLE": "rebuild",
+  "PARENTS-REQUIRED": "rebuild",
+  "PARENT-CONTRACT": "rebuild",
+  "DANGLING-LINK": "fix",
+  "DANGLING-OVERLAY": "fix",
+
+  // X.11 root-leaf containment invariant — `fix` runs Phase 4.4.5
+  // root-containment to move outlier leaves into per-slug
+  // subcategories:
+  "LEAF-AT-WIKI-ROOT": "fix",
+
+  // Size cap is a warning surface only:
+  "SIZE-CAP": "none",
+});
+
+// Priority ranking: if any finding maps to a higher-priority action,
+// that action wins for the whole wiki.
+const PRIORITY = Object.freeze({ none: 0, fix: 1, rebuild: 2, manual: 3 });
+
+// Verdict that corresponds to each action tier. Keeps the four
+// tables (FINDING_ACTIONS, PRIORITY, NEXT_COMMAND_BY_ACTION,
+// VERDICT_BY_ACTION) in parallel so adding a new action tier means
+// adding one row in each.
+const VERDICT_BY_ACTION = Object.freeze({
+  none: "ok",
+  fix: "fixable",
+  rebuild: "needs-rebuild",
+  manual: "broken",
+});
+
+function actionFor(code) {
+  return FINDING_ACTIONS[code] ?? "rebuild";
+}
+
+// Core routing. Pure: call validateWiki separately if you want to
+// avoid re-validating.
+export function classifyFindings(findings) {
+  const actions = new Set();
+  for (const f of findings) {
+    // Warnings never trigger a mutating verdict — they're advisory.
+    if (f.severity !== "error") continue;
+    actions.add(actionFor(f.code));
+  }
+  if (actions.size === 0) {
+    return { action: "none", verdict: "ok" };
+  }
+  let best = "none";
+  for (const a of actions) {
+    if (PRIORITY[a] > PRIORITY[best]) best = a;
+  }
+  return { action: best, verdict: VERDICT_BY_ACTION[best] };
+}
+
+// Full heal run against a wiki path. Returns an object the CLI
+// wraps into an envelope.
+export function runHeal(wikiPath) {
+  let findings;
+  try {
+    findings = validateWiki(wikiPath);
+  } catch (err) {
+    return {
+      target: wikiPath,
+      verdict: "ambiguous",
+      action: "manual",
+      findings: [],
+      error: err.message,
+      next_command: null,
+    };
+  }
+  const { action, verdict } = classifyFindings(findings);
+  const next_command = buildNextCommand(action, wikiPath);
+  return {
+    target: wikiPath,
+    verdict,
+    action,
+    findings,
+    error: null,
+    next_command,
+  };
+}
+
+// Map every action to the CLI invocation that resolves it. A map
+// rather than an if/else chain keeps the action vocabulary in one
+// place next to FINDING_ACTIONS / PRIORITY / VERDICT_BY_ACTION. To
+// add a new action tier, add a row here; anything else falls back
+// to `null` (no auto-step).
+const NEXT_COMMAND_BY_ACTION = Object.freeze({
+  none: null,
+  fix: (wikiPath) => ["skill-llm-wiki", "fix", wikiPath, "--json"],
+  rebuild: (wikiPath) => ["skill-llm-wiki", "rebuild", wikiPath, "--json"],
+  manual: null,
+});
+
+function buildNextCommand(action, wikiPath) {
+  const builder = NEXT_COMMAND_BY_ACTION[action];
+  if (typeof builder !== "function") return null;
+  return builder(wikiPath);
+}
+
+// Human-readable rendering of a runHeal result. Lives here so the
+// text and JSON output of heal stay under the same roof and cannot
+// drift. Mirrors the renderContractText / renderInitText pattern.
+export function renderHealText(result) {
+  const lines = [`heal: ${result.verdict} (${result.action})`];
+  for (const f of result.findings) {
+    const tag =
+      f.severity === "error"
+        ? "ERR "
+        : f.severity === "warning"
+          ? "WARN"
+          : "INFO";
+    lines.push(`  [${tag}] ${f.code}  ${f.target}`);
+    lines.push(`         ${f.message}`);
+  }
+  if (result.next_command) {
+    lines.push(`  next: ${result.next_command.join(" ")}`);
+  }
+  return lines.join("\n") + "\n";
+}