zaurakworks · Aug 25, 2026
diff --git a/...planning-artifacts/architecture/architecture-agent-system-2026-08-22/.memlog.md b/...planning-artifacts/architecture/architecture-agent-system-2026-08-22/.memlog.md
@@ -2,7 +2,7 @@
 scope: Agent System MVP 的 OMP Agent 配置、激活、验证、观察与跨 Session 追溯
 purpose: 面向后续实现者的中文 build substrate
 altitude: feature
-updated: 2026-08-25T03:32
+updated: 2026-08-25T08:01
 ---
 
 - (constraint) clean-slate：现有 Python CAP 仅可作为 Bad Case 证据，不是需求、架构或迁移基线。
@@ -71,3 +71,6 @@ updated: 2026-08-25T03:32
 - (decision) 2026-08-25 由 (b) 推出的落点不变量：字节不得落在任何客户端的原生发现路径上，否则'必须走 configs'不可强制（会重演 entrypoints 那三条'加载可用的 X'把硬门降级为空操作的失败模式）。canonical 位置 _bmad/ 恰好不是原生发现路径，且 skill-manifest.csv 的 path 列本就指向 _bmad/core/<skill>/SKILL.md——这是 BMad 自身的设计形状，不是新发明。因此第 (1) 步的形状固定为：安装器按 pin 写 canonical 到 _bmad/（gitignored、每机复现）；ides 配置为不产生任何 IDE 投影；configs 从 canonical 路径物化进被它启动的会话。原生发现拿不到任何东西，规则由机制强制而非自觉。
 - (constraint) 2026-08-25 核实发现：本仓当前的 BMad 安装是残缺的。files-manifest.csv 记录的 263 个文件全部位于 _bmad/ 下（176 个 bmm/、78 个 core/、5 个 scripts/、其余配置），而 _bmad/ 磁盘上只有 150 KB、九个配置文件——254 个 canonical 本体文件不存在，仓内只剩 .claude/skills 与 .agents/skills 两份 IDE 投影。这解释了此前 skill-manifest.csv 的 path 指向不存在路径之谜：不是安装器没写 canonical，是写完之后被删了、只留投影。退役第 (1) 步必须先把 canonical 恢复回来。
 - (event) 2026-08-25 AD-22 修订完成（#173 两项裁定落地）：字节所有权条补入已核实的可复现性证据（npm bmad-method 6.11.0 与 pin 一致；files-manifest 263 条带 sha256，且经交叉比对 49/49 覆盖 skill 本体——这是'完整性可校验'成立的关键，专门验过）；新增'字节的落点不得是原生发现路径'一条 Rule；第 (1) 步写实两项前提并补入'本仓当前 BMad 安装残缺、254 个 canonical 缺失、必须先恢复'；可移植性段补入 canonical 落点为每机相同仓库相对路径这条强指示（不预先裁定）。Reviewer gate 按 stakes 缩放为两条配置 lens，均 PASS with findings，2 项 medium 全部 autofix：[current-tech] source built-in 的含义属推断非核实，已如实标注并挂到第 (1) 步待证实；[adversarial] '机制强制'覆盖面写得比实际大——用户级/机器级 skill 目录本仓管不到，已限定范围并规定第 (2) 步 parity 必须在无用户级 BMad 安装的环境中取证否则假阳性。lint_spine 0 findings。
+- (decision) 2026-08-25 AD-22 回写：退役第 (1) 步的 sourceRef 可移植性开放项已关闭。裁定为库内相对 POSIX 路径唯一合法、绝对路径一律拒绝、根由单一共用 defaultSupplyRoot() 提供且不进修订；五条判定规则集中在唯一实现 validateSupplyRelativeRef，供给侧与解析侧共用且无任一侧单独覆盖入口，因此'禁止各自发明'从此由机制保证。已随 Story 3.4 落地并合并（8d56565）。第③④两条规则由实测逼出：known('')／known('.') 使 path.resolve 返回根本身、cp --recursive 把整个供给库当一个 Skill 拷入并报成功（fail-closed 被翻成 fail-open）；同盘 C:x/y 在 win32 被折进根内而接受且收敛判定转为依赖 cwd，C:/x/y 在 POSIX 上 isAbsolute 为假而被当相对名接受。兼容性依据：真实库 20 个 skill 条目 sourceRef 全为 Unknown、Known 零条。
+- (event) 2026-08-25 同轮修复一处此前引入的文本缺陷：2026-08-25 早些时候的 AD-22 修订（PR #176）在替换第 (1) 步文本时未清掉锚点，导致'并且必须在这一步一并裁定 sourceRef 的跨机器可移植性语义——'一句连续重复两遍。本轮回写时发现并删除重复。lint_spine 修订前后均 0 findings（该 lint 不检测重复句）。
+- (event) 2026-08-25 AD-22 回写完成。Reviewer gate 内联跑两条配置 lens（子 agent 授权只覆盖本轮 bmad-build 运行），落盘 reviews/review-ad22-writeback.md。current-tech PASS 无 findings（六条引用事实全部本 session 实测或直接观察）。adversarial PASS with findings，1 项 high 已当场修复：权威面从未说明根实际怎么取——AD-22 通篇只出现一次 defaultSupplyRoot，CONTROL_PLANE_SUPPLY_ROOT／部署场景／仓库根三词零出现，而同一条 AD 又把 canonical 落点定为仓库相对的 _bmad/；只读 spine 的 Story 3.5 实现者会推断用 $HOME 默认根，与 _bmad/ 拼起来解析不到任何东西且按 AD-10 静默降级。这与本 AD 当初成立的理由（成熟模型挂在工具 README 上、够不着权威面）是同一种病。已在落点那条 Rule 补入两种部署场景与各自的根来源。lint_spine 0 findings。
diff --git a/...tifacts/architecture/architecture-agent-system-2026-08-22/ARCHITECTURE-SPINE.md b/...tifacts/architecture/architecture-agent-system-2026-08-22/ARCHITECTURE-SPINE.md
@@ -219,9 +219,9 @@ flowchart LR
 - **Rule：** 产品装配面（消费者是 `configs` 的用户）与本仓自我开发装配面（消费者是在本仓工作的 agent 会话）是两个不同的**消费者**，但共用同一条装配路径与同一套合同——不为后者另立机制。
   - **唯一装配路径。** 本仓 agent 会话获得 Instructions/Skills/MCP 的唯一受认可方式是经 `configs use <revisionId> --client <clientId>` 启动，按 AD-21 在调用作用域内物化交付。客户端原生项目目录发现（Claude Code 读 `.claude/skills/` 已由本仓 session 直接观察证实；`.agents/skills/` 服务 Codex 是**未核实推断**——来源只是 BMad 安装器声明了 `ides: [claude-code, codex, pi]` 三个目标而仓内只有两个目录，按 AD-15 原则在有真实 probe/smoke 证据前保持 Unknown）**不是**装配面：它不产生 `AssemblyManifest`、不绑定 `capabilityStatus`、不产生 receipt，因此在 AD-8 的事实层级里不能为任何能力声称 `observationStage`。未经 `configs` 启动的会话按定义不具备本产品装配的能力——这是本条明确接受的结果，不是待修的缺陷。
   - **Skill 字节的所有权按来源判定，不按存放位置。** 第三方 Skill 组（当前唯一实例 `bmad`，fork 上游 v6.11.0，49 个成员）的字节是**上游可复现产物**，不是本仓源码：仓库跟踪其 **pin**，不跟踪其字节，字节由该 pin 在每台机器上复现。`bmad` 的可复现性已于 2026-08-25 核实，不再是假设——npm 包 `bmad-method` 的当前版本 `6.11.0` 与 `_bmad/_config/manifest.yaml` 的 `installation.version` 一致，两个 module 的 `source` 均为 `built-in` 且 `npmPackage`／`repoUrl` 均为 `null`，据此**推断**其本体随该 npm 包分发、无需另抓（未运行安装器核实，第 (1) 步恢复 canonical 时顺带证实），`_bmad/_config/files-manifest.csv` 记录 263 个文件且每条带 sha256，完整性可校验。一个 pin 只有在同时具备**可取得的来源**与**可校验的完整性**时才算成立；仅记版本号不算。每个 `fork` 组都必须有一个被跟踪的 pin，声明上游 ref 与可复现的取得方式；`bmad` 的 pin 是 `_bmad/_config/manifest.yaml` 的 `installation.version` 加 `_bmad/_config/skill-manifest.csv`，那是 BMad 安装器专有的产物，是当前唯一实例而不是通用格式——再出现来自其他上游的 `fork` 组时，其 pin 落点按本条要求另行确定，不得省略，也不得挪用 BMad 的清单。本仓自研 Skill 组（`plugins/` 下 `own`／`vendor` 各组）的字节是本仓源码，继续跟踪。
-  - **字节的落点不得是原生发现路径。** 上一条要求每机复现字节，本条约束它们落在哪：**不得落在任何客户端的原生发现路径上**（当前已知即 `.claude/skills/`、`.agents/skills/`）。否则会话不经 `configs` 也照样拿到 Skill，"唯一装配路径"就退化成一句无人执行的声明——与 `entrypoints/agent-system.md` 那三条"加载可用的 X"把硬门降级为空操作是同一种失败模式，本条要防的正是它重演。canonical 落点取 `_bmad/`：它不是任何客户端的原生发现路径，且 `_bmad/_config/skill-manifest.csv` 的 `path` 列本就指向 `_bmad/core/<skill>/SKILL.md`——这是 BMad 自身的安装形状，不是本条新发明。安装器须配置为不产生任何 IDE 投影，`configs` 从 canonical 路径物化。**在本仓可控面内，规则由机制强制而非自觉。**已知的外部限制：客户端同样会从**用户级／机器级** skill 目录发现 Skill，那不是项目目录，本仓的 `.gitignore` 与安装器 `ides` 配置都管不到——某台机器若在用户级装了 BMad，其会话不经 `configs` 也会拿到 Skill。本仓无权约束他人机器，不试图去管；但第 (2) 步的 parity 验证**必须在不存在用户级 BMad 安装的环境中进行**，否则结论是假阳性。（本机 2026-08-25 实测：`~/.claude/skills` 与 `~/.agents/skills` 均不存在。）
+  - **字节的落点不得是原生发现路径。** 上一条要求每机复现字节，本条约束它们落在哪：**不得落在任何客户端的原生发现路径上**（当前已知即 `.claude/skills/`、`.agents/skills/`）。否则会话不经 `configs` 也照样拿到 Skill，"唯一装配路径"就退化成一句无人执行的声明——与 `entrypoints/agent-system.md` 那三条"加载可用的 X"把硬门降级为空操作是同一种失败模式，本条要防的正是它重演。canonical 落点取 `_bmad/`：它不是任何客户端的原生发现路径，且 `_bmad/_config/skill-manifest.csv` 的 `path` 列本就指向 `_bmad/core/<skill>/SKILL.md`——这是 BMad 自身的安装形状，不是本条新发明。安装器须配置为不产生任何 IDE 投影，`configs` 从 canonical 路径物化。**根本身怎么取，两种部署场景都要认：** 本仓自我开发时，供给库就是本仓库，根经 `CONTROL_PLANE_SUPPLY_ROOT` 指向仓库根（否则 `_bmad/core/<skill>` 这类库内相对路径解析不到）；发行版 `configs` 用户的机器上没有「本仓库」这个东西，走 `defaultSupplyRoot()` 的默认值 （`path.dirname(defaultDbPath())` 派生的 `supply/`）。默认值只服务后者——不把它改成仓库根派生，是因为编译后的二进制没有仓库可派生，绕一圈仍要回退到某个 `$HOME` 约定。**在本仓可控面内，规则由机制强制而非自觉。**已知的外部限制：客户端同样会从**用户级／机器级** skill 目录发现 Skill，那不是项目目录，本仓的 `.gitignore` 与安装器 `ides` 配置都管不到——某台机器若在用户级装了 BMad，其会话不经 `configs` 也会拿到 Skill。本仓无权约束他人机器，不试图去管；但第 (2) 步的 parity 验证**必须在不存在用户级 BMad 安装的环境中进行**，否则结论是假阳性。（本机 2026-08-25 实测：`~/.claude/skills` 与 `~/.agents/skills` 均不存在。）
   - **组是第一结构。** 装卸、版本、发现、判定与复核都以**组**为单位，不以单个 Skill 为单位（当前 12 个组 / 82 个 Skill：判定 12 次，不是 82 次）。一个组可以服务多个事项，组内成员互相调用（路由、deprecated 转发），拆组会拆断这些调用，因此组是不可再分的装配与判定单元；`configs` 的装配意图、上面的字节所有权判据与下面的退役顺序全部按组表达。组的来源三分——`own`（自研，无上游）、`fork`（取自上游、承诺零本地改动、更新即拉上游新版）、`vendor`（取自上游但已打补丁，必须逐处登记）——是上面"按来源判归属"的判据本身，不是描述性标签；`fork` 的零改动必须可机械验证（内容指纹与上游 ref 不符即承诺已破，须转 `vendor` 或把改动推回上游），不接受仅凭声明。该模型此前只存在于 `tools/skill_registry/README.md`（一个工具的 README，不在权威面上），本条将其固定。
-  - **退役顺序（严格按序，不得先退役后落地）。** 复用 `.cap/` 退役已确立的三步形状：**(1) 落地替代**——`configs` 具备把一批磁盘上的 Skill 目录变成 `sourceRef` 可解析之修订的供给能力（缺口记于 `#173`），且本仓自身的装配意图能被表达为一条真实修订。本步的两项前提已由负责人于 2026-08-25 裁定（见 `#173`）：字节来源为按 pin 运行 BMad 安装器写出 canonical 到 `_bmad/`；原生启动的会话不再受支持。**本步必须先修一处现状：本仓当前的 BMad 安装是残缺的**——`files-manifest.csv` 记录的 263 个文件全部位于 `_bmad/` 下，而该目录磁盘上只剩九个配置文件，254 个 canonical 本体已被删除、仓内只余两份 IDE 投影；canonical 不恢复，就没有可供 `configs` 物化的来源。此外须核实安装器能否配置为不产生 IDE 投影（未验证，属本步实现细节）。**并且必须在这一步一并裁定 `sourceRef` 的跨机器可移植性语义**——**并且必须在这一步一并裁定 `sourceRef` 的跨机器可移植性语义**——本条规定第三方组字节由每台机器各自复现，同一条修订在两台机器上对应的绝对路径必然不同，而 AD-21 只说"把 `sourceRef` 解析为真实内容"、既有 `content-materializer.ts` 的实现把它当作可直接使用的路径、AD-21 的阻塞前提段又要求 `cap-fs.ts` 写入"已知的真实磁盘路径"，三处合起来事实上假定了绝对路径，与每机复现直接冲突。绝对路径、仓库相对路径还是符号引用，选哪一种留给这一步依据真实证据裁定，本条不预先选定——但需注意上面已裁定的 canonical 落点 `_bmad/` 是一个在每台机器上都相同的**仓库相对**路径，这对该选择是一条强指示；本条**禁止的是让两个实现者各自发明**——该语义必须一次裁定并同时约束 AD-21 的解析侧与供给侧，否则一方产出的修订在另一方手里会按 AD-10 静默全量降级为 `unsupported`，且没有任何门能指出根因；**(2) parity 验证**——经 `configs use` 启动的本仓会话，其实际可用 Skill 集合与今天由原生发现得到的集合做真实烟雾对照，不是清单比对；**(3) 退役**——`.claude/skills/`、`.agents/skills/` 改为非跟踪并进入 `.gitignore`，`skill-asset-checks.yml` 的双份字节一致门随之退役。第 (2) 步稳定之前，两份保持 git 跟踪、一致门继续生效。
+  - **退役顺序（严格按序，不得先退役后落地）。** 复用 `.cap/` 退役已确立的三步形状：**(1) 落地替代**——`configs` 具备把一批磁盘上的 Skill 目录变成 `sourceRef` 可解析之修订的供给能力（缺口记于 `#173`），且本仓自身的装配意图能被表达为一条真实修订。本步的两项前提已由负责人于 2026-08-25 裁定（见 `#173`）：字节来源为按 pin 运行 BMad 安装器写出 canonical 到 `_bmad/`；原生启动的会话不再受支持。**本步必须先修一处现状：本仓当前的 BMad 安装是残缺的**——`files-manifest.csv` 记录的 263 个文件全部位于 `_bmad/` 下，而该目录磁盘上只剩九个配置文件，254 个 canonical 本体已被删除、仓内只余两份 IDE 投影；canonical 不恢复，就没有可供 `configs` 物化的来源。此外须核实安装器能否配置为不产生 IDE 投影（未验证，属本步实现细节）。**并且必须在这一步一并裁定 `sourceRef` 的跨机器可移植性语义**——本条规定第三方组字节由每台机器各自复现，同一条修订在两台机器上对应的绝对路径必然不同，而 AD-21 只说"把 `sourceRef` 解析为真实内容"、既有 `content-materializer.ts` 的实现把它当作可直接使用的路径、AD-21 的阻塞前提段又要求 `cap-fs.ts` 写入"已知的真实磁盘路径"，三处合起来事实上假定了绝对路径，与每机复现直接冲突。**该裁定已于 2026-08-25 作出并落地，本开放项至此关闭**（Story 3.4，见 `_bmad-output/implementation-artifacts/spec-3-4-sourceref-跨机器可移植性语义.md`，合并于 `8d56565`）：`sourceRef` **只有一种合法形态——库内相对 POSIX 路径**；绝对路径一律拒绝；根由单一共用的 `defaultSupplyRoot()` 提供，是本机配置、不进修订，机器差异只由根承担。五条判定规则——非空 → 不含反斜杠 → 不带盘符前缀 → 非绝对 → 解析后严格落在根内——集中在唯一实现 `validateSupplyRelativeRef`（`packages/control-plane/src/cli/supply-root.ts`），供给侧与解析侧共用，**不存在任一侧的单独覆盖入口**，因此「禁止两个实现者各自发明」这条约束从此由机制保证而非靠自觉。其中第③④两条不是防御性编程，是实测逼出来的：`known('')` 与 `known('.')` 会让 `path.resolve` 返回根本身，`cp --recursive` 随后把整个供给库当作一个 Skill 拷入**并报告启动成功**，把 AD-10 的 fail-closed 翻成 fail-open；与根同盘的 `C:x/y` 在 win32 被折进根内而接受（且收敛判定转为依赖 `process.cwd()`），`C:/x/y` 在 POSIX 上 `isAbsolute` 为假而被当普通相对名接受——同一条修订两个平台含义不同。兼容性依据：实测真实库中 20 个 skill 条目的 `sourceRef` 全为 `Unknown`、Known 零条，拒绝绝对路径不作废任何真实数据；**(2) parity 验证**——经 `configs use` 启动的本仓会话，其实际可用 Skill 集合与今天由原生发现得到的集合做真实烟雾对照，不是清单比对；**(3) 退役**——`.claude/skills/`、`.agents/skills/` 改为非跟踪并进入 `.gitignore`，`skill-asset-checks.yml` 的双份字节一致门随之退役。第 (2) 步稳定之前，两份保持 git 跟踪、一致门继续生效。
   - **装配权威唯一。** `plugins/skill-imports.toml` 当前自称"当前默认装配声明"，实际只列 1 条且无任何产品代码读取（全仓唯一引用者是一致性测试 `plugins/tests/workflow-routing.test.ts`）——它不是装配权威。装配权威只有 `configs` 的修订（AD-4）。该文件与 `plugins/README.md` 的对应措辞在退役第 (3) 步一并收敛，不在此之前单独改动。
   - **规则与能力必须同真。** 仓库规则（`entrypoints/agent-system.md` 及其投影）不得强制加载一个本仓当前装配下不可获得的 Skill。任一时点二者必须一致：要么该 Skill 进入本仓装配意图，要么该规则改写或删除。"加载可用的 X"这类措辞**不构成豁免**——它把硬门静默降级为空操作，正是本条要防的失败模式。当前已知不一致：`entrypoints/agent-system.md` 第 62 行要求的 `orchestrated-collaboration`、第 78／84 行要求的 `adaptive-problem-solving`（后者含"父目标验收"硬门）都只存在于 `plugins/`，不在任何客户端的原生发现路径上，对本仓会话结构性不可见；退役第 (1) 步必须把它们纳入本仓装配意图，否则该步不算完成。
 - **开放问题（不阻塞本条，落地第 (1) 步时判断）：** Codex CLI 侧尚无等价的 `configs` 启动入口（Codex 仍按 AD-1 Deferred），因此第 (2) 步的 parity 验证在 Codex 侧暂时无法执行。是否允许两个客户端按各自节奏分别退役各自的投影目录（先退 `.claude/skills/`、`.agents/skills/` 等 Codex 激活后再退），留待第 (1) 步落地时依据当时的真实能力判断，不在本条预先裁定。