@bompus/house-rules 0.0.0-stage → 0.11.0

package/compose.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+// Composes rules and skills into explicit output paths; config commands manage selections.
+//   node compose.mjs --config <path> [--out <file>] [--skills-out <dir>]
+//   node compose.mjs config help
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { composeConfiguration, configurationPath, modifierList } from "./composition.mjs";
+import { configCommand } from "./config.mjs";
+import { setupCommand } from "./setup.mjs";
+import { checkOutputPath, planReferenceOutput, writeReferenceOutput } from "./rule-references.mjs";
+export {
+  compose,
+  composeConfiguration,
+  configurationPath,
+  loadFragments,
+  modifierList,
+  parseFragment,
+  skillSources,
+  splitSections,
+} from "./composition.mjs";
+const BASE = dirname(fileURLToPath(import.meta.url));
+const NOTICES = ["LICENSE", "THIRD_PARTY_NOTICES.md"];
+
+function main(argv) {
+  if (argv[0] === "setup") return setupCommand(argv.slice(1));
+  if (argv[0] === "config") {
+    return configCommand(argv.slice(1));
+  }
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      config: { type: "string" },
+      out: { type: "string" },
+      "skills-out": { type: "string" },
+      "references-out": { type: "string" },
+      list: { type: "boolean" },
+    },
+  });
+  if (values.list) {
+    for (const m of modifierList()) console.log(`${m.name}: ${m.description ?? ""}`);
+    return;
+  }
+  const configPath = configurationPath(values.config);
+  const config = JSON.parse(readFileSync(configPath, "utf8").replace(/^\uFEFF/, ""));
+  const { out, "skills-out": skillsOut, "references-out": explicitReferences } = values;
+  if (explicitReferences && !out) throw new Error("--references-out requires --out");
+  const referencesOut = out
+    ? resolve(explicitReferences ?? join(dirname(resolve(out)), "house-rules-references"))
+    : null;
+  const { fragments, rules, skills, warnings, references } = composeConfiguration(
+    config,
+    dirname(configPath),
+    referencesOut
+      ? { referencesDirectory: relative(dirname(resolve(out)), referencesOut) || "." }
+      : {},
+  );
+  for (const warning of warnings) console.error(`warning: ${warning}`);
+  const paths = [
+    out && { path: resolve(out), directory: false },
+    skillsOut && { path: resolve(skillsOut), directory: true },
+    referencesOut && { path: referencesOut, directory: true },
+  ].filter(Boolean);
+  for (const { path, directory } of paths) checkOutputPath(path, directory);
+  for (const a of paths)
+    for (const b of paths) {
+      if (a === b) continue;
+      const rel = relative(a.path, b.path);
+      if (
+        !rel ||
+        (rel !== ".." &&
+          !rel.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) &&
+          !isAbsolute(rel))
+      )
+        throw new Error("Output paths must not overlap");
+    }
+  // Composition errors and a non-empty --skills-out stop the run before anything is written.
+  if (skillsOut && existsSync(skillsOut) && readdirSync(skillsOut).length)
+    throw new Error(`--skills-out ${skillsOut} must be empty or absent`);
+  const referenceWrites = references.size ? planReferenceOutput(referencesOut, references) : [];
+  writeReferenceOutput(referenceWrites);
+  if (out) {
+    mkdirSync(dirname(resolve(out)), { recursive: true });
+    writeFileSync(out, rules);
+  } else process.stdout.write(rules);
+  if (skillsOut) {
+    // Skill tests stay in the source checkout; hosts get only what the skill uses.
+    for (const [name, from] of skills)
+      cpSync(from, join(skillsOut, name), {
+        recursive: true,
+        filter: (src) => src !== join(from, "test"),
+      });
+    for (const f of NOTICES) cpSync(join(BASE, f), join(skillsOut, f));
+  }
+  console.error(
+    `composed ${fragments.length} fragment(s), ${rules.split("\n").length} lines${skillsOut ? `, ${skills.size} skill(s)` : ""}`,
+  );
+}
+
+if (
+  process.argv[1] &&
+  realpathSync(resolve(process.argv[1])) === realpathSync(fileURLToPath(import.meta.url))
+) {
+  try {
+    await main(process.argv.slice(2));
+  } catch (e) {
+    console.error(`house-rules: ${e.message}`);
+    process.exit(e.exitCode ?? 1);
+  }
+}

package/composition.mjs

@@ -0,0 +1,353 @@
+// Composition and source discovery shared by output generation and configuration management.
+import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const BASE = dirname(fileURLToPath(import.meta.url));
+const PROTECTED = "End of every reply";
+// The protected section points at § Offers, so Offers may be replaced but not removed.
+const REQUIRED = [PROTECTED, "Offers"];
+const OPS = ["replaces", "after", "before", "removes"];
+const KEYS = [...OPS, "description", "requires", "reference"];
+
+// Windows line endings and a byte-order mark would otherwise hide frontmatter and headings.
+const normalize = (text) => text.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n");
+
+// Minimal frontmatter: `key: value` lines between `---` fences.
+export function parseFragment(rawText, source) {
+  const text = normalize(rawText);
+  const m = /^---\n([\s\S]*?)\n---\n?/.exec(text);
+  const meta = {};
+  if (m) {
+    for (const line of m[1].split("\n")) {
+      const i = line.indexOf(":");
+      if (i > 0) meta[line.slice(0, i).trim()] = line.slice(i + 1).trim();
+    }
+  }
+  return { meta, body: (m ? text.slice(m[0].length) : text).trim(), source };
+}
+
+// Splits on level-2 headings outside fenced code blocks; level-3 and deeper stay inside their section.
+export function splitSections(rawText) {
+  const parts = [[]];
+  let fence = null;
+  for (const line of normalize(rawText).split("\n")) {
+    const f = /^(`{3,}|~{3,})/.exec(line);
+    if (f && (!fence || f[1][0] === fence[0])) fence = fence ? null : f[1];
+    if (!fence && line.startsWith("## ")) parts.push([]);
+    parts.at(-1).push(line);
+  }
+  const preamble = parts.shift().join("\n").trim();
+  const sections = parts.map((lines) => ({
+    heading: lines[0].slice(3).trim(),
+    text: lines.join("\n").trim(),
+  }));
+  return { preamble, sections };
+}
+
+function composeParts(coreText, fragments, referencesDirectory, candidates) {
+  const core = parseFragment(coreText, "core");
+  if ("reference" in core.meta && "references" in core.meta)
+    throw new Error("core: use reference or references, not both");
+  const paths =
+    "references" in core.meta
+      ? core.meta.references.split(",").map((path) => path.trim())
+      : "reference" in core.meta
+        ? [core.meta.reference]
+        : [];
+  if (paths.some((path) => !path) || new Set(paths).size !== paths.length)
+    throw new Error("core: references must contain distinct non-empty paths");
+  const outputs = new Map();
+  if (paths.length) {
+    core.path = join(BASE, "rules/core.md");
+    core.root = BASE;
+    for (const path of paths) {
+      const output = renderReference(core, referencesDirectory, true, path);
+      if (outputs.has(output.heading))
+        throw new Error(`core: duplicate reference section "${output.heading}"`);
+      outputs.set(output.heading, output);
+    }
+    coreText = core.body;
+  }
+  const { preamble, sections } = splitSections(coreText);
+  if (referencesDirectory !== undefined)
+    for (const section of sections) section.referenceOutput = outputs.get(section.heading);
+  const find = (heading, f) => {
+    const i = sections.findIndex((s) => s.heading === heading);
+    if (i < 0) throw new Error(`${f.source}: no section "${heading}" to target`);
+    return i;
+  };
+  for (const f of fragments) {
+    const unknown = Object.keys(f.meta).filter((k) => !KEYS.includes(k));
+    if (unknown.length)
+      throw new Error(
+        `${f.source}: unknown frontmatter key "${unknown[0]}" (use ${KEYS.join(", ")})`,
+      );
+    const ops = OPS.filter((k) => k in f.meta);
+    if (ops.length > 1) throw new Error(`${f.source}: use one of ${OPS.join(", ")}`);
+    const op = ops[0];
+    const target = op && f.meta[op];
+    if (op && !target) throw new Error(`${f.source}: ${op}: needs a section heading`);
+    if (target === PROTECTED && op !== "after")
+      throw new Error(
+        `${f.source}: "${PROTECTED}" stays first and can only be added to with after:`,
+      );
+    if (op === "removes") {
+      if (REQUIRED.includes(target))
+        throw new Error(`${f.source}: "${target}" can be replaced, not removed`);
+      if (f.body) throw new Error(`${f.source}: a removes: fragment has no body`);
+      sections.splice(find(target, f), 1);
+      continue;
+    }
+    const { preamble: stray, sections: added } = splitSections(f.body);
+    for (const section of added) section.referenceOutput = f.referenceOutput;
+    if (!added.length || stray)
+      throw new Error(`${f.source}: body must start with a "## " heading`);
+    if (op === "replaces") {
+      // A replacement keeps the `after:` tag of the section it replaces, so later `after:` fragments still queue behind it.
+      const i = find(target, f);
+      sections.splice(i, 1, ...added.map((s) => ({ ...s, after: sections[i].after })));
+    } else if (op === "before") sections.splice(find(target, f), 0, ...added);
+    else if (op === "after") {
+      // Earlier `after:` fragments for the same target stay first, in configured order.
+      let i = find(target, f) + 1;
+      while (sections[i]?.after === target) i++;
+      sections.splice(i, 0, ...added.map((s) => ({ ...s, after: target })));
+    } else sections.push(...added);
+  }
+  const seen = new Set();
+  for (const s of sections) {
+    if (seen.has(s.heading))
+      throw new Error(`duplicate section "${s.heading}"; use replaces: to override it`);
+    seen.add(s.heading);
+    if (s.referenceOutput) {
+      const resource = s.referenceOutput;
+      const previous = candidates.get(resource.name);
+      if (previous && previous.text !== resource.text)
+        throw new Error(`conflicting reference "${resource.name}"`);
+      candidates.set(resource.name, resource);
+    }
+  }
+  if (sections[0]?.heading !== PROTECTED)
+    throw new Error(`"${PROTECTED}" must stay the first section`);
+  for (const h of REQUIRED)
+    if (!seen.has(h))
+      throw new Error(`a "${h}" section is required; a replacement must keep that heading`);
+  return [preamble, ...sections.map((s) => s.text)].filter(Boolean).join("\n\n") + "\n";
+}
+
+export function compose(coreText, fragments) {
+  const inline = fragments.map((fragment) => {
+    if (!("reference" in fragment.meta) || !fragment.body.includes(`](${fragment.meta.reference})`))
+      return fragment;
+    const f = { ...fragment };
+    if (!f.path) {
+      const name =
+        typeof f.source === "string" ? f.source.replace(/^modifier /, "").replace(/\.md$/, "") : "";
+      const path = join(BASE, "rules/modifiers", `${name}.md`);
+      if (
+        !/^[a-z0-9-]+$/.test(name) ||
+        !existsSync(path) ||
+        parseFragment(readFileSync(path, "utf8"), name).body !== f.body
+      )
+        throw new Error(`${f.source}: use loadFragments to establish the reference source layer`);
+      f.path = path;
+      f.root = BASE;
+    }
+    renderReference(f, undefined);
+    return f;
+  });
+  return composeParts(coreText, inline, undefined, new Map());
+}
+
+const mdFiles = (dir) =>
+  existsSync(dir)
+    ? readdirSync(dir)
+        .filter((f) => f.endsWith(".md"))
+        .sort()
+    : [];
+
+export function modifierList() {
+  const dir = join(BASE, "rules/modifiers");
+  return mdFiles(dir).map((f) => ({
+    name: f.slice(0, -3),
+    ...parseFragment(readFileSync(join(dir, f), "utf8"), f).meta,
+  }));
+}
+
+// The directory holding house-rules.json is the user's layer unless the config lists others.
+const layersOf = (config) => config.layers ?? ["."];
+
+function loadRawFragments(config, configDir) {
+  const fragments = (config.modifiers ?? []).map((name) => {
+    const path = join(BASE, "rules/modifiers", `${name}.md`);
+    if (!existsSync(path)) throw new Error(`unknown modifier "${name}" (see --list)`);
+    return { ...parseFragment(readFileSync(path, "utf8"), `modifier ${name}`), path, root: BASE };
+  });
+  for (const layer of layersOf(config)) {
+    const dir = join(resolve(configDir, layer), "rules");
+    for (const f of mdFiles(dir))
+      fragments.push({
+        ...parseFragment(readFileSync(join(dir, f), "utf8"), join(dir, f)),
+        path: join(dir, f),
+        root: resolve(configDir, layer),
+      });
+  }
+  return fragments;
+}
+
+// Later layers' skills shadow base skills of the same name.
+export function skillSources(config, configDir) {
+  const base = join(BASE, "skills");
+  const shipped = new Set(
+    readdirSync(base).filter((name) => existsSync(join(base, name, "SKILL.md"))),
+  );
+  const legacyNames = new Map(
+    [...shipped].filter((name) => name.startsWith("hr-")).map((name) => [name.slice(3), name]),
+  );
+  const exclude = new Set(config.skills?.exclude ?? []);
+  const independent = new Set(config.skills?.independent ?? []);
+  const included = config.skills?.include;
+  if (included !== undefined) {
+    if (
+      !Array.isArray(included) ||
+      included.some((name) => typeof name !== "string" || !name.trim())
+    )
+      throw new Error("skills.include must be an array of non-empty strings");
+    if (new Set(included).size !== included.length)
+      throw new Error("skills.include contains duplicates");
+    for (const name of included) {
+      if (!shipped.has(name))
+        throw new Error(`unknown shipped skill "${name}" in skills.include (see config catalog)`);
+    }
+  }
+  for (const name of exclude) {
+    if (legacyNames.has(name) && !independent.has(name))
+      throw new Error(
+        `legacy skill name "${name}" in skills.exclude; replace it with "${legacyNames.get(name)}"`,
+      );
+  }
+  const sources = new Map();
+  for (const root of [
+    base,
+    ...layersOf(config).map((l) => join(resolve(configDir, l), "skills")),
+  ]) {
+    if (!existsSync(root)) continue;
+    for (const name of readdirSync(root)) {
+      if (!existsSync(join(root, name, "SKILL.md"))) continue;
+      if (legacyNames.has(name) && !independent.has(name))
+        throw new Error(
+          `legacy skill name "${name}" in a personal layer; rename its directory and frontmatter name to "${legacyNames.get(name)}", or list "${name}" in skills.independent to keep it as an independent skill`,
+        );
+      if (root !== base && legacyNames.get(name.slice(3)) === name) {
+        const declaredName = parseFragment(readFileSync(join(root, name, "SKILL.md"), "utf8"), name)
+          .meta.name?.replace(/\s+#.*$/, "")
+          .replace(/^(['"])(.*)\1$/, "$2");
+        if (legacyNames.has(declaredName))
+          throw new Error(
+            `legacy skill name "${declaredName}" in frontmatter; set name to "${name}" to match its renamed override directory`,
+          );
+      }
+      if (
+        !exclude.has(name) &&
+        (root !== base || included === undefined || included.includes(name))
+      )
+        sources.set(name, join(root, name));
+    }
+  }
+  return sources;
+}
+
+export function configurationPath(path) {
+  return resolve(
+    path ??
+      join(
+        process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"),
+        "house-rules/house-rules.json",
+      ),
+  );
+}
+
+function renderReference(f, referencesDirectory, core = false, reference = f.meta.reference) {
+  const invalidReference = `${f.source}: reference must be a regular file within its source layer`;
+  const path = resolve(dirname(f.path), reference);
+  if (!reference || !existsSync(path) || !lstatSync(path).isFile())
+    throw new Error(invalidReference);
+  const inside = relative(realpathSync(f.root), realpathSync(path));
+  if (inside.startsWith("..") || isAbsolute(inside)) throw new Error(invalidReference);
+  const name = basename(path);
+  if (!/^[a-z0-9][a-z0-9-]*\.md$/.test(name))
+    throw new Error(`${f.source}: invalid reference filename`);
+  const text = readFileSync(path, "utf8");
+  const original = splitSections(text);
+  const parts = splitSections(f.body);
+  const section = core
+    ? parts.sections.find((s) => s.heading === original.sections[0]?.heading)
+    : null;
+  const short = core ? splitSections(section?.text ?? "") : parts;
+  if (
+    original.preamble ||
+    short.preamble ||
+    original.sections.length !== 1 ||
+    short.sections.length !== 1 ||
+    original.sections[0].heading !== short.sections[0].heading
+  )
+    throw new Error(`${f.source}: reference must contain the same single section heading`);
+  const sourceLink = `](${reference})`;
+  if (!(core ? section.text : f.body).includes(sourceLink))
+    throw new Error(`${f.source}: reference link missing from body`);
+  if (referencesDirectory === undefined) {
+    f.body = core ? f.body.replace(section.text, text.trim()) : text.trim();
+  } else {
+    const href = encodeURI(
+      `${referencesDirectory.replace(/\\/g, "/").replace(/\/$/, "")}/${name}`,
+    ).replace(/[()#?]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+    f.body = f.body.replaceAll(sourceLink, `](${href})`);
+    if (!core) f.referenceOutput = { name, text, heading: original.sections[0].heading };
+  }
+  return { name, text, heading: original.sections[0].heading };
+}
+
+function referenceFragments(config, configDir, referencesDirectory) {
+  if (
+    referencesDirectory !== undefined &&
+    (typeof referencesDirectory !== "string" || !referencesDirectory.trim())
+  )
+    throw new Error("referencesDirectory must be a non-empty string");
+  const fragments = loadRawFragments(config, configDir);
+  const candidates = new Map();
+  for (const f of fragments) {
+    if (!("reference" in f.meta)) continue;
+    renderReference(f, referencesDirectory);
+  }
+  return { fragments, candidates };
+}
+
+// Existing low-level callers receive complete inline procedure bodies too.
+export function loadFragments(config, configDir) {
+  return referenceFragments(config, configDir).fragments;
+}
+
+export function composeConfiguration(config, configDir, { referencesDirectory } = {}) {
+  const { fragments, candidates } = referenceFragments(config, configDir, referencesDirectory);
+  const rules = composeParts(
+    readFileSync(join(BASE, "rules/core.md"), "utf8"),
+    fragments,
+    referencesDirectory,
+    candidates,
+  );
+  const references = new Map([...candidates].map(([name, value]) => [name, value.text]));
+  const skills = skillSources(config, configDir);
+  const warnings = [];
+  for (const f of fragments) {
+    for (const need of (f.meta.requires ?? "")
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean)) {
+      if (!skills.has(need))
+        warnings.push(`${f.source} expects the "${need}" skill, which is not in the composed set`);
+    }
+  }
+  return { fragments, rules, skills, warnings, references };
+}

package/config-view.mjs

@@ -0,0 +1,194 @@
+// Human output is grouped and aligned; JSON output bypasses this renderer.
+import { styleText } from "node:util";
+
+const clean = (value) => String(value ?? "").replace(/\p{Cc}/gu, " ");
+function display() {
+  const color =
+    process.stdout.isTTY && !Object.hasOwn(process.env, "NO_COLOR") && process.env.TERM !== "dumb";
+  const paint = (style, text) => (color ? styleText(style, text, { validateStream: false }) : text);
+  const width = Math.max(24, Math.min(process.stdout.columns ?? 100, 120));
+  const wrap = (text, size) => {
+    const words = clean(text).split(/\s+/);
+    const lines = [""];
+    for (let word of words) {
+      while (word.length > size) {
+        if (lines.at(-1)) lines.push("");
+        lines[lines.length - 1] = word.slice(0, size);
+        word = word.slice(size);
+        lines.push("");
+      }
+      if (lines.at(-1).length + word.length + 1 > size) lines.push("");
+      lines[lines.length - 1] += (lines.at(-1) ? " " : "") + word;
+    }
+    return lines;
+  };
+  const table = (headers, rows) => {
+    const first = Math.max(headers[0].length, ...rows.map((row) => clean(row[0]).length));
+    const second = Math.max(headers[1].length, ...rows.map((row) => clean(row[1]).length));
+    if (first + second + 14 > width) {
+      return rows
+        .flatMap((row) => [
+          ...wrap(`${row[0]}  [${row[1]}]`, width - 2).map((l) => `  ${paint("bold", l)}`),
+          ...wrap(row[2], width - 4).map((l) => `    ${l}`),
+          "",
+        ])
+        .join("\n");
+    }
+    const third = width - first - second - 8;
+    const line = (a, b, c) => {
+      const state = b.padEnd(second);
+      return `  ${a.padEnd(first)}  ${paint(b === "on" ? "green" : b === "off" ? "dim" : "cyan", state)}  ${c}`;
+    };
+    const heading = paint("dim", line(...headers));
+    return [
+      heading,
+      ...rows.flatMap(([a, b, c]) =>
+        wrap(c, third).map((text, index) =>
+          line(index ? "" : clean(a), index ? "" : clean(b), text),
+        ),
+      ),
+    ].join("\n");
+  };
+  return { paint, table, wrap, width };
+}
+
+export function renderHelp() {
+  const { paint, table } = display();
+  return [
+    "",
+    `  ${paint("dim", "╭─")} ${paint("cyan", paint("bold", "HOUSE RULES"))}  ${paint("dim", "configuration")}`,
+    "",
+    "  node compose.mjs config <command> [options]",
+    "",
+    table(
+      ["Command", "Writes", "Purpose"],
+      [
+        ["catalog", "no", "Browse modifiers, skills and rule sections."],
+        ["status", "no", "See selections, personal origins and current revision."],
+        ["validate", "no", "Check configuration and compose every selected layer."],
+        ["preview", "no", "Review proposed selections; --rules prints composed rules."],
+        ["set", "opt-in", "Preview changes, then save with --apply --expect <revision>."],
+      ],
+    ),
+    "",
+    "  Selection",
+    "    --enable-modifier <name>    --disable-modifier <name>",
+    "    --enable-skill <name>       --disable-skill <name>",
+    "    --questions plain|coded|cards",
+    "",
+    "  Output",
+    "    --config <path>   --json   --rules (preview only)",
+    "",
+    "  Repeat toggle flags to change several selections together.",
+    "  Saving config does not regenerate output or connect agent hosts.",
+    "",
+  ].join("\n");
+}
+
+export function renderConfig(report) {
+  const { paint, table, wrap, width } = display();
+  const lines = [
+    "",
+    `  ${paint("dim", "╭─")} ${paint("cyan", paint("bold", "HOUSE RULES"))}  ${paint("dim", report.command)}`,
+    "",
+  ];
+  const section = (label) => lines.push(`  ${paint("bold", label)}`, "");
+  const detail = (text) => lines.push(...wrap(text, width - 2).map((l) => `  ${l}`));
+  detail(`Config  ${report.configPath}${report.exists ? "" : " (not created)"}`);
+  detail(`Revision  ${report.applied?.revision ?? report.revision}`);
+  lines.push("");
+  const enabled = report.modifiers.filter((m) => m.enabled).length;
+  detail(
+    `${enabled}/${report.modifiers.length} modifiers enabled   ${report.skills.filter((s) => s.enabled).length}/${report.skills.length} skills selected   ${report.rules.length} rule sections`,
+  );
+  detail(`Configured questions  ${report.questions}   Host loading  ${report.hostLoading}`);
+  lines.push("");
+  if (["set", "preview"].includes(report.command)) {
+    section(
+      report.applied
+        ? report.applied.changed
+          ? "Configuration saved"
+          : "Already configured"
+        : "Change preview",
+    );
+    if (!report.changes.length) detail("No selection changes.");
+    for (const change of report.changes) {
+      detail(change.key);
+      const removed = change.before.filter((name) => !change.after.includes(name));
+      const added = change.after.filter((name) => !change.before.includes(name));
+      for (const [sign, names, style] of [
+        ["-", removed, "red"],
+        ["+", added, "green"],
+      ]) {
+        for (const name of names) lines.push(`    ${paint(style, `${sign} ${clean(name)}`)}`);
+      }
+      if (!removed.length && !added.length) detail("Selection order changed.");
+    }
+    lines.push("");
+    if (!report.applied) {
+      detail(
+        report.command === "set"
+          ? `To save, repeat with --apply --expect ${report.revision}`
+          : `To save, run config set with the same selection flags plus --apply --expect ${report.revision}`,
+      );
+      detail("Review personal rule overrides below before choosing a question format.");
+    } else
+      detail(
+        "Next, recompose output with compose.mjs or rerun the installer. Existing skills directories are retained; host connection is separate.",
+      );
+    lines.push("");
+  }
+  if (report.command === "validate") detail("Configuration and composition are valid.");
+  else if (["status", "catalog"].includes(report.command)) {
+    section("Modifiers");
+    lines.push(
+      table(
+        ["Name", "State", "Purpose"],
+        report.modifiers.map((m) => [m.name, m.enabled ? "on" : "off", m.description]),
+      ),
+      "",
+    );
+    section("Skills");
+    lines.push(
+      table(
+        ["Name", "State", report.command === "catalog" ? "Purpose" : "Origin"],
+        report.skills.map((s) => [
+          s.name,
+          s.enabled ? "on" : "off",
+          report.command === "catalog" ? s.description : s.origin,
+        ]),
+      ),
+      "",
+    );
+    section("Effective rules");
+    lines.push(
+      table(
+        ["Section", "State", "Source"],
+        report.rules.map((r) => [r.heading, "active", r.origin]),
+      ),
+      "",
+    );
+    section("Personal layers");
+    for (const layer of report.layers) detail(layer);
+  }
+  const personal = report.rules.filter(
+    (rule) => rule.source !== "core" && !rule.source.startsWith("modifier "),
+  );
+  if (["preview", "set"].includes(report.command) && personal.length) {
+    section("Personal rule overrides and additions");
+    lines.push(
+      table(
+        ["Section", "State", "Source"],
+        personal.map((r) => [r.heading, "active", r.origin]),
+      ),
+      "",
+    );
+  }
+  for (const name of report.unavailable)
+    detail(`Retained exclusion with no current source: ${name}`);
+  for (const warning of report.warnings) detail(`Warning: ${warning}`);
+  lines.push("");
+  detail("Status describes composed selections. It does not verify an agent's loaded context.");
+  lines.push(`  ${paint("dim", "╰─")}`);
+  return lines.join("\n");
+}