@rness/cli 0.8.1 → 0.9.1

package/dist/{chunk-ONLF4VFA.js → chunk-N3F6N6GA.js}

@@ -743,6 +743,21 @@ async function isClean(dir, ignore = []) {
     dir
   )).trim() === "";
 }
+async function changedPaths(dir, paths) {
+  if (paths.length === 0) return [];
+  const entries = (await git(
+    ["status", "--porcelain", "-z", "--untracked-files=all", "--", ...paths],
+    dir
+  )).split("\0");
+  const changed = [];
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i] ?? "";
+    if (entry.length < 4) continue;
+    changed.push(entry.slice(3));
+    if (entry[0] === "R" || entry[0] === "C") i++;
+  }
+  return changed;
+}
 async function pullFastForward(dir, credentials) {
   await git(["pull", "--ff-only", "--quiet"], dir, credentials);
 }
@@ -797,7 +812,7 @@ function classifyProbe(url, exitCode, stderr) {
 var STDERR_FLUSH_MS = 200;
 async function probeRemote(url, timeoutMs = 6e4, credentials) {
   positional(url, "repository url");
-  return new Promise((resolve6) => {
+  return new Promise((resolve7) => {
     const auth = withCredentials(credentials);
     const child = spawn(
       "git",
@@ -816,7 +831,7 @@ async function probeRemote(url, timeoutMs = 6e4, credentials) {
       settled = true;
       clearTimeout(timer);
       child.stderr?.destroy();
-      resolve6(probe);
+      resolve7(probe);
     };
     const timer = setTimeout(() => {
       child.kill("SIGKILL");
@@ -1198,8 +1213,8 @@ function warn(text) {
 var WORD = [" \u2588\u2580\u2588 \u2588\u2584 \u2588 \u2588\u2580\u2580 \u2588\u2580\u2580 \u2588\u2580\u2580", " \u2588\u2580\u2584 \u2588 \u2580\u2588 \u2588\u2588\u2584 \u2584\u2584\u2588 \u2584\u2584\u2588"];
 var FROM = [63, 185, 80];
 var TO = [57, 197, 207];
-function gradient(line) {
-  const chars = [...line];
+function gradient(line2) {
+  const chars = [...line2];
   const last = Math.max(1, chars.length - 1);
   const painted = chars.map((ch, i) => {
     if (ch === " ") return ch;
@@ -1216,7 +1231,7 @@ function banner(version, stream = process.stdout) {
   const coloured = paint("done", "x", stream) !== "x";
   const trueColour = coloured && typeof stream.hasColors === "function" && stream.hasColors(2 ** 24);
   const word = WORD.map(
-    (line) => trueColour ? gradient(line) : paint("done", line, stream)
+    (line2) => trueColour ? gradient(line2) : paint("done", line2, stream)
   );
   return [
     "",
@@ -1248,7 +1263,7 @@ async function detectGithubSsh(opts) {
     ...opts.interactive ? [] : ["-o", "BatchMode=yes"],
     "git@github.com"
   ];
-  return new Promise((resolve6) => {
+  return new Promise((resolve7) => {
     const child = spawn2(opts.command ?? "ssh", args, {
       stdio: [opts.interactive ? "inherit" : "ignore", "ignore", "pipe"]
     });
@@ -1261,7 +1276,7 @@ async function detectGithubSsh(opts) {
       settled = true;
       clearTimeout(timer);
       child.stderr?.destroy();
-      resolve6(access2);
+      resolve7(access2);
     };
     const timer = setTimeout(() => {
       child.kill("SIGKILL");
@@ -1390,7 +1405,7 @@ function reportError(e) {
 }
 
 // src/version.ts
-var VERSION = "0.8.1";
+var VERSION = "0.9.1";
 
 // src/core/block.ts
 import { createHash } from "crypto";
@@ -1427,9 +1442,9 @@ function renderBlock({
   scope,
   org,
   depth,
-  context
+  context: context2
 }) {
-  const standards = context.collections.find((c) => c.name === "standards")?.files ?? [];
+  const standards = context2.collections.find((c) => c.name === "standards")?.files ?? [];
   const rules = standards.length === 0 ? ["_No standards apply to this scope yet._"] : standards.map(
     (f) => `<!-- rness: standards/${f.rel} -->
 ${toLf(f.content).trim()}`
@@ -1442,8 +1457,8 @@ ${rules.join("\n\n")}`;
   const text = [BEGIN, header(scope, hash), body, END].join("\n");
   return { text, hash, bytes: Buffer.byteLength(text, "utf8") };
 }
-function parseHeader(line) {
-  const m = HEADER.exec(line.trimEnd());
+function parseHeader(line2) {
+  const m = HEADER.exec(line2.trimEnd());
   if (m === null) return null;
   return { version: m[1] ?? null, scope: m[2] ?? "", hash: m[3] ?? "" };
 }
@@ -1614,8 +1629,8 @@ import { join as join8 } from "path";
 function findBlock(lines) {
   const begins = [];
   const ends = [];
-  lines.forEach((line, i) => {
-    const l = line.trimEnd();
+  lines.forEach((line2, i) => {
+    const l = line2.trimEnd();
     if (l === BEGIN) begins.push(i);
     if (l === END) ends.push(i);
   });
@@ -1695,14 +1710,38 @@ var TARGETS = {
   claude: {
     name: "claude",
     label: "Claude Code",
-    file: ".claude/settings.json",
-    // Read the context repository from a repository without a prompt. The
-    // path is resolved against the project directory, and only once Claude
-    // Code has trusted it (verified on 2.1.284, spec 0011 §7).
-    guarantees: [
+    files: [
       {
-        path: ["permissions", "additionalDirectories"],
-        contains: "../../.rness"
+        file: ".claude/settings.json",
+        guarantees: [
+          // Read the context repository from a repository without a prompt.
+          // Resolved against the project directory, and applied once Claude
+          // Code has trusted it (verified on 2.1.284, spec 0011 §7).
+          {
+            path: ["permissions", "additionalDirectories"],
+            contains: "../../.rness"
+          }
+        ]
+      },
+      {
+        file: ".mcp.json",
+        guarantees: [
+          // The pinned copy, by a path relative to the repository — the
+          // directory Claude Code starts the server in (spec 0014 §6). Not
+          // pre-approved in settings: each developer approves it once, since
+          // a repository approving its own command would run any change to
+          // it unasked (spec 0014 §3, 0.9.1).
+          {
+            path: ["mcpServers", "rness"],
+            value: {
+              command: "node",
+              args: [
+                "../../.rness/node_modules/@rness/cli/dist/bin/rness.js",
+                "mcp"
+              ]
+            }
+          }
+        ]
       }
     ]
   }
@@ -1728,7 +1767,7 @@ function parse3(text) {
   }
   return isObject(data) ? { ok: true, data } : { ok: false, reason: "not a JSON object" };
 }
-function listAt(root, g, create) {
+function parentOf(root, g, create) {
   let node = root;
   for (const [i, key] of g.path.slice(0, -1).entries()) {
     const next = node[key];
@@ -1742,17 +1781,32 @@ function listAt(root, g, create) {
       };
     node = node[key];
   }
+  return { kind: "node", node };
+}
+function apply(root, g, create) {
+  const found = parentOf(root, g, create);
+  if (found.kind === "absent") return { holds: false, changed: false };
+  if (found.kind === "invalid") return { invalid: found.reason };
+  const parent = found.node;
   const last = g.path[g.path.length - 1] ?? "";
-  const value = node[last];
+  const value = parent[last];
+  if ("value" in g) {
+    if (value !== void 0) return { holds: true, changed: false };
+    if (!create) return { holds: false, changed: false };
+    parent[last] = structuredClone(g.value);
+    return { holds: true, changed: true };
+  }
   if (value === void 0) {
-    if (!create) return { kind: "absent" };
-    const list = [];
-    node[last] = list;
-    return { kind: "list", list };
+    if (!create) return { holds: false, changed: false };
+    parent[last] = [g.contains];
+    return { holds: true, changed: true };
   }
   if (!Array.isArray(value))
-    return { kind: "invalid", reason: `${g.path.join(".")} is not a list` };
-  return { kind: "list", list: value };
+    return { invalid: `${g.path.join(".")} is not a list` };
+  if (value.includes(g.contains)) return { holds: true, changed: false };
+  if (!create) return { holds: false, changed: false };
+  value.push(g.contains);
+  return { holds: true, changed: true };
 }
 function styleOf(text) {
   const indent = text.split(/\r?\n/).slice(1).map((l) => /^[ \t]+/.exec(l)?.[0]).find((w) => w !== void 0);
@@ -1767,13 +1821,9 @@ function ensureGuarantees(existing, guarantees) {
   if (!parsed.ok) return { kind: "invalid", reason: parsed.reason };
   let changed = false;
   for (const g of guarantees) {
-    const found = listAt(parsed.data, g, true);
-    if (found.kind === "invalid")
-      return { kind: "invalid", reason: found.reason };
-    if (found.kind === "list" && !found.list.includes(g.contains)) {
-      found.list.push(g.contains);
-      changed = true;
-    }
+    const r = apply(parsed.data, g, true);
+    if ("invalid" in r) return { kind: "invalid", reason: r.invalid };
+    changed ||= r.changed;
   }
   if (existing === null)
     return {
@@ -1792,15 +1842,14 @@ function missingGuarantees(existing, guarantees) {
   if (!parsed.ok) return { invalid: parsed.reason };
   const missing = [];
   for (const g of guarantees) {
-    const found = listAt(parsed.data, g, false);
-    if (found.kind === "invalid") return { invalid: found.reason };
-    if (found.kind === "absent" || !found.list.includes(g.contains))
-      missing.push(g);
+    const r = apply(parsed.data, g, false);
+    if ("invalid" in r) return { invalid: r.invalid };
+    if (!r.holds) missing.push(g);
   }
   return missing;
 }
 function describeGuarantee(g) {
-  return `${g.path.join(".")} lacks ${g.contains}`;
+  return "value" in g ? `${g.path.join(".")} is missing` : `${g.path.join(".")} lacks ${g.contains}`;
 }
 
 // src/core/agent-targets.ts
@@ -1809,11 +1858,12 @@ async function filesOf(root, manifest, targets) {
   for (const repo of Object.keys(manifest.repos)) {
     if (!await exists(join9(root, "org", repo))) continue;
     for (const target of targets)
-      files.push({
-        target,
-        file: join9(root, "org", repo, ...target.file.split("/")),
-        label: `org/${repo}/${target.file}`
-      });
+      for (const owned of target.files)
+        files.push({
+          guarantees: owned.guarantees,
+          file: join9(root, "org", repo, ...owned.file.split("/")),
+          label: `org/${repo}/${owned.file}`
+        });
   }
   return files;
 }
@@ -1822,16 +1872,23 @@ function declared(manifest) {
     (name) => Object.hasOwn(TARGETS, name) ? [TARGETS[name]] : []
   );
 }
+var BLOCK_FILES = ["AGENTS.md", "CLAUDE.md"];
+function writtenFiles(manifest) {
+  return [
+    ...BLOCK_FILES,
+    ...declared(manifest).flatMap((t) => t.files.map((f) => f.file))
+  ];
+}
 async function agentTargets(root, manifest, opts) {
   const outcomes = [];
-  for (const { target, file, label } of await filesOf(
+  for (const { guarantees, file, label } of await filesOf(
     root,
     manifest,
     declared(manifest)
   )) {
     const existing = await readOrNull(file);
     if (opts.check) {
-      const missing = missingGuarantees(existing, target.guarantees);
+      const missing = missingGuarantees(existing, guarantees);
       if ("invalid" in missing)
         outcomes.push({ label, status: "invalid", detail: missing.invalid });
       else if (missing.length > 0)
@@ -1843,7 +1900,7 @@ async function agentTargets(root, manifest, opts) {
       else outcomes.push({ label, status: "unchanged", detail: null });
       continue;
     }
-    const ensured = ensureGuarantees(existing, target.guarantees);
+    const ensured = ensureGuarantees(existing, guarantees);
     if (ensured.kind === "invalid") {
       outcomes.push({ label, status: "invalid", detail: ensured.reason });
       continue;
@@ -1865,14 +1922,14 @@ async function leftoverTargets(root, manifest) {
     (t) => !agents.includes(t.name)
   );
   const leftovers = [];
-  for (const { target, file, label } of await filesOf(
+  for (const { guarantees, file, label } of await filesOf(
     root,
     manifest,
     undeclared
   )) {
     const existing = await readOrNull(file);
     if (existing === null) continue;
-    const missing = missingGuarantees(existing, target.guarantees);
+    const missing = missingGuarantees(existing, guarantees);
     if (!("invalid" in missing) && missing.length === 0) leftovers.push(label);
   }
   return leftovers;
@@ -1920,7 +1977,7 @@ async function step(options, work) {
   const rawErr = process.stderr.write.bind(
     process.stderr
   );
-  const guard = (raw) => ((...args) => {
+  const guard2 = (raw) => ((...args) => {
     erase();
     return raw(...args);
   });
@@ -1935,8 +1992,8 @@ async function step(options, work) {
   } else {
     draw("\u2026");
   }
-  stream.write = guard(rawWrite);
-  if (process.stderr !== stream) process.stderr.write = guard(rawErr);
+  stream.write = guard2(rawWrite);
+  if (process.stderr !== stream) process.stderr.write = guard2(rawErr);
   try {
     return await work();
   } finally {
@@ -1983,8 +2040,8 @@ var plainUi = {
       { label: options.doing, animate: options.git !== true },
       work
     );
-    const line = options.quiet === true ? null : done?.(result) ?? null;
-    if (line !== null) this.line(line[0], line[1]);
+    const line2 = options.quiet === true ? null : done?.(result) ?? null;
+    if (line2 !== null) this.line(line2[0], line2[1]);
     return result;
   }
 };
@@ -2017,7 +2074,7 @@ function sessionUi(p) {
       p.log.warn(text);
     },
     note: (title, lines) => {
-      p.note(lines.join("\n"), title, { format: (line) => grey(line) });
+      p.note(lines.join("\n"), title, { format: (line2) => grey(line2) });
     },
     hint: (text) => {
       p.log.message(paint("idle", text));
@@ -2031,20 +2088,20 @@ function sessionUi(p) {
     async step(options, work, done) {
       const label = options.sentence ?? tidy(options.doing);
       const finish2 = (result) => done?.(result) ?? null;
-      const label_ = (line) => `${line[1]} ${line[0]}`;
+      const label_ = (line2) => `${line2[1]} ${line2[0]}`;
       if (options.git === true && !this.gitIsSilent) {
         p.log.message(paint("idle", `${label}\u2026`));
         const result = await work();
-        const line = finish2(result);
-        if (line !== null) say(line[0], label_(line));
+        const line2 = finish2(result);
+        if (line2 !== null) say(line2[0], label_(line2));
         return result;
       }
       const spin = p.spinner();
       spin.start(label);
       try {
         const result = await work();
-        const line = finish2(result);
-        spin.stop(line === null ? label : label_(line));
+        const line2 = finish2(result);
+        spin.stop(line2 === null ? label : label_(line2));
         return result;
       } catch (e) {
         spin.error(`${label} \u2014 failed`);
@@ -2070,7 +2127,6 @@ async function makeUi(terminal) {
 }
 
 // src/commands/sync.ts
-var MANAGED_FILES = ["AGENTS.md", "CLAUDE.md"];
 function targetsOf(manifest, root, only) {
   const targets = [];
   if (only === void 0)
@@ -2260,13 +2316,7 @@ async function syncCommand(opts, deps = {}) {
           }
         } else if (opts.pull === true && !check) {
           try {
-            const written = [
-              ...MANAGED_FILES,
-              ...(manifest.agents ?? []).flatMap(
-                (a) => Object.hasOwn(TARGETS, a) ? [TARGETS[a].file] : []
-              )
-            ];
-            if (!await isClean(dir, written)) {
+            if (!await isClean(dir, writtenFiles(manifest))) {
               lines.push(["skipped", `${label} (working tree not clean)`]);
               continue;
             }
@@ -2309,14 +2359,14 @@ async function syncCommand(opts, deps = {}) {
             continue;
           }
           const [agentsLinked, claudeLinked] = await Promise.all(
-            MANAGED_FILES.map((f) => isSymlink(join10(t.dir, f)))
+            BLOCK_FILES.map((f) => isSymlink(join10(t.dir, f)))
           );
           const atRoot = t.scope === null;
           if (!atRoot && (agentsLinked === true || claudeLinked === true)) {
             lines.push(["skipped", `${t.label} (symlink)`]);
             continue;
           }
-          const context = await assembleContext({
+          const context2 = await assembleContext({
             rnessDir: ws.rnessDir,
             manifest,
             scope: t.scope
@@ -2325,7 +2375,7 @@ async function syncCommand(opts, deps = {}) {
             scope: t.scope,
             org,
             depth: t.depth,
-            context
+            context: context2
           });
           if (block.bytes > BLOCK_SIZE_WARNING) {
             ui.warn(
@@ -3062,10 +3112,10 @@ async function runPinnedSync(root) {
 function summariseSync(stdout) {
   const counts = /* @__PURE__ */ new Map();
   const others = [];
-  for (const line of stdout.split("\n")) {
-    if (line.trim() === "") continue;
-    const verb = /^(updated|unchanged|stale)\s/.exec(line)?.[1];
-    if (verb === void 0) others.push(line);
+  for (const line2 of stdout.split("\n")) {
+    if (line2.trim() === "") continue;
+    const verb = /^(updated|unchanged|stale)\s/.exec(line2)?.[1];
+    if (verb === void 0) others.push(line2);
     else counts.set(verb, (counts.get(verb) ?? 0) + 1);
   }
   const total = [...counts.values()].reduce((a, b) => a + b, 0);
@@ -3177,12 +3227,33 @@ function scaffoldMessage(subject, version) {
 
 ${SCAFFOLD_TRAILER}: ${version}`;
 }
+async function commitUpgrade(rnessDir, message) {
+  const add = await run(rnessDir, ["add", "-A"]);
+  if (add.code !== 0) return { kind: "refused", output: add.stderr.trim() };
+  const staged = await run(rnessDir, ["diff", "--cached", "--quiet"]);
+  if (staged.code === 0 && !await mergeInProgress(rnessDir))
+    return { kind: "nothing" };
+  const commit = await run(rnessDir, ["commit", "-q", "-m", message]);
+  if (commit.code !== 0)
+    return {
+      kind: "refused",
+      output: `${commit.stdout}
+${commit.stderr}`.trim()
+    };
+  return { kind: "committed" };
+}
+async function mergeInProgress(dir) {
+  const r = await run(dir, ["rev-parse", "-q", "--verify", "MERGE_HEAD"]);
+  return r.code === 0;
+}
 async function findScaffoldBase(rnessDir) {
+  const merging = await mergeInProgress(rnessDir);
   const log = await run(rnessDir, [
     "log",
     "--topo-order",
     `--format=%H%x1f%P%x1f%s%x1f%(trailers:key=${SCAFFOLD_TRAILER},valueonly,separator=%x2C)%x1e`,
-    "HEAD"
+    "HEAD",
+    ...merging ? ["MERGE_HEAD"] : []
   ]);
   if (log.code !== 0) return null;
   const commits = log.stdout.split("").map((r) => r.trim()).filter((r) => r !== "").map((r) => {
@@ -3269,8 +3340,8 @@ async function mergeScaffold(rnessDir, commit, base) {
     "--name-status",
     "HEAD"
   ]);
-  for (const line of status2.split("\n")) {
-    const [letter = "", path = ""] = line.split("	");
+  for (const line2 of status2.split("\n")) {
+    const [letter = "", path = ""] = line2.split("	");
     if (path === "" || conflicts.includes(path)) continue;
     if (letter === "A") changes.push(["added", path]);
     else if (letter === "D") changes.push(["removed", path]);
@@ -3413,8 +3484,8 @@ async function syncBlocks(ui, root, shown, inPlace, sshWorks) {
     return 1;
   }
   const outcome = syncOutcome(result, { sshWorks: sshWorks === true });
-  for (const line of outcome.hints) ui.hint(line);
-  for (const line of outcome.errors) ui.error(line);
+  for (const line2 of outcome.hints) ui.hint(line2);
+  for (const line2 of outcome.errors) ui.error(line2);
   return outcome.code;
 }
 
@@ -3519,7 +3590,7 @@ async function createBlank(input) {
         `Workspace \`${name}\` is ready in ${shown}/.`,
         "",
         "Next:",
-        ...next.map((line) => `  ${line}`),
+        ...next.map((line2) => `  ${line2}`),
         ""
       ].join("\n")
     );
@@ -3530,8 +3601,8 @@ async function createBlank(input) {
 function firstLine4(text) {
   return text.split("\n").find((l) => l.trim() !== "")?.trim() ?? "unknown error";
 }
-function splitSpecs(list) {
-  return list.split(",").map((s) => s.trim()).filter((s) => s !== "");
+function splitSpecs(list2) {
+  return list2.split(",").map((s) => s.trim()).filter((s) => s !== "");
 }
 function cancelled(ui) {
   ui.cancelled();
@@ -4162,7 +4233,7 @@ ${next2.map((l) => `  ${l}`).join("\n")}
           `Workspace for \`${org}\` is ready in ${shown}/.`,
           "",
           "Next:",
-          ...next.map((line) => `  ${line}`),
+          ...next.map((line2) => `  ${line2}`),
           ""
         ].join("\n")
       );
@@ -4203,11 +4274,67 @@ async function logoutCommand() {
   }
 }
 
+// src/core/contract.ts
+import { join as join20 } from "path";
+var STATUSES = {
+  adr: ["Proposed", "Accepted", "Rejected", "Superseded"],
+  specs: [
+    "Draft",
+    "Proposed",
+    "Approved",
+    "Implemented",
+    "Superseded",
+    "Rejected"
+  ],
+  plans: ["Draft", "Ready", "In progress", "Blocked", "Completed", "Abandoned"]
+};
+var SKIP = /* @__PURE__ */ new Set(["adr/0000-template.md"]);
+var PLACEMENT_KEYS = ["scopes", "scope"];
+async function checkContract(rnessDir) {
+  const problems = [];
+  for (const name of COLLECTIONS) {
+    const allowed = STATUSES[name];
+    const items = await collectMarkdown(join20(rnessDir, name));
+    for (const item of items) {
+      const where = `${name}/${item.rel}`;
+      if (SKIP.has(where)) continue;
+      if (item.fieldsError !== null) {
+        problems.push(`${where}: invalid front matter (${item.fieldsError})`);
+        continue;
+      }
+      if (item.fields !== null) {
+        for (const key of PLACEMENT_KEYS) {
+          if (Object.hasOwn(item.fields, key)) {
+            problems.push(
+              `${where}: front matter "${key}" is not supported \u2014 the directory decides the scope; move the file`
+            );
+          }
+        }
+      }
+      if (allowed === void 0) continue;
+      if (item.fields === null) {
+        problems.push(`${where}: missing a front-matter block`);
+        continue;
+      }
+      if (item.title === null) problems.push(`${where}: missing a "# " title`);
+      const status2 = item.fields["status"];
+      if (status2 === void 0 || status2 === null || status2 === "") {
+        problems.push(`${where}: missing "status"`);
+      } else if (typeof status2 !== "string" || !allowed.includes(status2)) {
+        problems.push(
+          `${where}: unknown status ${JSON.stringify(status2)} (expected ${allowed.join(", ")})`
+        );
+      }
+    }
+  }
+  return problems;
+}
+
 // src/commands/upgrade.ts
 import { execFile as execFile6 } from "child_process";
 import { mkdtemp as mkdtemp3, readFile as readFile9, rm as rm7 } from "fs/promises";
 import { tmpdir as tmpdir3 } from "os";
-import { basename as basename5, join as join20, relative as relative5 } from "path";
+import { basename as basename5, join as join21, relative as relative5 } from "path";
 import { promisify as promisify6 } from "util";
 var execFileP6 = promisify6(execFile6);
 var NOTES = "https://github.com/rness-dev/rness/tree/main/packages/cli#readme";
@@ -4227,10 +4354,10 @@ async function latestVersion() {
 async function scaffoldFor(version, rnessDir) {
   if (version === VERSION) return { dir: scaffoldDir() };
   const installed = await readPinnedCli(rnessDir);
-  const inside = installed === null ? null : join20(installed.dir, "scaffold");
-  if (installed?.version === version && inside !== null && await exists(join20(inside, "package.json")))
+  const inside = installed === null ? null : join21(installed.dir, "scaffold");
+  if (installed?.version === version && inside !== null && await exists(join21(inside, "package.json")))
     return { dir: inside };
-  const scratch = await mkdtemp3(join20(tmpdir3(), "rness-pack-"));
+  const scratch = await mkdtemp3(join21(tmpdir3(), "rness-pack-"));
   const cleanup = () => rm7(scratch, { recursive: true, force: true });
   try {
     const { stdout } = await execFileP6(
@@ -4245,8 +4372,8 @@ async function scaffoldFor(version, rnessDir) {
       { timeout: 6e4 }
     );
     const tarball = stdout.trim().split("\n").at(-1) ?? "";
-    await execFileP6("tar", ["-xzf", join20(scratch, tarball), "-C", scratch]);
-    return { dir: join20(scratch, "package", "scaffold"), cleanup };
+    await execFileP6("tar", ["-xzf", join21(scratch, tarball), "-C", scratch]);
+    return { dir: join21(scratch, "package", "scaffold"), cleanup };
   } catch (e) {
     await cleanup();
     throw new Error(
@@ -4258,21 +4385,43 @@ async function scaffoldFor(version, rnessDir) {
 async function declaredManager(rnessDir, pm) {
   try {
     const pkg = JSON.parse(
-      await readFile9(join20(rnessDir, "package.json"), "utf8")
+      await readFile9(join21(rnessDir, "package.json"), "utf8")
     );
     if (typeof pkg.packageManager === "string") return pkg.packageManager;
   } catch {
   }
   return `${pm}@${await packageManagerVersion(pm)}`;
 }
-function finish(ui, cwd, rnessDir, label, target) {
+async function clonesToCommit(root, cwd, manifest) {
+  const files = writtenFiles(manifest);
+  const clones = [];
+  for (const repo of Object.keys(manifest.repos)) {
+    const dir = join21(root, "org", repo);
+    if (!await exists(dir)) continue;
+    try {
+      const paths = await changedPaths(dir, files);
+      if (paths.length > 0)
+        clones.push({ dir: relative5(cwd, dir) || ".", paths });
+    } catch {
+    }
+  }
+  return clones;
+}
+function finish(ui, cwd, rnessDir, label, target, ending) {
   const rel = relative5(cwd, rnessDir) || ".";
-  const next = [
-    `git -C ${rel} add -A && git -C ${rel} commit -m "chore: rness ${target}"`,
-    "# teammates: git pull \u2014 the next rness command installs it"
-  ];
+  const message = `chore: rness ${target}`;
+  const next = [];
+  if (ending.commit === "committed") next.push(`git -C ${rel} push`);
+  if (ending.commit === "refused")
+    next.push(`git -C ${rel} commit -m "${message}"`);
+  for (const c of ending.clones)
+    next.push(
+      `git -C ${c.dir} add ${c.paths.join(" ")} && git -C ${c.dir} commit -m "${message}"`
+    );
+  if (ending.commit !== "nothing")
+    next.push("# teammates: git pull \u2014 the next rness command installs it");
   if (ui.session) {
-    ui.note("Next steps", next);
+    if (next.length > 0) ui.note("Next steps", next);
     ui.outro(`${label} runs @rness/cli ${target}`);
   } else
     process.stdout.write(
@@ -4280,12 +4429,10 @@ function finish(ui, cwd, rnessDir, label, target) {
         "",
         status("upgraded", `${label} to @rness/cli ${target}`),
         "",
-        "Next:",
-        ...next.map((line) => `  ${line}`),
-        ""
+        ...next.length > 0 ? ["Next:", ...next.map((line2) => `  ${line2}`), ""] : []
       ].join("\n")
     );
-  return 0;
+  return ending.commit === "refused" ? 1 : 0;
 }
 async function upgradeCommand(version, opts, terminal = defaultTerminal, deps = {}) {
   const cwd = opts.cwd ?? process.cwd();
@@ -4334,6 +4481,13 @@ async function upgradeCommand(version, opts, terminal = defaultTerminal, deps =
 `);
       return 1;
     }
+    if (await mergeInProgress(ws.rnessDir)) {
+      process.stderr.write(
+        `${label} has a merge in progress; commit it, or abort it with git -C ${relative5(cwd, ws.rnessDir) || "."} merge --abort, then ${rnessCommand()} upgrade
+`
+      );
+      return 1;
+    }
     if (!await isClean(ws.rnessDir)) {
       process.stderr.write(
         `${label} has uncommitted changes; commit or stash them, then ${rnessCommand()} upgrade
@@ -4435,62 +4589,85 @@ async function upgradeCommand(version, opts, terminal = defaultTerminal, deps =
         await source.cleanup?.();
       }
     }
-    const packageFile = join20(ws.rnessDir, "package.json");
+    const packageFile = join21(ws.rnessDir, "package.json");
     const restore = /* @__PURE__ */ new Map([
       [packageFile, await readFile9(packageFile, "utf8")]
     ]);
     const moved = await readPin(ws.rnessDir);
     if (moved !== null && moved.spec !== target)
       await writePin(ws.rnessDir, moved.spec, target);
-    if (pin.spec === target && installed === target)
-      return finish(ui, cwd, ws.rnessDir, label, target);
-    try {
-      await ui.step(
-        { doing: `installing dependencies with ${pm}` },
-        () => installDependencies(pm, ws.rnessDir),
-        () => ["installed", `dependencies with ${pm}`]
-      );
-    } catch (e) {
-      const message = e instanceof Error ? e.message : String(e);
-      ui.error(message);
-      if (!merged) {
-        for (const [file, text] of restore) await writeFileAtomic(file, text);
-        ui.hint(
-          `restored ${relative5(cwd, packageFile) || packageFile}`,
-          "stderr"
+    const mustInstall = !(pin.spec === target && installed === target);
+    if (mustInstall) {
+      try {
+        await ui.step(
+          { doing: `installing dependencies with ${pm}` },
+          () => installDependencies(pm, ws.rnessDir),
+          () => ["installed", `dependencies with ${pm}`]
         );
+      } catch (e) {
+        const message2 = e instanceof Error ? e.message : String(e);
+        ui.error(message2);
+        if (!merged) {
+          for (const [file, text] of restore) await writeFileAtomic(file, text);
+          ui.hint(
+            `restored ${relative5(cwd, packageFile) || packageFile}`,
+            "stderr"
+          );
+        }
+        if (merged)
+          ui.hint(
+            `the scaffold merge is still staged; undo it with: git -C ${relative5(cwd, ws.rnessDir) || "."} merge --abort`,
+            "stderr"
+          );
+        if (/minimum.?release.?age|NO_MATURE/i.test(message2))
+          ui.hint(
+            "pnpm refuses versions published less than 24 h ago: add '@rness/cli' under minimumReleaseAgeExclude in .rness/pnpm-workspace.yaml",
+            "stderr"
+          );
+        return 1;
       }
-      if (merged)
-        ui.hint(
-          `the scaffold merge is still staged; undo it with: git -C ${relative5(cwd, ws.rnessDir) || "."} merge --abort`,
-          "stderr"
-        );
-      if (/minimum.?release.?age|NO_MATURE/i.test(message))
-        ui.hint(
-          "pnpm refuses versions published less than 24 h ago: add '@rness/cli' under minimumReleaseAgeExclude in .rness/pnpm-workspace.yaml",
-          "stderr"
-        );
-      return 1;
-    }
-    const now = (await readPinnedCli(ws.rnessDir))?.version ?? null;
-    if (now !== target) {
-      process.stderr.write(
-        `${pm} install left @rness/cli ${now ?? "not installed"} in ${label}, not ${target}
+      const now = (await readPinnedCli(ws.rnessDir))?.version ?? null;
+      if (now !== target) {
+        process.stderr.write(
+          `${pm} install left @rness/cli ${now ?? "not installed"} in ${label}, not ${target}
 `
-      );
-      return 1;
+        );
+        return 1;
+      }
     }
     ui.gitIsSilent = true;
     const code = await syncBlocks(ui, ws.root, basename5(ws.root));
     if (code !== 0) return code;
-    return finish(ui, cwd, ws.rnessDir, label, target);
+    const message = `chore: rness ${target}`;
+    const committed = await commitUpgrade(ws.rnessDir, message);
+    if (committed.kind === "committed")
+      ui.line(
+        "committed",
+        `${label} \u2014 ${message}`,
+        `Committed ${label}: ${message}`
+      );
+    if (committed.kind === "refused") {
+      ui.error(
+        `the commit of ${label} was refused; everything is staged \u2014 deal with what git said, then commit`
+      );
+      for (const line2 of committed.output.split("\n"))
+        if (line2.trim() !== "") ui.hint(line2, "stderr");
+    }
+    return finish(ui, cwd, ws.rnessDir, label, target, {
+      commit: committed.kind,
+      clones: await clonesToCommit(
+        ws.root,
+        cwd,
+        await loadManifest(ws.rnessDir)
+      )
+    });
   } catch (e) {
     return reportError(e);
   }
 }
 
 // src/core/blocks.ts
-import { join as join21 } from "path";
+import { join as join22 } from "path";
 var PROBLEM = /* @__PURE__ */ new Set(["stale", "malformed"]);
 async function checkBlocks({
   root,
@@ -4507,7 +4684,7 @@ async function checkBlocks({
     warnings: checks.filter((c) => !PROBLEM.has(c.status) && c.message !== null).map((c) => c.message),
     checks
   });
-  if (!await exists(join21(root, "org"))) return derive();
+  if (!await exists(join22(root, "org"))) return derive();
   const targets = [
     { scope: null, dir: root, depth: 0, file: "AGENTS.md", label: "AGENTS.md" },
     { scope: null, dir: root, depth: 0, file: "CLAUDE.md", label: "CLAUDE.md" }
@@ -4516,7 +4693,7 @@ async function checkBlocks({
     const segments = entry.path.split("/");
     targets.push({
       scope: name,
-      dir: join21(root, ...segments),
+      dir: join22(root, ...segments),
       depth: segments.length,
       file: "AGENTS.md",
       label: `${entry.path}/AGENTS.md`
@@ -4531,7 +4708,7 @@ async function checkBlocks({
       );
       continue;
     }
-    const text = await readOrNull(join21(t.dir, t.file));
+    const text = await readOrNull(join22(t.dir, t.file));
     const lines = text === null ? [] : text.split(/\r?\n/);
     const found = findBlock(lines);
     if (found.kind === "none") {
@@ -4546,7 +4723,7 @@ async function checkBlocks({
       note(t.label, "malformed", `${t.label}: ${found.message}`);
       continue;
     }
-    const context = await assembleContext({
+    const context2 = await assembleContext({
       rnessDir,
       manifest,
       scope: t.scope
@@ -4555,7 +4732,7 @@ async function checkBlocks({
       scope: t.scope,
       org,
       depth: t.depth,
-      context
+      context: context2
     });
     const pointerLeft = t.file === "CLAUDE.md" && lines.some((l) => l.trim() === "@AGENTS.md");
     if (isCurrentBlock(lines.slice(found.begin, found.end + 1), fresh2.hash) && !pointerLeft)
@@ -4570,62 +4747,6 @@ async function checkBlocks({
   return derive();
 }
 
-// src/core/contract.ts
-import { join as join22 } from "path";
-var STATUSES = {
-  adr: ["Proposed", "Accepted", "Rejected", "Superseded"],
-  specs: [
-    "Draft",
-    "Proposed",
-    "Approved",
-    "Implemented",
-    "Superseded",
-    "Rejected"
-  ],
-  plans: ["Draft", "Ready", "In progress", "Blocked", "Completed", "Abandoned"]
-};
-var SKIP = /* @__PURE__ */ new Set(["adr/0000-template.md"]);
-var PLACEMENT_KEYS = ["scopes", "scope"];
-async function checkContract(rnessDir) {
-  const problems = [];
-  for (const name of COLLECTIONS) {
-    const allowed = STATUSES[name];
-    const items = await collectMarkdown(join22(rnessDir, name));
-    for (const item of items) {
-      const where = `${name}/${item.rel}`;
-      if (SKIP.has(where)) continue;
-      if (item.fieldsError !== null) {
-        problems.push(`${where}: invalid front matter (${item.fieldsError})`);
-        continue;
-      }
-      if (item.fields !== null) {
-        for (const key of PLACEMENT_KEYS) {
-          if (Object.hasOwn(item.fields, key)) {
-            problems.push(
-              `${where}: front matter "${key}" is not supported \u2014 the directory decides the scope; move the file`
-            );
-          }
-        }
-      }
-      if (allowed === void 0) continue;
-      if (item.fields === null) {
-        problems.push(`${where}: missing a front-matter block`);
-        continue;
-      }
-      if (item.title === null) problems.push(`${where}: missing a "# " title`);
-      const status2 = item.fields["status"];
-      if (status2 === void 0 || status2 === null || status2 === "") {
-        problems.push(`${where}: missing "status"`);
-      } else if (typeof status2 !== "string" || !allowed.includes(status2)) {
-        problems.push(
-          `${where}: unknown status ${JSON.stringify(status2)} (expected ${allowed.join(", ")})`
-        );
-      }
-    }
-  }
-  return problems;
-}
-
 // src/commands/validate.ts
 async function validateCommand(opts, deps = {}) {
   const cwd = opts.cwd ?? process.cwd();
@@ -4714,9 +4835,9 @@ async function readStdin() {
 async function gitCredentialCommand(operation, input) {
   if (operation !== "get") return 0;
   const fields = /* @__PURE__ */ new Map();
-  for (const line of (input ?? await readStdin()).split("\n")) {
-    const eq = line.indexOf("=");
-    if (eq > 0) fields.set(line.slice(0, eq), line.slice(eq + 1).trimEnd());
+  for (const line2 of (input ?? await readStdin()).split("\n")) {
+    const eq = line2.indexOf("=");
+    if (eq > 0) fields.set(line2.slice(0, eq), line2.slice(eq + 1).trimEnd());
   }
   if (fields.get("protocol") !== "https" || fields.get("host") !== "github.com")
     return 0;
@@ -4728,6 +4849,409 @@ password=${resolved.token}
   return 0;
 }
 
+// src/commands/mcp.ts
+import { createInterface } from "readline";
+
+// src/mcp/protocol.ts
+var MODERN_VERSIONS = ["2026-07-28"];
+var LEGACY_VERSIONS = [
+  "2025-11-25",
+  "2025-06-18",
+  "2025-03-26",
+  "2024-11-05"
+];
+var SUPPORTED = [...MODERN_VERSIONS, ...LEGACY_VERSIONS];
+var VERSION_KEY = "io.modelcontextprotocol/protocolVersion";
+var CAPABILITIES_KEY = "io.modelcontextprotocol/clientCapabilities";
+var SERVER_INFO_KEY = "io.modelcontextprotocol/serverInfo";
+function isObject2(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function errorLine(id, code, message, data) {
+  return JSON.stringify({
+    jsonrpc: "2.0",
+    id,
+    error: data === void 0 ? { code, message } : { code, message, data }
+  });
+}
+function createProtocol(opts) {
+  const serverInfo = { name: opts.name, version: opts.version };
+  return {
+    async handle(line2) {
+      let message;
+      try {
+        message = JSON.parse(line2);
+      } catch {
+        return errorLine(null, -32700, "Parse error");
+      }
+      const rawId = isObject2(message) ? message["id"] : void 0;
+      const id = typeof rawId === "string" || typeof rawId === "number" ? rawId : null;
+      if (!isObject2(message) || message["jsonrpc"] !== "2.0" || typeof message["method"] !== "string")
+        return errorLine(id, -32600, "Invalid Request");
+      if (!("id" in message)) return null;
+      if (id === null) return errorLine(null, -32600, "Invalid Request");
+      const method = message["method"];
+      const params = isObject2(message["params"]) ? message["params"] : {};
+      const meta = isObject2(params["_meta"]) ? params["_meta"] : null;
+      const modern = meta !== null && typeof meta[VERSION_KEY] === "string";
+      if (modern) {
+        const requested = meta[VERSION_KEY];
+        if (!MODERN_VERSIONS.includes(requested))
+          return errorLine(id, -32022, "Unsupported protocol version", {
+            supported: SUPPORTED,
+            requested
+          });
+        if (!isObject2(meta[CAPABILITIES_KEY]))
+          return errorLine(
+            id,
+            -32602,
+            `Invalid params: ${CAPABILITIES_KEY} is required`
+          );
+      }
+      const answer = (result) => JSON.stringify({
+        jsonrpc: "2.0",
+        id,
+        result: modern ? {
+          resultType: "complete",
+          ...result,
+          _meta: { [SERVER_INFO_KEY]: serverInfo }
+        } : result
+      });
+      switch (method) {
+        case "server/discover":
+          return answer({
+            supportedVersions: SUPPORTED,
+            capabilities: { tools: {} }
+          });
+        case "initialize": {
+          const asked = params["protocolVersion"];
+          const protocolVersion = typeof asked === "string" && LEGACY_VERSIONS.includes(asked) ? asked : LEGACY_VERSIONS[0];
+          return JSON.stringify({
+            jsonrpc: "2.0",
+            id,
+            result: {
+              protocolVersion,
+              capabilities: { tools: {} },
+              serverInfo
+            }
+          });
+        }
+        case "ping":
+          return answer({});
+        case "tools/list":
+          return answer({
+            tools: opts.tools.map((t) => ({
+              name: t.name,
+              title: t.title,
+              description: t.description,
+              inputSchema: t.inputSchema
+            }))
+          });
+        case "tools/call": {
+          const name = params["name"];
+          const tool = opts.tools.find((t) => t.name === name);
+          if (tool === void 0)
+            return errorLine(id, -32602, `Unknown tool: ${String(name)}`);
+          const args = isObject2(params["arguments"]) ? params["arguments"] : {};
+          try {
+            const r = await tool.call(args);
+            return answer({
+              content: [{ type: "text", text: r.text }],
+              isError: r.isError === true
+            });
+          } catch (e) {
+            return answer({
+              content: [
+                {
+                  type: "text",
+                  text: `${tool.name} failed: ${e instanceof Error ? e.message : String(e)}`
+                }
+              ],
+              isError: true
+            });
+          }
+        }
+        default:
+          return errorLine(id, -32601, "Method not found");
+      }
+    }
+  };
+}
+
+// src/mcp/tools.ts
+import { readFile as readFile10, realpath as realpath3, stat as stat4 } from "fs/promises";
+import { isAbsolute, join as join23, posix as posix4, relative as relative6, resolve as resolve6, sep as sep4 } from "path";
+var LABELS = {
+  standards: "Standards",
+  adr: "Decisions",
+  specs: "Specifications",
+  plans: "Plans",
+  skills: "Skills"
+};
+var TEMPLATE = "adr/0000-template.md";
+var READ_LIMIT = 256 * 1024;
+var SEARCH_LIMIT = 20;
+var LINES_PER_HIT = 3;
+var LINE_WIDTH = 200;
+var refuse = (text) => ({ text, isError: true });
+async function guard(run3) {
+  try {
+    return await run3();
+  } catch (e) {
+    return refuse(e instanceof Error ? e.message : String(e));
+  }
+}
+async function workspaceAt(cwd) {
+  const ws = await findWorkspace(cwd);
+  return { ws, manifest: await loadManifest(ws.rnessDir) };
+}
+function titleOf(heading, id) {
+  if (id === null) return heading;
+  const rest = new RegExp(`^${id}\\s*[\u2014\u2013:-]\\s*(.+)$`).exec(heading)?.[1];
+  return rest ?? heading;
+}
+async function documents(rnessDir, only) {
+  const docs = [];
+  for (const collection of COLLECTIONS) {
+    if (only !== void 0 && collection !== only) continue;
+    for (const item of await collectMarkdown(join23(rnessDir, collection))) {
+      const path = `${collection}/${item.rel}`;
+      if (path === TEMPLATE) continue;
+      const status2 = item.fields?.["status"];
+      const id = /^(\d{4})-/.exec(posix4.basename(item.rel))?.[1] ?? null;
+      docs.push({
+        collection,
+        path,
+        scope: ownerScope(item.rel),
+        id,
+        status: typeof status2 === "string" ? status2 : null,
+        title: titleOf(item.title ?? posix4.basename(item.rel, ".md"), id),
+        text: item.body
+      });
+    }
+  }
+  return docs;
+}
+function line(d, withScope = false) {
+  const head = [d.id, d.status].filter((x) => x !== null).join(" ");
+  return `- ${head === "" ? "" : `${head} \u2014 `}${d.title}${withScope ? ` \u2014 ${d.scope ?? "global"}` : ""} \u2014 ${d.path}`;
+}
+function isCollection(value) {
+  return COLLECTIONS.includes(value);
+}
+var collectionError = (value) => refuse(
+  `unknown collection ${JSON.stringify(value)}; one of ${COLLECTIONS.join(", ")}`
+);
+async function context(cwd, args) {
+  const { ws, manifest } = await workspaceAt(cwd);
+  let scope;
+  if (args["scope"] !== void 0) {
+    const known = Object.keys(manifest.scopes).sort();
+    if (typeof args["scope"] !== "string" || !Object.hasOwn(manifest.scopes, args["scope"]))
+      return refuse(
+        `unknown scope ${JSON.stringify(args["scope"])}; known: ${known.length === 0 ? "none" : known.join(", ")}`
+      );
+    scope = args["scope"];
+  } else
+    scope = resolveScope(
+      manifest,
+      relative6(ws.root, cwd).split(sep4).join(posix4.sep)
+    );
+  const entry = scope === null ? void 0 : manifest.scopes[scope];
+  const where = scope === null || entry === void 0 ? "global scope" : `scope ${scope} (${entry.path}${entry.extends.length > 0 ? `, extends ${entry.extends.join(", ")}` : ""})`;
+  const ctx = await assembleContext({ rnessDir: ws.rnessDir, manifest, scope });
+  const index = new Map(
+    (await documents(ws.rnessDir)).map((d) => [d.path, d])
+  );
+  const out = [`Workspace ${workspaceName(manifest, ws.root)} \xB7 ${where}`];
+  for (const collection of ctx.collections) {
+    const docs = collection.files.map((f) => index.get(`${collection.name}/${f.rel}`)).filter((d) => d !== void 0);
+    if (docs.length === 0) continue;
+    out.push(`${LABELS[collection.name]} (${docs.length}):`);
+    for (const d of docs) out.push(line(d));
+  }
+  out.push("Read one with rness_read; search with rness_search.");
+  return { text: out.join("\n") };
+}
+async function list(cwd, args) {
+  const { ws } = await workspaceAt(cwd);
+  const collection = args["collection"];
+  if (!isCollection(collection)) return collectionError(collection);
+  const status2 = args["status"];
+  const allowed = STATUSES[collection];
+  if (status2 !== void 0) {
+    if (allowed === void 0)
+      return refuse(`${collection} have no status to filter on`);
+    if (typeof status2 !== "string" || !allowed.includes(status2))
+      return refuse(
+        `unknown status ${JSON.stringify(status2)} for ${collection}; one of ${allowed.join(", ")}`
+      );
+  }
+  const docs = (await documents(ws.rnessDir, collection)).filter(
+    (d) => status2 === void 0 || d.status === status2
+  );
+  if (docs.length === 0)
+    return {
+      text: `No document in ${collection}${status2 === void 0 ? "" : ` with status ${String(status2)}`}.`
+    };
+  return {
+    text: [
+      `${LABELS[collection]} (${docs.length}):`,
+      ...docs.map((d) => line(d, true))
+    ].join("\n")
+  };
+}
+async function read(cwd, args) {
+  const { ws } = await workspaceAt(cwd);
+  const path = args["path"];
+  if (typeof path !== "string" || path.trim() === "")
+    return refuse("path is required, relative to .rness/");
+  const segments = path.split(/[\\/]/);
+  if (isAbsolute(path) || segments.includes("..") || segments[0] === ".git" || segments.includes("node_modules"))
+    return refuse(
+      `${path}: not a document of .rness/ (a relative path, no "..", nothing under .git/ or node_modules/)`
+    );
+  const root = await realpath3(ws.rnessDir);
+  let real;
+  try {
+    real = await realpath3(resolve6(ws.rnessDir, path));
+  } catch {
+    return refuse(`${path}: no such file in .rness/`);
+  }
+  if (!real.startsWith(`${root}${sep4}`))
+    return refuse(`${path}: leads outside .rness/`);
+  const info = await stat4(real);
+  if (!info.isFile()) return refuse(`${path}: not a file`);
+  if (info.size > READ_LIMIT)
+    return refuse(
+      `${path}: ${info.size} bytes, over the 256 KiB rness_read returns`
+    );
+  return { text: await readFile10(real, "utf8") };
+}
+async function search(cwd, args) {
+  const { ws } = await workspaceAt(cwd);
+  const query = args["query"];
+  if (typeof query !== "string" || query.trim() === "")
+    return refuse("query is required");
+  const collection = args["collection"];
+  if (collection !== void 0 && !isCollection(collection))
+    return collectionError(collection);
+  const needle = query.toLowerCase();
+  const hits = (await documents(ws.rnessDir, collection)).map((d) => ({
+    d,
+    lines: d.text.split(/\r?\n/).map((text, i) => ({ n: i + 1, text })).filter((l) => l.text.toLowerCase().includes(needle))
+  })).filter((h) => h.lines.length > 0).sort(
+    (a, b) => b.lines.length - a.lines.length || a.d.path.localeCompare(b.d.path)
+  );
+  if (hits.length === 0)
+    return { text: `No document matches ${JSON.stringify(query)}.` };
+  const shown = hits.slice(0, SEARCH_LIMIT);
+  const out = [
+    `${hits.length} document${hits.length === 1 ? "" : "s"} match${hits.length === 1 ? "es" : ""} ${JSON.stringify(query)}${hits.length > SEARCH_LIMIT ? ` (the ${SEARCH_LIMIT} most matching)` : ""}`
+  ];
+  for (const h of shown) {
+    out.push(line(h.d, true));
+    for (const l of h.lines.slice(0, LINES_PER_HIT))
+      out.push(`  ${l.n}: ${l.text.trim().slice(0, LINE_WIDTH)}`);
+  }
+  return { text: out.join("\n") };
+}
+var collectionProperty = {
+  type: "string",
+  enum: [...COLLECTIONS],
+  description: "standards (rules), adr (decisions), specs (specifications), plans, skills"
+};
+function mcpTools(cwd) {
+  return [
+    {
+      name: "rness_context",
+      title: "rness: what applies here",
+      description: "The rness scope of the current repository (or the one named) and what applies to it: the standards, decisions (ADRs), specifications and plans of that scope and of the scopes it extends \u2014 ids, statuses, titles and paths, no bodies. Start here, then read a document with rness_read.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          scope: {
+            type: "string",
+            description: "A scope of rness.json; default: the one owning the working directory"
+          }
+        },
+        additionalProperties: false
+      },
+      call: (args) => guard(() => context(cwd, args))
+    },
+    {
+      name: "rness_list",
+      title: "rness: a collection",
+      description: "Every document of one collection of .rness/, across all scopes, with id, status, title, scope and path; optionally only those with a given status (for example the Accepted decisions).",
+      inputSchema: {
+        type: "object",
+        properties: {
+          collection: collectionProperty,
+          status: {
+            type: "string",
+            description: "adr: Proposed, Accepted, Rejected, Superseded; specs: Draft, Proposed, Approved, Implemented, Superseded, Rejected; plans: Draft, Ready, In progress, Blocked, Completed, Abandoned"
+          }
+        },
+        required: ["collection"],
+        additionalProperties: false
+      },
+      call: (args) => guard(() => list(cwd, args))
+    },
+    {
+      name: "rness_read",
+      title: "rness: read a document",
+      description: "One file of .rness/ as it is, by its path relative to .rness/ (as rness_context, rness_list and rness_search give it). Nothing outside .rness/.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          path: {
+            type: "string",
+            description: "For example adr/0006-workspace.md"
+          }
+        },
+        required: ["path"],
+        additionalProperties: false
+      },
+      call: (args) => guard(() => read(cwd, args))
+    },
+    {
+      name: "rness_search",
+      title: "rness: search the context",
+      description: "Where a subject is decided, specified or planned: a case-insensitive search of the documents of .rness/, most matching first, with the matching lines.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "Text to find" },
+          collection: collectionProperty
+        },
+        required: ["query"],
+        additionalProperties: false
+      },
+      call: (args) => guard(() => search(cwd, args))
+    }
+  ];
+}
+
+// src/commands/mcp.ts
+async function mcpCommand(opts, io = {
+  input: process.stdin,
+  output: process.stdout
+}) {
+  const protocol = createProtocol({
+    name: "rness",
+    version: VERSION,
+    tools: mcpTools(opts.cwd ?? process.cwd())
+  });
+  const lines = createInterface({ input: io.input, crlfDelay: Infinity });
+  for await (const line2 of lines) {
+    if (line2.trim() === "") continue;
+    const answer = await protocol.handle(line2);
+    if (answer !== null) io.output.write(`${answer}
+`);
+  }
+  return 0;
+}
+
 // src/cli.ts
 function buildProgram(state) {
   const program = new Command().name("rness").description("Configuration-plane CLI for rness workspaces").version(VERSION, "-v, --version", "print the version").exitOverride().showHelpAfterError().configureOutput({
@@ -4772,6 +5296,11 @@ function buildProgram(state) {
   ).option("-y, --yes", "do not ask for confirmation").addOption(new Option("--cwd <dir>").hideHelp()).action(async (opts) => {
     state.code = await syncCommand(opts);
   });
+  program.command("mcp").description(
+    "Serve the workspace context to agents over MCP (stdio, read-only)"
+  ).addOption(new Option("--cwd <dir>").hideHelp()).action(async (opts) => {
+    state.code = await mcpCommand(opts);
+  });
   program.command("add").description(
     "Clone (or adopt) a repository under org/ and declare it in rness.json"
   ).argument("<repo>", "<repo>, <owner>/<repo>, or a clone URL").option(
@@ -4965,13 +5494,13 @@ export {
   loginCommand,
   createCommand,
   logoutCommand,
-  upgradeCommand,
-  checkBlocks,
   STATUSES,
   checkContract,
+  upgradeCommand,
+  checkBlocks,
   validateCommand,
   run2 as run,
   OWN_COMMANDS,
   catchUp
 };
-//# sourceMappingURL=chunk-ONLF4VFA.js.map
+//# sourceMappingURL=chunk-N3F6N6GA.js.map