@nodii/dev 0.5.0 → 0.6.2

package/dist/harness.js

@@ -0,0 +1,343 @@
+// `nodii-dev harness install|update`: write the agent harness Dev generates
+// for one repository from the ratified methodology (AD-era contract §7).
+// Nothing about the rules is authored here. This module places Dev's files
+// (Dev stamps each with its methodology version) and keeps an ownership
+// record, so it never touches a file, block or hook entry it did not write.
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join, normalize, sep } from "node:path";
+import { promisify } from "node:util";
+import { CliError, devRequest, query } from "./core.js";
+
+/** What this CLI wrote, per path: { mode, sha256 }, or for merge-json the hook entries it `added`. */
+export const STATE_PATH = ".nodii/harness-state.json";
+export const BEGIN = "<!-- nodii-dev:harness:begin -->";
+export const END = "<!-- nodii-dev:harness:end -->";
+const MODES = new Set(["managed-block", "replace", "merge-json"]);
+
+const sha = (text) => createHash("sha256").update(text).digest("hex");
+// Key-order independent, so a tool that rewrites settings.json does not hide an entry.
+const stable = (value) => JSON.stringify(value, (_, v) => (v && typeof v === "object" && !Array.isArray(v) ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => a.localeCompare(b))) : v));
+
+// Dev's stamp file carries the time of each request; a new time alone is not a change.
+function sameStamp(current, content) {
+  try {
+    const strip = (text) => stable({ ...JSON.parse(text), generatedAt: null });
+    return strip(current) === strip(content);
+  } catch { return false; }
+}
+
+async function optional(path) {
+  try { return await readFile(path, "utf8"); } catch (error) { if (error.code === "ENOENT") return null; throw error; }
+}
+
+// The only files Dev generates (AD-era contract §7). Anything else, such as a
+// git hook or a CI workflow, is refused whatever the disk's case rules.
+const HARNESS_PATHS = [/^CLAUDE\.md$/, /^AGENTS\.md$/, /^\.claude\/settings\.json$/, /^\.nodii\/harness\.json$/, /^\.claude\/skills\/nodii-[a-z0-9][a-z0-9._-]*\/SKILL\.md$/];
+
+/** A generated path must be one of the harness files the contract names. */
+export function safeRelative(path) {
+  const raw = String(path ?? "");
+  const clean = normalize(raw).split(sep).join("/");
+  if (clean !== raw || !HARNESS_PATHS.some((p) => p.test(clean)))
+    throw new CliError("HARNESS_INVALID", `Dev sent a path that is not a harness file: ${path}`, 1);
+  return clean;
+}
+
+// ─── managed blocks ─────────────────────────────────────────────────────────
+const blockPattern = new RegExp(`${BEGIN.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${END.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\n?`);
+export const blockOf = (content) => {
+  const trimmed = content.trim();
+  return `${trimmed.startsWith(BEGIN) ? trimmed : `${BEGIN}\n${trimmed}\n${END}`}\n`;
+};
+export const currentBlock = (text) => blockPattern.exec(text ?? "")?.[0] ?? null;
+// An editor may drop the final newline or check the file out with CRLF; neither is an edit.
+const blockSha = (block) => sha(block.replace(/\r\n/g, "\n").replace(/\n?$/, "\n"));
+export function withBlock(text, block) {
+  if (text === null || text.trim() === "") return block;
+  if (blockPattern.test(text)) return text.replace(blockPattern, () => block);
+  return `${text.trimEnd()}\n\n${block}`;
+}
+// Only the gap the block sat in is closed; the rest of the file is left as it was.
+export function withoutBlock(text) {
+  const match = blockPattern.exec(text);
+  if (!match) return text;
+  const before = text.slice(0, match.index).replace(/\n+$/, "");
+  const after = text.slice(match.index + match[0].length).replace(/^\n+/, "");
+  const out = before && after ? `${before}\n\n${after}` : before || after;
+  return out.trim() === "" ? "" : `${out.trimEnd()}\n`;
+}
+// A CRLF checkout of a file nodii-dev wrote is not an edit.
+const fileSha = (text) => sha(text.replace(/\r\n/g, "\n"));
+
+// ─── merged JSON (Claude Code settings hooks) ───────────────────────────────
+function parseJson(text, path) {
+  try { return text === null || text.trim() === "" ? {} : JSON.parse(text); }
+  catch { throw new CliError("HARNESS_SETTINGS_INVALID", `${path} is not valid JSON; fix it before installing the harness.`, 2); }
+}
+/**
+ * Remove exactly the hook entries nodii-dev added before (`added`), then add
+ * the new fragment's entries that are not already there. Returns the merged
+ * settings and the entries this merge owns: the ones it added now, plus the
+ * ones it added before and still wants. An entry the user had first is never
+ * owned, so a later update never removes it.
+ */
+export function mergeHooks(current, added = {}, fragment = {}) {
+  const hooks = Object.fromEntries(Object.entries(current.hooks ?? {}).map(([e, list]) => [e, [...list]]));
+  const owned = {};
+  const wanted = (event, entry) => (fragment.hooks?.[event] ?? []).some((x) => stable(x) === stable(entry));
+  for (const [event, entries] of Object.entries(added.hooks ?? {}))
+    for (const entry of entries) {
+      if (wanted(event, entry) && (hooks[event] ?? []).some((x) => stable(x) === stable(entry))) { (owned[event] ??= []).push(entry); continue; }
+      // Only the one copy nodii-dev added goes; an identical copy the user added stays.
+      const list = hooks[event] ?? [];
+      const at = list.findLastIndex((x) => stable(x) === stable(entry));
+      if (at !== -1) list.splice(at, 1);
+      if (!list.length) delete hooks[event];
+    }
+  for (const [event, entries] of Object.entries(fragment.hooks ?? {}))
+    for (const entry of entries) {
+      const list = (hooks[event] ??= []);
+      if (list.some((x) => stable(x) === stable(entry))) continue;
+      list.push(entry);
+      (owned[event] ??= []).push(entry);
+    }
+  const out = { ...current };
+  if (Object.keys(hooks).length) out.hooks = hooks;
+  else delete out.hooks;
+  return { merged: out, owned: { hooks: owned } };
+}
+
+/** The first event whose recorded entry is no longer in the settings exactly as written, or null. */
+export function missingHooks(current, added = {}) {
+  for (const [event, entries] of Object.entries(added.hooks ?? {}))
+    if (entries.some((entry) => !(current.hooks?.[event] ?? []).some((x) => stable(x) === stable(entry)))) return event;
+  return null;
+}
+
+export async function readState(root) {
+  const text = await optional(join(root, STATE_PATH));
+  if (text === null) return null;
+  try { return JSON.parse(text); }
+  catch { throw new CliError("HARNESS_STATE_INVALID", `${STATE_PATH} is not valid JSON; restore it from git before updating.`, 2); }
+}
+
+/** Check Dev's response before anything is planned from it. */
+export function checkHarness(harness) {
+  if (!harness?.methodologyVersion || !Array.isArray(harness.files)) throw new CliError("HARNESS_INVALID", "Dev's harness response has no methodologyVersion or files.", 1);
+  const seen = new Set();
+  return harness.files.map((file) => {
+    const path = safeRelative(file.path);
+    if (seen.has(path)) throw new CliError("HARNESS_INVALID", `Dev sent ${path} twice.`, 1);
+    seen.add(path);
+    if (!MODES.has(file.mode)) throw new CliError("HARNESS_INVALID", `Dev sent ${path} with unknown mode ${file.mode}.`, 1);
+    const content = String(file.content ?? "");
+    if (file.sha256 && sha(content) !== file.sha256) throw new CliError("HARNESS_INVALID", `${path} does not match the sha256 Dev sent with it.`, 1);
+    if (file.mode === "merge-json") {
+      try { JSON.parse(content); } catch { throw new CliError("HARNESS_INVALID", `Dev sent ${path} with content that is not JSON.`, 1); }
+    }
+    return { path, mode: file.mode, kind: file.kind, content };
+  });
+}
+
+/**
+ * Compare Dev's harness with the repository. `adopt` names existing files the
+ * operator lets nodii-dev take over (on install, or when an update adds a file). Returns the planned
+ * writes, the new ownership state, and every reason the plan cannot apply.
+ */
+export async function planHarness(root, harness, { install, adopt = [], request = {} }) {
+  const files = checkHarness(harness);
+  const state = await readState(root);
+  if (install && state) throw new CliError("HARNESS_INSTALLED", `This repository already has the nodii-dev harness for ${state.repo} (methodology ${state.methodologyVersion}). Run \`nodii-dev harness update\`.`, 2);
+  if (!install && !state) throw new CliError("HARNESS_NOT_INSTALLED", "No nodii-dev harness here. Run `nodii-dev harness install` first.", 2);
+  if (state && (state.repo !== harness.repo || (state.serviceId ?? null) !== (harness.serviceId ?? null)))
+    throw new CliError("HARNESS_SERVICE_MISMATCH", `This repository's harness is for ${state.repo}${state.serviceId ? ` (${state.serviceId})` : ""}, not ${harness.repo}${harness.serviceId ? ` (${harness.serviceId})` : ""}. One service per repository.`, 2);
+  const owned = state?.files ?? {};
+  const adopted = new Set(adopt.map((path) => {
+    try { return safeRelative(path); }
+    catch { throw new CliError("USAGE", `--adopt ${path} is not a harness file (CLAUDE.md, AGENTS.md, .claude/settings.json, .claude/skills/nodii-CODE/SKILL.md).`, 2); }
+  }));
+  const changes = [];
+  const conflicts = [];
+  const next = {};
+  for (const file of files) {
+    const before = owned[file.path];
+    const current = await optional(join(root, file.path));
+    const unowned = current !== null && !before && !adopted.has(file.path);
+    if (file.mode === "replace") {
+      if (unowned) { conflicts.push({ path: file.path, reason: "exists and was not written by nodii-dev" }); continue; }
+      if (current !== null && before && fileSha(current) !== before.sha256) { conflicts.push({ path: file.path, reason: "edited since nodii-dev wrote it" }); continue; }
+      if (current !== null && file.kind === "stamp" && sameStamp(current, file.content)) { next[file.path] = { mode: file.mode, sha256: fileSha(current) }; continue; }
+      next[file.path] = { mode: file.mode, sha256: sha(file.content) };
+      // A CRLF checkout of the same text is not a change.
+      if (current === null || fileSha(current) !== sha(file.content)) changes.push({ path: file.path, mode: file.mode, action: current === null ? "create" : "update", text: file.content });
+    } else if (file.mode === "managed-block") {
+      const block = blockOf(file.content);
+      const existing = currentBlock(current);
+      // A BEGIN marker without its END: appending would later swallow the text between them.
+      if (!existing && (current ?? "").includes(BEGIN)) { conflicts.push({ path: file.path, reason: `has a ${BEGIN} line without its ${END}; restore the end marker or remove the begin marker` }); continue; }
+      if (unowned && current.trim() !== "") { conflicts.push({ path: file.path, reason: "exists and was not written by nodii-dev; adopt it to add the managed block" }); continue; }
+      if (before && existing && blockSha(existing) !== before.sha256) { conflicts.push({ path: file.path, reason: "its nodii-dev block was edited since nodii-dev wrote it" }); continue; }
+      next[file.path] = { mode: file.mode, sha256: blockSha(block) };
+      const text = withBlock(current, block);
+      // The same block with CRLF line endings or no final newline is not a change.
+      if (text !== current && !(existing && blockSha(existing) === blockSha(block))) changes.push({ path: file.path, mode: file.mode, action: current === null ? "create" : existing ? "update" : "add block", text });
+    } else {
+      const fragment = JSON.parse(file.content);
+      if (unowned) { conflicts.push({ path: file.path, reason: "exists and was not written by nodii-dev; adopt it to merge the hooks" }); continue; }
+      const parsed = parseJson(current, file.path);
+      const edited = current !== null && missingHooks(parsed, before?.added);
+      if (edited) { conflicts.push({ path: file.path, reason: `the hook entry nodii-dev added under ${edited} was edited or removed since nodii-dev wrote it` }); continue; }
+      const { merged, owned: added } = mergeHooks(parsed, before?.added, fragment);
+      next[file.path] = { mode: file.mode, added };
+      const text = `${JSON.stringify(merged, null, 2)}\n`;
+      // Compare content, not formatting: another indent or key order is not a change.
+      if (current === null || stable(merged) !== stable(parsed))
+        changes.push({ path: file.path, mode: file.mode, action: current === null ? "create" : "merge", text });
+    }
+  }
+  for (const [path, before] of Object.entries(owned)) {
+    if (next[path] || files.some((f) => f.path === path)) continue;
+    const current = await optional(join(root, path));
+    if (current === null) continue;
+    if (before.mode === "replace") {
+      if (fileSha(current) !== before.sha256) conflicts.push({ path, reason: "edited since nodii-dev wrote it; Dev no longer generates it" });
+      else changes.push({ path, mode: before.mode, action: "remove" });
+    } else if (before.mode === "managed-block") {
+      const existing = currentBlock(current);
+      if (existing && blockSha(existing) !== before.sha256) conflicts.push({ path, reason: "its nodii-dev block was edited; Dev no longer generates it" });
+      else if (existing) {
+        const text = withoutBlock(current);
+        changes.push(text === "" ? { path, mode: before.mode, action: "remove" } : { path, mode: before.mode, action: "remove block", text });
+      }
+    } else {
+      const parsed = parseJson(current, path);
+      const edited = missingHooks(parsed, before.added);
+      if (edited) { conflicts.push({ path, reason: `the hook entry nodii-dev added under ${edited} was edited or removed; Dev no longer generates it` }); continue; }
+      const { merged } = mergeHooks(parsed, before.added, {});
+      changes.push({ path, mode: before.mode, action: "unmerge", text: `${JSON.stringify(merged, null, 2)}\n` });
+    }
+  }
+  const nextState = {
+    repo: harness.repo,
+    serviceId: harness.serviceId ?? null,
+    methodologyVersion: harness.methodologyVersion,
+    generatedAt: harness.generatedAt ?? null,
+    sources: harness.sources ?? [],
+    // What install asked Dev for, so update asks the same.
+    request,
+    files: Object.fromEntries(Object.entries(next).sort(([a], [b]) => a.localeCompare(b))),
+  };
+  return { state, nextState, changes, conflicts };
+}
+
+export async function applyHarness(root, plan) {
+  if (plan.conflicts.length) throw new CliError("HARNESS_CONFLICT", "Refusing to apply a harness plan with conflicts.", 1);
+  const writeState = async (state) => {
+    await mkdir(dirname(join(root, STATE_PATH)), { recursive: true });
+    await writeFile(join(root, STATE_PATH), `${JSON.stringify(state, null, 2)}\n`);
+  };
+  const done = [];
+  try {
+    for (const change of plan.changes) {
+      const target = join(root, change.path);
+      if (change.action === "remove") await rm(target, { force: true });
+      else {
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, change.text);
+      }
+      done.push(change.path);
+    }
+  } catch (error) {
+    // Record ownership of what was written before the failure, so the next
+    // run neither disowns those files nor reports them as edited.
+    const files = { ...(plan.state?.files ?? {}) };
+    for (const path of done) if (plan.nextState.files[path]) files[path] = plan.nextState.files[path]; else delete files[path];
+    await writeState({ ...(plan.state ?? plan.nextState), files }).catch(() => {});
+    throw error;
+  }
+  await writeState(plan.nextState);
+  return plan.nextState;
+}
+
+/** Which methodology sources moved between two states: "M05 0.2 → 1.0", "+M10 1.0", "-M04". */
+export function sourceChanges(before = [], after = []) {
+  const from = new Map(before.map((s) => [s.code, s.version]));
+  const to = new Map(after.map((s) => [s.code, s.version]));
+  const out = [];
+  for (const [code, version] of to)
+    if (!from.has(code)) out.push(`+${code} ${version}`);
+    else if (from.get(code) !== version) out.push(`${code} ${from.get(code)} → ${version}`);
+  for (const code of from.keys()) if (!to.has(code)) out.push(`-${code}`);
+  return out;
+}
+
+// ─── the command ────────────────────────────────────────────────────────────
+const execFileAsync = promisify(execFile);
+
+/** The repository root and Dev's `repo` key: the git remote's name, else the folder's. */
+export async function repoContext(cwd = process.cwd()) {
+  let root;
+  try { root = (await execFileAsync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf8" })).stdout.trim(); }
+  catch { throw new CliError("GIT_REQUIRED", "Run harness commands inside the repository's git checkout, or pass --root DIR --repo NAME.", 2); }
+  let name;
+  try { name = (await execFileAsync("git", ["remote", "get-url", "origin"], { cwd: root, encoding: "utf8" })).stdout.trim(); }
+  catch { name = root; }
+  return { root, repo: name.replace(/\.git$/, "").split(/[/:]/).filter(Boolean).at(-1).toLowerCase() };
+}
+
+const flagList = (value) => (value === undefined || value === true ? [] : [value].flat().flatMap((x) => String(x).split(",")).filter(Boolean));
+const changeLine = (c) => `${{ create: "+", remove: "-" }[c.action] ?? "~"} ${c.path}${["create", "update", "remove"].includes(c.action) ? "" : ` (${c.action})`}`;
+
+export async function harnessCommand(action, flags, { request = devRequest, context = repoContext } = {}) {
+  if (!["install", "update"].includes(action)) throw new CliError("USAGE", "harness install|update [--repo NAME] [--service ID] [--include-drafts[=false]] [--adopt PATH,...] [--dry-run] [--check]", 2);
+  if (flags.fleet || flags.all) throw new CliError("USAGE", "The harness is installed one service at a time, in that service's repository. There is no fleet mode.", 2);
+  if (flags.root === true || flags.repo === true) throw new CliError("USAGE", "--root and --repo need a value.", 2);
+  const ctx = flags.root ? { root: flags.root, repo: flags.repo } : await context();
+  const repo = flags.repo && flags.repo !== true ? String(flags.repo) : ctx.repo;
+  if (!repo) throw new CliError("USAGE", "Pass --repo NAME.", 2);
+  const state = await readState(ctx.root);
+  // Update asks Dev for what install asked for, unless told otherwise.
+  const saved = action === "update" ? (state?.request ?? {}) : {};
+  const serviceId = flags.service && flags.service !== true ? String(flags.service) : (saved.serviceId ?? undefined);
+  const includeDrafts = flags["include-drafts"] !== undefined ? flags["include-drafts"] !== "false" : Boolean(saved.includeDrafts);
+  const params = { repo, serviceId, includeDrafts: includeDrafts ? "true" : undefined };
+
+  if (action === "install" && flags.check) throw new CliError("USAGE", "--check goes with `harness update`; to preview an install use --dry-run.", 2);
+  if (action === "update" && flags.check) {
+    if (!state) throw new CliError("HARNESS_NOT_INSTALLED", "No nodii-dev harness here. Run `nodii-dev harness install` first.", 2);
+    // Compare the files Dev would write now, not only the version: the
+    // CLAUDE.md block also changes when the service's domain becomes AD.
+    const harness = (await request("GET", `/api/v1/harness${query(params)}`)).data;
+    const plan = await planHarness(ctx.root, harness, { install: false });
+    const moved = sourceChanges(state.sources, harness.sources);
+    const behind = harness.methodologyVersion !== state.methodologyVersion || plan.changes.length > 0 || plan.conflicts.length > 0;
+    const payload = { data: { repo, current: !behind, installed: state.methodologyVersion, available: harness.methodologyVersion, sources: moved, changes: plan.changes.map(({ path, action: a, mode }) => ({ path, action: a, mode })), conflicts: plan.conflicts } };
+    if (behind) process.exitCode = 1;
+    return { payload, human: behind ? [`Harness is behind: ${state.methodologyVersion} → ${harness.methodologyVersion}`, ...moved.map((x) => `  source ${x}`), ...plan.changes.map(changeLine), ...plan.conflicts.map((c) => `  conflict ${c.path}: ${c.reason}`), "Run `nodii-dev harness update`."].join("\n") : `Harness is current (${state.methodologyVersion}).` };
+  }
+
+  const harness = (await request("GET", `/api/v1/harness${query(params)}`)).data;
+  const plan = await planHarness(ctx.root, harness, { install: action === "install", adopt: flagList(flags.adopt), request: { ...(serviceId ? { serviceId } : {}), includeDrafts } });
+  const summary = {
+    repo: harness.repo, serviceId: harness.serviceId ?? null,
+    from: state?.methodologyVersion ?? null, to: harness.methodologyVersion,
+    sources: sourceChanges(state?.sources, harness.sources),
+    changes: plan.changes.map(({ path, action: a, mode }) => ({ path, action: a, mode })),
+    conflicts: plan.conflicts, warnings: harness.warnings ?? [],
+  };
+  const lines = [
+    `${harness.repo}${harness.serviceId ? ` (${harness.serviceId})` : ""}: methodology ${summary.from ? `${summary.from} → ` : ""}${summary.to}`,
+    ...summary.sources.map((x) => `  source ${x}`),
+    ...plan.changes.map(changeLine),
+    ...summary.warnings.map((w) => `warning: ${w}`),
+  ];
+  if (plan.conflicts.length)
+    throw new CliError("HARNESS_CONFLICT",
+      `Nothing written. These files are not nodii-dev's to change:\n${plan.conflicts.map((c) => `  ${c.path}: ${c.reason}`).join("\n")}\n` +
+      "Restore files nodii-dev wrote (git checkout, or remove your edits). For your own files, remove them or let nodii-dev take them over with --adopt PATH[,PATH].", 1, summary);
+  if (flags["dry-run"]) return { payload: { data: { ...summary, dryRun: true } }, human: `${lines.join("\n")}\n${plan.changes.length ? "Dry run: nothing written." : "No changes."}` };
+  await applyHarness(ctx.root, plan);
+  return { payload: { data: { ...summary, applied: true } }, human: `${lines.join("\n")}\n${plan.changes.length ? `${action === "install" ? "Installed" : "Updated"}: ${plan.changes.length} change${plan.changes.length === 1 ? "" : "s"}.` : "Harness already current."}` };
+}

package/dist/upload.js

@@ -0,0 +1,291 @@
+// `nodii-dev docs check|validate|upload|ratify|parked` and `rulebook list|show`:
+// AD documents (M-05; AD-era contract §1–3). Every document is checked
+// locally first, then sent to Dev, which runs the same checks plus the ones
+// that need its data, the version precondition and the parked-items gate.
+// Dev's refusals are shown unchanged.
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { CliError, devRequest, devTextRequest, encode, query } from "./core.js";
+import { CHANGE_CLASSES, validateDocument } from "./docs.js";
+
+/** Exit code when Dev is waiting on the operator to acknowledge parked items. */
+export const EXIT_PARKED = 4;
+
+/** Expand files and directories into the Markdown documents under them, sorted. */
+export async function collectDocuments(paths) {
+  if (!paths.length) throw new CliError("USAGE", "docs needs at least one file or directory", 2);
+  const out = new Set();
+  async function walk(path) {
+    const info = await stat(path).catch(() => null);
+    if (!info) throw new CliError("NOT_FOUND", `No such file or directory: ${path}`, 2);
+    if (info.isFile()) return void out.add(resolve(path));
+    for (const entry of await readdir(path, { withFileTypes: true })) {
+      // `_`-prefixed files and folders are working material, not documents.
+      if (entry.name.startsWith("_") || entry.name.startsWith(".")) continue;
+      const child = join(path, entry.name);
+      if (entry.isDirectory()) await walk(child);
+      else if (entry.name.endsWith(".md")) out.add(resolve(child));
+    }
+  }
+  for (const path of paths) await walk(path);
+  return [...out].sort();
+}
+
+export async function checkDocuments(paths, cwd = process.cwd()) {
+  const files = await collectDocuments(paths);
+  const docs = await Promise.all(files.map(async (file) => {
+    const content = await readFile(file, "utf8");
+    return { path: relative(cwd, file) || file, content, ...validateDocument(content) };
+  }));
+  const byCode = new Map();
+  for (const d of docs) {
+    const code = d.meta.code;
+    if (!code) continue;
+    if (byCode.has(code)) d.errors.push({ code: "DUPLICATE_IN_UPLOAD", message: `code ${code} is also used by ${byCode.get(code)}` });
+    else byCode.set(code, d.path);
+  }
+  return docs;
+}
+
+const errorLines = (docs) =>
+  docs.flatMap((d) => (d.errors ?? []).map((e) => `${d.path}${e.line ? `:${e.line}` : ""}: ${e.code}: ${e.message}`));
+
+const parkedLines = (docs) =>
+  docs.filter((d) => d.items?.length).flatMap((d) => [
+    `${d.label} has ${d.items.length} parked item${d.items.length === 1 ? "" : "s"}:`,
+    ...d.items.map((p, i) => `  ${i + 1}. ${p.text}${p.line ? `  (line ${p.line})` : ""}`),
+  ]);
+const warningLines = (docs) =>
+  docs.flatMap((d) => (d.warnings ?? []).map((w) => `${d.path}${w.line ? `:${w.line}` : ""}: warning: ${w.message}`));
+
+const localParked = (docs) => docs.map((d) => ({ label: `${d.path} (${d.meta.code ?? "?"})`, items: d.parked }));
+
+const ACK_HINT =
+  "An operator must acknowledge each list in Dev (Parked items, or the document's entry page). nodii-dev is an OAuth app and cannot acknowledge for them. " +
+  "Re-run this command after they do, or add --wait to keep waiting.";
+
+function localGate(docs, json) {
+  const lines = errorLines(docs);
+  if (!lines.length) return;
+  throw new CliError("DOCUMENT_INVALID", `${lines.length} problem${lines.length === 1 ? "" : "s"} found locally; nothing sent to Dev.${json ? "" : `\n${lines.join("\n")}`}`, 1,
+    json ? { documents: docs.filter((d) => d.errors.length).map((d) => ({ path: d.path, code: d.meta.code ?? null, errors: d.errors })) } : undefined);
+}
+
+function changeClass(flags) {
+  const value = flags.class ?? flags["change-class"];
+  if (!CHANGE_CLASSES.includes(value)) throw new CliError("USAGE", `--class is required: ${CHANGE_CLASSES.join(" | ")} (M05-8)`, 2);
+  return value;
+}
+
+/** `--base CODE=VERSION` (repeatable) or `--base VERSION` for one document. */
+function baseFlags(flags, docs) {
+  const map = new Map();
+  for (const raw of [flags.base].flat().filter((x) => x !== undefined && x !== true)) {
+    const value = String(raw);
+    const at = value.indexOf("=");
+    if (at > 0) map.set(value.slice(0, at), value.slice(at + 1));
+    else if (docs.length === 1) map.set(docs[0].meta.code, value);
+    else throw new CliError("USAGE", "With several documents, pass --base CODE=VERSION for each existing one.", 2);
+  }
+  return map;
+}
+
+/**
+ * M05-11: each write names the version it was based on. A new document is
+ * based on nothing (null). For an existing one the author must say which
+ * version they started from; the CLI never fills in Dev's current version
+ * for them, because that would turn the precondition into a silent overwrite.
+ */
+async function baseVersions(docs, flags, request) {
+  const given = baseFlags(flags, docs);
+  const missing = [];
+  for (const d of docs) {
+    let current = null;
+    try { current = (await request("GET", `/api/v1/documents/${encode(d.meta.code)}`)).data?.currentVersion ?? null; }
+    catch (error) { if (error.code !== "DOCUMENT_NOT_FOUND" && error.code !== "HTTP_404") throw error; }
+    d.currentVersion = current;
+    if (given.has(d.meta.code)) d.baseVersion = given.get(d.meta.code);
+    else if (current === null) d.baseVersion = null;
+    else missing.push(`${d.meta.code} (Dev is at ${current})`);
+  }
+  if (missing.length)
+    throw new CliError("BASE_VERSION_REQUIRED", `These documents already exist in Dev. Say which version you started from with --base CODE=VERSION (M05-11): ${missing.join(", ")}`, 2);
+}
+
+async function readJsonFile(path, flag) {
+  if (!path || path === true) return undefined;
+  try { return JSON.parse(await readFile(path, "utf8")); }
+  catch { throw new CliError("USAGE", `--${flag} must name a JSON file`, 2); }
+}
+
+const serverParked = (details) => (details?.documents ?? []).map((d) => ({ label: `${d.code} (${d.title ?? ""})`.replace(" ()", ""), code: d.code, itemsSha256: d.itemsSha256, items: d.items ?? [] }));
+
+/**
+ * Poll Dev until every refused list is acknowledged. The acknowledgement
+ * records are matched on code and digest: the document being uploaded may
+ * not exist yet, or may differ from Dev's current version.
+ */
+async function waitForAcknowledgement(pending, { request, interval, timeout, log }) {
+  const deadline = Date.now() + timeout;
+  const open = new Map(pending.map((p) => [p.code, p.itemsSha256]));
+  while (open.size) {
+    const acknowledged = (await request("GET", "/api/v1/documents/parked?status=acknowledged")).data ?? [];
+    for (const [code, digest] of [...open])
+      if (acknowledged.some((r) => r.docCode === code && r.itemsSha256 === digest)) { open.delete(code); log(`${code}: parked items acknowledged.`); }
+    if (!open.size) return;
+    if (Date.now() >= deadline) throw new CliError("PARKED_ITEMS_UNACKNOWLEDGED", `Still waiting on the operator for: ${[...open.keys()].join(", ")}`, EXIT_PARKED);
+    await sleep(interval);
+  }
+}
+
+/** Dev's per-document refusals (`details.documents[].errors`), one line each, as the local check prints them. */
+function withDocumentErrors(error) {
+  const docs = error.details?.documents;
+  if (!(error instanceof CliError) || !Array.isArray(docs) || !docs.some((d) => d.errors?.length)) return error;
+  const lines = docs.flatMap((d) => (d.errors ?? []).map((e) => `${d.path ?? d.code}${e.line ? `:${e.line}` : ""}: ${e.code}: ${e.message}`));
+  return new CliError(error.code, `${error.message}\n${lines.join("\n")}`, error.exitCode, error.details);
+}
+
+/** Send a write; on the parked gate, show Dev's list and (with --wait) retry once acknowledged. */
+async function withParkedGate(send, flags, { request, log, waitInterval = 15000 }) {
+  for (;;) {
+    try { return await send(); }
+    catch (error) {
+      if (error.code !== "PARKED_ITEMS_UNACKNOWLEDGED") throw withDocumentErrors(error);
+      const pending = serverParked(error.details);
+      if (!flags.wait) throw new CliError(error.code, `${error.message}\n${parkedLines(pending).join("\n")}\n${ACK_HINT}`, EXIT_PARKED, error.details);
+      log(`${parkedLines(pending).join("\n")}\nWaiting for the operator to acknowledge in Dev…`);
+      await waitForAcknowledgement(pending, { request, interval: waitInterval, timeout: Number(flags["wait-minutes"] ?? 120) * 60000, log });
+    }
+  }
+}
+
+const uploadBody = (docs, cls, flags, decision) => ({
+  documents: docs.map((d) => ({
+    path: d.path, content: d.content, changeClass: cls, baseVersion: d.baseVersion,
+    ...(flags["conformance-ref"] && cls === "conformance" ? { conformanceRef: String(flags["conformance-ref"]) } : {}),
+    ...(flags["meaning-unchanged"] && cls === "editorial" ? { meaningUnchangedReason: String(flags["meaning-unchanged"]) } : {}),
+  })),
+  ...(decision ? { decision } : {}),
+});
+
+export async function docsCommand(action, args, flags, { request = devRequest, log = console.error, cwd = process.cwd(), waitInterval } = {}) {
+  const json = Boolean(flags.json);
+  if (action === "check") {
+    const docs = await checkDocuments(args, cwd);
+    const lines = errorLines(docs);
+    const parked = parkedLines(localParked(docs));
+    if (lines.length) process.exitCode = 1;
+    return {
+      payload: { data: { ok: !lines.length, documents: docs.map((d) => ({ path: d.path, code: d.meta.code ?? null, kind: d.meta.devKind ?? null, version: d.meta.version ?? null, clauseCount: d.clauses.length, parked: d.parked, errors: d.errors, warnings: d.warnings })) } },
+      human: [...lines, ...warningLines(docs), ...parked, `${docs.length} document${docs.length === 1 ? "" : "s"} checked: ${lines.length ? `${lines.length} problem${lines.length === 1 ? "" : "s"}` : "no problems"}.`].join("\n"),
+    };
+  }
+
+  if (action === "validate" || action === "upload") {
+    const cls = changeClass(flags);
+    const decision = await readJsonFile(flags.decision, "decision");
+    if (cls === "ruling" && !decision) throw new CliError("RULING_NEEDS_DECISION", "A ruling write needs its decision: --decision DECISION.json (title, context, options, ruling, consequences, provenance, amends).", 2);
+    if (cls !== "ruling" && decision) throw new CliError("DECISION_NEEDS_RULING", "--decision goes with --class ruling only.", 2);
+    if (decision && !decision.amends?.length) throw new CliError("AMENDS_EMPTY", "A decision whose amends list is empty is refused (M05-13).", 2);
+    if (cls === "editorial" && flags["meaning-unchanged"] === true) throw new CliError("USAGE", "--meaning-unchanged needs a reason.", 2);
+    if (flags["conformance-ref"] === true) throw new CliError("USAGE", "--conformance-ref needs a value: a PR or REPO@SHA.", 2);
+    const docs = await checkDocuments(args, cwd);
+    localGate(docs, json);
+    await baseVersions(docs, flags, request);
+    const notes = [...warningLines(docs), ...parkedLines(localParked(docs))];
+    if (notes.length) log(notes.join("\n"));
+    const body = uploadBody(docs, cls, flags, decision);
+
+    if (action === "validate") {
+      const result = (await request("POST", "/api/v1/documents/validate", body).catch((e) => { throw withDocumentErrors(e); })).data;
+      if (!result.ok) process.exitCode = 1;
+      return {
+        payload: { data: result },
+        human: [
+          ...result.documents.flatMap((d) => [
+            `${d.path ?? d.code}\t${d.code} ${d.version} ${d.changeClass} ${d.kind} ${d.domain}\tclauses=${d.clauseCount} parked=${d.parkedCount}${d.parkedCount ? (d.parkedAcknowledged ? " (acknowledged)" : " (NOT acknowledged)") : ""}`,
+            ...d.errors.map((e) => `  ${e.code}${e.line ? ` (line ${e.line})` : ""}: ${e.message}`),
+            ...(d.warnings ?? []).map((w) => `  warning ${w.code}${w.line ? ` (line ${w.line})` : ""}: ${w.message}`),
+          ]),
+          ...(result.decisionErrors ?? []).map((e) => `decision: ${e.code}: ${e.message}`),
+          result.ok ? "Dev accepts this upload." : "Dev would refuse this upload.",
+        ].join("\n"),
+      };
+    }
+
+    const result = (await withParkedGate(() => request("POST", "/api/v1/documents/upload", body), flags, { request, log, waitInterval })).data;
+    return {
+      payload: { data: result },
+      human: [
+        ...result.documents.map((d) => `${d.created ? "+" : "~"} ${d.code} ${d.version}\t${d.changeNote}`),
+        ...(result.decision ? [`Locked ${result.decision.id}: ${result.decision.title}`] : []),
+        `Uploaded ${result.documents.length} document${result.documents.length === 1 ? "" : "s"} (${cls}).`,
+      ].join("\n"),
+    };
+  }
+
+  if (action === "ratify") {
+    // Bulk ratification (M05-2): one decision locks v1.0 of every draft in
+    // the named domains, and those domains become AD. A domain that is
+    // already AD may be named again to ratify drafts added to it since.
+    const domains = [flags.domain].flat().filter((x) => x && x !== true).flatMap((x) => String(x).split(",")).filter(Boolean);
+    if (!domains.length) throw new CliError("USAGE", "docs ratify needs --domain KEY (repeatable), e.g. --domain rulebook/methodology", 2);
+    const decision = await readJsonFile(flags.decision, "decision");
+    const parts = ["title", "context", "options", "ruling", "consequences", "provenance"];
+    const absent = parts.filter((k) => typeof decision?.[k] !== "string" || !decision[k].trim());
+    if (absent.length) throw new CliError("USAGE", `--decision DECISION.json needs non-empty ${absent.join(", ")} (Dev generates the amends).`, 2);
+    const documents = [];
+    for (const key of domains) {
+      const domain = (await request("GET", `/api/v1/domains/${encode(key)}`)).data;
+      for (const d of domain.documents ?? []) if (d.status === "draft") documents.push({ code: d.code, baseVersion: d.currentVersion, parkedCount: d.parkedCount ?? 0 });
+    }
+    if (!documents.length) throw new CliError("DOMAIN_EMPTY", `No draft documents in ${domains.join(", ")}; upload them first with \`nodii-dev docs upload\`.`, 1);
+    // Dev's ratify gate decides on the current versions' parked lists; its refusal carries the real list.
+    log(`Ratifying ${documents.length} document${documents.length === 1 ? "" : "s"} in ${domains.join(", ")} as v1.0:\n${documents.map((d) => `  ${d.code} ${d.baseVersion}${d.parkedCount ? `  (${d.parkedCount} parked)` : ""}`).join("\n")}`);
+    const body = { domains, documents: documents.map(({ code, baseVersion }) => ({ code, baseVersion })), decision: Object.fromEntries(parts.map((k) => [k, decision[k]])) };
+    const result = (await withParkedGate(() => request("POST", "/api/v1/documents/ratify", body), flags, { request, log, waitInterval })).data;
+    return {
+      payload: { data: result },
+      human: [`Locked ${result.decision.id}: ${result.decision.title}`, ...result.documents.map((d) => `  ${d.code} ${d.version}`), `AD now: ${result.domains.map((d) => d.key).join(", ")}`].join("\n"),
+    };
+  }
+
+  if (action === "parked") {
+    if (args[0]) {
+      const p = (await request("GET", `/api/v1/documents/${encode(args[0])}/parked`)).data;
+      const ack = p.current?.acknowledgement;
+      const lines = p.current
+        ? [`${p.code}: ${p.current.count} parked item${p.current.count === 1 ? "" : "s"} in the current version${ack ? ` (${ack.status}${ack.acknowledgedByLabel ? ` by ${ack.acknowledgedByLabel}` : ""})` : ""}`, ...p.current.items.map((x, i) => `  ${i + 1}. ${x.text}`)]
+        : [`${p.code}: not in Dev yet`];
+      for (const x of p.pending ?? []) lines.push(`Awaiting acknowledgement (${x.count} item${x.count === 1 ? "" : "s"}, requested ${x.requestedAt}):`, ...x.items.map((it, i) => `  ${i + 1}. ${it.text}`));
+      return { payload: { data: p }, human: lines.join("\n") };
+    }
+    const payload = await request("GET", `/api/v1/documents/parked${query({ status: flags.status })}`);
+    return { payload, human: (p) => p.data.map((x) => `${x.docCode}\t${x.status}\t${x.count} item${x.count === 1 ? "" : "s"}\t${x.title}`).join("\n") || "No parked-item lists." };
+  }
+  throw new CliError("USAGE", "docs check|validate|upload|ratify|parked", 2);
+}
+
+export async function rulebookCommand(action, args, flags, { request = devRequest, text = devTextRequest } = {}) {
+  for (const name of ["version", "from", "to"])
+    if (flags[name] === true) throw new CliError("USAGE", `--${name} needs a version, e.g. --${name} 1.0`, 2);
+  if (action === "list") {
+    const payload = await request("GET", `/api/v1/documents${query({ section: flags.section ?? (flags.all ? undefined : "rulebook"), kind: flags.kind, serviceId: flags.service, domain: flags.domain, status: flags.status, q: flags.q, limit: flags.limit ?? 500, offset: flags.offset })}`);
+    return { payload, human: (p) => p.data.map((x) => `${x.code}\t${x.currentVersion}\t${x.status}\t${x.kind}\t${x.title}${x.parkedCount ? `\tparked=${x.parkedCount}` : ""}`).join("\n") || "No documents." };
+  }
+  if (action === "show") {
+    const code = args[0];
+    if (!code) throw new CliError("USAGE", "rulebook show CODE [--version V]", 2);
+    if (flags.json) return { payload: await request("GET", flags.version ? `/api/v1/documents/${encode(code)}/versions/${encode(flags.version)}` : `/api/v1/documents/${encode(code)}`) };
+    return { payload: null, human: (await text("GET", `/api/v1/documents/${encode(code)}/body${query({ version: flags.version })}`)).trimEnd() };
+  }
+  if (action === "diff") {
+    const code = args[0];
+    if (!code) throw new CliError("USAGE", "rulebook diff CODE [--from V] [--to V]", 2);
+    const payload = await request("GET", `/api/v1/documents/${encode(code)}/diff${query({ from: flags.from, to: flags.to })}`);
+    return { payload, human: (p) => `${p.data.code} ${p.data.from} → ${p.data.to}\nclauses added: ${p.data.clauses.added.join(", ") || "none"}; removed: ${p.data.clauses.removed.join(", ") || "none"}; changed: ${p.data.clauses.changed.join(", ") || "none"}\n${p.data.unified}` };
+  }
+  throw new CliError("USAGE", "rulebook list|show|diff", 2);
+}