@nodii/dev 0.4.1 → 0.6.1

package/dist/docs.js

@@ -0,0 +1,204 @@
+// Local checks for AD documents (M-05) before anything is sent to Dev. They
+// mirror Dev's structure checks (AD-era contract §1.3) rule for rule, so a
+// document that passes here fails in Dev only on checks that need Dev's data:
+// `pre:` and DEC resolution, versions, retired clause ids. Dev stays the
+// authority; this exists so an upload fails fast, offline, with every problem
+// in one report, using Dev's error codes. Warnings name text Dev reads
+// differently from what its author probably meant.
+
+export const CHANGE_CLASSES = ["ruling", "conformance", "editorial"];
+
+// Contract §1.4.
+export const RULEBOOK_SECTIONS = ["Summary", "Scope", "Rules", "Rationale", "Edge cases and examples", "Enforcement", "Relations", "Sources", "Open questions for ratification", "Change history"];
+export const FEATURE_SECTIONS = ["Summary", "Scope and non-goals", "Actors and permissions", "Rules", "Behaviour", "Data and contracts", "Edge cases and failure modes", "Rationale", "Enforcement and tests", "Relations", "Sources", "Known gaps", "Open questions for ratification", "Change history"];
+export const OVERVIEW_SECTIONS = ["Summary", "Purpose and users", "Capability map", "Component map", "Peer services", "Deployment and environments", "State of the service", "Known gaps", "Open questions for ratification", "Change history"];
+
+// Contract §1.2: front matter `kind` as written → Dev's kind.
+const KINDS = {
+  principles: "principles", methodology: "methodology", standard: "standard", standards: "standard",
+  doctrine: "doctrine", doctrines: "doctrine", "ux-guideline": "ux-guideline", "ux guideline": "ux-guideline",
+  "ux-guidelines": "ux-guideline", "ux guidelines": "ux-guideline", ux: "ux-guideline", "know-how": "know-how",
+  feature: "feature-doc", "feature-doc": "feature-doc",
+  "feature-overview": "service-overview", "feature-doc-overview": "service-overview", "service-overview": "service-overview", overview: "service-overview",
+  "capability-plan": "capability-plan", "feature-plan": "capability-plan", "feature-doc-plan": "capability-plan",
+};
+const ANATOMY = { "feature-doc": FEATURE_SECTIONS, "service-overview": OVERVIEW_SECTIONS, "capability-plan": ["Change history"] };
+const FRONT_MATTER = ["id", "code", "title", "kind", "era", "status", "version", "owner", "incorporates"];
+const CODE_PATTERN = /^[A-Z][A-Z0-9]*(-[A-Z0-9]+)*$/;
+const GROUNDED_AT = /^[a-z0-9][a-z0-9._-]*@[0-9a-f]{7,40}$/;
+const VERSION = /^(\d{1,4})(?:\.(\d{1,4}))?$/;
+
+export const devKind = (label) => KINDS[String(label ?? "").trim().toLowerCase()] ?? null;
+
+const unquote = (raw) => (raw.length >= 2 && ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))) ? raw.slice(1, -1) : raw);
+function flowList(raw) {
+  const items = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of raw.slice(1, -1)) {
+    if (ch === "(" || ch === "[") depth++;
+    if (ch === ")" || ch === "]") depth--;
+    if (ch === "," && depth === 0) { items.push(current); current = ""; continue; }
+    current += ch;
+  }
+  items.push(current);
+  return items.map((x) => unquote(x.trim())).filter(Boolean);
+}
+
+/** Flat `key: value` front matter with `[a, b]` flow lists, as Dev reads it. */
+export function parseFrontMatter(content) {
+  const lines = content.split("\n");
+  if (lines[0]?.trim() !== "---") return null;
+  const end = lines.findIndex((l, i) => i > 0 && l.trim() === "---");
+  if (end === -1) return null;
+  const fields = {};
+  const blockLists = [];
+  for (const [i, line] of lines.slice(1, end).entries()) {
+    const m = /^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(line);
+    if (!m) {
+      if (/^\s+-\s/.test(line) && i > 0) blockLists.push(i + 2);
+      continue;
+    }
+    const value = m[2].trim();
+    fields[m[1]] = value.startsWith("[") && value.endsWith("]") ? flowList(value) : unquote(value);
+  }
+  return { fields, bodyStartLine: end + 2, blockLists };
+}
+
+const sectionTitle = (heading) => heading.replace(/^\d+(\.\d+)*\.?\s+/, "").trim();
+// Dev's definitions (src/lib/ad/markdown.ts), exactly.
+// A clause id: `<code>-<n>`, a Scope clause `<code>-S<n>`, sub-clauses `.m`.
+const CLAUSE_ID = "[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*-S?\\d+(?:\\.\\d+)*";
+const CLAUSE_DEF = new RegExp(`^\\s*[-*+]\\s+\\*\\*(${CLAUSE_ID})\\*\\*(?=\\s|$)(.*)$`);
+// A parked item (M05-11.1): Undecided: … · **Undecided:** … · **Undecided** …
+// · **Undecided (PAYC-26):** … · **Undecided: … (MW1-12.4).** · - **TELE-32** Undecided: …
+const PARKED = new RegExp(`^\\s*(?:[-*+]\\s+|\\d+\\.\\s+)?(?:\\*\\*(${CLAUSE_ID})\\*\\*\\s+)?(\\*\\*)?Undecided(?:\\s*\\(([^)]*)\\))?(?:\\*\\*\\s*:|:\\s*\\*\\*|:|\\*\\*(?=\\s))\\s*(.*)$`);
+// A bare `D` id needs two or more digits (a lone `D1` is Cloudflare's
+// database); namespaced ids (`billing-D7`) are always decisions.
+const DECISION_ID = /\b(?:[a-z][a-z0-9_]*(?:-[a-z0-9_]+)*-D\d+|D\d{2,})\b/g;
+
+/** One line as a parked item, as Dev stores it; null when it is not one. */
+export function parkedItem(line) {
+  const m = PARKED.exec(line);
+  if (!m) return null;
+  return `${m[3] ? `(${m[3]}) ` : ""}${(m[4] ?? "").trim()}`.replace(/\*\*\s*$/, "").trim();
+}
+
+/** Which lines are fenced code (the fence lines included). */
+function fencedLines(lines) {
+  let open = false;
+  return lines.map((line) => {
+    if (/^\s*(```|~~~)/.test(line)) { open = !open; return true; }
+    return open;
+  });
+}
+
+/** Sections, clause definitions and parked items, skipping fenced code, with 1-based lines of the whole file. */
+export function parseBody(content, bodyStartLine = 1) {
+  const lines = content.split("\n");
+  const sections = [];
+  const clauses = [];
+  const parked = [];
+  const fenced = fencedLines(lines);
+  let section = "";
+  for (let i = bodyStartLine - 1; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    if (fenced[i]) continue;
+    const h2 = /^##\s+(.+?)\s*#*\s*$/.exec(line);
+    if (h2 && !line.startsWith("###")) {
+      section = sectionTitle(h2[1]);
+      sections.push({ title: section, line: i + 1 });
+      continue;
+    }
+    // `- **TELE-32** Undecided: …` parks that clause; it is not a second definition of it.
+    const p = parkedItem(line);
+    if (p !== null) { parked.push({ text: p, line: i + 1 }); continue; }
+    const clause = CLAUSE_DEF.exec(line);
+    if (clause) clauses.push({ id: clause[1], section, line: i + 1 });
+  }
+  return { sections, clauses, parked };
+}
+
+/**
+ * Bare pre-dev decision ids (M05-5): a `D12`+ or `billing-D7` in prose, not
+ * right after `pre:`. Fenced code and inline code spans are skipped, as Dev does.
+ */
+export function bareCitations(content) {
+  const out = [];
+  const lines = content.split("\n");
+  const fenced = fencedLines(lines);
+  lines.forEach((line, i) => {
+    if (fenced[i]) return;
+    const prose = line.replace(/`[^`]*`/g, (span) => " ".repeat(span.length));
+    for (const m of prose.matchAll(DECISION_ID))
+      if (prose.slice(Math.max(0, m.index - 4), m.index) !== "pre:") out.push({ citation: m[0], line: i + 1 });
+  });
+  return out;
+}
+
+// "The capability map" is the "Capability map" section.
+const startsWithTitle = (actual, expected) => actual.replace(/^the\s+/i, "").toLowerCase().startsWith(expected.toLowerCase());
+
+function sectionErrors(sections, kind) {
+  const titles = sections.map((s) => s.title);
+  if (kind === "feature-doc" && titles.some((t) => startsWithTitle(t, "Capability map")) && titles.some((t) => startsWithTitle(t, "Purpose and users")))
+    return [{ code: "LOOKS_LIKE_OVERVIEW", message: "this document has the service-overview sections; set `kind: service-overview`", line: 1 }];
+  const errors = [];
+  const required = ANATOMY[kind] ?? RULEBOOK_SECTIONS;
+  let cursor = 0;
+  for (const expected of required) {
+    const at = sections.findIndex((s) => startsWithTitle(s.title, expected));
+    if (at === -1) { errors.push({ code: "SECTION_MISSING", message: `section \`## ${expected}\` is required for kind \`${kind}\`` }); continue; }
+    if (at < cursor) { errors.push({ code: "SECTION_ORDER", message: `section \`## ${expected}\` is out of order (expected: ${required.join(" · ")})`, line: sections[at].line }); continue; }
+    cursor = at;
+  }
+  return errors;
+}
+
+const scalar = (v) => (v === undefined ? "" : Array.isArray(v) ? v.join(", ") : v);
+
+/**
+ * Validate one AD document. Returns { meta, errors, warnings, parked, clauses };
+ * each error is { code, message, line? } with Dev's codes (contract §1.3).
+ */
+export function validateDocument(content) {
+  const text = content.replace(/\r\n/g, "\n");
+  const errors = [];
+  const warnings = [];
+  const parsed = parseFrontMatter(text);
+  if (!parsed) {
+    errors.push({ code: "FRONT_MATTER_MISSING", message: "the document must open with a `---` front matter block (M05-15)", line: 1 });
+    return { meta: {}, errors, warnings, parked: [], clauses: [] };
+  }
+  const { fields, bodyStartLine, blockLists } = parsed;
+  for (const key of FRONT_MATTER)
+    if (fields[key] === undefined || (scalar(fields[key]).length === 0 && !(key === "incorporates" && Array.isArray(fields[key]))))
+      errors.push({ code: "FRONT_MATTER_FIELD_MISSING", message: `front matter field \`${key}\` is required (M05-15)`, line: 1 });
+  if (blockLists.length)
+    warnings.push({ message: "front matter uses a YAML block list (`  - item`); Dev reads only `key: value` and `[a, b]` lists, so write it as `[a, b]`", line: blockLists[0] });
+  const kind = scalar(fields.kind) ? devKind(scalar(fields.kind)) : null;
+  if (scalar(fields.kind) && !kind) errors.push({ code: "KIND_UNKNOWN", message: `kind \`${scalar(fields.kind)}\` is not a rulebook kind or a feature-doc kind`, line: 1 });
+  const code = scalar(fields.code);
+  if (code && !CODE_PATTERN.test(code)) errors.push({ code: "CODE_INVALID", message: `code \`${code}\` must be upper-case letters, digits and hyphens (e.g. PII, M05, AUTH-SES)`, line: 1 });
+  const version = scalar(fields.version);
+  if (version && !VERSION.test(version.trim())) errors.push({ code: "VERSION_INVALID", message: `version \`${version}\` must be \`major.minor\` (e.g. 0.2, 1.0)`, line: 1 });
+  const groundedAt = fields.grounded_at === undefined ? null : scalar(fields.grounded_at);
+  if ((kind === "feature-doc" || kind === "service-overview") && !groundedAt)
+    errors.push({ code: "FRONT_MATTER_FIELD_MISSING", message: "front matter field `grounded_at` (`<repo>@<sha>`) is required on feature docs (M05-15)", line: 1 });
+  else if (groundedAt && !GROUNDED_AT.test(groundedAt))
+    errors.push({ code: "FRONT_MATTER_FIELD_MISSING", message: `grounded_at \`${groundedAt}\` must be \`<repo>@<sha>\``, line: 1 });
+
+  const body = parseBody(text, bodyStartLine);
+  if (kind) errors.push(...sectionErrors(body.sections, kind));
+  if (code) {
+    const seen = new Map();
+    for (const c of body.clauses) {
+      if (!c.id.startsWith(`${code}-`)) { errors.push({ code: "CLAUSE_CODE_MISMATCH", message: `clause \`${c.id}\` does not start with the document code \`${code}-\` (M05-6)`, line: c.line }); continue; }
+      if (seen.has(c.id)) errors.push({ code: "CLAUSE_ID_DUPLICATE", message: `clause \`${c.id}\` is defined twice (first at line ${seen.get(c.id)}) (M05-6)`, line: c.line });
+      else seen.set(c.id, c.line);
+    }
+  }
+  for (const b of bareCitations(text))
+    errors.push({ code: "BARE_DECISION_ID", message: `\`${b.citation}\` is a bare pre-dev decision id; cite it as \`pre:${b.citation}\` (M05-5)`, line: b.line });
+  return { meta: { ...fields, devKind: kind }, errors, warnings, parked: body.parked, clauses: body.clauses };
+}

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/hooks.js

@@ -1,4 +1,4 @@
-import { CliError, hubRequest } from "./core.js";
+import { CliError, devRequest } from "./core.js";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 
@@ -73,7 +73,7 @@ export function extractNodeIds(value, out = new Set()) {
   return [...out];
 }
 
-export async function preHook(payload, request = hubRequest) {
+export async function preHook(payload, request = devRequest) {
   const name = payload.tool_name ?? "";
   if (!isFigmaTool(name) || isReadTool(name))
     return { allowed: true, ignored: true };
@@ -109,7 +109,7 @@ export async function preHook(payload, request = hubRequest) {
   return { allowed: true, fileKey, changeSetId: response.data.changeSetId };
 }
 
-export async function postHook(payload, request = hubRequest) {
+export async function postHook(payload, request = devRequest) {
   const name = payload.tool_name ?? "";
   if (!isFigmaTool(name) || isReadTool(name))
     return { logged: false, ignored: true };
@@ -156,7 +156,7 @@ export const settingsSnippet = () => ({
   },
 });
 
-export async function heartbeatCurrentLane(request = hubRequest) {
+export async function heartbeatCurrentLane(request = devRequest) {
   let branch;
   try { branch = (await execFileAsync("git", ["branch", "--show-current"], { encoding: "utf8" })).stdout.trim(); }
   catch { return { heartbeated: false, reason: "not a git worktree" }; }

package/dist/lanes.js

@@ -1,6 +1,6 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { CliError, encode, hubRequest, query, readConfig, requireFlag } from "./core.js";
+import { CliError, encode, devRequest, query, readConfig, requireFlag } from "./core.js";
 
 const execFileAsync = promisify(execFile);
 const via = { via: "nodii-dev" };
@@ -42,7 +42,7 @@ function evidence(flags) {
   return { kind: flag === "figma" ? "figma_frame" : flag.replace("-", "_"), ...(URL.canParse(value) ? { url: value } : { ref: value }), ...via };
 }
 
-export async function laneCommand(action, args, flags, { request = hubRequest, config = readConfig, gitContext = inferGitContext } = {}) {
+export async function laneCommand(action, args, flags, { request = devRequest, config = readConfig, gitContext = inferGitContext } = {}) {
   if (action === "list") {
     const c = flags.mine ? await config() : null;
     const payload = await request("GET", `/api/v1/lanes${query({ kind: flags.kind, status: flags.status, machine: flags.machine, agent: flags.mine ? c.agentId : flags.agent, "waiting-on": flags["waiting-on"], stuck: flags.stuck, cursor: flags.cursor, limit: flags.limit })}`);
@@ -105,7 +105,7 @@ export async function laneCommand(action, args, flags, { request = hubRequest, c
   throw new CliError("USAGE", `Unknown lane action: ${action}`, 2);
 }
 
-export async function nextCommand(ref, flags, { request = hubRequest } = {}) {
+export async function nextCommand(ref, flags, { request = devRequest } = {}) {
   const lane = (await request("GET", `/api/v1/lanes/${encode(ref)}`)).data;
   const pending = lane.steps.filter((x) => ["waiting", "current", "blocked"].includes(x.state)).sort((a, b) => a.position - b.position);
   const steps = ["backend", "frontend"].map((side) => pending.find((x) => x.side === side)).filter(Boolean);
@@ -113,7 +113,7 @@ export async function nextCommand(ref, flags, { request = hubRequest } = {}) {
   return { payload: { data }, human: data.length ? data.map((x) => `${x.side}: ${x.label}\n  ${x.command}`).join("\n") : `All workflow steps are complete. Run: nodii-dev lane land ${lane.key}` };
 }
 
-export async function builtCommand(action, args, flags, { request = hubRequest } = {}) {
+export async function builtCommand(action, args, flags, { request = devRequest } = {}) {
   if (action === "list") {
     const payload = await request("GET", `/api/v1/built${query({ cursor: flags.cursor, limit: flags.limit, includeAcknowledged: flags["include-acknowledged"] })}`);
     return { payload, human: (p) => p.data.map(laneLine).join("\n") || "No built lanes awaiting acknowledgement." };
@@ -126,7 +126,7 @@ export async function builtCommand(action, args, flags, { request = hubRequest }
   throw new CliError("USAGE", `Unknown built action: ${action}`, 2);
 }
 
-export async function machineCommand(action, args, flags, { request = hubRequest } = {}) {
+export async function machineCommand(action, args, flags, { request = devRequest } = {}) {
   if (action === "list") return { payload: await request("GET", "/api/v1/machines"), human: (p) => p.data.map((x) => `${x.id}\t${x.name}\tcoordinator=${x.coordinatorAgentId}`).join("\n") || "No machines." };
   const id = need(args[0], `machine ${action} needs <machine>`);
   if (action === "show") return { payload: await request("GET", `/api/v1/machines/${encode(id)}`) };
@@ -136,7 +136,7 @@ export async function machineCommand(action, args, flags, { request = hubRequest
   throw new CliError("USAGE", `Unknown machine action: ${action}`, 2);
 }
 
-export async function peopleCommand(action, args, flags, { request = hubRequest } = {}) {
+export async function peopleCommand(action, args, flags, { request = devRequest } = {}) {
   if (action === "reveal") {
     const id = need(args[0], "people reveal needs <person>");
     return { payload: await request("POST", `/api/v1/people/${encode(id)}/reveal-name`, { reason: requireFlag(flags, "reason") }), human: (p) => p.data.value ?? p.data.hint ?? "Name unavailable." };
@@ -145,7 +145,7 @@ export async function peopleCommand(action, args, flags, { request = hubRequest
   throw new CliError("USAGE", `Unknown people action: ${action}`, 2);
 }
 
-export async function agentWorkflowCommand(action, args, flags, { request = hubRequest } = {}) {
+export async function agentWorkflowCommand(action, args, flags, { request = devRequest } = {}) {
   const agent = need(args[0], `agent ${action} needs <agent>`);
   if (action === "lane-limit") return { payload: await request("PUT", `/api/v1/agents/${encode(agent)}/lane-limit`, { laneLimit: Number(need(args[1], "agent lane-limit needs <agent> <n>")) }), human: "Lane limit updated." };
   if (action === "grant") return { payload: await request("POST", `/api/v1/agents/${encode(agent)}/repo-grants`, { repo: need(args[1], `agent ${action} needs <agent> <repo>`) }), human: "Repository grant added." };