@oevery/rsp 3.3.0 → 4.1.0

package/README.md

@@ -4,31 +4,30 @@ English | [简体中文](./README.zh-CN.md)
 
 **A repository-native engineering workflow for humans and AI agents.**
 
-RSP turns unclear intent into shaped, implemented, reviewed, and verified software changes while keeping project knowledge durable and work recoverable. It uses ordinary repository files—Rules, Specs, and Plans—rather than hidden workflow state.
+RSP turns unclear intent into shaped, implemented, reviewed, and verified software changes while keeping project knowledge durable and work recoverable. It uses ordinary repository files—Skills, Specs, and Plans—rather than hidden workflow state.
 
 ## What RSP helps you do
 
 - Shape ambiguous work into an executable Change.
 - Resolve design questions from repository evidence before implementation.
-- Route diagnosis, implementation, TDD, review, and release work to explicit capabilities.
+- Route diagnosis, implementation, risk-selected test-first work, review, and release work to explicit capabilities.
 - Preserve current facts, lasting rationale, scoped instructions, and completed history in the right owners.
 - Keep authority visible: RSP never infers permission to commit, publish, deploy, or approve work.
 
-```text
-intent → shape → design when needed → diagnose | TDD | implement
-       → review → durable review → archive
-```
+RSP selects the next responsibility from the task and evidence, not a fixed stage pipeline. A settled authorized task can proceed directly to implementation and its own checks; design, review, coordination and lifecycle closeout apply only when needed and permitted.
 
 ## Five-minute start
 
-RSP requires Node.js 22 (`>=22`). Use the current stable release:
+RSP requires Node.js 22 (`>=22`). Run setup from the target project root. For a new project, resolve a stable version once and keep that exact selection. Existing projects use the version in `.rsp/version` and the generated AGENTS entry, not a fresh `latest` resolution. Later `rsp` examples denote that exact invocation or a verified matching executable:
 
 ```bash
-npx -y @oevery/rsp@latest init --with-project-setup
+npm view @oevery/rsp dist-tags.latest
+# Replace <version> with the inspected exact version.
+RSP_VERSION='<version>'
+npx -y @oevery/rsp@"$RSP_VERSION" init --with-project-setup
 # fill .rsp/changes/project-setup.md
 # fill .rsp/specs/design.md
-npx -y @oevery/rsp@latest doctor
-npx -y @oevery/rsp@latest status --json
+npx -y @oevery/rsp@"$RSP_VERSION" status
 ```
 
 Then create and focus one tracked change:
@@ -36,10 +35,12 @@ Then create and focus one tracked change:
 ```bash
 rsp create improve-login "Make login failures actionable"
 rsp focus improve-login
-rsp show --focused
+rsp show improve-login
 ```
 
-Follow the nearest `AGENTS.md`, edit the focused Change as work progresses, run fresh project checks, make the durable-update decision, and archive only after acceptance is satisfied.
+Focus is a set: the setup Change may still be focused alongside improve-login. Use the explicit name to inspect it; show --focused requires exactly one marker.
+
+Confirm that `status` shows the expected work; use read-only `doctor` when diagnosing setup. These are deterministic observations, not semantic acceptance. Follow the nearest `AGENTS.md`, keep the selected Change current and establish applicable required verification, reusing traceable passing evidence when its tested boundary and relevant inputs still apply. Before authorized archive, decide necessary knowledge updates, converge the whole Change and check current readiness.
 
 [Read the full getting-started guide](./docs/site/en/getting-started.md).
 
@@ -47,8 +48,8 @@ Follow the nearest `AGENTS.md`, edit the focused Change as work progresses, run
 
 ```text
 .rsp/
-├── rsp-rules.md       # minimal fallback protocol
-├── specs/             # durable current facts
+├── version            # exact CLI package selection
+├── specs/             # current contracts, boundaries, and constraints
 ├── changes/           # open work
 ├── focus.d/           # markers selecting work; optional short recovery capsules
 └── archives/          # completed history
@@ -65,8 +66,12 @@ A Change is one Markdown file with canonical Proposal, Spec, Design, Tasks, Veri
 - [Configuration reference](./docs/site/en/reference/configuration.md)
 - [CLI reference](./docs/site/en/reference/cli.md)
 - [3.0 migration guide](./docs/migrations/3.0.md) and [3.1 migration guide](./docs/migrations/3.1.md)
-- [Release notes](./docs/releases/3.3.0.md)
-- [Design philosophy](./docs/maintainers/design-philosophy.md) and [maintainer upstream research](./docs/maintainers/upstreams.md)
+- [4.0 migration guide](./docs/migrations/pinned-skills.md)
+- [Changelog](./CHANGELOG.md)
+- [Maintainer tests and Skill validation](./tests/README.md)
+- [Maintainer workflows, publication and documentation recovery](./docs/site/en/contributing.md)
+- [Repository context and contract navigation](./CONTEXT.md)
+- [Authoritative architecture and Specs](./.rsp/specs/design.md) and [maintainer research](./research/README.md)
 
 Run the documentation locally:
 
@@ -80,6 +85,8 @@ The site is only a presentation layer over the Markdown in this repository. It a
 
 ## Platform support
 
-RSP is a tool-agnostic file convention and works with any assistant or editor that can read project files. Humans start here; agents follow the nearest `AGENTS.md`, load `skills/rsp/SKILL.md` when available, and use `.rsp/rsp-rules.md` only when the Skill is unavailable.
+RSP is a tool-agnostic file convention and works with any assistant or editor that can read project files. Humans start here; agents follow the nearest `AGENTS.md`, load the required project Core through host Skill discovery or `.agents/skills/rsp/SKILL.md`. Missing required Skills stop dependent work; there is no Rules fallback. Root `skills/` contains authored sources in the RSP repository, not the consumer installation entry.
+
+RSP 4.0 uses `init` for a complete setup and the selected target CLI's `update` for the complete environment. It pins exact versions and retires Rules and separate Skill installation; existing projects must follow the [4.0 migration guide](docs/migrations/pinned-skills.md). The seven core Skills remain independently invocable; see [Skill ownership](docs/site/en/guides/skills.md).
 
 RSP is licensed under the [MIT License](./LICENSE).

package/README.zh-CN.md

@@ -4,31 +4,30 @@
 
 **面向人类与 AI 智能体的仓库原生工程工作流。**
 
-RSP 把模糊意图转化为经过塑造、实现、审查和验证的软件变更，同时让项目知识可持久化、工作可恢复。它使用普通仓库文件——规则、规格和计划——而不是隐藏的工作流状态。
+RSP 把模糊意图转化为经过塑造、实现、审查和验证的软件变更，同时让项目知识可持久化、工作可恢复。它使用普通仓库文件——Skills、规格和计划——而不是隐藏的工作流状态。
 
 ## RSP 帮助你完成什么
 
 - 把模糊工作塑造成一个可执行 Change。
 - 在实现前根据仓库证据解决设计问题。
-- 把诊断、实现、TDD、审查和发布工作路由给明确的能力。
+- 把诊断、实现、按风险选择的测试先行、审查和发布工作路由给明确的能力。
 - 把当前事实、长期理由、作用域指令和完成历史保存在正确的归属位置。
 - 保持权限可见：RSP 不会推断提交、发布、部署或批准权限。
 
-```text
-意图 → 塑造 → 必要时设计 → 诊断 | TDD | 实现
-     → 审查 → 持久化审查 → 归档
-```
+RSP 根据任务与证据选择下一项职责，不采用固定阶段流水线。已经明确且获授权的任务可以直接实现并完成自身检查；设计、审查、协调和生命周期收尾仅在需要且权限允许时执行。
 
 ## 五分钟入门
 
-RSP 需要 Node.js 22（`>=22`）。使用当前稳定版本：
+RSP 需要 Node.js 22（`>=22`），从目标项目根目录执行初始化。新项目只解析一次稳定版本，后续始终使用同一精确版本；已有项目使用 `.rsp/version` 和 AGENTS 中记录的版本，不重新解析 `latest`。后续 `rsp` 表示该精确调用或已核验版本一致的可执行文件：
 
 ```bash
-npx -y @oevery/rsp@latest init --with-project-setup
+npm view @oevery/rsp dist-tags.latest
+# 把 <version> 替换为已检查的精确版本。
+RSP_VERSION='<version>'
+npx -y @oevery/rsp@"$RSP_VERSION" init --with-project-setup
 # 填写 .rsp/changes/project-setup.md
 # 填写 .rsp/specs/design.md
-npx -y @oevery/rsp@latest doctor
-npx -y @oevery/rsp@latest status --json
+npx -y @oevery/rsp@"$RSP_VERSION" status
 ```
 
 然后创建并聚焦一个受跟踪变更：
@@ -36,10 +35,12 @@ npx -y @oevery/rsp@latest status --json
 ```bash
 rsp create improve-login "让登录失败信息可供用户采取行动"
 rsp focus improve-login
-rsp show --focused
+rsp show improve-login
 ```
 
-遵循最近的 `AGENTS.md`，在工作推进时同步当前聚焦的 Change，运行最新的项目检查，判断是否需要持久化更新，并仅在满足验收条件后归档。
+Focus 是一个集合：project-setup 和 improve-login 可以同时聚焦。使用明确名称查看目标；show --focused 要求恰好一个标记。
+
+确认 `doctor` 显示预期的项目设置，`status` 显示预期工作；这些是确定性观察，不是语义验收。遵循最近的 `AGENTS.md`，保持选中的 Change 与实际结果同步，并建立适用的必需验证：被测边界和相关输入仍然适用时，复用可追溯的通过证据。授权归档前，判断必要的知识更新，收敛整个 Change，再检查当前就绪状态。
 
 [阅读完整入门指南](./docs/site/zh-CN/getting-started.md)。
 
@@ -47,10 +48,10 @@ rsp show --focused
 
 ```text
 .rsp/
-├── rsp-rules.md       # 最小后备协议
-├── specs/             # 持久化的当前事实
+├── version            # 精确的 CLI 软件包版本
+├── specs/             # 当前契约、边界与必要约束
 ├── changes/           # 未完成工作
-├── focus.d/           # 选择当前工作的空标记文件
+├── focus.d/           # 工作选择标记；可附短恢复胶囊
 └── archives/          # 已完成历史
 ```
 
@@ -65,8 +66,12 @@ rsp show --focused
 - [配置参考](./docs/site/zh-CN/reference/configuration.md)
 - [CLI 参考](./docs/site/zh-CN/reference/cli.md)
 - [3.0 迁移指南](./docs/migrations/3.0.md)与 [3.1 迁移指南](./docs/migrations/3.1.md)
-- [发布说明](./docs/releases/3.3.0.md)
-- [设计哲学](./docs/maintainers/design-philosophy.md)与[维护者上游研究](./docs/maintainers/upstreams.md)
+- [4.0 迁移指南](./docs/migrations/pinned-skills.md)
+- [变更日志](./CHANGELOG.md)
+- [维护者测试与 Skill 验证](./tests/README.md)
+- [维护工作流、发布与文档恢复](./docs/site/zh-CN/contributing.md)
+- [仓库上下文与契约导航](./CONTEXT.md)
+- [权威架构与 Specs](./.rsp/specs/design.md)及[维护者研究](./research/README.md)
 
 在本地运行文档：
 
@@ -80,6 +85,8 @@ pnpm docs:build
 
 ## 平台支持
 
-RSP 是与工具无关的文件约定，适用于任何能读取项目文件的助手或编辑器。人类从这里开始；AI 智能体遵循最近的 `AGENTS.md`，优先加载 `skills/rsp/SKILL.md`，仅在 Skill 不可用时使用 `.rsp/rsp-rules.md` 后备协议。
+RSP 是与工具无关的文件约定，适用于任何能读取项目文件的助手或编辑器。人类从这里开始；AI 智能体遵循最近的 `AGENTS.md`，通过宿主 Skill discovery 或 `.agents/skills/rsp/SKILL.md` 加载必需的项目 Core。缺少必需 Skill 时停止依赖工作，不再使用 Rules 后备协议。根目录 `skills/` 是 RSP 仓库中的分发源码，不是消费者的安装入口。
+
+RSP 4.0 用 `init` 完成接入，用选定目标 CLI 的 `update` 一次更新完整环境；固定精确版本，退役 Rules 与独立 Skill 安装流程。已有项目须先阅读 [4.0 迁移指南](docs/migrations/pinned-skills.md)。七个核心 Skills 仍可独立调用，职责见 [Skills 指南](docs/site/zh-CN/guides/skills.md)。
 
 RSP 使用 [MIT 许可证](./LICENSE)。

package/dist/chunk-JO6NDJM4.mjs

@@ -0,0 +1,360 @@
+#!/usr/bin/env node
+import {
+  readCurrentDocument
+} from "./chunk-LGDCIQYL.mjs";
+import {
+  PKG_ROOT,
+  RSP_DIR,
+  getVersion,
+  inspectManagedDirectory,
+  inspectManagedFile,
+  inspectRspConfig,
+  markdownText,
+  parseMarkdown,
+  walkMarkdown
+} from "./chunk-P3KO3GZW.mjs";
+
+// src/architecture/model.ts
+import { createHash } from "crypto";
+import { realpath } from "fs/promises";
+import { isAbsolute, relative, resolve } from "path";
+
+// src/architecture/selection.ts
+function selectArchitecture(model, selection) {
+  const selected = new Set(model.nodes.map((node) => node.id));
+  if (selection.kind === "focus") {
+    if (!selected.has(selection.id))
+      throw new Error(`Unknown architecture node: ${selection.id}`);
+    selected.clear();
+    selected.add(selection.id);
+  }
+  if (selection.kind === "node") {
+    if (!selected.has(selection.id))
+      throw new Error(`Unknown architecture node: ${selection.id}`);
+    selected.clear();
+    selected.add(selection.id);
+    let added = true;
+    while (added) {
+      added = false;
+      for (const node of model.nodes) {
+        if (node.parent && selected.has(node.parent) && !selected.has(node.id)) {
+          selected.add(node.id);
+          added = true;
+        }
+      }
+    }
+  }
+  if (selection.kind === "view") {
+    const view = model.views.find((view2) => view2.id === selection.id);
+    if (!view)
+      throw new Error(`Unknown architecture view: ${selection.id}`);
+    selected.clear();
+    view.include.forEach((id) => selected.add(id));
+  }
+  const relations = model.relations.filter((edge) => selected.has(edge.source) || selected.has(edge.target));
+  const visible = /* @__PURE__ */ new Set([...selected, ...relations.flatMap((edge) => [edge.source, edge.target])]);
+  return { selected, visible, relations };
+}
+
+// src/architecture/model.ts
+var ARCHITECTURE_FILE = ".rsp/architecture.json";
+var MAX_CONTENT_BYTES = 16 * 1024 * 1024;
+var digest = (value) => createHash("sha256").update(value).digest("hex");
+function projectPath(file) {
+  if (!file || isAbsolute(file) || file.includes("\\") || file.split("/").some((part) => !part || part === "." || part === "..") || file.includes("\0"))
+    throw new Error(`Unsafe project-relative path: ${file}`);
+  if (file.split("/").some((part) => part === ".git" || part === "node_modules"))
+    throw new Error(`Private/runtime path is not readable: ${file}`);
+  return file;
+}
+async function readProjectFile(root, file) {
+  projectPath(file);
+  return (await readCurrentDocument(resolve(root, file), root, file, MAX_CONTENT_BYTES)).content;
+}
+function object(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("Architecture entries must be objects");
+  return value;
+}
+function text(value, field) {
+  if (typeof value !== "string" || !value.trim())
+    throw new Error(`Architecture ${field} must be a non-empty string`);
+  return value;
+}
+function strings(value, field) {
+  if (!Array.isArray(value))
+    throw new Error(`Architecture ${field} must be an array`);
+  return value.map((item) => text(item, field));
+}
+function collection(value, field) {
+  if (!Array.isArray(value))
+    throw new Error(`Architecture ${field} must be an array`);
+  return value.map(object);
+}
+function unique(items, field) {
+  if (new Set(items.map((item) => item.id)).size !== items.length)
+    throw new Error(`Duplicate architecture ${field} identity`);
+}
+function parseArchitecture(content) {
+  const value = object(JSON.parse(content));
+  if (value.schemaVersion !== 1)
+    throw new Error(`Unsupported architecture schemaVersion: ${String(value.schemaVersion)}`);
+  const nodes = collection(value.nodes, "nodes").map((node) => ({ id: text(node.id, "node.id"), title: text(node.title, "node.title"), description: text(node.description, "node.description"), ...node.parent === void 0 ? {} : { parent: text(node.parent, "node.parent") } }));
+  const relations = collection(value.relations, "relations").map((edge) => ({ id: text(edge.id, "relation.id"), source: text(edge.source, "relation.source"), target: text(edge.target, "relation.target"), type: text(edge.type, "relation.type"), description: text(edge.description, "relation.description") }));
+  const views = collection(value.views, "views").map((view) => ({ id: text(view.id, "view.id"), title: text(view.title, "view.title"), node: text(view.node, "view.node"), include: strings(view.include, "view.include") }));
+  const bindings = collection(value.bindings, "bindings").map((binding) => {
+    const file = projectPath(text(binding.file, "binding.file"));
+    if (!/\.md$/i.test(file))
+      throw new Error("Architecture bindings must reference Markdown files");
+    const scope = binding.scope ?? "node";
+    if (scope !== "node" && scope !== "subtree")
+      throw new Error("Architecture binding.scope must be node or subtree");
+    const headings = binding.headings === void 0 ? void 0 : strings(binding.headings, "binding.headings");
+    if (headings?.length === 0)
+      throw new Error("Omit headings for a whole-file binding");
+    return { node: text(binding.node, "binding.node"), file, ...headings ? { headings } : {}, scope };
+  });
+  unique(nodes, "node");
+  unique(relations, "relation");
+  unique(views, "view");
+  const ids = new Set(nodes.map((node) => node.id));
+  const requireNode = (id) => {
+    if (!ids.has(id))
+      throw new Error(`Missing architecture node: ${id}`);
+  };
+  for (const node of nodes) {
+    const visited = /* @__PURE__ */ new Set([node.id]);
+    let parent = node.parent;
+    while (parent !== void 0) {
+      requireNode(parent);
+      if (visited.has(parent))
+        throw new Error(`Architecture hierarchy cycle: ${parent}`);
+      visited.add(parent);
+      parent = nodes.find((node2) => node2.id === parent).parent;
+    }
+  }
+  relations.forEach((edge) => {
+    requireNode(edge.source);
+    requireNode(edge.target);
+  });
+  views.forEach((view) => {
+    requireNode(view.node);
+    view.include.forEach(requireNode);
+  });
+  bindings.forEach((binding) => requireNode(binding.node));
+  return { schemaVersion: 1, nodes, relations, views, bindings };
+}
+function documentHeadings(content) {
+  const result = [];
+  const stack = [];
+  const counts = /* @__PURE__ */ new Map();
+  const anchors = /* @__PURE__ */ new Set();
+  walkMarkdown(parseMarkdown(content).root, (node) => {
+    if (node.type !== "heading")
+      return;
+    const title = markdownText(node);
+    while (stack.length && stack.at(-1).depth >= node.depth) stack.pop();
+    stack.push({ title, depth: node.depth });
+    const base = title.toLowerCase().replace(/[^\p{L}\p{N}\s_-]/gu, "").replace(/\s/g, "-") || "section";
+    let count = counts.get(base) ?? 0;
+    let anchor = count ? `${base}-${count}` : base;
+    while (anchors.has(anchor)) anchor = `${base}-${++count}`;
+    counts.set(base, count + 1);
+    anchors.add(anchor);
+    result.push({ title, depth: node.depth, anchor, hierarchy: stack.map((item) => item.title) });
+  });
+  return result;
+}
+function resolveHeading(headings, hierarchy) {
+  const matches = headings.filter((heading) => hierarchy.length <= heading.hierarchy.length && hierarchy.every((title, i) => title === heading.hierarchy[heading.hierarchy.length - hierarchy.length + i]));
+  if (matches.length !== 1)
+    throw new Error(`${matches.length ? "Ambiguous" : "Missing"} chapter: ${hierarchy.join(" > ")}`);
+  return matches[0];
+}
+async function queryArchitecture(options = {}) {
+  if (options.node !== void 0 && !options.node.trim())
+    throw new Error("--node requires a non-empty ID");
+  if (options.view !== void 0 && !options.view.trim())
+    throw new Error("--view requires a non-empty ID");
+  if (options.node && options.view)
+    throw new Error("--node and --view are mutually exclusive");
+  const root = await realpath(resolve(options.root ?? process.cwd()));
+  const config = await inspectRspConfig(root);
+  if (config.issues.length)
+    throw new Error(config.issues.join("; "));
+  let content;
+  try {
+    content = await readProjectFile(root, ARCHITECTURE_FILE);
+  } catch (error) {
+    const { lstat } = await import("fs/promises");
+    try {
+      await lstat(resolve(root, ARCHITECTURE_FILE));
+    } catch (missing) {
+      if (missing.code === "ENOENT")
+        return { configured: false, source: { root, file: ARCHITECTURE_FILE, revision: "" }, selection: { kind: "full" }, nodes: [], relations: [], views: [], documents: [], diagnostics: [{ code: "not_configured", message: `Architecture is not configured: ${ARCHITECTURE_FILE}` }] };
+    }
+    throw error;
+  }
+  const model = parseArchitecture(content);
+  const selection = options.node ? { kind: "node", id: options.node } : options.view ? { kind: "view", id: options.view } : { kind: "full" };
+  const { selected, visible, relations } = selectArchitecture(model, selection);
+  const diagnostics = [];
+  const chapterMaps = /* @__PURE__ */ new Map();
+  const sourceInputs = [content, JSON.stringify(config.config)];
+  for (const file of new Set(model.bindings.map((binding) => binding.file))) {
+    try {
+      const body = await readProjectFile(root, file);
+      chapterMaps.set(file, documentHeadings(body));
+      sourceInputs.push(file, body);
+    } catch (error) {
+      diagnostics.push({ code: "document_unavailable", file, message: error.message });
+    }
+  }
+  const nodes = model.nodes.filter((node) => visible.has(node.id)).map((node) => {
+    const ancestors = /* @__PURE__ */ new Set();
+    let parent = node.parent;
+    while (parent) {
+      ancestors.add(parent);
+      parent = model.nodes.find((node2) => node2.id === parent)?.parent;
+    }
+    const bindings = model.bindings.filter((binding) => binding.node === node.id || binding.scope === "subtree" && ancestors.has(binding.node)).map((binding) => {
+      const reference = { ...binding, origin: binding.node, inherited: binding.node !== node.id };
+      if (!binding.headings || !chapterMaps.has(binding.file))
+        return reference;
+      try {
+        return { ...reference, anchor: resolveHeading(chapterMaps.get(binding.file), binding.headings).anchor };
+      } catch (error) {
+        diagnostics.push({ code: "chapter_unresolved", file: binding.file, message: error.message });
+        return reference;
+      }
+    });
+    return { ...node, boundary: !selected.has(node.id), bindings };
+  });
+  return { configured: true, source: { root, file: ARCHITECTURE_FILE, revision: digest(sourceInputs.join("\0")) }, selection, nodes, relations, views: model.views.filter((view) => selection.kind === "full" || view.id === options.view || selected.has(view.node)), documents: [...new Set(nodes.flatMap((node) => node.bindings.map((binding) => binding.file)))], diagnostics };
+}
+function isWithin(root, target) {
+  const path = relative(root, target);
+  return path !== ".." && !path.startsWith("../") && !isAbsolute(path);
+}
+
+// src/core/project-version.ts
+import { readFile, realpath as realpath2 } from "fs/promises";
+import { join } from "path";
+var PROJECT_VERSION_PATH = ".rsp/version";
+var PROJECT_SOURCE_PATH = ".rsp/source";
+var SOURCE_INVOCATION = "mise exec -- node dist/cli.mjs";
+function isExactVersion(value) {
+  return /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:0|[1-9]\d*|\d*[a-z-][\da-z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-z-][\da-z-]*))*)?(?:\+[\da-z-]+(?:\.[\da-z-]+)*)?$/i.test(value);
+}
+function exactInvocation(version) {
+  if (!isExactVersion(version))
+    throw new Error(`Invalid exact RSP version: ${version}`);
+  return `npx -y @oevery/rsp@${version}`;
+}
+async function readProjectVersion(projectRoot = ".") {
+  const directory = inspectManagedDirectory(join(projectRoot, RSP_DIR), "RSP root", { allowMissing: true });
+  if (directory.issue)
+    throw directory.issue;
+  if (!directory.exists)
+    return null;
+  const path = join(projectRoot, PROJECT_VERSION_PATH);
+  const inspection = inspectManagedFile(path, "project CLI version", { allowMissing: true });
+  if (inspection.issue)
+    throw inspection.issue;
+  if (!inspection.exists)
+    return null;
+  const version = (await readFile(path, "utf8")).trim();
+  if (!isExactVersion(version))
+    throw new Error(`${PROJECT_VERSION_PATH} must contain one exact package version, not a tag or range`);
+  return version;
+}
+async function readProjectRuntime(projectRoot = ".") {
+  const version = await readProjectVersion(projectRoot);
+  const source = inspectManagedFile(join(projectRoot, PROJECT_SOURCE_PATH), "project source selection", { allowMissing: true });
+  if (source.issue)
+    throw source.issue;
+  if (!source.exists)
+    return { mode: "package", version };
+  if (version !== null)
+    throw new Error(`${PROJECT_SOURCE_PATH} and ${PROJECT_VERSION_PATH} are mutually exclusive; explicitly select one runtime.`);
+  if ((await readFile(join(projectRoot, PROJECT_SOURCE_PATH), "utf8")).trim() !== ".")
+    throw new Error(`${PROJECT_SOURCE_PATH} must contain . to select this RSP source checkout.`);
+  if (await realpath2(projectRoot) !== await realpath2(PKG_ROOT))
+    throw new Error(`Source mode requires this checkout's local CLI. Build here, then use ${SOURCE_INVOCATION} <command>; a registry package or another checkout cannot substitute.`);
+  const sourceDirectory = inspectManagedDirectory(join(projectRoot, "src"), "RSP source directory");
+  const sourceEntry = inspectManagedFile(join(projectRoot, "src/cli.ts"), "RSP source entry");
+  if (sourceDirectory.issue || sourceEntry.issue)
+    throw sourceDirectory.issue ?? sourceEntry.issue;
+  return { mode: "source" };
+}
+async function selectProjectRuntime(operation = "ordinary") {
+  const version = await getVersion();
+  exactInvocation(version);
+  const selected = await readProjectRuntime();
+  if (selected.mode === "source")
+    return { mode: "source", version };
+  if (selected.version && selected.version !== version && operation !== "update") {
+    throw new Error(`Project pins RSP ${selected.version}; running CLI is ${version}. Use ${exactInvocation(selected.version)} <command>. To migrate deliberately, inspect the target version and run ${exactInvocation(version)} update.`);
+  }
+  if (selected.version && operation === "update" && compareVersions(version, selected.version) < 0)
+    throw new Error(`Downgrading RSP from ${selected.version} to ${version} is unsupported. Use ${exactInvocation(selected.version)} <command>.`);
+  return { mode: "package", version };
+}
+function compareVersions(left, right) {
+  const parts = (value) => {
+    const [core, ...pre] = value.split("+", 1)[0].split("-");
+    return { core: core.split(".").map(BigInt), pre: pre.length ? pre.join("-").split(".") : [] };
+  };
+  const a = parts(left);
+  const b = parts(right);
+  for (let i = 0; i < 3; i++) {
+    if (a.core[i] !== b.core[i])
+      return a.core[i] > b.core[i] ? 1 : -1;
+  }
+  if (!a.pre.length || !b.pre.length)
+    return Number(!a.pre.length) - Number(!b.pre.length);
+  for (let i = 0; i < Math.max(a.pre.length, b.pre.length); i++) {
+    const x = a.pre[i];
+    const y = b.pre[i];
+    if (x === y)
+      continue;
+    if (x === void 0 || y === void 0)
+      return x === void 0 ? -1 : 1;
+    const nx = /^\d+$/.test(x);
+    const ny = /^\d+$/.test(y);
+    if (nx && ny)
+      return BigInt(x) > BigInt(y) ? 1 : -1;
+    if (nx !== ny)
+      return nx ? -1 : 1;
+    return x > y ? 1 : -1;
+  }
+  return 0;
+}
+async function guardProjectVersion(rawArgs) {
+  if (rawArgs.some((arg) => ["--help", "-h"].includes(arg)) || rawArgs.length === 1 && ["--version", "-v"].includes(rawArgs[0]))
+    return;
+  if (["doctor", "config", "update"].includes(rawArgs[0] ?? ""))
+    return;
+  await selectProjectRuntime();
+}
+
+export {
+  selectArchitecture,
+  ARCHITECTURE_FILE,
+  MAX_CONTENT_BYTES,
+  digest,
+  projectPath,
+  readProjectFile,
+  documentHeadings,
+  queryArchitecture,
+  isWithin,
+  PROJECT_VERSION_PATH,
+  SOURCE_INVOCATION,
+  isExactVersion,
+  exactInvocation,
+  readProjectVersion,
+  readProjectRuntime,
+  selectProjectRuntime,
+  compareVersions,
+  guardProjectVersion
+};