reviewer-harness 1.14.0 → 1.15.0

package/README.md

@@ -187,7 +187,7 @@ Expected output when everything is fine:
 
 `validate` checks for empty or duplicate rules and scans the config for leaked API keys and tokens — secrets must never be synced into instruction files (they would leak into Git).
 
-**Step 3 — Add the skills you want.** Pick from the 22 bundled skills (full list below):
+**Step 3 — Add the skills you want.** Pick from the 27 bundled skills (full list below):
 
 ```bash
 reviewer-harness skills add safe-editing
@@ -237,12 +237,12 @@ npx reviewer-harness skills add no-hallucination
 A skill is a playbook: a short, checkable set of rules for one job (safe editing, API security, UI taste, debugging, and so on), distilled from real, reputable sources — not generic advice. Every rule cites its source.
 
 ```bash
-reviewer-harness skills list            # see all 22 bundled skills (+ which are enabled)
+reviewer-harness skills list            # see all 27 bundled skills (+ which are enabled)
 reviewer-harness skills add <name>      # install into the project and enable it in the config
 reviewer-harness skills remove <name>   # disable it in the config and remove it
 ```
 
-All 22 bundled skills (v1.14.0):
+All 27 bundled skills (v1.14.0):
 
 | Skill | What it does |
 |---|---|
@@ -268,6 +268,11 @@ All 22 bundled skills (v1.14.0):
 | `vengeance-ui` | Modern animated React components from VengeanceUI — 79 copy-paste components across 9 families. |
 | `brainstorming` | Find out what you actually want — and why — before anything gets built. Design doc first, approval first. |
 | `writing-plans` | Turn an approved spec into a bite-sized TDD implementation plan. |
+| `fix-team` | Run an 11-agent fix over an audit report's findings — 8 domain fixers plus ub-mode, superpowers, and a verification agent that runs last. Fix plan first, user approves, verification re-checks every fix. |
+| `verify_before_done` | Check defined-and-called plus remote evidence before reporting done, pushed, fixed, or working — never present an untested guess as done. |
+| `instruction_registers` | Name the user's target and action registers before building, pushing, or planning, and ask one clarifying question when they are ambiguous. |
+| `verify_provider_claims` | Check a provider's live documentation or the user's verified setup before asserting its current availability, free tier, pricing, endpoints, or retired status. |
+| `verify_publish_install_surface` | Verify a published version on each surface the user can see (commit/tag, registry, installed file) before claiming it is installed or live. |
 
 Enabled skills render below the rules in every instruction file — and sync also generates a **slash command** for each one (`.opencode/commands/<name>.md` and `.claude/commands/<name>.md`), so every enabled skill appears in the `/` menu of OpenCode and Claude, ready to invoke on a specific task: `/safe-editing`, `/no-hallucination`, and so on.
 
@@ -304,6 +309,14 @@ Four guardrails run before any file is written:
 3. **BACKUP** — before overwriting an existing file, sync writes a `.bak` copy first.
 4. **IDEMPOTENT** — if nothing changed, sync touches nothing. Safe to run repeatedly.
 
+### Scale limit — instruction files grow linearly with skills
+
+Every enabled skill is inlined in full into every instruction file, bundle, and slash command. Measured at audit (22 skills): **266,198 bytes** of skill source → **2,660,559 bytes** of generated output across 124 files (**10×** amplification); `CLAUDE.md` alone is **262,243 bytes** today. Growth is linear: at 10× skills (220), each instruction file would be ≈ 2.6 MB and total output ≈ 26.6 MB. The binding constraint is the AI runtime's context window, not disk.
+
+**Target ceiling the project accepts: total generated output ≤ 10 MB, and no single instruction file larger than 1 MB** — roughly 4× today's skills (≈ 80 skills). Two cheap wins already reduce the amplification: shared bundle directories are written once (Freebuff + Antigravity share `.agents/skills`), and each skill's content is built once per `sync` run instead of once per runtime.
+
+Beyond that ceiling, the fix is a re-architecture (summaries + lazy-loading skills on demand) — that is **out of scope** for this fix; nothing here shrinks the files, it only documents the limit and the ceiling.
+
 ### Validate + secret scanning
 
 `validate` inspects the config before it becomes instructions:
@@ -387,7 +400,7 @@ Requires Node.js 18+ (no dependencies). Run these inside your project — every
 
 | Command | What it does |
 |---|---|
-| `reviewer-harness skills list` | List all 22 bundled skills (+ which are enabled) |
+| `reviewer-harness skills list` | List all 27 bundled skills (+ which are enabled) |
 | `reviewer-harness skills add <name>` | Install a skill into the project and enable it in the config |
 | `reviewer-harness skills remove <name>` | Disable a skill and remove it |
 | `reviewer-harness agents list` | List the bundled sub-agents |
@@ -452,7 +465,7 @@ Check that you edited the config in the same folder you are syncing (`--target`
 5. ✅ Sub-agents and slash commands — `agents add`, `commands add`
 6. ✅ Polish and publish — v1.0.0, LICENSE, publish-ready for GitHub/npx
 7. ✅ v1.1.0 — all-English repo, validate-and-report rule, self-governing repo, modular skills, one-liner installers, Docker
-8. ✅ v1.14.0 — the working peak: 22 skills (audit-team + ub-mode, design-taste-frontend, ui-ux-pro-max, vengeance-ui, brainstorming, writing-plans), Qoder as 8th runtime, system-design, nodejs-quality, all fix rounds verified WORKS, CRLF frontmatter fix (Windows sync without manual LF conversion)
+8. ✅ v1.14.0 — the working peak: 27 skills (audit-team + fix-team, ub-mode, design-taste-frontend, ui-ux-pro-max, vengeance-ui, brainstorming, writing-plans, verification skills), Qoder as 8th runtime, system-design, nodejs-quality, all fix rounds verified WORKS, CRLF frontmatter fix (Windows sync without manual LF conversion), --help/--version flags fixed
 
 ## Contributing & Security
 

package/bin/cli.js

@@ -4,7 +4,7 @@
 // Commands: status | sync | init | validate | memory | skills | agents | commands | global
 
 import { parseArgs } from "node:util";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { loadConfig } from "../lib/config.js";
@@ -17,19 +17,49 @@ import { listBundledSkills, addSkill, removeSkill, loadBundledSkills, skillComma
 import { listBundledAgents, addAgent } from "../lib/agents.js";
 import { listBundledCommands, addCommand } from "../lib/commands.js";
 
-const { values, positionals } = parseArgs({
-  allowPositionals: true,
-  options: {
-    "dry-run": { type: "boolean", default: false },
-    target: { type: "string", default: process.cwd() },
-  },
-});
+// F-B1 (full fix): the top-level parse sits outside main().catch, so
+// an unknown flag used to crash with a raw Node stack trace. Catch it
+// here: clean one-line error + help on stderr, exit 1. helpText() is a
+// hoisted function declaration, so it is callable this early.
+let values;
+let positionals;
+try {
+  ({ values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      "dry-run": { type: "boolean", default: false },
+      target: { type: "string", default: process.cwd() },
+      help: { type: "boolean", short: "h", default: false },
+      version: { type: "boolean", default: false },
+      verbose: { type: "boolean", default: false },
+    },
+  }));
+} catch (err) {
+  console.error(`Error: ${err.message}`);
+  console.error(helpText());
+  process.exit(1);
+}
 const [command, sub, arg] = positionals;
 const targetDir = values.target;
 const dryRun = values["dry-run"];
 
-function help() {
-  console.log(`reviewer-harness — your own AI harness
+// devops-basics rule 4: handle SIGTERM/SIGINT gracefully — finish the
+// current write, then exit cleanly. Node runs a synchronous write to
+// completion before a signal handler executes, and writeSafe is atomic
+// (temp file + rename), so exiting here can never leave a half-written
+// file behind.
+let shuttingDown = false;
+function handleShutdownSignal(signal) {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  console.error(`\nReceived ${signal} — finishing the current write, then exiting.`);
+  process.exit(0);
+}
+process.on("SIGTERM", () => handleShutdownSignal("SIGTERM"));
+process.on("SIGINT", () => handleShutdownSignal("SIGINT"));
+
+function helpText() {
+  return `reviewer-harness — your own AI harness
 
 Usage (run inside your project):
   reviewer-harness init                     Create harness.config.json (one-time setup)
@@ -52,7 +82,15 @@ Usage (run inside your project):
   reviewer-harness memory list              List memory notes + their links
 
 Every command accepts --target <dir> (default: the current directory).
-`);
+`;
+}
+
+function help() {
+  console.log(helpText());
+}
+
+function packageVersion() {
+  return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 }
 
 function cmdStatus() {
@@ -60,6 +98,7 @@ function cmdStatus() {
   console.log(`Harness : ${config.name} v${config.version}`);
   console.log(`Target  : ${targetDir}`);
   console.log(`Runtimes:`);
+  if (!config.runtimes?.length) console.log(`  (none)`);
   for (const name of config.runtimes) {
     const adapter = adapters[name];
     const target = !adapter ? "(no adapter!)"
@@ -72,8 +111,13 @@ function cmdStatus() {
 }
 
 function cmdSync() {
+  const config = loadConfig(targetDir);
   const results = sync({ targetDir, dryRun });
   if (dryRun) console.log("(dry-run: nothing was written)\n");
+  if (!config.runtimes?.length && !config.skills?.length) {
+    console.log(`Nothing to sync — no runtimes and no skills are enabled.`);
+    console.log(`Run "skills add <name>" or add a runtime to the config to enable something.`);
+  }
   for (const r of results) {
     if (r.skillCommands) {
       const written = r.skillCommands.filter((f) => f.written).length;
@@ -106,10 +150,18 @@ function cmdSync() {
     }
   }
   // If the project has a local memory, refresh its index as part of
-  // sync — so the graph the AI reads is always current.
+  // sync — so the graph the AI reads is always current. The index is
+  // a secondary artifact, so its failure is a warning, not a failed
+  // sync (system-design failure isolation): the sync already succeeded.
   if (!dryRun && existsSync(memoryDir(targetDir))) {
-    const stats = buildIndex(targetDir);
-    console.log(`- memory: index refreshed (${stats.notes} notes, ${stats.edges} links) ✓`);
+    try {
+      const stats = buildIndex(targetDir);
+      console.log(`- memory: index refreshed (${stats.notes} notes, ${stats.edges} links) ✓`);
+    } catch (err) {
+      console.error(
+        `Warning: memory index could not be updated — ${err.message} (sync itself succeeded; run "memory index" to retry.)`
+      );
+    }
   }
 }
 
@@ -137,7 +189,8 @@ function cmdMemory() {
       console.log(`- [[${n.id}]] ${n.title}${n.links.length ? ` → ${n.links.join(", ")}` : ""}`);
     }
   } else {
-    console.log(`Usage: memory <init|index|list> [--target <dir>]`);
+    console.error(`Usage: memory <init|index|list> [--target <dir>]`);
+    process.exitCode = 1;
   }
 }
 
@@ -195,7 +248,8 @@ function cmdSkills() {
         : `Skill "${arg}" was not enabled.`
     );
   } else {
-    console.log(`Usage: skills <list|add <name>|remove <name>> [--target <dir>]`);
+    console.error(`Usage: skills <list|add <name>|remove <name>> [--target <dir>]`);
+    process.exitCode = 1;
   }
 }
 
@@ -207,7 +261,8 @@ function cmdAgents() {
     console.log(`Agent "${arg}" installed:`);
     for (const f of r.written) console.log(`  → ${f}`);
   } else {
-    console.log(`Usage: agents <list|add <name>> [--target <dir>]`);
+    console.error(`Usage: agents <list|add <name>> [--target <dir>]`);
+    process.exitCode = 1;
   }
 }
 
@@ -219,7 +274,8 @@ function cmdCommands() {
     console.log(`Command "/${arg}" installed:`);
     for (const f of r.written) console.log(`  → ${f}`);
   } else {
-    console.log(`Usage: commands <list|add <name>> [--target <dir>]`);
+    console.error(`Usage: commands <list|add <name>> [--target <dir>]`);
+    process.exitCode = 1;
   }
 }
 
@@ -251,15 +307,21 @@ function cmdGlobal() {
     if (dryRun) console.log(`- ${runtime} (global): ${pending} would be written/updated, ${unchanged} unchanged → ${where}`);
     else console.log(`- ${runtime} (global): ${written} written ✓, ${unchanged} unchanged → ${where}`);
   }
-  console.log(
-    `\nDone: ${skills.map((s) => "/" + s.name).join(", ")} are now available in EVERY project.` +
-      `\n(OpenCode + Claude: "/" menu commands. Freebuff, Copilot CLI, Antigravity, Qoder: Agent Skills bundles.)` +
-      `\n(Per-project rules still come from "sync" inside a project.)`
-  );
+  if (dryRun) {
+    console.log(`Dry run complete — nothing was written. Run without --dry-run to install.`);
+  } else {
+    console.log(
+      `\nDone: ${skills.map((s) => "/" + s.name).join(", ")} are now available in EVERY project.` +
+        `\n(OpenCode + Claude: "/" menu commands. Freebuff, Copilot CLI, Antigravity, Qoder: Agent Skills bundles.)` +
+        `\n(Per-project rules still come from "sync" inside a project.)`
+    );
+  }
 }
 
 async function main() {
-  if (!command || command === "status") cmdStatus();
+  if (values.help) help();
+  else if (values.version) console.log(`reviewer-harness ${packageVersion()}`);
+  else if (!command || command === "status") cmdStatus();
   else if (command === "sync") cmdSync();
   else if (command === "init") cmdInit();
   else if (command === "validate") cmdValidate();
@@ -268,10 +330,16 @@ async function main() {
   else if (command === "agents") cmdAgents();
   else if (command === "commands") cmdCommands();
   else if (command === "global") cmdGlobal();
-  else help();
+  else if (command === "help") help();
+  else {
+    console.error(`Unknown command "${command}".`);
+    console.error(helpText());
+    process.exitCode = 1;
+  }
 }
 
 main().catch((err) => {
   console.error("Error:", err.message);
+  if (values.verbose) console.error(err.stack);
   process.exit(1);
 });

package/lib/adapters/antigravity.js

@@ -9,6 +9,10 @@
 //
 // Like Freebuff and Copilot CLI, Antigravity is skills-only here:
 // it exports skillBundleDir() instead of targetFile()/renderInstructions().
+//
+// NOTE: this directory is shared with Freebuff (which returns the
+// same ".agents/skills"). sync() writes a shared bundle directory
+// once per run — the later runtime reports it as deduped (F-S44).
 
 export function skillBundleDir() {
   return ".agents/skills";

package/lib/adapters/claude.js

@@ -3,26 +3,12 @@
 // Claude Code reads CLAUDE.md in the project root at every session.
 // It is the best-known instruction file among AI coding tools.
 
+import { renderInstructions as renderShared } from "./render.js";
+
 export function targetFile() {
   return "CLAUDE.md";
 }
 
 export function renderInstructions(config) {
-  return [
-    `# ${config.name} — harness instructions`,
-    ``,
-    `> This file is generated by your harness. Do not edit it directly —`,
-    `> change harness.config.json and sync again.`,
-    ``,
-    // The "why" — the problem the rules solve, synced along with them.
-    ...(config.problem
-      ? [`## The problem this solves`, ``, config.problem, ``]
-      : []),
-    `## Rules — the AI must never break these`,
-    ``,
-    ...config.rules.map((rule, i) => `${i + 1}. ${rule}`),
-    ``,
-    // Skills (Lesson 4): rendered after the rules.
-    ...(config.skillSections ?? []).flatMap((s) => [s, ``]),
-  ].join("\n");
+  return renderShared(config, { numbered: true });
 }

package/lib/adapters/freebuff.js

@@ -10,6 +10,10 @@
 // Freebuff has no single instruction file like CLAUDE.md, so this
 // adapter is skills-only: it exports skillBundleDir() instead of
 // targetFile()/renderInstructions().
+//
+// NOTE: this directory is shared with Antigravity (which returns the
+// same ".agents/skills"). sync() writes a shared bundle directory
+// once per run — the later runtime reports it as deduped (F-S44).
 
 export function skillBundleDir() {
   return ".agents/skills";

package/lib/adapters/gemini.js

@@ -5,26 +5,12 @@
 // renderInstructions) — only the target file and a little flavor
 // differ. That is the power of the adapter pattern.
 
+import { renderInstructions as renderShared } from "./render.js";
+
 export function targetFile() {
   return "GEMINI.md";
 }
 
 export function renderInstructions(config) {
-  return [
-    `# ${config.name} — harness instructions`,
-    ``,
-    `> This file is generated by your harness. Do not edit it directly —`,
-    `> change harness.config.json and sync again.`,
-    ``,
-    // The "why" — the problem the rules solve, synced along with them.
-    ...(config.problem
-      ? [`## The problem this solves`, ``, config.problem, ``]
-      : []),
-    `## Rules — the AI must never break these`,
-    ``,
-    ...config.rules.map((rule) => `- ${rule}`),
-    ``,
-    // Skills (Lesson 4): rendered after the rules.
-    ...(config.skillSections ?? []).flatMap((s) => [s, ``]),
-  ].join("\n");
+  return renderShared(config, { numbered: false });
 }

package/lib/adapters/opencode.js

@@ -7,36 +7,12 @@
 //
 // OpenCode reads `.opencode/instructions.md` in your project.
 
+import { renderInstructions as renderShared } from "./render.js";
+
 export function targetFile() {
   return ".opencode/instructions.md";
 }
 
 export function renderInstructions(config) {
-  const lines = [];
-  lines.push(`# ${config.name} — harness instructions`);
-  lines.push(``);
-  lines.push(
-    `> This file is generated by your harness. Do not edit it directly —`,
-    `> change harness.config.json and sync again.`
-  );
-  lines.push(``);
-  // The "why" — the problem the rules solve, synced along with them.
-  if (config.problem) {
-    lines.push(`## The problem this solves`);
-    lines.push(``);
-    lines.push(config.problem);
-    lines.push(``);
-  }
-  lines.push(`## Rules — the AI must never break these`);
-  lines.push(``);
-  config.rules.forEach((rule, i) => {
-    lines.push(`${i + 1}. ${rule}`);
-  });
-  lines.push(``);
-  // Skills (Lesson 4): rendered after the rules.
-  for (const section of config.skillSections ?? []) {
-    lines.push(section);
-    lines.push(``);
-  }
-  return lines.join("\n");
+  return renderShared(config, { numbered: true });
 }

package/lib/adapters/render.js

@@ -0,0 +1,29 @@
+// lib/adapters/render.js — the ONE shared instruction-file renderer.
+//
+// Every adapter renders the same shape: header, generated-file notice,
+// optional problem section, numbered-or-bulleted rules, skill sections.
+// The only per-adapter difference is the list marker, chosen here by
+// `numbered` (true → `1. …`, false → `- …`). Adapters are thin wrappers
+// over this function; see lib/adapters/claude.js, gemini.js, opencode.js.
+
+export function renderInstructions(config, { numbered }) {
+  return [
+    `# ${config.name} — harness instructions`,
+    ``,
+    `> This file is generated by your harness. Do not edit it directly —`,
+    `> change harness.config.json and sync again.`,
+    ``,
+    // The "why" — the problem the rules solve, synced along with them.
+    ...(config.problem
+      ? [`## The problem this solves`, ``, config.problem, ``]
+      : []),
+    `## Rules — the AI must never break these`,
+    ``,
+    ...config.rules.map((rule, i) =>
+      numbered ? `${i + 1}. ${rule}` : `- ${rule}`
+    ),
+    ``,
+    // Skills (Lesson 4): rendered after the rules.
+    ...(config.skillSections ?? []).flatMap((s) => [s, ``]),
+  ].join("\n");
+}

package/lib/agents.js

@@ -10,10 +10,12 @@
 // harness), and `agents add` generates both formats. The same pattern
 // as the rules: one source, every runtime.
 
-import { readdirSync, readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { readdirSync, readFileSync, existsSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseFrontmatter } from "./frontmatter.js";
+import { assertValidName, assertInside, warnIfModified, yamlQuote } from "./skills.js";
+import { writeSafe } from "./sync.js";
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 const BUNDLED_DIR = join(ROOT, "agents");
@@ -31,7 +33,9 @@ export function listBundledAgents() {
 
 // Install an agent into the project: one master, two runtime files.
 export function addAgent(name, targetDir) {
+  assertValidName(name, "agent");
   const src = join(BUNDLED_DIR, `${name}.md`);
+  assertInside(BUNDLED_DIR, src);
   if (!existsSync(src)) {
     const available = listBundledAgents().map((a) => a.name).join(", ");
     throw new Error(`No bundled agent named "${name}". Available: ${available}`);
@@ -43,19 +47,21 @@ export function addAgent(name, targetDir) {
   const opencodeDir = join(targetDir, ".opencode", "agents");
   mkdirSync(opencodeDir, { recursive: true });
   const opencodeFile = join(opencodeDir, `${name}.md`);
-  writeFileSync(
-    opencodeFile,
-    `---\ndescription: ${description}\nmode: subagent\n---\n\n${body.trim()}\n`
-  );
+  assertInside(opencodeDir, opencodeFile);
+  const opencodeContent =
+    `---\ndescription: ${yamlQuote(description)}\nmode: subagent\n---\n\n${body.trim()}\n`;
+  warnIfModified(opencodeFile, opencodeContent);
+  writeSafe(opencodeFile, opencodeContent);
   written.push(opencodeFile);
 
   const claudeDir = join(targetDir, ".claude", "agents");
   mkdirSync(claudeDir, { recursive: true });
   const claudeFile = join(claudeDir, `${name}.md`);
-  writeFileSync(
-    claudeFile,
-    `---\nname: ${name}\ndescription: ${description}\n---\n\n${body.trim()}\n`
-  );
+  assertInside(claudeDir, claudeFile);
+  const claudeContent =
+    `---\nname: ${name}\ndescription: ${yamlQuote(description)}\n---\n\n${body.trim()}\n`;
+  warnIfModified(claudeFile, claudeContent);
+  writeSafe(claudeFile, claudeContent);
   written.push(claudeFile);
 
   return { written };

package/lib/commands.js

@@ -10,10 +10,12 @@
 // $ARGUMENTS is replaced by the runtime with whatever you type
 // after the command.
 
-import { readdirSync, readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { readdirSync, readFileSync, existsSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseFrontmatter } from "./frontmatter.js";
+import { assertValidName, assertInside, warnIfModified, yamlQuote } from "./skills.js";
+import { writeSafe } from "./sync.js";
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 const BUNDLED_DIR = join(ROOT, "commands");
@@ -30,14 +32,16 @@ export function listBundledCommands() {
 }
 
 export function addCommand(name, targetDir) {
+  assertValidName(name, "command");
   const src = join(BUNDLED_DIR, `${name}.md`);
+  assertInside(BUNDLED_DIR, src);
   if (!existsSync(src)) {
     const available = listBundledCommands().map((c) => c.name).join(", ");
     throw new Error(`No bundled command named "${name}". Available: ${available}`);
   }
   const { data, body } = parseFrontmatter(readFileSync(src, "utf8"));
   const description = data.description ?? name;
-  const content = `---\ndescription: ${description}\n---\n\n${body.trim()}\n`;
+  const content = `---\ndescription: ${yamlQuote(description)}\n---\n\n${body.trim()}\n`;
   const written = [];
 
   for (const dir of [
@@ -46,7 +50,9 @@ export function addCommand(name, targetDir) {
   ]) {
     mkdirSync(dir, { recursive: true });
     const file = join(dir, `${name}.md`);
-    writeFileSync(file, content);
+    assertInside(dir, file);
+    warnIfModified(file, content);
+    writeSafe(file, content);
     written.push(file);
   }
   return { written };

package/lib/config.js

@@ -21,8 +21,21 @@ export function loadConfig(dir = ROOT) {
   let config;
   try {
     config = JSON.parse(readFileSync(path, "utf8"));
-  } catch {
-    throw new Error(`Config is not valid JSON: ${path}`);
+  } catch (err) {
+    throw new Error(
+      `Config is not valid JSON: ${path}: ${err.message}\nCheck for a trailing comma or other syntax error.`
+    );
+  }
+
+  // A valid-JSON file is not necessarily a config: null, an array, or a
+  // bare string must fail here with a clear error — never a raw
+  // TypeError from the `.name` check below (F-W20, Review Focus #5).
+  if (typeof config !== "object" || config === null || Array.isArray(config)) {
+    throw new Error(
+      `Config must be an object, not ${
+        config === null ? "null" : Array.isArray(config) ? "an array" : `a ${typeof config}`
+      }.`
+    );
   }
 
   // Light structural validation — the harness rejects a broken spec.

package/lib/frontmatter.js

@@ -7,13 +7,31 @@ export function parseFrontmatter(text) {
   // use CR (\r). Without this, the "---\n" checks below fail on CRLF input and
   // the whole frontmatter is silently dropped (name/description lost).
   text = text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  // A byte-order mark in front of the opening delimiter is not part of
+  // the frontmatter — strip it so BOM-prefixed files parse.
+  if (text.charCodeAt(0) === 0xfeff) text = text.slice(1);
   if (!text.startsWith("---\n")) return { data: {}, body: text };
-  const end = text.indexOf("\n---\n", 4);
-  if (end === -1) return { data: {}, body: text };
+  // Find the closing delimiter as a whole line, so a file ending exactly
+  // at "---" (EOF, no trailing newline) still parses, and so does empty
+  // frontmatter ("---\n---\nbody").
+  const lines = text.split("\n");
+  let close = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === "---") {
+      close = i;
+      break;
+    }
+  }
+  if (close === -1) {
+    console.warn(
+      "Warning: frontmatter block has no closing '---' — treating the whole file as body."
+    );
+    return { data: {}, body: text };
+  }
   const data = {};
-  for (const line of text.slice(4, end).split("\n")) {
+  for (const line of lines.slice(1, close)) {
     const idx = line.indexOf(":");
     if (idx > 0) data[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
   }
-  return { data, body: text.slice(end + 5) };
+  return { data, body: lines.slice(close + 1).join("\n") };
 }

package/lib/init.js

@@ -3,12 +3,14 @@
 // Creates harness.config.json from the template if none exists yet.
 // Never overwrites an existing config — safe by default.
 
-import { writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { writeFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
+const TOOL_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+
 const TEMPLATE = {
   name: "reviewer-harness",
-  version: "1.0.0",
+  version: TOOL_VERSION,
   problem:
     "The problem — an AI with no guardrails: it sometimes breaks existing code it was never asked to touch, and hallucinates — inventing functions, libraries, or output that do not actually exist. These rules are the guardrails against that.",
   runtimes: ["opencode", "claude", "gemini", "cline", "freebuff", "copilot", "antigravity", "qoder"],

package/lib/memory.js

@@ -25,6 +25,7 @@ import {
   mkdirSync,
 } from "node:fs";
 import { join } from "node:path";
+import { writeSafe } from "./sync.js";
 
 export function memoryDir(targetDir) {
   return join(targetDir, "memory");
@@ -111,7 +112,10 @@ export function buildIndex(targetDir) {
   const notes = readNotes(targetDir);
   const graph = buildGraph(notes);
 
-  writeFileSync(
+  // Atomic writes (F-W16 memory half): graph.json and INDEX.md go
+  // through writeSafe — temp file + fsync + rename, rotating backups —
+  // so a kill mid-index cannot leave the pair half-updated.
+  writeSafe(
     join(dir, "graph.json"),
     JSON.stringify({ generated_by: "reviewer-harness", ...graph }, null, 2) + "\n"
   );
@@ -147,7 +151,7 @@ export function buildIndex(targetDir) {
   lines.push(``);
   lines.push(`Graph: ${graph.nodes.length} nodes, ${graph.edges.length} edges.`);
   lines.push(``);
-  writeFileSync(join(dir, "INDEX.md"), lines.join("\n"));
+  writeSafe(join(dir, "INDEX.md"), lines.join("\n"));
 
   return {
     notes: notes.length,